Integration flow

Transfer integration can be organized into four stages: preparation, transfer submission, result retrieval, and transaction completion.

Overview

Stage 1: Preparation

Confirm beneficiary field requirements

Use one of the following methods:

• Call POST /api/v1/acct/queryPaymentFeild to retrieve the required fields
• Contact your account manager to get the required field template for the target country, currency, transfer method, and entity type

Prepare beneficiary information

After you have the field requirements, collect and validate beneficiary information according to the returned or provided template.

The key order in this stage is:

• confirm the supported transfer method for the target country and currency
• confirm the required fields for that method
• prepare beneficiary, address, and account information based on that template

If the prerequisite fields are not confirmed first, both beneficiary creation and transfer initiation can fail because of missing or invalid data.

Stage 2: Submit the transfer

Decide which submission path to use

• if the real-time path has been enabled, you can submit beneficiary information and initiate the transfer in one request
• if it has not been enabled, you must maintain the beneficiary first and then initiate the transfer by beneficiaryId

Default path

1. Create a beneficiary ID

• Enter or import beneficiary information
• Call POST /api/v1/beneficiary/add
• Store the returned beneficiaryId

This is the starting point of the default path. In other words, the default path is not "fill and pay immediately". It first turns beneficiary data into a reusable record.

2. Beneficiary reuse logic

• Check whether the existing beneficiaryId can still be reused
• If the information is unchanged, keep using the existing beneficiaryId
• If the beneficiary information is inconsistent, call POST /api/v1/beneficiary/edit first and then continue using the existing beneficiaryId

Do not recreate a new beneficiary for every transfer when the existing record is still valid. Reuse first, update only when the information has changed.

3. Initiate the transfer request

• Call POST /api/v1/txn/remittance
• The transaction enters Onerway transfer processing

After this step, the transaction enters processing. A successful synchronous response only means the request has been accepted, not that the final transfer result has been confirmed.

Real-time path

1. Submit beneficiary information dynamically

• Call POST /api/v2/txn/remittance
• Put beneficiary information directly in the request body
• No pre-created beneficiaryId is required

2. Initiate the transfer

• Submit the request
• The transaction enters transfer processing directly

Compared with the default path, the real-time path removes the pre-created beneficiary step. This path has to be enabled in advance and should not be assumed to be available by default.

Stage 3: Retrieve the result

You can retrieve transfer results in two ways:

1. Active query through POST /api/v1/txn/query
2. Asynchronous notification through webhook callbacks

Result retrieval methods

Result retrieval is separated into two lines:

• active query for fallback confirmation, reconciliation, or investigation
• asynchronous callbacks as the main production result channel

Callback payload usually includes

• transaction status
• failure code when the transfer fails
• failure description when the transfer fails

This is why a successful synchronous response is not the end of the workflow.

Stage 4: Complete the transaction

Successful transfer

• Call POST /api/v1/txn/queryVoucher to retrieve the voucher

Unsuccessful transfer

• Query the failure reason
• Continue with manual handling or retry based on your internal process

The focus of this stage is straightforward:

• successful transfers move into voucher retrieval and reconciliation
• unsuccessful transfers move into retry or manual handling based on the reason
• the transaction flow is only truly closed after the result is confirmed and the follow-up action is completed

Recommended operating model

Use this operating model in production:

• use webhook callbacks as the primary result channel
• keep the query APIs for reconciliation, retry handling, and fallback checks
• reuse existing beneficiary records when the information is still valid

Notes

• If the real-time path is not enabled, use the default path first instead of submitting a real-time request directly
• In the default path, store beneficiaryId properly to avoid duplicate beneficiary creation
• Even after a transfer request is accepted, confirm the final status through webhooks or query APIs
• If you need proof of payment after success, continue with the voucher API

Continue Reading

• Setup
• Request signing
• Testing and go-live