openapi: 3.0.0
info:
  description: Welcome to Xfers' API documentation. You can find information on our API endpoint specific to your country.
  version: '3'
  title: Xfers Bank Account Fixed Virtual Account Bank Transfers API
  contact:
    name: Contact us through our help desk
    url: https://bit.ly/XfersSupport
servers:
- description: Indonesia Production
  url: https://id.xfers.com/api
- description: Indonesia Sandbox for testing
  url: https://sandbox-id.xfers.com/api
tags:
- name: Fixed Virtual Account Bank Transfers
paths:
  /v3/payment_gateway/payment_methods/fixed_virtual_account_bank_transfers:
    post:
      tags:
      - Fixed Virtual Account Bank Transfers
      summary: Create Fixed Virtual Account
      description: 'With Fixed Virtual Account (VA) Bank Transfer payment method, we will create a fixed/permanent VA for the given customer id and bank combination.


        Any amount that we receive in the given VA will be associated to the given destination account and we will notify you with the successful callback.'
      security:
      - X-XFERS-APP-API-KEY: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/base_class/fixed_virtual_account_bank_transfers/schemas/RequestBody'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/base_class/fixed_virtual_account_bank_transfers/schemas/RequestBody'
                - $ref: '#/base_class/fixed_virtual_account_bank_transfers/schemas/FixedVirtualAccountObject'
        4XX:
          $ref: '#/components/responses/v3Error:4XX'
      callbacks:
        payment_paid:
          $callback_settings.v3_payment_gateway_payment_paid:
            post:
              summary: Callback when payment paid
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/base_class/payment/schemas/Callback'
                    examples:
                      paid:
                        $ref: '#/base_class/payment/examples/callback/paid'
              responses:
                '200':
                  description: Your server returns this code if it accepts the callback
        payment_completed:
          $callback_settings.v3_payment_gateway_payment_completed:
            post:
              summary: Callback when payment completed
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/base_class/payment/schemas/Callback'
                    examples:
                      paid:
                        $ref: '#/base_class/payment/examples/callback/completed'
              responses:
                '200':
                  description: Your server returns this code if it accepts the callback
  /v3/payment_gateway/payment_methods/fixed_virtual_account_bank_transfers/{id}/payments:
    get:
      tags:
      - Fixed Virtual Account Bank Transfers
      summary: Payment History
      description: From a given Payment Method, list the payment history sorted from newest to oldest.
      security:
      - X-XFERS-APP-API-KEY: []
      parameters:
      - name: id
        in: path
        description: '[Virtual Account Number](./payment-gateway#tag/Fixed-Virtual-Account-Bank-Transfers) from Xfers.'
        required: true
        schema:
          type: string
          example: '8624095700121411'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/base_class/payment/schemas/BaseObject'
                - properties:
                    payment_method:
                      allOf:
                      - $ref: '#/base_class/fixed_virtual_account_bank_transfers/schemas/RequestBody'
                      - $ref: '#/base_class/fixed_virtual_account_bank_transfers/schemas/FixedVirtualAccountObject'
              examples:
                payment_history:
                  $ref: '#/base_class/payment/examples/payment_history'
    post:
      tags:
      - Fixed Virtual Account Bank Transfers
      summary: Simulate Payment (Sandbox Only)
      description: In sandbox, this will allow you to simulate customer making payment to the given virtual account number. It will return the details of the contract created as well as triggering a callback as configured.
      security:
      - X-XFERS-APP-API-KEY: []
      parameters:
      - name: id
        in: path
        description: '[Virtual Account Number](./payment-gateway#tag/Fixed-Virtual-Account-Bank-Transfers) from Xfers.'
        required: true
        schema:
          type: string
          example: '8624095700121411'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                amount:
                  description: Payment amount to simulate
                  type: integer
                  example: 10000
              required: amount
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/base_class/payment/schemas/BaseObject'
                - properties:
                    payment_method:
                      allOf:
                      - $ref: '#/base_class/fixed_virtual_account_bank_transfers/schemas/RequestBody'
                      - $ref: '#/base_class/fixed_virtual_account_bank_transfers/schemas/FixedVirtualAccountObject'
              examples:
                paid:
                  $ref: '#/base_class/payment/examples/payment_response/paid'
        4XX:
          $ref: '#/components/responses/v3Error:4XX'
      callbacks:
        payment_paid:
          $callback_settings.v3_payment_gateway_payment_paid:
            post:
              summary: Callback with payment paid
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/base_class/payment/schemas/Callback'
                    examples:
                      paid:
                        $ref: '#/base_class/payment/examples/callback/paid'
              responses:
                '200':
                  description: Your server returns this code if it accepts the callback
components:
  examples:
    XFE403:
      summary: XFE403 - ...
      value:
        error: string
        error_code: XFE403
        error_handling: '...'
    XFE111:
      summary: XFE1 - Duplicate credentials
      value:
        error: string
        error_code: XFE111
        error_handling: Particulars already exist. Please make sure you entered the correct parameters.
    XFE3:
      summary: XFE3 - Internal Error
      value:
        error: string
        error_code: XFE3
        error_handling: Unexpected error. Try again later or contact customer support at https://bit.ly/XfersSupport.
    XFE312:
      summary: XFE312 - Conditions not met to close account
      value:
        error: string
        error_code: XFE312
        error_handling: Invalid request to close account. Follow instruction in the response.
    XFE1:
      summary: XFE1 - Server busy
      value:
        error: string
        error_code: XFE1
        error_handling: Follow instructions in the response.
    XFE311:
      summary: XFE311 - Cannot be different wallet type
      value:
        error: string
        error_code: XFE311
        error_handling: Follow instruction in response or contact customer support at https://bit.ly/XfersSupport.
    XFE301:
      summary: XFE301 - Account locked
      value:
        error: string
        error_code: XFE301
        error_handling: Request not available. Please contact customer support at https://bit.ly/XfersSupport.
    XFE108:
      summary: XFE108 - More user information required
      value:
        error: string
        error_code: XFE108
        error_handling: Follow instructions in the response.
    XFE107:
      summary: XFE107 - Only enter one auth_code
      value:
        error: string
        error_code: XFE107
        error_handling: Do not enter both OTP or Google Auth OTP. Only need to enter one.
    XFE402:
      summary: XFE402 - Cannot use placeholder account
      value:
        error: string
        error_code: XFE402
        error_handling: Follow instructions in response.
    XFE502:
      summary: XFE502 - Unexpected BANK API error
      value:
        error: string
        error_code: XFE502
        error_handling: Try again later or contact customer support at https://bit.ly/XfersSupport.
    XFE106:
      summary: XFE106 - No auth_code provided
      value:
        error: string
        error_code: XFE106
        error_handling: Enter either phone OTP or Google Auth OTP
    XFE407:
      summary: XFE407 - Conditions to charge card not met
      value:
        error: string
        error_code: XFE407
        error_handling: Invalid request for this transaction. Make sure you entered the correct txn_id.
    XFE409:
      summary: XFE409 - Order id exist
      value:
        error: string
        error_code: XFE409
        error_handling: Please enter another order_id.
    XFE105:
      summary: XFE105 - Captcha error
      value:
        error: string
        error_code: XFE1
        error_handling: Follow instructions in the response.
    XFE404:
      summary: XFE404 - Forex not supported
      value:
        error: string
        error_code: XFE404
        error_handling: Make sure you call the correct API or contact customer support at https://bit.ly/XfersSupport.
    XFE102:
      summary: XFE102 - Entered value is less than minimum
      value:
        error: string
        error_code: XFE102
        error_handling: Make sure you entered the correct number.
    XFE109:
      summary: XFE109 - Invalid credentials
      value:
        error: string
        error_code: XFE109
        error_handling: Make sure you entered the correct credentials.
    XFE104:
      summary: XFE104 - Media provided too large
      value:
        error: string
        error_code: XFE104
        error_handling: Media too big. Follow the guidelines in the response.
    XFE15:
      summary: XFE15 - Required parameter empty
      value:
        error: string
        error_code: XFE15
        error_handling: Make sure you entered the correct required parameter.
    XFE14:
      summary: XFE14 - API only allowed for fully verified user
      value:
        error: string
        error_code: XFE14
        error_handling: Please submit KYC data to get your account fully verified.
    XFE2:
      summary: XFE2 - Access denied
      value:
        error: string
        error_code: XFE2
        error_handling: Make sure you call the correct API or contact customer support at https://bit.ly/XfersSupport.
    XFE506:
      summary: XFE506 - Bank account already taken
      value:
        error: string
        error_code: XFE506
        error_handling: Please use another bank account.
    XFE309:
      summary: XFE309 - Cannot use same account
      value:
        error: string
        error_code: XFE309
        error_handling: Follow instructions in the response.
    XFE13:
      summary: XFE13 - Record not found
      value:
        error: string
        error_code: XFE13
        error_handling: Please check that you provided the correct API Key and the correct parameters.
    XFE8:
      summary: XFE8 - Cannot retrieve media
      value:
        error: string
        error_code: XFE8
        error_handling: Cannot retrieve media. Please enter a new URL or try again later.
    XFE7:
      summary: XFE7 - Database error
      value:
        error: string
        error_code: XFE7
        error_handling: Follow instructions in the response.
    XFE408:
      summary: XFE408 - Invalid charge request
      value:
        error: string
        error_code: XFE408
        error_handling: Invalid request. Please follow instructions in response or contact customer support at https://bit.ly/XfersSupport.
    XFE302:
      summary: XFE302 - Account deleted
      value:
        error: string
        error_code: XFE302
        error_handling: Request not available. Please contact customer support at https://bit.ly/XfersSupport.
    XFE201:
      summary: XFE201 - Not yet a merchant
      value:
        error: string
        error_code: XFE201
        error_handling: Please verify your merchant or business account.
    XFE103:
      summary: XFE103 - ...
      value:
        error: string
        error_code: XFE103
        error_handling: Follow instructions in the response.
    XFE406:
      summary: XFE406 - Cannot refund prepaid transaction
      value:
        error: string
        error_code: XFE406
        error_handling: Please choose another transaction to refund.
    XFE401:
      summary: XFE401 - Cannot refund charge
      value:
        error: string
        error_code: XFE401
        error_handling: Invalid request. Please call another API or Contact customer support at https://bit.ly/XfersSupport.
    XFE503:
      summary: XFE503 - Failed name check
      value:
        error: string
        error_code: XFE503
        error_handling: Bank account name and name provided have to be similar.
    XFE410:
      summary: XFE410 - Invalid application fee
      value:
        error: string
        error_code: XFE410
        error_handling: Invalid request. Please make changes to the parameters as stated in the response.
    XFE304:
      summary: XFE304- Account closed
      value:
        error: string
        error_code: XFE304
        error_handling: Request not available. Please contact customer support at https://bit.ly/XfersSupport.
    XFE110:
      summary: XFE110 - Cannot sign up twice
      value:
        error: string
        error_code: XFE110
        error_handling: Please sign in instead
    XFE504:
      summary: XFE504 - Maximum number of bank account
      value:
        error: string
        error_code: XFE504
        error_handling: Delete existing bank accounts.
    XFE16:
      summary: XFE16 - Invalid request
      value:
        error: string
        error_code: XFE16
        error_handling: API request not supported. Make sure you entered the correct API key or contact customer support at https://bit.ly/XfersSupport.
    XFE310:
      summary: XFE310 - Cannot use same account
      value:
        error: string
        error_code: XFE310
        error_handling: Follow instructions in the response.
    XFE9:
      summary: XFE9 - ....
      value:
        error: string
        error_code: XFE9
        error_handling: '...'
    XFE601:
      summary: XFE601 - Conditions to withdraw not met. Can be solved by changing amount
      value:
        error: string
        error_code: XFE601
        error_handling: Your withdrawal does not meet the conditions required. Please follow the instructions in the response.
    XFE10:
      summary: XFE10 - Invalid environment
      value:
        error: string
        error_code: XFE10
        error_handling: Request not supported for this environment.
    XFE4:
      summary: XFE4 - Authentication field empty
      value:
        error: string
        error_code: XFE4
        error_handling: Follow instructions in the response.
    XFE307:
      summary: XFE307 - ...
      value:
        error: string
        error_code: XFE307
        error_handling: '...'
    XFE303:
      summary: XFE303 - Account terminated
      value:
        error: string
        error_code: XFE303
        error_handling: Request not available. Please contact customer support at https://bit.ly/XfersSupport.
    XFE101:
      summary: XFE101 - Not local number
      value:
        error: string
        error_code: XFE101
        error_handling: Follow instructions in the response.
    XFE405:
      summary: XFE405 - Charge cannot be refunded
      value:
        error: string
        error_code: XFE405
        error_handling: Only completed contract can be refunded.
    XFE505:
      summary: XFE505 - Bank abbrev provided invalid
      value:
        error: string
        error_code: XFE505
        error_handling: Use GET {{base-api-url}}api/v3/banks to get the correct bank abbrev.
    XFE6:
      summary: XFE6 - Invalid signature
      value:
        error: string
        error_code: XFE6
        error_handling: Follow instructions in the response.
    XFE5:
      summary: XFE5 - Api key is invalid
      value:
        error: string
        error_code: XFE5
        error_handling: Make sure you entered the correct API key or contact customer support at https://bit.ly/XfersSupport
    XFE603:
      summary: XFE603 - Not allowed to carry out request
      value:
        error: string
        error_code: XFE603
        error_handling: Invalid request. Please call another API or contact customer support at https://bit.ly/XfersSupport.
    XFE12:
      summary: XFE12 - Invalid parameter
      value:
        error: string
        error_code: XFE12
        error_handling: Make sure you entered the correct parameters.
    XFE306:
      summary: XFE306 - ...
      value:
        error: string
        error_code: XFE306
        error_handling: '...'
    XFE602:
      summary: XFE602 - Server busy
      value:
        error: string
        error_code: XFE602
        error_handling: Your withdrawal exceeds the limit for the time period. Please change the amount or verify your account.
    XFE11:
      summary: XFE11 - Timeout
      value:
        error: string
        error_code: XFE11
        error_handling: Please try again later.
    XFE308:
      summary: XFE308 - ...
      value:
        error: string
        error_code: XFE308
        error_handling: '...'
    XFE501:
      summary: XFE501 - Expected Bank API error
      value:
        error: string
        error_code: XFE501
        error_handling: Try again later or contact customer support at https://bit.ly/XfersSupport.
    XFE112:
      summary: XFE112 - Repeat request
      value:
        error: string
        error_code: XFE112
        error_handling: API request has already been made. Please follow the instructions in the response or call aother API.
    XFE305:
      summary: XFE305 - ....
      value:
        error: string
        error_code: XFE305
        error_handling: '...'
  schemas:
    error_response:
      type: object
      properties:
        error:
          description: Error Message
          type: string
        error_code:
          description: Xfers' error code XFEXXX
          type: string
        error_handling:
          description: Instruction on how to handle error. Refer to Error Codes tag for more information.
          type: string
  responses:
    v3Error:4XX:
      description: List of possible errors
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error_response'
          examples:
            XFE1:
              $ref: '#/components/examples/XFE1'
            XFE2:
              $ref: '#/components/examples/XFE2'
            XFE3:
              $ref: '#/components/examples/XFE3'
            XFE4:
              $ref: '#/components/examples/XFE4'
            XFE5:
              $ref: '#/components/examples/XFE5'
            XFE6:
              $ref: '#/components/examples/XFE6'
            XFE7:
              $ref: '#/components/examples/XFE7'
            XFE8:
              $ref: '#/components/examples/XFE8'
            XFE9:
              $ref: '#/components/examples/XFE9'
            XFE10:
              $ref: '#/components/examples/XFE10'
            XFE11:
              $ref: '#/components/examples/XFE11'
            XFE12:
              $ref: '#/components/examples/XFE12'
            XFE13:
              $ref: '#/components/examples/XFE13'
            XFE14:
              $ref: '#/components/examples/XFE14'
            XFE15:
              $ref: '#/components/examples/XFE15'
            XFE16:
              $ref: '#/components/examples/XFE16'
            XFE101:
              $ref: '#/components/examples/XFE101'
            XFE102:
              $ref: '#/components/examples/XFE102'
            XFE103:
              $ref: '#/components/examples/XFE103'
            XFE104:
              $ref: '#/components/examples/XFE104'
            XFE105:
              $ref: '#/components/examples/XFE105'
            XFE106:
              $ref: '#/components/examples/XFE106'
            XFE107:
              $ref: '#/components/examples/XFE107'
            XFE108:
              $ref: '#/components/examples/XFE108'
            XFE109:
              $ref: '#/components/examples/XFE109'
            XFE110:
              $ref: '#/components/examples/XFE110'
            XFE111:
              $ref: '#/components/examples/XFE111'
            XFE112:
              $ref: '#/components/examples/XFE112'
            XFE201:
              $ref: '#/components/examples/XFE201'
            XFE301:
              $ref: '#/components/examples/XFE301'
            XFE302:
              $ref: '#/components/examples/XFE302'
            XFE303:
              $ref: '#/components/examples/XFE303'
            XFE304:
              $ref: '#/components/examples/XFE304'
            XFE305:
              $ref: '#/components/examples/XFE305'
            XFE306:
              $ref: '#/components/examples/XFE306'
            XFE307:
              $ref: '#/components/examples/XFE307'
            XFE308:
              $ref: '#/components/examples/XFE308'
            XFE309:
              $ref: '#/components/examples/XFE309'
            XFE310:
              $ref: '#/components/examples/XFE310'
            XFE311:
              $ref: '#/components/examples/XFE311'
            XFE312:
              $ref: '#/components/examples/XFE312'
            XFE401:
              $ref: '#/components/examples/XFE401'
            XFE402:
              $ref: '#/components/examples/XFE402'
            XFE403:
              $ref: '#/components/examples/XFE403'
            XFE404:
              $ref: '#/components/examples/XFE404'
            XFE405:
              $ref: '#/components/examples/XFE405'
            XFE406:
              $ref: '#/components/examples/XFE406'
            XFE407:
              $ref: '#/components/examples/XFE407'
            XFE408:
              $ref: '#/components/examples/XFE408'
            XFE409:
              $ref: '#/components/examples/XFE409'
            XFE410:
              $ref: '#/components/examples/XFE410'
            XFE501:
              $ref: '#/components/examples/XFE501'
            XFE502:
              $ref: '#/components/examples/XFE502'
            XFE503:
              $ref: '#/components/examples/XFE503'
            XFE504:
              $ref: '#/components/examples/XFE504'
            XFE505:
              $ref: '#/components/examples/XFE505'
            XFE506:
              $ref: '#/components/examples/XFE506'
            XFE601:
              $ref: '#/components/examples/XFE601'
            XFE602:
              $ref: '#/components/examples/XFE602'
            XFE603:
              $ref: '#/components/examples/XFE603'
  securitySchemes:
    X-XFERS-USER-API-KEY:
      type: apiKey
      name: X-XFERS-USER-API-KEY
      in: header
      description: You can retrieve this by using [get_token API](../sg/api/cutting-edge#operation/getToken)
externalDocs:
  description: Find out more about Xfers
  url: https://id.xfers.com
x-tagGroups:
- name: User Management
  tags:
  - Registration
  - User Account
  - Bank Account
  - E-signature
- name: Payments
  tags:
  - Charge
  - Payout
  - Withdraw
  - Intents
- name: Loans
  tags:
  - Loans
  - Disbursements
  - Repayments
- name: Appendix
  tags:
  - Testing
  - Error Response
  - Pagination
  - Callback Configuration
  - Try it out with Postman