FX Transactions with a single settlement

clients who wish to execute multiple fx transactions with a single consolidated settlement to a beneficiary can leverage the 'hold funds on account' feature this functionality enables automatic settlement of all associated fx transactions, streamlining them into a single payout to the designated beneficiary 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 { "rate" { "base currency" { "id" 10004, "name" "australian dollar", "currency code" "aud" }, "counter currency" { "id" 10001, "name" "us dollar", "currency code" "usd" }, "exchange rate" "0 6605", "updated date" "2025 09 18t15 31 35+10 00" } } step 2 create fx transaction to create a transaction, api requires a currency pairing with "hold funds on account" assigned as the beneficiary 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 'hold funds on account' beneficiary id of the buy currency, enter in the value date and re confirm the buy currency amount { "transaction" { // "base currency id" 10001, // provide one of base currency id or base currency code "base currency code" "aud", // provide one of base currency id or base currency code // "counter currency id" 10004, // provide one of counter currency id or counter currency code "counter currency code" "cnh", // provide one of counter currency id or counter currency code // "counter currency code" "", // provide one of counter currency id or counter currency code // "base currency amount" "1,234 56", // provide one of base currency amount or counter currency amount "counter currency amount" 123 45, // provide one of base currency amount or counter currency amount // "value date" "2025 06 03" // optional // "receipt payment mode" "electronic fund transfer", // optional, one of \[electronic fund transfer, available funds] // "receipt account id" 10001, // optional, for settling via electronic fund transfer "payments" \[ // optionally provide payment information when creating the quote // { "beneficiary id" \ beneficiary id, // "payment reference" "i 123456", // optional // "payment type" null, // optional, one of \['chaps', 'faster', 'mccy', nil] // "transaction reason id" 10341, // 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", // provide one of transaction reason id or transaction reason name "amount" 123 45 // } ] } }{ "transaction" { "id" 210893, "customer id" 12905, "user id" 13392, "status" "created", "status label" "created", "base currency" { "id" 10004, "name" "australian dollar", "currency code" "aud" }, "counter currency" { "id" 10221, "name" "chinese yuan hong kong", "currency code" "cnh" }, "base currency amount" "53 35", "counter currency amount" "250 00", "receipt amount" "53 35", "receipt account" { "id" 10040, "name" "aud account", "receipt text" "bsb 802 985\naccount number 115727675\npayid \n", "bank account" { "account number" "115727675" } }, "fees" "0 00", "payments" \[ { "id" 160217, "status" "pending", "amount" "250 00", "fee" "0 00", "beneficiary" { "id" 10034, "name" { "first name" "hold funds on account", "middle name" null, "last name" null }, "status" "approved by client", "country" { "id" 10004, "name" "australia", "country code" "aus" }, "currency" { "id" 10221, "name" "chinese yuan hong kong", "currency code" "cnh" }, "created date" "2020 12 22t12 10 45+11 00", "updated date" "2020 12 22t12 10 45+11 00" }, "payment reference" null, "payment type" null, "transaction reason" { "id" 10341, "name" "purchase of inventory" }, "created date" "2025 09 19t13 51 12+10 00", "updated date" "2025 09 19t13 51 12+10 00" } ], "exchange rate" "4 6860", "value date" "2025 09 19", "created date" "2025 09 19t13 51 08+10 00", "updated date" "2025 09 19t13 51 09+10 00" } } to obtain 'hold funds on account' id, retrieve beneficiaries docid\ b7ovvhgmmotawpdvq1rgi and enter in the currency code of your buy amount eg usd the search result will provide the id of the "hold funds on account" enter this id as the beneficiary id in the create a transaction quote curl location 'https //sand api monoova com/global/v1/beneficiaries'{ "beneficiaries" \[ { "id" 10034, //"name" { //"first name" "hold funds on account", //"middle name" null, //"last name" null }, //"status" "approved by client", //"country" { //"id" 10004, //"name" "australia", //"country code" "aus" }, //"currency" { "id" 10221, "name" "chinese yuan hong kong", "currency code" "cnh" }, "email" null, "address" { "address line 1" "receiptaccount address", "address line 2" null, "suburb" null, "city" "receiptaccount city", "province" "receiptaccount province", "postcode" "receiptaccount zip", "country code" "aus" }, "remuneration type" { "id" 4, "name" "priority", "label" "priority" }, "reason for payment" "", "relation with customer" null, "bank details" { "bank name" "receiptaccount bank name", "bank code" null, "branch code" null, "branch name" "receiptaccount branch name", "account name" null, "account number" "uat receipt account details", "local code" null, "international code" "receiptaccount swift code", "address line 1" "", "address line 2" null, "country" { "id" 10004, "name" "australia", "country code" "aus" } }, "created date" "2020 12 22t12 10 45+11 00", "updated date" "2020 12 22t12 10 45+11 00" }, once all the details are entered, a transaction quote will be generated shown in 'created' status you will find the deal "id" under transaction response { "transaction" { "id" 210893, //"customer id" 12905, //"user id" 13392, //"status" "created", //"status label" "created", //"base currency" { //"id" 10004, //"name" "australian dollar", //"currency code" "aud" }, 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' curl location g request post 'https //sand api monoova com/global/v1/transactions/{{transaction id}}/confirm'{ "transaction" { "id" 210894, "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" 10221, "name" "chinese yuan hong kong", "currency code" "cnh" }, "base currency amount" "53 45", "counter currency amount" "250 00", "receipt amount" "53 45", "receipt account" { "id" 10040, "name" "aud account", "receipt text" "bsb 802 985\naccount number 115727675\npayid \n", "bank account" { "account number" "115727675" } }, "fees" "0 00", "payments" \[ { "id" 160218, "status" "pending", "amount" "250 00", "fee" "0 00", "beneficiary" { "id" 10034, "name" { "first name" "hold funds on account", "middle name" null, "last name" null }, "status" "approved by client", "country" { "id" 10004, "name" "australia", "country code" "aus" }, "currency" { "id" 10221, "name" "chinese yuan hong kong", "currency code" "cnh" }, "created date" "2020 12 22t12 10 45+11 00", "updated date" "2020 12 22t12 10 45+11 00" }, "payment reference" null, "payment type" null, "transaction reason" { "id" 10341, "name" "purchase of inventory" }, "created date" "2025 09 19t15 58 29+10 00", "updated date" "2025 09 19t15 58 29+10 00" } ], "exchange rate" "4 6774", "value date" "2025 09 20", "created date" "2025 09 19t15 58 27+10 00", "updated date" "2025 09 19t15 58 44+10 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 curl location g request post 'https //sand api monoova com/global/v1/transactions/{{transaction id}}/confirm payments'{ "transaction" { "id" 210894, "customer id" 12905, "user id" 13392, "status" "open", "status label" "open", "base currency" { "id" 10004, "name" "australian dollar", "currency code" "aud" }, "counter currency" { "id" 10221, "name" "chinese yuan hong kong", "currency code" "cnh" }, "base currency amount" "53 45", "counter currency amount" "250 00", "receipt amount" "53 45", "receipt account" { "id" 10040, "name" "aud account", "receipt text" "bsb 802 985\naccount number 115727675\npayid \n", "bank account" { "account number" "115727675" } }, "fees" "0 00", "payments" \[ { "id" 160218, "status" "pending", "amount" "250 00", "fee" "0 00", "beneficiary" { "id" 10034, "name" { "first name" "hold funds on account", "middle name" null, "last name" null }, "status" "approved by client", "country" { "id" 10004, "name" "australia", "country code" "aus" }, "currency" { "id" 10221, "name" "chinese yuan hong kong", "currency code" "cnh" }, "created date" "2020 12 22t12 10 45+11 00", "updated date" "2020 12 22t12 10 45+11 00" }, "payment reference" null, "payment type" null, "transaction reason" { "id" 10341, "name" "purchase of inventory" }, "created date" "2025 09 19t15 58 29+10 00", "updated date" "2025 09 19t15 58 29+10 00" } ], "exchange rate" "4 6774", "value date" "2025 09 20", "created date" "2025 09 19t15 58 27+10 00", "updated date" "2025 09 19t16 44 22+10 00" } } step 4 settlement during the settlement phase, transactions can instantly settle via npp payments bank details (bsb and account number) are provided in the transaction confirmation response res //"base currency amount" "14 99", //"counter currency amount" "70 00", //"receipt amount" "14 99", //"receipt account" { //"id" 10040, //"name" "aud account", "receipt text" "bsb 802 985\naccount number 115727675\npayid \n", //"bank account" { //"account number" "115727675" } to make a payment via npp, you must include the correct sell amount and transaction id if the payment details do not exactly match the transaction information, the payment will not settle automatically and will require manual intervention, potentially causing delays it is crucial to add a 'c' in front of the deal id—for example, '210532' should be entered as 'c210532' { "transaction" { "id" 210932, //"customer id" 12905, //"user id" 13392, //"status" "open", // "status label" "open", // "base currency" { //"id" 10004, //"name" "australian dollar", //"currency code" "aud" }, //"counter currency" { //"id" 10221, //"name" "chinese yuan hong kong", //"currency code" "cnh" }, "base currency amount" "14 99", //"counter currency amount" "70 00", //"receipt amount" "14 99", //"receipt account" { //"id" 10040, //"name" "aud account", //"receipt text" "bsb 802 985\naccount number 115727675\npayid \n", //"bank account" { //"account number" "115727675" } }, to make a payment through monoova's domestic portal , the 'lodgementreference' field must include the deal id in the format cxxxxxx, and the 'amount' field must contain the correct sell amount step 5 sending payment to beneficiary you can view your buy currency balance, which will automatically update as soon as funds become available to make a payment to your beneficiary, you’ll need to initiate a withdrawal to transfer the funds to create a withdrawal from the customer's account docid\ uxmwzl rib7pkdmwadkty you will need to retrieve beneficiaries docid\ b7ovvhgmmotawpdvq1rgi stored in your account once you have selected the beneficiary, entering the desired amount to be sent note please see creating a new beneficiary sequence docid\ lamdcykd53ybb7htmbpji for adding new beneficiaries { "transaction" { "beneficiary id" "{{beneficiary id}}", //"payment reference" "test payment", // optional payment reference //"payment type" null, // optional payment type \['chaps', 'faster', 'mccy', nil] //"transaction reason id" "12357", // optional transaction reason (by id) //"transaction reason name" "investment", // optional transaction reason (by name) // "transaction reason other" "foreign investment", // optional customer transaction reason "amount" "{{amount}}" } } there are additional fields that are required based on the location of the beneficiary such as 'payment reference', retrieve a remuneration type docid 3hpglkccpbvsmfnyppc2c and retrieve transaction reasons docid\ mwyscy45cvxfgsdh7ejp2 once the withdrawal request has been created, it will need to be confirmed please confirm a withdrawal docid\ gy9433g0ydzjvmnusrvfk with the transaction id provided in the create request { "transaction" { "id" 211063, //"customer id" 12905, //"user id" 13392, //"status" "settled", //"status label" "settled", //"base currency" { //"id" 10221, //"name" "chinese yuan hong kong", //"currency code" "cnh" }, //"counter currency" { //"id" 10221, //"name" "chinese yuan hong kong", //"currency code" "cnh" }, //"base currency amount" "100 00", //"counter currency amount" "100 00", //"receipt amount" "100 00", //"receipt account" { //"id" 10029, //"name" "uat receipt account details", //"receipt text" "uat settlement text", //"bank account" null }, //"fees" "0 00", //"payments" \[ { //"id" 160332, //"status" "pending", //"amount" "100 00", //"fee" "0 00", //"beneficiary" { //"id" 24323, //"name" { //"first name" "monoova global payments pty ltd", //"middle name" null, //"last name" null }, //"status" "approved by client", //"country" { //"id" 10004, //"name" "australia", //"country code" "aus" }, //"currency" { //"id" 10221, //"name" "chinese yuan hong kong", //"currency code" "cnh" }, //"created date" "2025 07 29t14 01 27+10 00", //"updated date" "2025 07 29t14 07 00+10 00" }, //"payment reference" null, //"payment type" null, //"created date" "2025 09 26t13 42 45+10 00", //"updated date" "2025 09 26t13 42 45+10 00" } ], //"exchange rate" "1 0000", //"value date" "2025 09 26", //"created date" "2025 09 26t13 42 45+10 00", //"updated date" "2025 09 26t13 43 31+10 00" } }