--- title: Definitions slug: fx/definitions docTags: createdAt: 2025-05-30T00:03:50.039Z --- ## Transaction Represents an FX conversion/deal/order between two currencies the base currency and counter currency. A base currency amount is sold and counter currency amount is purchased, one of which is provided by the customer and the other is calculated based on the exchange\_rate. ### Parameters - **status** - the current state of the transaction. *read only* - **status\_label** - a human readable version of status. *read only* - **base\_currency** - This is the currency that the customer wants to sell. - **counter\_currency** - This is the currency that the customer wants to buy, and send to beneficiaries via payments. - **base\_currency\_amount** - The amount of base\_currency being sold. - **counter\_currency\_amount** - The amount of counter\_currency being purchased. - **exchange\_rate** - The exchange rate including any markup. *read only* - **value\_date** - This is the date the FX conversion will be executed. - **fees** - This is sum of fees across all payments. *read only* - **receipt\_amount** - This is the total amount payable by the customer including and markup and payment fees. *read only* - **receipt\_account** - This is the account the customer should pay into to settle the transaction. *read only* - **payments** - the payments that have been added to the transaction. *read only* - **created\_date** - the date the payment was created. *read only* - **updated\_date** - the date the payment was updated. *read only* ### States & progression | **Status** | **Description** | | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **created** | Transaction has been created but not confirmed | | **pending\_payment** | **Transaction Confirmed – Awaiting Payment**

The transaction has been successfully confirmed, and the corresponding counter party transaction has been automatically created.

**Next Step:** One or multiple payments must now be added. | | **open** | **Payments Added – Ready for Settlement**

All required payments have been successfully added to the transaction.

**Next Step:** Proceed with settlement to enable the payments to be released. | | **partially\_settled** | **Payments Added – Partial Settlement Received**

All payments have been added to the transaction. A partial settlement has been received.

**Next Step:** Await full settlement to release the remaining payments. | | **settled** | **Payments Added – Full Settlement Received**

All payments have been added to the transaction, and full settlement has been received.

**Next Step:** Payments can now be released. | | **partially\_released** | **Partial Payment Release**

The transaction contains multiple payments. Some payments have been partially released following settlement.

**Next Step:** Await release of the outstanding payments. | | **released** | **All Payments Released**

All payments associated with this transaction have been successfully released.

**Next Step:** Await confirmation that the payments have been successfully completed. This confirmation may be received:
A status webhook from the external payment provider, or
Reconciliation of bank statements imported and matched against the relevant payments. | | **paritally\_complete** | **Partial Payments Completed**
Some of the payments associated with this transaction have been successfully paid.
**Next Step:** Await payment confirmation for the remaining outstanding payments via status webhooks or bank statement reconciliation. | | **complete** | **All Payments Completed**

All payments associated with this transaction have been successfully paid.

**Final State** | | **cancellation\_requested** | **Transaction Cancellation Pending Approval**

The cancellation request for this transaction requires approval before it can be processed.

**Next Step:** Await for approval | | **cancelled** | **Transaction Cancelled**

The transaction has been successfully cancelled.

**Final State** | ## Withdrawal A withdrawal is a type of transaction, where the customer is withdrawing funds they already have on account. There is only one beneficiary associated. The base currency is the same as the counter currency, which is taken from the beneficiary provided and there is no FX component. ## Payment Represents an external payment to a beneficiary. ### Attributes - **status** - the current state of the payment. *read only* - **amount** - the payment amount. - **fee** - the fee that has been assigned to the payment. *read only* - **beneficiary** - the beneficiary that has been assigned to the payment. - **payment\_reference** - the reference that has been assigned to the payment. - **payment\_type** - the type of payment when applicable, e.g. **\['CHAPS', 'Faster', 'MCCY']** - **transaction\_reason** - the transaction reason assigned to the payment. - **created\_date** - the date the payment was created. *read only* - **updated\_date** - the date the payment was updated. *read only* ### States & progression | status | description | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | **pending** | **Payment Pending Release**

The payment is currently pending release. | | **hold** | **Payment Held for Compliance Review**

The payment is currently on hold pending compliance review. | | **unapproved** | **Payment Pending Signatory Approval**
The payment requires approval from a designated signatory before it can be released. | | **released** | **Payment Released – Awaiting Confirmation**
The payment has been released and is awaiting confirmation of receipt. | | **failed** | **Payment Released – Payment Failure Confirmed**

The payment was released, but confirmation has been received that the payment has failed. | | **repaired** | **Failed Payment Repaired – Awaiting Approval**

The failed payment has been repaired and is pending approval before it can be re-released. | | **repair\_approved** | **Repaired Payment Approved – Ready for Release**

The repaired payment has been approved and is now ready for release. | | **paid** | **Payment Successfully Completed**

The payment has been successfully processed and paid.

**Final State** | | **cancelled** | **Payment Cancelled**

The payment has been cancelled successfully.

**Final State** | ## Beneficiary A beneficiary is a recipient of payments, from withdrawals or FX conversions. They can be either individuals or organisations, and the bank details required depend on the supplied renumeration\_type. ### Attributes - **status** - the current state of the beneficiary. *read only* - **name** - the name object containing the first\_name, middle\_nameand last\_name of the beneficiary. - **country** - the beneficiary's country. - **email** - the beneficiary email. - **address** - the address object containing **address\_line\_1**, **address\_line\_2**, **suburb**, **city**, **province**, **postcode**, and **country\_code**. - **remuneration\_type** - the type of beneficiary either local or priority. *read only* - **reason\_for\_payment** - a specific reason for payment that has been assigned to the beneficiary. - **relation\_with\_customer** - the relationship to the customer. - **bank\_details** - the bank detail object containing the bank account details **bank\_name**, **bank\_code**, **branch\_code**, **branch\_name**, **account\_name**, **account\_number**, **local\_code**, **international\_code**, **address\_line\_1**, **address\_line\_2**, and **country**. - **created\_date** - the date the beneficiary was created. *read only* - **updated\_date** - the date the beneficiary was updated. *read only* ### States & progression | status | description | | ------------------------ | ------------------------------------------------------------------------------------------------------------------- | | **created** | **Beneficiary Created – Awaiting Approval**
The beneficiary has been created and is pending approval. | | **approved\_by\_client** | **Beneficiary Approved**
The beneficiary has been approved and is now eligible to be assigned to a payment. | | **edited** | **Beneficiary Edited – Awaiting Approval**
The beneficiary details have been updated and are pending approval. | | **archived** | **Beneficiary Archived**
The beneficiary has been successfully archived. | ## Sub Customer A sub-customer represents an ultimate remitter or originator of funds. The actual individual or entity on whose behalf a customer (typically a business or platform) is conducting transactions. Sub-customers enable customers to track and report the true source of funds when the customer is acting as an intermediary. ### Attributes - **id** - the unique identifier for the sub-customer. *read only* - **status** - the current state of the sub-customer (**active** or **archived**). *read only* - **account\_type** - whether the sub-customer is an **Individual** or **Company**. - **name** - the name object containing the **first\_name**, **middle\_name** and **last\_name** of the sub-customer. - **email** - the sub-customer's email address. - **gender** - the sub-customer's gender (**male** or **female**). - **birth\_date** - the sub-customer's date of birth. - **company\_name** - the company name (if account type is Company). - **registration\_number** - the company registration number (if account type is Company). - **country** - the sub-customer's country. - **phone** - the phone object containing **isd** and **number**. - **mobile** - the mobile object containing **isd** and **number**. - **address** - the address object containing **address\_line\_1**, **address\_line\_2**, **suburb**, **city**, **province**, **postcode**, and **country\_code**. - **created\_date** - the date the sub-customer was created. *read only* - **updated\_date** - the date the sub-customer was updated. *read only* ### States & progression | status | description | | ------------ | --------------------------------------------------------------------------------------------------------------------------- | | **active** | **Sub-Customer Active**

The sub-customer is active and can be associated with transactions and payments. | | **archived** | **Sub-Customer Archived**

The sub-customer has been archived and cannot be used in new transactions or payments. |