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 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 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 request { "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 docid\ ymrotswke izd73gjvpn7 the search result will provide a list of sub customers associated to your account enter "sub customers id" in the docid\ wmcpwdrontdls d6uwgwq request response { "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 docid\ y5u00ny24gpovdy hxi6q attaching a beneficiary to obtain a beneficiary id, 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 docid\ wmcpwdrontdls d6uwgwq response { "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" response { "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 docid\ q3u5vkm8sgchudeuaks46 it will require "transaction id" and placed in the call sequence the transaction status will change from 'created' to 'pending payment' response { "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 ( 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 response { "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 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" } }