FX Transaction with Beneficiary payout (1:1 Sequence)
To book a FX Transaction with an existing beneficiary
For clients who already have existing beneficiary stored in their account.
Step 1. Retrieve FX Rate.
This will display the rate of the chosen currency pairing.
- Set up Retrieve an FX rate. and enter in the currency pairing (base and counter) with counter currency amount.

Step 2. Create FX Transaction.
To create a transaction, API requires a currency pairing with at least 1 beneficiary assigned.
- Create a transaction quote. by entering the currency pair (sell currency and buy currency) along with the buy currency amount. In the same sequence, include the beneficiary ID of the buy currency, enter in the value date and re-confirm the buy currency amount.
{
"transaction": {
"base_currency_code": "{{base_currency_code}}",
"counter_currency_code": "{{counter_currency_code}}",
"counter_currency_amount": "{{counter_currency_amount}}",
"value_date": "{{value_date}}", // Optional
"rate_id": "{{rate_id}}", //Optional
"payments": [
{
"beneficiary_id": "{{beneficiary_id}}",
"payment_reference": "I-123456", // Optional
"transaction_reason_id": 10451, // Provide one of transaction_reason_id or transaction_reason_name
"transaction_reason_name": "Purchase of Inventory", // Provide one of transaction_reason_id or transaction_reason_name
"transaction_reason_other": "Something else",
"amount": "{{counter_currency_amount}}",
"sub_customer_ids": [{{sub_customer}}] //Optional
}
]
}
}
Attaching a sub-customer (Optional)
To obtain an existing sub-customer, first Retrieve sub-customers. The search result will provide a list of sub-customers associated to your account. Enter "sub_customers.id" in the Create a transaction quote. request.
{
"sub_customers": [
{
"id": 10220,
"status": "active",
"gender": null,
"birth_date": null,
"company_name": "Lemons",
"registration_number": "12345567",
"account_type": {
"id": 10000,
"name": "Company"
},
"name": {
"first_name": "Test",
"middle_name": "lemon",
"last_name": "Tree"
},
"country": {
"id": 10004,
"name": "Australia",
"country_code": "AUS"
},
"address": {
"address_line_1": "123 Test Street",
"address_line_2": null,
"suburb": "Kensley",
"city": null,
"province": "NSW",
"postcode": "2034",
"country_code": "AUS"
},
"created_date": "2026-03-12T14:29:41+11:00",
"updated_date": "2026-03-12T14:29:41+11:00"
},To add a sub-customer in the same step as creating a transaction, please refer to Adding sub customer details to FX Transaction

Attaching a beneficiary
- To obtain a beneficiary ID, Retrieve beneficiaries. and enter in the currency code of your buy amount eg USD. The search result will provide a list of beneficiaries associated to the currency code. Enter "beneficiaries.id" in the Create a transaction quote.
{
"beneficiaries": [
{
"id": 24368,
"name": {
"first_name": "Leo US",
"middle_name": null,
"last_name": "Test"
},
"status": "approved_by_client",
"country": {
"id": 10131,
"name": "United States",
"country_code": "USA"
},
"currency": {
"id": 10001,
"name": "US Dollar",
"currency_code": "USD"
},
"account_type": {
"id": 10001,
"name": "Individual"
},
"mobile": {
"isd": "{{beneficiary_mobile_isd_code}}",
"number": "5555551234"
},
"email": null,
"address": {
"address_line_1": "123 Test street",
"address_line_2": "",
"suburb": "null",
"city": "New york",
"province": "America",
"postcode": "07008",
"country_code": "USA"
},
"remuneration_type": {
"id": 3,
"name": "local",
"label": "Local"
},
"reason_for_payment": "test",
"relation_with_customer": "friend Testing",
"bank_details": {
"bank_name": "Testing Bank",
"bank_code": null,
"branch_code": null,
"branch_name": "Test Branch",
"account_name": null,
"account_number": "GB83CLRB04056810006132",
"local_code": null,
"international_code": "BOFAUS3NXXX",
"address_line_1": "123 Test street",
"address_line_2": null,
"country": {
"id": 10131,
"name": "United States",
"country_code": "USA"
}
},
"created_date": "2025-08-13T14:19:30+10:00",
"updated_date": "2025-08-13T14:19:30+10:00"
}
],- Once all the details are entered, a transaction quote will be generated shown in 'created' status. You will find the "transaction.id"
{
"transaction": {
"id": 213935,
"customer_id": 12905,
"user_id": 13392,
"status": "created",
"status_label": "Created",
"base_currency": {
"id": 10004,
"name": "Australian Dollar",
"currency_code": "AUD"
},
"counter_currency": {
"id": 10001,
"name": "US Dollar",
"currency_code": "USD"
},
"base_currency_amount": "179.31",
"counter_currency_amount": "123.00",
"receipt_amount": "199.28",
"receipt_account": {
"id": 10040,
"name": "AUD Account",
"receipt_text": "BSB: 802-985\nAccount Number: 115727675\nPayID: \n",
"bank_account": {
"account_number": "115727675"
}
},
"fees": "20.00",
"payments": [
{
"id": 162232,
"status": "pending",
"amount": "123.00",
"fee": "20.00",
"beneficiary": {
"id": 24368,
"name": {
"first_name": "Leo US",
"middle_name": null,
"last_name": "Test"
},
"status": "approved_by_client",
"country": {
"id": 10131,
"name": "United States",
"country_code": "USA"
},
"currency": {
"id": 10001,
"name": "US Dollar",
"currency_code": "USD"
},
"created_date": "2025-08-13T14:19:30+10:00",
"updated_date": "2025-08-13T14:19:30+10:00"
},
"payment_reference": null,
"payment_type": null,
"transaction_reason": {
"id": 10451,
"name": "Goods Trade"
},
"sub_customers": [
{
"id": 10220,
"status": "active",
"gender": null,
"birth_date": null,
"company_name": "Lemons",
"registration_number": "12345567",
"account_type": {
"id": 10000,
"name": "Company"
},
"name": {
"first_name": "Test",
"middle_name": "lemon",
"last_name": "Tree"
},
"country": {
"id": 10004,
"name": "Australia",
"country_code": "AUS"
}
}
],
"created_date": "2026-03-24T15:04:10+11:00",
"updated_date": "2026-03-24T15:04:10+11:00"
}
],
"exchange_rate": "0.6860",
"value_date": "2026-03-24",
"created_date": "2026-03-24T15:04:09+11:00",
"updated_date": "2026-03-24T15:04:12+11:00"
}
}
Step 3. Confirm FX Transaction
All transactions marked as 'created' will need to be confirmed. Once confirmed, the transaction becomes a binding payment agreement.
- To Confirm a transaction quote. it will require "transaction.id" and placed in the call sequence. The transaction status will change from 'created' to 'pending payment'.
{
"transaction": {
"id": 213935,
"customer_id": 12905,
"user_id": 13392,
"status": "pending_payment",
"status_label": "Pending Payment",
"base_currency": {
"id": 10004,
"name": "Australian Dollar",
"currency_code": "AUD"
},
"counter_currency": {
"id": 10001,
"name": "US Dollar",
"currency_code": "USD"
},
"base_currency_amount": "179.24",
"counter_currency_amount": "123.00",
"receipt_amount": "199.24",
"receipt_account": {
"id": 10040,
"name": "AUD Account",
"receipt_text": "BSB: 802-985\nAccount Number: 115727675\nPayID: \n",
"bank_account": {
"account_number": "115727675"
}
},
"fees": "20.00",
"payments": [
{
"id": 162232,
"status": "pending",
"amount": "123.00",
"fee": "20.00",
"beneficiary": {
"id": 24368,
"name": {
"first_name": "Leo US",
"middle_name": null,
"last_name": "Test"
},
"status": "approved_by_client",
"country": {
"id": 10131,
"name": "United States",
"country_code": "USA"
},
"currency": {
"id": 10001,
"name": "US Dollar",
"currency_code": "USD"
},
"created_date": "2025-08-13T14:19:30+10:00",
"updated_date": "2025-08-13T14:19:30+10:00"
},
"payment_reference": null,
"payment_type": null,
"transaction_reason": {
"id": 10451,
"name": "Goods Trade"
},
"sub_customers": [
{
"id": 10220,
"status": "active",
"gender": null,
"birth_date": null,
"company_name": "Lemons",
"registration_number": "12345567",
"account_type": {
"id": 10000,
"name": "Company"
},
"name": {
"first_name": "Test",
"middle_name": "lemon",
"last_name": "Tree"
},
"country": {
"id": 10004,
"name": "Australia",
"country_code": "AUS"
}
}
],
"created_date": "2026-03-24T15:04:10+11:00",
"updated_date": "2026-03-24T15:04:10+11:00"
}
],
"exchange_rate": "0.6862",
"value_date": "2026-03-24",
"created_date": "2026-03-24T15:04:09+11:00",
"updated_date": "2026-03-24T15:11:05+11:00"
}
}- After confirming the transaction, it must be verified that all payments are fully allocated to it (Confirm that the payments are fully allocated to a transaction.). This ensures that the total buy currency amount is completely covered by the payments. Once this step is completed, payments can no longer be edited, and the transaction details are finalised. At this point, the "transaction.status" will change from 'pending payment' to 'open', indicating that it is now awaiting payment.
{
"transaction": {
"id": 213935,
"customer_id": 12905,
"user_id": 13392,
"status": "open",
"status_label": "Open",
"base_currency": {
"id": 10004,
"name": "Australian Dollar",
"currency_code": "AUD"
},
"counter_currency": {
"id": 10001,
"name": "US Dollar",
"currency_code": "USD"
},
"base_currency_amount": "179.24",
"counter_currency_amount": "123.00",
"receipt_amount": "199.24",
"receipt_account": {
"id": 10040,
"name": "AUD Account",
"receipt_text": "BSB: 802-985\nAccount Number: 115727675\nPayID: \n",
"bank_account": {
"account_number": "115727675"
}
},
"fees": "20.00",
"payments": [
{
"id": 162232,
"status": "pending",
"amount": "123.00",
"fee": "20.00",
"beneficiary": {
"id": 24368,
"name": {
"first_name": "Leo US",
"middle_name": null,
"last_name": "Test"
},
"status": "approved_by_client",
"country": {
"id": 10131,
"name": "United States",
"country_code": "USA"
},
"currency": {
"id": 10001,
"name": "US Dollar",
"currency_code": "USD"
},
"created_date": "2025-08-13T14:19:30+10:00",
"updated_date": "2025-08-13T14:19:30+10:00"
},
"payment_reference": null,
"payment_type": null,
"transaction_reason": {
"id": 10451,
"name": "Goods Trade"
},
"sub_customers": [
{
"id": 10220,
"status": "active",
"gender": null,
"birth_date": null,
"company_name": "Lemons",
"registration_number": "12345567",
"account_type": {
"id": 10000,
"name": "Company"
},
"name": {
"first_name": "Test",
"middle_name": "lemon",
"last_name": "Tree"
},
"country": {
"id": 10004,
"name": "Australia",
"country_code": "AUS"
}
}
],
"created_date": "2026-03-24T15:04:10+11:00",
"updated_date": "2026-03-24T15:21:47+11:00"
}
],
"exchange_rate": "0.6862",
"value_date": "2026-03-24",
"created_date": "2026-03-24T15:04:09+11:00",
"updated_date": "2026-03-24T15:21:45+11:00"
}
}
Step 4. Settlement
Bank details "transaction.receipt_account.receipt_text" (BSB and Account Number) are provided in the transaction confirmation response.
{
"transaction": {
"id": 214065,
"customer_id": 12905,
"user_id": 13392,
"status": "open",
"status_label": "Open",
"base_currency": {
"id": 10004,
"name": "Australian Dollar",
"currency_code": "AUD"
},
"counter_currency": {
"id": 10001,
"name": "US Dollar",
"currency_code": "USD"
},
"base_currency_amount": "22.04",
"counter_currency_amount": "15.00",
"receipt_amount": "52.04",
"receipt_account": {
"id": 10040,
"name": "AUD Account",
"receipt_text": "BSB: 802-985\nAccount Number: 115727675\nPayID: \n",
"bank_account": {
"account_number": "115727675"
}
},
"fees": "30.00",
"payments": [
{
"id": 162318,
"status": "pending",
"amount": "15.00",
"fee": "30.00",
"beneficiary": {
"id": 24567,
"name": {
"first_name": "Peter",
"middle_name": null,
"last_name": "Rabbit"
},
"status": "approved_by_client",
"country": {
"id": 10131,
"name": "United States",
"country_code": "USA"
},
"currency": {
"id": 10001,
"name": "US Dollar",
"currency_code": "USD"
},
"created_date": "2025-11-06T11:22:38+11:00",
"updated_date": "2025-11-06T11:22:38+11:00"
},
"payment_reference": null,
"payment_type": null,
"transaction_reason": {
"id": 10451,
"name": "Goods Trade"
},
"sub_customers": [
{
"id": 10263,
"status": "active",
"gender": null,
"birth_date": null,
"company_name": "Jenny Co",
"registration_number": "23465",
"account_type": {
"id": 10001,
"name": "Individual"
},
"name": {
"first_name": "Jenny",
"middle_name": null,
"last_name": "Smith"
},
"country": {
"id": 10004,
"name": "Australia",
"country_code": "AUS"
}
}
],
"created_date": "2026-03-27T14:23:08+11:00",
"updated_date": "2026-03-27T16:01:50+11:00"
}
],
"exchange_rate": "0.6806",
"value_date": "2026-03-27",
"created_date": "2026-03-27T14:23:03+11:00",
"updated_date": "2026-03-27T16:01:46+11:00"
}
}