--- title: FX Transaction with Beneficiary payout (1:1 Sequence) slug: fx/fx-transaction-with-beneficiary-payout-11-sequence docTags: createdAt: 2025-05-12T05:26:14.977Z --- ### ***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.](docId:9sFmgJ-9ap3lYzBCyc40J) 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.](docId\:wmCPWDROnTDls-D6UwGWQ) 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. :::CodeblockTabs Request ```json { "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.](docId\:yMRotswkE_IZd73GJVPn7) The search result will provide a list of sub-customers associated to your account. Enter `"sub_customers.id"` in the [Create a transaction quote.](docId\:wmCPWDROnTDls-D6UwGWQ) request. :::CodeblockTabs Response ```json { "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](docId\:Y5u00Ny24GpovdY-HXi6q) *** ***Attaching a beneficiary*** - To obtain a beneficiary ID, [Retrieve beneficiaries.](docId\:B7OvVHGMMOtAwPDvQ1Rgi) 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.](docId\:wmCPWDROnTDls-D6UwGWQ) :::CodeblockTabs Response ```json { "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"` :::CodeblockTabs Response ```json { "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.](docId\:Q3U5VKM8sGcHUDeuaKS46) it will require `"transaction.id"` and placed in the call sequence. The transaction status will change from 'created' to 'pending payment'. :::CodeblockTabs Response ```json { "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.](docId\:z-Z8bXiAlWhRa-Qi5ATqa)). 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. :::CodeblockTabs Response ```json { "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. :::CodeblockTabs Response ```json { "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" } } ``` :::