Xfers Disbursements API

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 Disbursements 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: Disbursements
  description: API for Disbursement
paths:
  /v3/loans/{id}/disbursement_reports:
    post:
      operationId: createDisbursementReport
      tags:
      - Disbursements
      x-code-samples:
      - lang: Shell
        source: "curl --location --request POST \"{base_url}/loans/loan_457d2959cff448a1951c589f8c841946/disbursement_reports\" \\\r\n  --header \"X-XFERS-USER-API-KEY: {{user-api-token}}\""
      summary: Create Disbursement Report
      description: Create a disbursement report to complete a loan disbursement process. We will pass this loan asynchronously and give callback after complete
      security:
      - user-api-token: []
      parameters:
      - name: id
        in: path
        description: Loan ID. You can find this from the response when you create loan.
        required: true
        explode: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              example:
                msg: success
        4XX:
          $ref: '#/components/responses/v3Error:4XX'
  /v3/notify_disbursement_report_callback:
    post:
      operationId: disbursementReportNotification
      description: After you setup your callback url in {{base-api-url}}/merchant_settings/callback_settings (loan_disbursement_report_completed)
      summary: Disbursement Report Notification Callback
      tags:
      - Disbursements
      security: []
      servers:
      - url: http://yourserver.com
        description: This is your endpoint you set in the dashboard or notify_url
      requestBody:
        content:
          application/json:
            schema:
              properties:
                id:
                  description: the loan id as provided
                  type: string
                  format: loan_XXX
                  example: loan_dfghjkiuyfdcbnmjhgfc
                status:
                  description: the latest status after callback
                  type: string
                  enum:
                  - disbursement_report_completed
                  - disbursement_report_failed
                  example: disbursement_report_completed
                failure_reason:
                  description: failure reason as given from the bank , only exist on `disbursement_report_failed`
                  type: string
                  example: some error JSON
      responses:
        '200':
          description: Your server returns this code if it accepts the callback
  /v3/loans/{loan_id}/disbursements:
    post:
      operationId: createLoanDisbursement
      tags:
      - Disbursements
      x-code-samples:
      - lang: Shell
        source: "curl --location --request POST \"{base_url}/loans/%3Cloan_id%3E/disbursements\" \\\r\n  --header \"X-XFERS-USER-API-KEY: {{user-api-token}}\" \\\r\n  --header \"Content-Type: application/x-www-form-urlencoded\" \\\r\n  --form \"bank_account_id=12345678\" \\\r\n  --form \"amount=120000.0\" \\\r\n  --form \"idempotency_id=Order_1234\" \\\r\n  --form \"user_api_token={{user-api-token}}\""
      summary: Create Loan Disbursement
      description: 'Note: Disbursement and Withdrawal will be used synonymously. Disbursement is instantenous.

        Disbursement (Withdrawal on Behalf)

        If you wish to disburse to a bank account not belonging to you, add in user_api_token in the params.

        Disbursement (a.k.a Withdrawal) notification

        After you setup your callback url in {{base-api-url}}/merchant_settings/callback_settings, we will send you the callback with the following parameter when the withdrawal is completed or failed. You need to acknowledge the callback by responding with a HTTP 200 status when succesfully processed.

        We will send completed callback after we have confirmed with the bank that the money has been sent.'
      security:
      - user-api-token: []
      parameters:
      - name: loan_id
        in: path
        description: Loan ID. You can find this from the response when you create loan.
        required: true
        explode: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              required:
              - bank_account_id
              - amount
              - idempotency_id
              properties:
                bank_account_id:
                  type: string
                  description: ' User Bank Account id'
                amount:
                  type: string
                  description: Transaction Amount
                idempotency_id:
                  type: string
                  description: Unique ref no provided by you to prevent double transaction, this cannot be repeated, Currently only activated for Indonesia.
                user_api_token:
                  type: string
                  description: Use this param if you want to withdraw to another user’s bank account instead of your own. This is your user API token which you can retrieve from the get token API response
            examples:
              Request Body Example:
                summary: Request Body Example
                value:
                  bank_account_id: '12345678'
                  amount: '120000.0'
                  idempotency_id: Order_1234
      responses:
        '200':
          description: Success
          content:
            application/json:
              example:
                msg: success
        4XX:
          $ref: '#/components/responses/v3Error:4XX'
    get:
      operationId: listLoanDisbursement
      tags:
      - Disbursements
      x-code-samples:
      - lang: Shell
        source: "curl --location --request GET \"{base_url}/loans/%3Cloan_id%3E/disbursements\" \\\r\n  --header \"X-XFERS-USER-API-KEY: {{user-api-token}}\""
      summary: List Loan Disbursement
      description: This API will be used to get a list of the last 10 withdrawal requests associated with the loan
      security:
      - user-api-token: []
      parameters:
      - name: loan_id
        in: path
        description: Loan ID. You can find this from the response when you create loan.
        required: true
        explode: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              example:
                msg: success
        4XX:
          $ref: '#/components/responses/v3Error:4XX'
  /v3/notify_loan_disbursement_callback:
    post:
      operationId: loanDisbursementNotification
      description: This is Xfers' callback request to your server to notify loan disbursement status
      summary: Loan Disbursement Notification
      tags:
      - Disbursements
      security: []
      servers:
      - url: http://yourserver.com
        description: This is your endpoint you set in the dashboard or notify_url
      requestBody:
        content:
          application/json:
            schema:
              properties:
                id:
                  description: Xfers Generated Unique Key
                  type: string
                  example: contract_dd5a6b83
                idempotency_id:
                  description: The key you put in the withdrawal request
                  type: string
                  example: AZ0001
                type:
                  description: Status of repayment
                  type: string
                  enum:
                  - success
                  - failed
                  example: completed
                status:
                  description: Status of transaction
                  type: string
                  enum:
                  - completed
                  - failed
                  example: Sample Error Message
                amount:
                  description: Withdrawal amount
                  type: string
                  example: '125000'
                fees:
                  description: Withdrawal Fee
                  type: string
                  example: '0'
                account_no:
                  description: bank account number of withdrawal
                  type: string
                  example: 0393123432
                bank_abbrev:
                  description: bank abbreviation of withdrawal
                  type: string
                  example: BNI
                express:
                  description: Express/normal withdrawal
                  type: string
                  example: 'true'
                value_date:
                  description: Date of withdrawal completed as provided by partner bank. Will only available for `"completed"` status
                  type: string
                  example: '2019-02-15'
                failure_reason:
                  description: Reason for failure as provided by partner bank. Will only available for `"failed"` status
                  type: string
                  example: Request tidak dapat diproses - BusinessException IB-1009 (Mohon maaf transaksi tidak dapat dilakukan. Ulangi beberapa saat lagi.)
                arrival:
                  description: arrival
                  type: string
                  example: 15 Feb 2019 - 4:04 PM
                created_at:
                  description: Created at
                  type: string
                  example: '2019-02-15T16:00:02+07:00'
      responses:
        '200':
          description: Your server returns this code if it accepts the callback
  /v3/loans/{loan_id}/disbursements/{id}:
    get:
      operationId: getLoanDisbursement
      tags:
      - Disbursements
      summary: Get Loan Disbursement
      description: This API is used to get the current status of the loan disbursement (in the form of a withdrawal contract), in case the callback of the disbursement status is unclear.
      x-code-samples:
      - lang: Shell
        source: "curl --location --request POST \"{base_url}/authorize/signup_login\" \\\r\n  --header \"X-XFERS-APP-API-KEY: dS7zxQydn4PLxwNE3kuyb4pg6BsNWHE818D2wbhoavQ\" \\\r\n  --header \"Content-Type: application/json\" \\\r\n  --data \"{\\\"phone_no\\\" : \\\"+6287785725657\\\", \\\"signature\\\" : \\\"5488737c67d790565a15a2dbc3c98bf778aac2c0\\\"}\""
      security:
      - user-api-token: []
      parameters:
      - name: loan_id
        in: path
        description: Loan ID. You can find this from the response when you create loan.
        required: true
        explode: true
        schema:
          type: string
      - name: id
        in: path
        description: Disbursement ID. You can find this from the response when you create loan.
        required: true
        explode: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              example:
                msg: success
        4XX:
          $ref: '#/components/responses/v3Error:4XX'
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