OpenAPI Specification
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 Withdraw 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: Withdraw
description: API for Withdrawal
paths:
/v3/user/bank_account/{bank_account_id}/withdraw:
post:
operationId: createWithdrawal
x-code-samples:
- lang: Shell
source: "curl --location --request POST \"$BASE_URL/v3/user/bank_account/175/withdraw\" \\\r\n --header \"X-XFERS-USER-API-KEY: $CUSTOMER_API_KEY\" \\\r\n --header \"Content-Type: application/json\" \\\r\n --data \"{\\\"amount\\\": \\\"120000.0\\\"}\""
tags:
- Withdraw
summary: Create Withdrawal
description: "Withdrawal Time varies upon country. \r\nFor Indonesia, withdrawal time is instantaneous.\r\nFor Singapore, withdrawal time depends on whether it is an express withdrawal.\r\n\r\n#### Withdrawal on Behalf\r\nIf you wish to withdraw to a bank account that does not belong to you, add in user_api_token in the params.\r\n\r\nBehind the scenes, Xfers does a payout of funds from your Xfers account to that user’s Xfers account, followed by a withdrawal. This is required for compliance purposes as we cannot directly withdraw funds to a bank account that does not belong to you.\r\n\r\nTo clarify this:\r\n\r\nPlacing of xfers_api_token | Flow | Remark\r\n--------------- | ----------- | -----\r\nmerchant's token in header, user's token in body| merchant's Xfers account -> user's Xfers account -> user's bank Account | We call this `Withdrawal on Behalf`\r\nuser's token in header, nothing in body| user's Xfers account -> user's bank Account | This is the standard Withdrawal usage\r\nmerchant's token in header, nothing in body| merchant's Xfers account -> merchant's bank Account | This is usually done via Xfers Dashboard\r\n"
security:
- X-XFERS-USER-API-KEY: []
parameters:
- name: bank_account_id
in: path
description: The ID of the bank account. You can retrieve this from in the response of Create Bank Account and List Bank Account API
required: true
explode: true
schema:
type: string
example: '175'
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
required:
- amount
- idempotency_id
properties:
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
express:
type: boolean
default: false
description: 'Only Singapore.
Express Withdrawal has fees but will arrive at recipient bank within 24 hrs.
Standard withdrawal is free but takes 2-3 business day to arrive at recipient bank.
Defaults to false'
user_api_token:
type: string
description: Use this param if you want to withdraw to another user’s bank account instead of your own.
examples:
Request Body Example:
summary: Request Body Example
value:
amount: '1200000'
idempotency_id: Order_1234
responses:
'200':
description: Success
content:
application/json:
example:
available_balance: 68596
ledger_balance: 68596
withdrawal_request:
id: contract_d3b5b84ba7814eb28ed4f9845d65e53a
idempotency_id: Order_12346
type: Sobatku/withdrawal
status: pending
amount: '110000.0'
fees: '0.0'
account_no: '1680366060'
bank_abbrev: BCA
express: true
value_date: null
failure_reason: null
created_at: '2018-12-05T11:15:37+07:00'
4XX:
$ref: '#/components/responses/v3Error:4XX'
/v3/user/bank_account/withdrawal_requests:
get:
operationId: listWithdrawalRequests
x-code-samples:
- lang: Shell
source: "curl --location --request GET \"$BASE_URL/v3/user/bank_account/withdrawal_requests/contract_51005437f4734be5b7e3a548b4fa7d0e\" \\\r\n --header \"X-XFERS-USER-API-KEY: $CUSTOMER_API_KEY\""
tags:
- Withdraw
summary: List Withdrawal Requests
description: This API will be used to get a list of the last 10 withdrawal requests.
security:
- X-XFERS-USER-API-KEY: []
responses:
'200':
description: Success
content:
application/json:
example:
id: contract_51005437f4734be5b7e3a548b4fa7d0e
idempotency_id: Order_1234
type: Sobatku/withdrawal on behalf
status: pending
amount: '120000.0'
fees: '0.0'
account_no: '1680366060'
bank_abbrev: BCA
express: true
value_date: null
failure_reason: null
created_at: '2018-11-06T10:43:29+07:00'
4XX:
$ref: '#/components/responses/v3Error:4XX'
/v3/notify_withdrawal_callback:
post:
operationId: withdrawalNotificationCallback
description: This is Xfers' callback request to your server to notify withdrawl status
summary: Withdrawal Notification Callback
tags:
- Withdraw
security: []
servers:
- url: https://yourserver.com
description: This is your endpoint you set in the dashboard or notify_url
requestBody:
content:
application/json:
schema:
properties:
account_no:
description: bank account no of withdrawal
type: string
example: 0393123432
amount:
description: withdrawal amount
type: string
example: '125000'
bank_abbrev:
description: bank abbreviation of withdrawal
type: string
example: DBS
fees:
description: Withdrawal Fee
type: string
example: '0'
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
status:
description: Status of transaction
type: string
enum:
- completed
- failed
example: completed
value_date:
format: YYYY-MM-DD
description: Date of withdrawal completed as provided by partner bank. will only available for "completed" status
type: string
example: '2018-09-12'
failure_reason:
description: Reason of failed. Will only available for "failed" status
type: string
example: Sample Error Message - Request cannot be processed
express:
description: Express/normal withdrawal
type: string
example: 'true'
responses:
'200':
description: Your server returns this code if it accepts the callback
/v3/user/bank_account/withdrawal_requests/{withdrawal_request_id}:
get:
operationId: getWithdrawal
x-code-samples:
- lang: Shell
source: "curl --location --request GET \"$BASE_URL/v3/user/bank_account/withdrawal_requests/contract_51005437f4734be5b7e3a548b4fa7d0e\" \\\r\n --header \"X-XFERS-USER-API-KEY: $CUSTOMER_API_KEY\""
tags:
- Withdraw
summary: Get Withdrawal Request
description: 'This API will be used to get the current status of withdrawal request.
It is useful if you want to check with Xfers again about the status of your withdrawal request in case there is something wrong with the callback of the withdrawal request status.'
security:
- X-XFERS-USER-API-KEY: []
parameters:
- name: withdrawal_request_id
in: path
description: 'The ID of the withdrawal you want to get information of. You can retrieve this information from the '
required: true
explode: true
schema:
type: string
example: '175'
responses:
'200':
description: Success
content:
application/json:
example:
id: contract_51005437f4734be5b7e3a548b4fa7d0e
idempotency_id: Order_1234
type: Sobatku/withdrawal on behalf
status: pending
amount: '120000.0'
fees: '0.0'
account_no: '1680366060'
bank_abbrev: BCA
express: true
value_date: null
failure_reason: null
created_at: '2018-11-06T10:43:29+07:00'
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