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 Charge 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: Charge
description: API for Charges
paths:
/v3/charges:
post:
operationId: createCharge
x-code-samples:
- lang: Shell
source: "curl --location --request POST \"$BASE_URL/v3/charges\" \\\r\n --header \"X-XFERS-USER-API-KEY: $CUSTOMER_API_KEY\" \\\r\n --header \"Content-Type: application/json\" \\\r\n --form \"amount=10000\" \\\r\n --form \"order_id=Order_docs_12345\" \\\r\n --form \"description=Testing for Documentation\" \\\r\n --form \"notify_url=https://www.example.com/updates\" \\\r\n --form \"meta_data=test metadata\""
tags:
- Charge
summary: Create Charge
description: The following API will allow you to move money from user's account to merchant's account.
security:
- X-XFERS-USER-API-KEY: []
requestBody:
required: true
content:
application/json:
schema:
properties:
amount:
type: number
format: float
description: Transaction Amount.
order_id:
type: string
description: Unique ref no provided by you to prevent double charging, this cannot be repeated.
description:
type: string
description: Testing for Documentation.
meta_data:
type: string
description: A set of key/value pairs that you can attach to a charge. It can be useful for storing additional information about the customer in a structured format.
currency:
type: string
description: 3-letter ISO code for currency
customer:
type: string
description: Customer email or phone number. If provided, only that user can use the checkout_url returned. If the customer does not exist, an account will be created for them using the email/phone number provided. An OTP will be sent to the email/phone for the user to log in.
return_url:
type: string
description: URL Xfers will redirect customer to on completion of Xfers checkout.
debit_only:
type: boolean
description: When this is true, this charge will attempt to debit from users existing balance/card on file. Status returned will be “completed” on successful debit or “cancelled” when there insufficient funds / valid card on file in user wallet.
card_only:
type: string
x-custom-params:
- Singapore
description: When this is true, this charge will will attempt to take payments via credit/debit card.
redirect:
type: string
x-custom-params:
- Singapore
description: When this is true, instead of the JSON response, Xfers will automatically redirect the request to our checkout page
cancel_url:
type: string
x-custom-params:
- Singapore
description: URL Xfers will redirect customer to on cancellation of Xfers checkout.
google_auth:
type: string
deprecated: true
description: When this is true and user_phone_no is provided, instead of phone SMS OTP, user can use Google Authenticator to do OTP. See Authorize a Charge
receipt_email:
type: string
deprecated: true
description: The email address to send this charge’s receipt.
skip_notifications:
type: string
deprecated: true
description: Setting this to true will not send transaction reminders/cancelled/expired emails/SMS. Users will still receive payment completed notification.
required:
- amount
- order_id
- currency
x-custom-params-requirements:
Indonesia:
- user_api_token
Singapore:
- currency
examples:
Request Body Example:
summary: Request Body Example
value:
amount: 10000
order_id: Order_docs_12345
description: Testing for Documentation
notify_url: https://www.example.com/updates
meta_data: test metadata
responses:
'200':
description: Success
content:
application/json:
example:
id: contract_7abf6bb130d44c02862982ff6022875d
object: Sobatku::TransferContract
status: processing
amount: '10000.0'
total_amount: '10000.0'
currency: idr
fee_amount: '100.0'
notify_url: https://www.example.com/updates
wallet_name: General Wallet
order_id: Order_docs_12345
description: Testing for Documentation
receipt_email: winston@xfers.com
metadata:
callback_url: https://www.example.com/updates
merchant_metadata: test metadata
4XX:
$ref: '#/components/responses/v3Error:4XX'
get:
operationId: listCharge
x-code-samples:
- lang: Shell
source: "curl \"$BASE_URL/v3/charges?limit=1\" \\\r\n -H \"X-XFERS-USER-API-KEY: $CUSTOMER_API_KEY\""
tags:
- Charge
summary: List all Charge
description: Returns a list of charges you’ve previously created. The charges are returned in sorted order, with the most recent charges appearing first.
security:
- X-XFERS-USER-API-KEY: []
responses:
'200':
description: Success
content:
application/json:
example:
- id: contract_b840cc9fc5a359c22ed2ccef3427aacd
object: TransferContract
checkout_url: https://sandbox.xfers.io/checkout_transaction/b840cc9fc5a359c22ed2ccef3427aacd
notify_url: https://mysite.com/payment_notification
return_url: https://mysite.com/return
cancel_url: https://mysite.com/cancel
amount: '9.99'
currency: SGD
order_id: A012312
description: Carousell user - Konsolidate
receipt_email: ''
total_amount: '12.49'
fee_amount: '0.12'
status: completed
metadata:
firstname: Tianwei
lastname: Liu
transfer_info:
bank_name_full: United Overseas Bank
bank_name_abbreviation: UOB
bank_account_no: '123456789'
bank_code: '7375'
swift_code: UOVBSGSGXXX
unique_id: '89898989'
outstanding_amount: '0'
4XX:
$ref: '#/components/responses/v3Error:4XX'
/v3/charges/{id}/authorize:
post:
operationId: authorizeCharge
x-code-samples:
- lang: Shell
source: "curl \"$BASE_URL/v3/charges/<id>/authorize\" \\\r\n -H \"X-XFERS-USER-API-KEY: $CUSTOMER_API_KEY\" \\\r\n -H \"Content-Type: application/json\" \\\r\n -d '{\"auth_code\": \"512312\"}'"
tags:
- Charge
summary: Authorize Charge
description: "Authorize a previously created charge. This is an optional process that will allow buyer to skip the sign in flow on Xfers, allowing checkout to be completed on merchant site. If a correct auth_code is provided, the charge will immediately become “accepted” by the buyer.\r\n\r\nThis endpoint is only used if `user_phone_no` param was passed in during charge creation. The response will return the `transfer_info` object containing information the bank the user should transfer to. If multiple banks are available, the `transfer_info_array` will also be returned."
security:
- X-XFERS-USER-API-KEY: []
parameters:
- name: id
in: path
description: Charge ID that could be retrieved from the response in Create Charge endpoint
required: true
explode: true
schema:
type: string
example: contract_7abf6bb130d44c02862982ff6022875d
requestBody:
description: Either `auth_code` or `google_auth_code` required
required: true
content:
application/json:
schema:
required:
- auth_code
- google_auth_code
properties:
auth_code:
type: string
description: Either auth_code or google_auth_code required. SMS OTP code provided to the buyer.
google_auth_code:
type: string
description: Google Auth OTP code provided to the buyer. If google_auth_enabled of Get Account Info is false, user has not enabled Google Auth with Xfers. Direct users to Xfers 2FA setup page
responses:
'200':
description: Success
content:
application/json:
example:
value:
id: contract_b840cc9fc5a359c22ed2ccef3427aacd
object: TransferContract
checkout_url: https://sandbox.xfers.io/checkout_transaction/b840cc9fc5a359c22ed2ccef3427aacd
notify_url: https://mysite.com/payment_notification
return_url: https://mysite.com/return
cancel_url: https://mysite.com/cancel
amount: '9.99'
currency: SGD
order_id: A012312
description: Carousell user - Konsolidate
receipt_email: ''
total_amount: '12.49'
fee_amount: '0.12'
status: accepted
metadata:
firstname: Tianwei
lastname: Liu
transfer_info:
bank_name_full: United Overseas Bank
bank_name_abbreviation: UOB
bank_account_no: '123456789'
bank_code: '7375'
swift_code: UOVBSGSGXXX
unique_id: '89898989'
outstanding_amount: '0'
4XX:
$ref: '#/components/responses/v3Error:4XX'
/v3/charges/{id}/cancel:
post:
operationId: cancelCharge
x-code-samples:
- lang: Shell
source: "curl \"$BASE_URL/v3/charges/<CHARGE_ID>/cancel\" \\\r\n -H \"X-XFERS-USER-API-KEY: $CUSTOMER_API_KEY\"\r\n -X POST"
tags:
- Charge
summary: Cancel Charge
description: Cancelling a charge that has been previously created by not yet paid. To refund a paid charge, refer to creating a refund.
security:
- X-XFERS-USER-API-KEY: []
parameters:
- name: id
in: path
description: Charge ID that could be retrieved from the response in Create Charge endpoint
required: true
explode: true
schema:
type: string
example: contract_7abf6bb130d44c02862982ff6022875d
responses:
'200':
description: Success
content:
application/json:
example:
value:
id: contract_b840cc9fc5a359c22ed2ccef3427aacd
object: PendingTransferContract
checkout_url: https://sandbox.xfers.io/checkout_transaction/b840cc9fc5a359c22ed2ccef3427aacd
notify_url: https://mysite.com/payment_notification
return_url: https://mysite.com/return
cancel_url: https://mysite.com/cancel
amount: '9.99'
currency: SGD
order_id: A012312
description: Carousell user - Konsolidate
receipt_email: ''
total_amount: '12.49'
fee_amount: '0.12'
status: cancelled
metadata:
firstname: Tianwei
lastname: Liu
transfer_info:
bank_name_full: United Overseas Bank
bank_name_abbreviation: UOB
bank_account_no: '123456789'
bank_code: '7375'
swift_code: UOVBSGSGXXX
unique_id: '89898989'
outstanding_amount: '0'
4XX:
$ref: '#/components/responses/v3Error:4XX'
/v3/charges/{id}:
get:
operationId: getCharge
x-code-samples:
- lang: Shell
source: "curl --location --request GET \"$BASE_URL/v3/charges/contract_7abf6bb130d44c02862982ff6022875d\" \\\r\n --header \"X-XFERS-USER-API-KEY: {{user-api-key}}\""
tags:
- Charge
summary: Get Charge
description: 'Retrieves the details of a charge that has previously been created.
Supply the ID that was returned from your previous request, and Xfers will return the corresponding charge information.'
security:
- X-XFERS-USER-API-KEY: []
parameters:
- name: id
in: path
description: Charge ID that could be retrieved from the response in Create Charge endpoint
required: true
explode: true
schema:
type: string
example: contract_7abf6bb130d44c02862982ff6022875d
responses:
'200':
description: Success
content:
application/json:
example:
summary: Missing API KEY in header
value:
id: contract_7abf6bb130d44c02862982ff6022875d
object: Sobatku::TransferContract
status: completed
amount: '10000.0'
total_amount: '10000.0'
currency: idr
fee_amount: '100.0'
notify_url: https://www.example.com/updates
wallet_name: General Wallet
order_id: Order_docs_12345
description: Testing for Documentation
receipt_email: winston@xfers.com
metadata:
callback_url: https://www.example.com/updates
merchant_metadata: test metadata
4XX:
$ref: '#/components/responses/v3Error:4XX'
/v3/charges/{id}/refunds:
post:
operationId: refundCharge
x-code-samples:
- lang: Shell
source: "curl --location --request POST \"$BASE_URL/v3/charges/%3Cid%3E/refunds\" \\\r\n --header \"X-XFERS-USER-API-KEY: {{user-api-key}}\" \\\r\n --data \"\""
tags:
- Charge
summary: Refund Charge
description: 'This API will refund a charge.
Both funds and fees in this transaction will be refunded to the user''s Xfers account.
Please use the merchant’s API key for this endpoint'
security:
- X-XFERS-USER-API-KEY: []
parameters:
- $ref: '#/components/securitySchemes/X-XFERS-USER-API-KEY'
- name: id
in: path
description: Charge ID that could be retrieved from the response in Create Charge endpoint
required: true
explode: true
schema:
type: string
example: contract_7abf6bb130d44c02862982ff6022875d
responses:
'200':
description: Success
content:
application/json:
example:
value:
id: contract_7abf6bb130d44c02862982ff6022875d
object: Sobatku::TransferContract
status: completed
amount: '10000.0'
total_amount: '10000.0'
currency: idr
fee_amount: '100.0'
notify_url: https://www.example.com/updates
wallet_name: General Wallet
order_id: Order_docs_12345
description: Testing for Documentation
receipt_email: winston@xfers.com
metadata:
callback_url: https://www.example.com/updates
merchant_metadata: test metadata
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
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)
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'
# --- truncated at 32 KB (33 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/xfers/refs/heads/main/openapi/xfers-charge-api-openapi.yml