Overview
Introduction
Welcome to the Money Transfer API reference.
This API serves as the primary gateway to facilitate money transfers through Thunes’ platform.
The Money Transfer API is organised according to REST principles and provides the following functionalities:
- Process and retrieve transaction details
- Account management services
- Discovery services
Environments
This API is available in 2 environments: production and pre-production, reachable via IPSec VPN or HTTPS.
Specific details relating to the endpoints will be provided upon account creation.
For HTTPS connections, TLS version 1.2 onwards is required to reach production and pre-production environments.
Versioning
Endpoints of the API are prefixed with a corresponding version number. This documentation describes version 2 of the API. Documentation for version 1 of the API can be found here.
This method of versioning provides complete isolation between implementations and ensures that subsequent major changes to the API will not affect existing integrations. No breaking changes will be introduced within a major version.
Whenever possible, Thunes will not change the API contract in a non-backward compatible way, if required, a new major version of the API will be released, however Thunes reserves the right to make additive changes or any non-breaking changes to our API without releasing a new major version or notifying clients.
Clients should design their implementation not to break if new fields or other non-breaking changes are introduced
Non-breaking changes
Thunes regularly introduce backwards-compatible changes to our API to provide additional product features and capabilities. Non-breaking changes may be introduced without prior warning to users of the Thunes API. Examples of non-breaking changes would be:
- New API endpoints
- Additional new optional API request fields/parameters for existing endpoints
- Additional new optional HTTP headers in API requests for existing endpoints
- Additional new fields in API response for existing endpoints
- Additional HTTP headers in API response for existing endpoints
- Modification of text field values, for instance in error messages
- Introduction of new transaction statuses within a status class
- Introduction of new required fields linked to specific payers (list of required fields for a given payer is available by API, client implementation should rely on API response to define whether a field is mandatory)
- Increasing length of existing text field in API requests
- Adding new fields in callback endpoints
The client implementation should be designed with the above in mind, so that non-breaking changes do not adversely affect the implementation.
Breaking changes
A breaking change refers to a change that requires an application update to continue working with the API. Examples of breaking changes would be:
- Removing or renaming an API endpoint
- Changing the accepted values for an API request fields
- Adding new mandatory field to an API request body, outside of information required for processing a transaction
- Change in an API response structure (renaming of fields)
Whenever possible, a new major version will be introduced if a breaking change is introduced. In the event that a breaking change is unavoidable and a new major version in not possible (e.g., change in regulation, compliance) Thunes will contact clients in advance to ensure there is sufficient time to update the client’s application.
Headers
The endpoints of the API will respond with various header fields, such as Pagination information. All header fields in both requests and responses are case-insensitive, following the HTTP/1.1 specification (RFC 7230). It is advised not to rely on the case-sensitivity of any header fields.
Getting started
Thunes Money Transfer API allows the sending of transfers globally accross different payout ecosystems, Mobile Wallet, Bank Account, and Cash Pickup.
To send a transfer, the typical flow would be:
- Retrieval of desired payer information
Discovery endpoints allow Thunes’ partner to retrieve a list of services, countries and payers that are accessible to them. A payer in Thunes system represents the targeted destination crediting the money into the beneficiary account. Thunes coverage supports different payers across all services (banks, mobile wallets or cash pick-up networks) per country.
As part of the payer information, an API user can dynamically retrieve requirement and information linked to the selected payer, like lower and upper limits of accepted transfers, mandatory parameters, currencies (including precision and increment).
- Quotation’s creation
The quotation step allows a partner to book a rate for a transfer to a specific payer. The quotation will indicate the amount that is being sent as well as the amount that will be received by the beneficiary of the transfer.
- Transaction’s creation
From the quotation previously created, a partner is able to create a transaction, and input further details for the transfer, such as sender/beneficiary, or account details for instance. Optional documents can be uploaded at this stage.
- Transaction’s confirmation
After the transaction has been created, the last step to process a transfer is to confirm the transaction. Balance verification for instance will happen at that stage of the process.
- Transaction status inquiry / callback processing
To check the status of the transfer, a partner can provide a callback url. Thunes’ system will send a callback to this url when the transaction status is updated. A partner is also able to query the status of a transaction in the API, to check its current status.
Transaction states
During the course of a transfer, a transaction will undergo various status changes as illustrated in the diagram.
Conditions marked as “Upon request to customer care team” pertain to reversal and/or cancellation. These must be requested through the Thunes customer care team, who will act accordingly.
If a callback URL has been provided, updates will be sent to the URL in real-time when changes in transaction status occur. In addition, transaction status can be queried through one of two means: via the returned id or a provided external_id.
The latter serves as a unique reference from the perspective of the sending partner. This allows transaction details to be retrieved when exceptions occur, for example if an expected response was not received and the transaction success is unknown.
The numerical values within each of the illustrated states correspond to the transaction status, while the labels correspond to that of the transaction status class message.
Callback
POST /callback HTTP/1.1
Date: Wed, 02 Nov 2016 09:17:54 GMT
Content-Type: application/json{
"id": 1,
"status": "70000",
"status_message": "COMPLETED",
"status_class": "7",
"status_class_message": "COMPLETED",
"external_id": "1478078339357",
"external_code": null,
"transaction_type": "C2C",
"payer_transaction_reference": "SP-000-123",
"payer_transaction_code": "SP-ABC-DEF",
"creation_date": "2016-11-02T09:19:15",
"expiration_date": "2016-11-03T09:07:44",
"credit_party_identifier": {
"msisdn": "+263775892100",
"bank_account_number": "0123456789",
"swift_bic_code": "ABCDEFGH"
},
"source": {
"country_iso_code": "FRA",
"currency": "EUR",
"amount": 10
},
"destination": {
"currency": "USD",
"amount": 10.69
},
"payer": {
"id": 1,
"name": "Sample Payer",
"currency": "USD",
"country_iso_code": "ZWE",
"service": {
"id": 1,
"name": "MobileWallet"
}
},
"sender": {
"lastname": "Doe",
"lastname2": null,
"middlename": null,
"firstname": "John",
"nativename": null,
"nationality_country_iso_code": "FRA",
"code": null,
"date_of_birth": "1970-01-01",
"country_of_birth_iso_code": "FRA",
"gender": "MALE",
"address": "42 Rue des fleurs",
"postal_code": "75000",
"city": "Paris",
"country_iso_code": "FRA",
"msisdn": "33712345678",
"email": "john.doe@mail.com",
"id_type": "SOCIAL_SECURITY",
"id_country_iso_code": null,
"id_number": "502-42-0158",
"id_delivery_date": "2016-01-01",
"id_expiration_date": null,
"occupation": "Residential Advisor",
"province_state": null,
"beneficiary_relationship": null,
"source_of_funds": null,
"bank_account_number": null
},
"beneficiary": {
"lastname": "Doe",
"lastname2": null,
"middlename": null,
"firstname": "Jane",
"nativename": null,
"nationality_country_iso_code": "FRA",
"code": null,
"date_of_birth": "1971-01-01",
"country_of_birth_iso_code": "ZWE",
"gender": "MALE",
"address": "3 Norfolk Road",
"postal_code": "4581",
"city": "Harare",
"country_iso_code": "ZWE",
"msisdn": "263775892364",
"email": "jane.doe@mail.com",
"id_type": "SOCIAL_SECURITY",
"id_country_iso_code": "ZWE",
"id_number": "178027317681327",
"id_delivery_date": null,
"id_expiration_date": null,
"occupation": "Sales Executive",
"bank_account_holder_name": null,
"province_state": null
},
"callback_url": "{URL_PLACEHOLDER}",
"sent_amount": {
"currency": "EUR",
"amount": 10
},
"wholesale_fx_rate": 1.06891969534071,
"retail_rate": null,
"retail_fee": 1,
"retail_fee_currency": "EUR",
"fee": {
"currency": "EUR",
"amount": 1.88
},
"purpose_of_remittance": "FAMILY_SUPPORT",
"document_reference_number": null,
"additional_information_1": null,
"additional_information_2": null,
"additional_information_3": null
}While the transfer order is processed, changes in status will be notified in realtime to the provided callback URL (if provided).
The sending partner must implement this endpoint to receive these status changes. The endpoint should expect an HTTP POST request containing a transaction object represented in JSON.
Upon sucessful receipt of data, the callback endpoint should respond with an HTTP 2XX. In the event that the Money Transfer platform did not receive this response, callback notifications will be retried several times, beyond which, the transaction status will have to be queried by the sending partner.
Topics
Authentication
Access to all endpoints of the API requires authentication through HTTP Basic Authentication.
Basic Authentication
curl https://${API_ENDPOINT}/ping \
-u "${API_KEY}:${API_SECRET}"| URL Part | Value |
|---|---|
| user-ID | API key |
| password | API secret |
Your API keys and secrets represent your identity and authorization. Please keep and store them securely!
API credentials should not be shared or stored in clear text. Once in your possession, it is on you to keep those credentials safe.
Avoid storing your credentials in your source code, or in your version control system, like github for instance. Instead, you can use environment variables to pass secrets into your application, following the 12 factor app principles, use a vault mechanism (HashiCorp Vault, AWS Secret Manager, Secret in Kubernetes, …), or provide them through a configuration file excluded from your version control, provisioned automatically within your deployment process, only readable by the application.
Errors
HTTP Response
HTTP/1.1 401 Unauthorized{
"errors": [
{
"code": "1000401",
"message": "Unauthorized"
}
]
}Thunes uses standard HTTP response codes to indicate whether an API request is successful or not.
| Status | Description |
|---|---|
200 |
OK |
400 |
Bad Request: Request was malformed |
401 |
Unauthorized: Credentials missing or invalid |
404 |
Not Found: Resource doesn’t exist |
500 |
Server Error: An internal server error occurred processing the request |
Details will always be contained within the HTTP body.
API Error Codes
| Code | Description |
|---|---|
1000401 |
Unauthorized |
1000404 |
Resource not found |
1000999 |
Invalid parameter |
1000998 |
Source country not authorized |
1003001 |
Payer is inactive in your account |
1003002 |
Invalid payer |
1003007 |
Payer is currently unavailable |
1003008 |
Destination amount is invalid |
1003009 |
Parameter page is outside of the page range |
1003010 |
Destination currency not provided by payer |
1003011 |
Transaction amount below minimum of the selected payer |
1003012 |
Transaction amount exceeds maximum of the selected payer |
1005001 |
Account is invalid |
1006001 |
Transaction amount limit exceeded |
1006002 |
Account quantity limit exceeded |
1006099 |
Limit exceeded |
1007001 |
External ID has already been used |
1007002 |
Transaction has already been confirmed |
1007003 |
Transaction can not be confirmed |
1007004 |
Transaction can no longer be confirmed, quotation has expired |
1007005 |
Transaction can not be confirmed, insufficient balance |
1007014 |
Transaction can not be cancelled |
1007100 |
Method is not supported by this payer |
1007101 |
Method is currently unavailable |
1007401 |
Attachment is too big |
1007402 |
Max number of attachments reached |
1007403 |
Adding attachment is not allowed after transaction is confirmed |
1007404 |
Transaction attachment not found |
1007405 |
Attachment file type is invalid |
1008002 |
Quotation not found |
1008003 |
Quotation has expired |
1008004 |
Transaction not found |
1009001 |
Unexpected error, please contact our support team |
Pagination
GET /{resource}?page=1&per_page=50 HTTP/1.1
X-Total: 1
X-Total-Pages: 1
X-Per-Page: 50
X-Page: 1API resources supporting bulk fetches via “list” API methods will be returned in a paginated fashion.
Input Parameters
| Field | Required | Type | Description |
|---|---|---|---|
page |
No | Integer | Page number |
per_page |
No | Integer | Number of results per page (default 50, maximum 100) |
Output Headers
| Field | Description |
|---|---|
X-Total |
Total number of records |
X-Total-Pages |
Total number of pages |
X-Per-Page |
Number of records per page |
X-Page |
Current page number |
X-Next-Page |
Next page number (if any) |
X-Prev-Page |
Previous page number (if any) |
Endpoints
The various endpoints to the Thunes API are described in the following sections.
Connectivity
Ping
GET /ping HTTP/1.1
200 OK{
"status": "up"
}GET /ping
Query API status and check connectivity.
Returns
| Field | Type | Description |
|---|---|---|
status |
String | API status |
Expected value of status should be “up”.
Discovery
These endpoints are used to provide lists of information to the caller.
Services
List services available
GET /v2/money-transfer/services HTTP/1.1
X-Total: 1
X-Total-Pages: 1
X-Per-Page: 50
X-Page: 1
200 OK[
{
"id": 1,
"name": "MobileWallet"
},
{
"id": 2,
"name": "BankAccount"
},
{
"id": 3,
"name": "CashPickup"
}
]GET /v2/money-transfer/services
Retrieves a list of all services available to the caller.
Request parameters
| Field | Required | Type | Description |
|---|---|---|---|
page |
No | Integer | Page number |
per_page |
No | Integer | Number of results per page (default 50, max 100) |
country_iso_code |
No | String | Country code in ISO 3166-1 alpha-3 format |
Returns
An array of service objects in a paginated fashion.
Payers
List payers available
GET /v2/money-transfer/payers HTTP/1.1
X-Total: 1
X-Total-Pages: 1
X-Per-Page: 50
X-Page: 1
200 OK[
{
"id": 1,
"name": "MobileWallet Payer",
"precision": 2,
"increment": 0.01,
"currency": "USD",
"country_iso_code": "USA",
"service": {
"id": 1,
"name": "MobileWallet"
},
"transaction_types" : {
"C2C": {
"minimum_transaction_amount": 0,
"maximum_transaction_amount": null,
"credit_party_identifiers_accepted": [
[
"msisdn"
]
],
"required_sending_entity_fields": [
[
"firstname",
"lastname",
"date_of_birth"
]
],
"required_receiving_entity_fields": [
[
"firstname",
"lastname"
]
],
"required_documents": [
[
"invoice",
"purchase_order",
"contract"
]
],
"credit_party_information": {
"credit_party_identifiers_accepted": [
[]
]
},
"credit_party_verification": {
"credit_party_identifiers_accepted": [
[]
],
"required_receiving_entity_fields": [
[]
]
},
"purpose_of_remittance_values_accepted": [
]
}
}
},
{
"id": 2,
"name": "Bank Payer",
"precision": 2,
"increment": 0.01,
"currency": "PHP",
"country_iso_code": "PHL",
"service": {
"name": "BankAccount",
"id": 2
},
"transaction_types" : {
"B2C": {
"minimum_transaction_amount": 0,
"maximum_transaction_amount": null,
"credit_party_identifiers_accepted": [
[
"account_number"
]
],
"required_sending_entity_fields": [
[
"registered_name",
"representative_lastname",
"representative_firstname"
]
],
"required_receiving_entity_fields": [
[
"firstname",
"lastname"
]
],
"required_documents": [
[]
],
"credit_party_information": {
"credit_party_identifiers_accepted": [
[]
]
},
"credit_party_verification": {
"credit_party_identifiers_accepted": [
[]
],
"required_receiving_entity_fields": [
[]
]
},
"purpose_of_remittance_values_accepted": [
]
}
}
}
]GET /v2/money-transfer/payers
Retrieves a list of all payers available for the caller, optionally filtered based on specified parameters.
Request parameters
| Field | Required | Type | Description |
|---|---|---|---|
page |
No | Integer | Page number |
per_page |
No | Integer | Number of results per page (default 50, max 100) |
service_id |
No | Integer | Service ID |
country_iso_code |
No | String | Country code in ISO 3166-1 alpha-3 format |
currency |
No | String | Currency in ISO 4217 format |
Returns
Array of payer objects in a paginated fashion.
Get payer details
GET /v2/money-transfer/payers/3 HTTP/1.1
200 OK{
"id": 3,
"name": "Sample Payer",
"precision": 0,
"increment": 0.01,
"currency": "IDR",
"country_iso_code": "IDN",
"service": {
"id": 1,
"name": "MobileWallet"
},
"transaction_types": {
"C2C": {
"minimum_transaction_amount": 0,
"maximum_transaction_amount": null,
"credit_party_identifiers_accepted": [
[
"msisdn"
]
],
"required_sending_entity_fields": [
[
"firstname",
"date_of_birth",
"lastname"
]
],
"required_receiving_entity_fields": [
[
"firstname",
"lastname"
]
],
"required_documents": [
[
"invoice",
"contract"
]
],
"credit_party_information": {
"credit_party_identifiers_accepted": [
[]
]
},
"credit_party_verification": {
"credit_party_identifiers_accepted": [
[]
],
"required_receiving_entity_fields": [
[]
]
},
"purpose_of_remittance_values_accepted": [
]
}
}
}GET /v2/money-transfer/payers/{id}
Retrieve information for a given payer. The payer id must be supplied replacing {id} in the URI path.
Returns
Payer object.
Payer Rates
Retrieve rates for a given payer
GET /v2/money-transfer/payers/362/rates HTTP/1.1
200 OK{
"destination_currency": "USD",
"rates": {
"C2C": {
"EUR": [
{
"source_amount_min": 0,
"source_amount_max": 88,
"wholesale_fx_rate": 1.10847692409526
},
{
"source_amount_min": 88,
"source_amount_max": 8800,
"wholesale_fx_rate": 1.10847692409526
}
]
}
}
}GET /v2/money-transfer/payers/{id}/rates
Retrieve rates for a given payer. The id of the payer must be supplied replacing {id} in the URI path.
Returns
| Field | Type | Description |
|---|---|---|
destination_currency |
String | Currency in ISO 4217 format |
rates |
Object | Rates information |
Countries
List countries available
GET /v2/money-transfer/countries HTTP/1.1
X-Total: 1
X-Total-Pages: 1
X-Per-Page: 50
X-Page: 1
200 OK[
{
"iso_code": "KEN",
"name": "Kenya"
}
]GET /v2/money-transfer/countries
Retrieve list of countries for all money transfer services available for the caller.
Request parameters
| Field | Required | Type | Description |
|---|---|---|---|
page |
No | Integer | Page number |
per_page |
No | Integer | Number of results per page (default 50, max 100) |
Returns
Array of country objects in a paginated fashion.
Lookups
BIC code lookup
GET /v2/money-transfer/lookups/BIC/ABNAIDJA HTTP/1.1
X-Total: 1
X-Total-Pages: 1
X-Per-Page: 50
X-Page: 1
200 OK[
{
"id": 123
}
]GET /v2/money-transfer/lookups/BIC/{swift_bic_code}
Retrieve list of payers’ identifier for a given SWIFT BIC code.
Available for selected countries only
Request parameters
| Field | Required | Type | Description |
|---|---|---|---|
page |
No | Integer | Page number |
per_page |
No | Integer | Number of results per page (default 50, max 100) |
Output
Array of payers’ identifiers, paginated.
Account
Balances
GET /v2/money-transfer/balances HTTP/1.1
X-Total: 1
X-Total-Pages: 1
X-Per-Page: 50
X-Page: 1
200 OK[
{
"id": 1,
"currency": "EUR",
"balance": 10000000,
"pending": 0,
"available": 10000000,
"credit_facility": 0
}
]GET /v2/money-transfer/balances
Retrieve information for all account balances per currency.
available = balance - pending + credit_facility
Request parameters
| Field | Required | Type | Description |
|---|---|---|---|
page |
No | Integer | Page number |
per_page |
No | Integer | Number of results per page (default 50, max 100) |
Returns
Array of balance objects.
Balance Movements
GET /v2/money-transfer/balances/1/movements?from_date=2022-12-01T00:00:00Z&to_date=2022-12-02T00:00:00Z&limit=50 HTTP/1.1
X-Next-Url: /v2/money-transfer/balances/1/movements?cursor=eyJu....
X-Next-Cursor: eyJuZXh0X3JvdyI6NDM3NSwibGltaXQiOjF9
200 OK[
{
"balance_operation_number": 4376,
"creation_date": "2022-12-01T16:28:03Z",
"movement_type": "PAYOUT_FEES",
"amount": -1.25,
"currency": "USD",
"transaction_reference_id": 123,
"operation": "AUTHORIZE",
"balance": 1162.56,
"pending_balance": -120.39
},
{
"balance_operation_number": 4375,
"creation_date": "2022-12-01T16:28:03Z",
"movement_type": "PAYOUT",
"amount": -1.07,
"currency": "USD",
"transaction_reference_id": 123,
"operation": "AUTHORIZE",
"balance": 1162.56,
"pending_balance": -119.14
}
]GET /v2/money-transfer/balances/{balance_id}/movements
Retrieve information for balances movements for {balance_id} provided. Balance ID can be retrieved from Balances API.
Request parameters
| Field | Required | Type | Description |
|---|---|---|---|
from_date |
Yes | Datetime | from date in HTTP format |
to_date |
Yes | Datetime | to date in HTTP format † |
limit |
No | integer | Default 100, Max 200 |
cursor |
No | string | Base64 Encoded string, from X-Next-Cursor response header field |
† : to_date should be within 24 hours of from_date.
Returns
Array of Balance Movements.
Balance Topup Instructions
GET /v2/money-transfer/balances/1/topup_instructions HTTP/1.1
200 OK{
"account_code": "GT_XOF1234",
"account_number": "AA0000000000000000000000",
"account_name": "Sample account name",
"iban": "CI00CI0000000000000000000000",
"account_address": "Account address",
"local_account_identifier_type": null,
"local_account_identifier": "",
"bank_name": "Sample bank",
"bank_address": "Bank address",
"swift_code": "ABCDEFGH",
"local_code_type": null,
"local_code": null,
"intermediary_bank_name": null,
"intermediary_bank_swift_code": null,
"correspondant_code": null,
"update_date": "2022-12-01T16:28:03Z",
"creation_date": "2022-12-01T16:28:03Z"
}GET /v2/money-transfer/balances/{balance_id}/topup_instructions
Retrieve information for balance topup instructions for {balance_id} provided. Balance ID can be retrieved from Balances API.
Returns
Object of Balance Topup Instruction.
Reports
List reports available
GET /v2/money-transfer/reports HTTP/1.1
X-Total: 1
X-Total-Pages: 1
X-Per-Page: 50
X-Page: 1
200 OK[
{
"id": 123,
"type": "PARTNER_TRANSACTION_REPORT_DAILY",
"timezone": "UTC",
"cut_off_time": "00:00:00",
"report_date": "2023-10-23",
"period_start": "2023-10-23T00:00:00Z",
"period_end": "2023-10-24T00:00:00Z",
"files": [
{
"id": 4567,
"report_type": "PARTNER_TRANSACTION_REPORT_DAILY",
"file_type": "TRANSACTION_STATS",
"name": "daily_transaction_report_2023-10-23.csv"
}
]
},
{
"id": 124,
"type": "PARTNER_TRANSACTION_REPORT_DAILY",
"timezone": "UTC",
"cut_off_time": "00:00:00",
"report_date": "2023-10-21",
"period_start": "2023-10-21T00:00:00Z",
"period_end": "2023-10-22T00:00:00Z",
"files": [
{
"id": 4568,
"report_type": "PARTNER_TRANSACTION_REPORT_DAILY",
"file_type": "TRANSACTION_STATS",
"name": "daily_transaction_report_2023-10-21.csv"
}
]
},
{
"id": 4569,
"type": "PARTNER_TRANSACTION_REPORT_DAILY",
"timezone": "UTC",
"cut_off_time": "00:00:00",
"report_date": "2023-10-17",
"period_start": "2023-10-17T00:00:00Z",
"period_end": "2023-10-18T00:00:00Z",
"files": [
{
"id": 45610,
"report_type": "PARTNER_TRANSACTION_REPORT_DAILY",
"file_type": "TRANSACTION_STATS",
"name": "daily_transaction_report_2023-10-17.csv"
}
]
}
]GET /v2/money-transfer/reports
Retrieves a list of all reports available for the caller, optionally filtered based on specified parameters.
Request parameters
| Field | Required | Type | Description |
|---|---|---|---|
from_date |
No | Datetime | From date in HTTP format |
to_date |
No | Datetime | To date in HTTP format |
report_type |
No | String | Type of report |
page |
No | Integer | Page number |
per_page |
No | Integer | Number of results per page (default 50, max 100) |
Returns
An array of Report objects in a paginated fashion.
Get report details
GET /v2/money-transfer/reports/123 HTTP/1.1
200 OK{
"id": 123,
"type": "PARTNER_TRANSACTION_REPORT_DAILY",
"timezone": "UTC",
"cut_off_time": "00:00:00",
"report_date": "2023-10-17",
"period_start": "2023-10-17T00:00:00Z",
"period_end": "2023-10-18T00:00:00Z",
"files": [
{
"id": 4567,
"report_type": "PARTNER_TRANSACTION_REPORT_DAILY",
"file_type": "TRANSACTION_STATS",
"name": "daily_transaction_report_2023-10-17.csv"
}
]
}GET /v2/money-transfer/reports/{id}
Retrieve information for a given report. The report id must be supplied replacing {id} in the URI path.
Returns
Report object.
List report files available
GET /v2/money-transfer/reports/123/files HTTP/1.1
X-Total: 1
X-Total-Pages: 1
X-Per-Page: 50
X-Page: 1
200 OK[
{
"id": 4567,
"report_type": "PARTNER_TRANSACTION_REPORT_DAILY",
"file_type": "TRANSACTION_STATS",
"name": "daily_transaction_report_2023-10-17.csv"
}
]GET /v2/money-transfer/reports/{id}/files
Retrieve files for a given report. The report id must be supplied replacing {id} in the URI path.
Request parameters
| Field | Required | Type | Description |
|---|---|---|---|
page |
No | Integer | Page number |
per_page |
No | Integer | Number of results per page (default 50, max 100) |
Returns
List of Report File object.
Get report file details
GET /v2/money-transfer/reports/123/files/4567 HTTP/1.1
200 OK{
"url": "<Signed URL>"
}GET /v2/money-transfer/reports/{report_id}/files/{id}
Retrieve information for a given report file, It will return signed URL to download the file contents. The report id and file id must be supplied replacing {report_id} and {id} in the URI path respectively.
Returns
| Field | Type | Description |
|---|---|---|
url |
String | File download url |
Credit Parties
Information
POST /v2/money-transfer/payers/1/C2C/credit-party-information HTTP/1.1
200 OK{
"credit_party_identifier": {
"msisdn": "263775892364"
}
}{
"beneficiary": {
"address": "3 Norfolk Road",
"bank_account_holder_name": null,
"city": "Harare",
"code": null,
"country_iso_code": "ZWE",
"country_of_birth_iso_code": "ZWE",
"date_of_birth": "1971-01-01",
"email": "jane.doe@mail.com",
"firstname": "Jane",
"gender": "MALE",
"id_country_iso_code": "ZWE",
"id_delivery_date": null,
"id_expiration_date": null,
"id_number": "178027317681327",
"id_type": "SOCIAL_SECURITY",
"lastname": "Doe",
"lastname2": null,
"middlename": null,
"msisdn": "263775892364",
"nationality_country_iso_code": "FRA",
"nativename": null,
"occupation": "Sales Executive",
"postal_code": "4581",
"province_state": null
}
"id": 10252292
}POST /v2/money-transfer/payers/{id}/{transaction_type}/credit-party-information
Retrieve beneficiary or Receiving business information information based on account details for a given payer and transaction type. The id of the payer and transaction type must be supplied replacing {id} and {transaction_type} respectively in the URI path.
Request parameters
| Field | Required | Type | Description |
|---|---|---|---|
credit_party_identifier |
Yes | Object | Credit party identifier information |
Returns
Beneficiary object if C2C or B2C transaction type.
Receiving business information object if C2B or B2B transaction type.
Verification
POST /v2/money-transfer/payers/1/C2C/credit-party-verification HTTP/1.1
200 OK{
"credit_party_identifier": {
"msisdn": "263775892364"
}
}{
"id": 31,
"account_status": "AVAILABLE"
}POST /v2/money-transfer/payers/{id}/{transaction_type}/credit-party-verification
Validate status of an account for a given payer and transaction type. The id of the payer and transaction type must be supplied replacing {id} and {transaction_type} respectively in the URI path.
Request parameters
| Field | Required | Type | Description |
|---|---|---|---|
credit_party_identifier |
Yes | Object | Credit party identifier information |
beneficiary |
No† | Object | Beneficiary information |
receiving_business |
No† | Object | Receiving business information information |
†: Requiredness will depend on the payer
Returns
| Field | Type | Description |
|---|---|---|
id |
Integer | Verification request ID |
account_status |
String | Account status |
Transfers
Quotations
Create a quotation
POST /v2/money-transfer/quotations HTTP/1.1
201 Created{
"external_id": "1481184321405",
"payer_id": "1",
"mode": "SOURCE_AMOUNT",
"transaction_type": "C2C",
"source": {
"amount": "10",
"currency": "EUR",
"country_iso_code": "FRA"
},
"destination": {
"amount": null,
"currency": "USD"
}
}{
"id": 1,
"external_id": "1481184321405",
"payer": {
"id": 1,
"name": "Sample Payer",
"currency": "USD",
"country_iso_code": "ZWE",
"service": {
"id": 1,
"name": "MobileWallet"
}
},
"mode": "SOURCE_AMOUNT",
"transaction_type": "C2C",
"source": {
"country_iso_code": "FRA",
"currency": "EUR",
"amount": 10
},
"destination": {
"currency": "USD",
"amount": 10.69
},
"sent_amount": {
"currency": "EUR",
"amount": 10
},
"wholesale_fx_rate": 1.06891969534071,
"fee": {
"currency": "EUR",
"amount": 1.88
},
"creation_date": "2016-11-02T09:07:44",
"expiration_date": "2016-11-03T09:07:44"
}POST /v2/money-transfer/quotations
Creates a new quotation for a given source or destination value.
Request parameters
| Field | Required | Type | Description |
|---|---|---|---|
external_id |
Yes | String | External reference ID |
payer_id |
Yes | Integer | Payer ID |
mode |
Yes | String | Quotation mode |
transaction_type |
Yes | String | Transaction type |
source |
Yes | Object | Source information |
destination |
Yes | Object | Destination information |
Depending on the mode, amount is optional in either Source or Destination object.
Returns
Quotation object.
Retrieve a quotation by id
GET /v2/money-transfer/quotations/1 HTTP/1.1
200 OK{
"id": 1,
"external_id": "1481184321405",
"payer": {
"id": 1,
"name": "Sample Payer",
"precision": 2,
"increment": 0.01,
"currency": "USD",
"country_iso_code": "ZWE",
"service": {
"id": 1,
"name": "MobileWallet"
}
},
"mode": "SOURCE_AMOUNT",
"transaction_type": "C2C",
"source": {
"country_iso_code": "FRA",
"currency": "EUR",
"amount": 10
},
"destination": {
"currency": "USD",
"amount": 10.69
},
"sent_amount": {
"currency": "EUR",
"amount": 10
},
"wholesale_fx_rate": 1.06891969534071,
"fee": {
"currency": "EUR",
"amount": 1.88
},
"creation_date": "2016-11-02T09:07:44",
"expiration_date": "2016-11-03T09:07:44"
}GET /v2/money-transfer/quotations/{id}
Retrieve information for a given quotation. The id of the quotation must be supplied replacing {id} in the URI path.
Returns
Quotation object.
Retrieve quotation by external id
GET /v2/money-transfer/quotations/ext-1481184321405 HTTP/1.1
200 OK{
"id": 1,
"external_id": "1481184321405",
"payer": {
"id": 1,
"name": "Sample Payer",
"precision": 2,
"increment": 0.01,
"currency": "USD",
"country_iso_code": "ZWE",
"service": {
"id": 1,
"name": "MobileWallet"
}
},
"mode": "SOURCE_AMOUNT",
"transaction_type": "C2C",
"source": {
"country_iso_code": "FRA",
"currency": "EUR",
"amount": 10
},
"destination": {
"currency": "USD",
"amount": 10.69
},
"sent_amount": {
"currency": "EUR",
"amount": 10
},
"wholesale_fx_rate": 1.06891969534071,
"fee": {
"currency": "EUR",
"amount": 1.88
},
"creation_date": "2016-11-02T09:07:44",
"expiration_date": "2016-11-03T09:07:44"
}GET /v2/money-transfer/quotations/ext-{external_id}
Retrieve information for a given quotation through an external reference ID.
Returns
Quotation object.
Transactions
Create a transaction from a quotation id
POST /v2/money-transfer/quotations/1/transactions HTTP/1.1
201 Created{
"credit_party_identifier": {
"msisdn": "+263775892100",
"bank_account_number": "0123456789",
"swift_bic_code": "ABCDEFGH"
},
"sender": {
"lastname": "Doe",
"firstname": "John",
"nationality_country_iso_code": "FRA",
"date_of_birth": "1970-01-01",
"country_of_birth_iso_code": "FRA",
"gender": "MALE",
"address": "42 Rue des fleurs",
"postal_code": "75000",
"city": "Paris",
"country_iso_code": "FRA",
"msisdn": "33712345678",
"email": "john.doe@mail.com",
"id_type": "SOCIAL_SECURITY",
"id_number": "502-42-0158",
"id_delivery_date": "2016-01-01",
"occupation": "Residential Advisor"
},
"beneficiary": {
"lastname": "Doe",
"firstname": "Jane",
"nationality_country_iso_code": "FRA",
"date_of_birth": "1971-01-01",
"country_of_birth_iso_code": "ZWE",
"gender": "MALE",
"address": "3 Norfolk Road",
"postal_code": "4581",
"city": "Harare",
"country_iso_code": "ZWE",
"msisdn": "263775892364",
"email": "jane.doe@mail.com",
"id_type": "SOCIAL_SECURITY",
"id_country_iso_code": "ZWE",
"id_number": "178027317681327",
"occupation": "Sales Executive"
},
"external_id": "1478078339357",
"retail_fee": 1,
"retail_fee_currency": "EUR",
"purpose_of_remittance": "FAMILY_SUPPORT",
"document_reference_number": "12345678",
"callback_url": "{URL_PLACEHOLDER}",
"reference": "some reference"
}{
"id": 1,
"status": "10000",
"status_message": "CREATED",
"status_class": "1",
"status_class_message": "CREATED",
"external_id": "1478078339357",
"external_code": null,
"transaction_type": "C2C",
"payer_transaction_reference": null,
"payer_transaction_code": null,
"creation_date": "2016-11-02T09:19:15",
"expiration_date": "2016-11-03T09:07:44",
"credit_party_identifier": {
"msisdn": "+263775892100",
"bank_account_number": "0123456789",
"swift_bic_code": "ABCDEFGH"
},
"source": {
"country_iso_code": "FRA",
"currency": "EUR",
"amount": 10
},
"destination": {
"currency": "USD",
"amount": 10.69
},
"payer": {
"id": 1,
"name": "Sample Payer",
"currency": "USD",
"country_iso_code": "ZWE",
"service": {
"id": 1,
"name": "MobileWallet"
}
},
"sender": {
"lastname": "Doe",
"lastname2": null,
"middlename": null,
"firstname": "John",
"nativename": null,
"nationality_country_iso_code": "FRA",
"code": null,
"date_of_birth": "1970-01-01",
"country_of_birth_iso_code": "FRA",
"gender": "MALE",
"address": "42 Rue des fleurs",
"postal_code": "75000",
"city": "Paris",
"country_iso_code": "FRA",
"msisdn": "33712345678",
"email": "john.doe@mail.com",
"id_type": "SOCIAL_SECURITY",
"id_country_iso_code": null,
"id_number": "502-42-0158",
"id_delivery_date": "2016-01-01",
"id_expiration_date": null,
"occupation": "Residential Advisor",
"province_state": null,
"beneficiary_relationship": null,
"source_of_funds": null,
"bank_account_number": null
},
"beneficiary": {
"lastname": "Doe",
"lastname2": null,
"middlename": null,
"firstname": "Jane",
"nativename": null,
"nationality_country_iso_code": "FRA",
"code": null,
"date_of_birth": "1971-01-01",
"country_of_birth_iso_code": "ZWE",
"gender": "MALE",
"address": "3 Norfolk Road",
"postal_code": "4581",
"city": "Harare",
"country_iso_code": "ZWE",
"msisdn": "263775892364",
"email": "jane.doe@mail.com",
"id_type": "SOCIAL_SECURITY",
"id_country_iso_code": "ZWE",
"id_number": "178027317681327",
"id_delivery_date": null,
"id_expiration_date": null,
"occupation": "Sales Executive",
"bank_account_holder_name": null,
"province_state": null
},
"callback_url": "{URL_PLACEHOLDER}",
"sent_amount": {
"currency": "EUR",
"amount": 10
},
"wholesale_fx_rate": 1.06891969534071,
"retail_rate": null,
"retail_fee": 1,
"retail_fee_currency": "EUR",
"fee": {
"currency": "EUR",
"amount": 1.88
},
"purpose_of_remittance": "FAMILY_SUPPORT",
"document_reference_number": "12345678",
"additional_information_1": null,
"additional_information_2": null,
"additional_information_3": null,
"reference": "some reference"
}POST /v2/money-transfer/quotations/{id}/transactions
Create a new transaction with transfer values specified from a given quotation. The id of the quotation must be supplied replacing {id} in the URI path.
Request parameters
| Field | Required | Type | Description |
|---|---|---|---|
credit_party_identifier |
Yes | Object | Credit party identifier |
retail_rate |
No | Number | Retail rate |
retail_fee |
No | Number | Retail fee |
retail_fee_currency |
No | String | Retail fee currency in ISO 4217 format |
sender |
Yes† | Object | Sender information |
beneficiary |
Yes† | Object | Beneficiary information |
sending_business |
Yes† | Object | Sending business information |
receiving_business |
Yes† | Object | Receiving business information |
external_id |
Yes | String | External ID |
external_code |
No | String | External reference code |
callback_url |
No | String | Callback URL |
purpose_of_remittance |
Yes | String | Purpose of the remittance |
document_reference_number |
B2B: Yes Other: No |
String | Reference number of document related to the transaction |
additional_information_1 |
No | String | Additional information |
additional_information_2 |
No | String | Additional information |
additional_information_3 |
No | String | Additional information |
reference |
No | String | Reference value that will be reflected on the Beneficiary’s/Receiving Business’ statement |
†: Requiredness will depend on the chosen transaction type, quotation of type :
- C2C will require a sender and a beneficiary
- C2B will require a sender and a receiving business
- B2C will require a sending business and a beneficiary
- B2B will require a sending business and a receiving business
Returns
Transaction object.
Create a transaction from a quotation external id
POST /v2/money-transfer/quotations/ext-1481184321405/transactions HTTP/1.1
201 Created{
"credit_party_identifier": {
"msisdn": "+263775892100",
"bank_account_number": "0123456789",
"swift_bic_code": "ABCDEFGH"
},
"sender": {
"lastname": "Doe",
"firstname": "John",
"nationality_country_iso_code": "FRA",
"date_of_birth": "1970-01-01",
"country_of_birth_iso_code": "FRA",
"gender": "MALE",
"address": "42 Rue des fleurs",
"postal_code": "75000",
"city": "Paris",
"country_iso_code": "FRA",
"msisdn": "33712345678",
"email": "john.doe@mail.com",
"id_type": "SOCIAL_SECURITY",
"id_number": "502-42-0158",
"id_delivery_date": "2016-01-01",
"occupation": "Residential Advisor"
},
"beneficiary": {
"lastname": "Doe",
"firstname": "Jane",
"nationality_country_iso_code": "FRA",
"date_of_birth": "1971-01-01",
"country_of_birth_iso_code": "ZWE",
"gender": "MALE",
"address": "3 Norfolk Road",
"postal_code": "4581",
"city": "Harare",
"country_iso_code": "ZWE",
"msisdn": "263775892364",
"email": "jane.doe@mail.com",
"id_type": "SOCIAL_SECURITY",
"id_country_iso_code": "ZWE",
"id_number": "178027317681327",
"occupation": "Sales Executive"
},
"external_id": "1478078339357",
"retail_fee": 1,
"retail_fee_currency": "EUR",
"purpose_of_remittance": "FAMILY_SUPPORT",
"document_reference_number": "12345678",
"callback_url": "{URL_PLACEHOLDER}"
}{
"id": 1,
"status": "10000",
"status_message": "CREATED",
"status_class": "1",
"status_class_message": "CREATED",
"external_id": "1478078339357",
"external_code": null,
"transaction_type": "C2C",
"payer_transaction_reference": null,
"payer_transaction_code": null,
"creation_date": "2016-11-02T09:19:15",
"expiration_date": "2016-11-03T09:07:44",
"credit_party_identifier": {
"msisdn": "+263775892100",
"bank_account_number": "0123456789",
"swift_bic_code": "ABCDEFGH"
},
"source": {
"country_iso_code": "FRA",
"currency": "EUR",
"amount": 10
},
"destination": {
"currency": "USD",
"amount": 10.69
},
"payer": {
"id": 1,
"name": "Sample Payer",
"currency": "USD",
"country_iso_code": "ZWE",
"service": {
"id": 1,
"name": "MobileWallet"
}
},
"sender": {
"lastname": "Doe",
"lastname2": null,
"middlename": null,
"firstname": "John",
"nativename": null,
"nationality_country_iso_code": "FRA",
"code": null,
"date_of_birth": "1970-01-01",
"country_of_birth_iso_code": "FRA",
"gender": "MALE",
"address": "42 Rue des fleurs",
"postal_code": "75000",
"city": "Paris",
"country_iso_code": "FRA",
"msisdn": "33712345678",
"email": "john.doe@mail.com",
"id_type": "SOCIAL_SECURITY",
"id_country_iso_code": null,
"id_number": "502-42-0158",
"id_delivery_date": "2016-01-01",
"id_expiration_date": null,
"occupation": "Residential Advisor",
"province_state": null,
"beneficiary_relationship": null,
"source_of_funds": null,
"bank_account_number": null
},
"beneficiary": {
"lastname": "Doe",
"lastname2": null,
"middlename": null,
"firstname": "Jane",
"nativename": null,
"nationality_country_iso_code": "FRA",
"code": null,
"date_of_birth": "1971-01-01",
"country_of_birth_iso_code": "ZWE",
"gender": "MALE",
"address": "3 Norfolk Road",
"postal_code": "4581",
"city": "Harare",
"country_iso_code": "ZWE",
"msisdn": "263775892364",
"email": "jane.doe@mail.com",
"id_type": "SOCIAL_SECURITY",
"id_country_iso_code": "ZWE",
"id_number": "178027317681327",
"id_delivery_date": null,
"id_expiration_date": null,
"occupation": "Sales Executive",
"bank_account_holder_name": null,
"province_state": null
},
"callback_url": "{URL_PLACEHOLDER}",
"sent_amount": {
"currency": "EUR",
"amount": 10
},
"wholesale_fx_rate": 1.06891969534071,
"retail_rate": null,
"retail_fee": 1,
"retail_fee_currency": "EUR",
"fee": {
"currency": "EUR",
"amount": 1.88
},
"purpose_of_remittance": "FAMILY_SUPPORT",
"document_reference_number": "12345678",
"additional_information_1": null,
"additional_information_2": null,
"additional_information_3": null,
"reference": null
}POST /v2/money-transfer/quotations/ext-{external_id}/transactions
Create a new transaction with transfer values specified from a given quotation based on the external ID. The external ID of the quotation must be supplied replacing {external_id} in the URI path.
Request parameters
| Field | Required | Type | Description |
|---|---|---|---|
credit_party_identifier |
Yes | Object | Credit party identifier |
retail_rate |
No | Number | Retail rate |
retail_fee |
No | Number | Retail fee |
retail_fee_currency |
No | String | Retail fee currency in ISO 4217 format |
sender |
Yes | Object | Sender information |
beneficiary |
Yes | Object | Beneficiary information |
external_id |
Yes | String | External ID |
external_code |
No | String | External reference code |
callback_url |
No | String | Callback URL |
purpose_of_remittance |
Yes | String | Purpose of the remittance |
document_reference_number |
B2B: Yes Other: No |
String | Reference number of document related to the transaction |
additional_information_1 |
No | String | Additional information |
additional_information_2 |
No | String | Additional information |
additional_information_3 |
No | String | Additional information |
reference |
No | String | Reference value that will be reflected on the Beneficiary’s/Receiving Business’ statement |
Returns
Transaction object.
Add attachment to a transaction by id
POST /v2/money-transfer/transactions/1/attachments HTTP/1.1
201 OK
name=invoice.pdf
type=invoie
file=./invoice.pdf{
"id": 1,
"content_type": "application/pdf",
"name": "invoice.pdf",
"transaction_id": 1,
"type": "invoice"
}POST /v2/money-transfer/transactions/{id}/attachments
Add an attachment to a transaction. The id of the transaction must be supplied replacing {id} in the URI path.
To upload an attachment to a transaction, you’ll need to send a request of type multipart/form-data.
Request parameters
| Field | Required | Type | Description |
|---|---|---|---|
name |
Yes | String | Name of the attachment |
type |
Yes | String | Transaction attachment type |
file |
Yes | File | File to upload as an attachment |
- Maximum of 3 files per transaction (mix of different Transaction attachment type)
- Maximum size of 8MB per file
- Only specific file types are allowed (Transaction attachment allowed file types)
Returns
Transaction Attachment object.
Add attachment to a transaction by external id
POST /v2/money-transfer/transactions/ext-ABC123/attachments HTTP/1.1
201 OK
name=invoice.pdf
type=invoie
file=./invoice.pdf{
"id": 1,
"content_type": "application/pdf",
"name": "invoice.pdf",
"transaction_id": 1,
"type": "invoice"
}POST /v2/money-transfer/transactions/ext-{external_id}/attachments
Add an attachment to a transaction. The external ID of the quotation must be supplied replacing {external_id} in the URI path.
To upload an attachment to a transaction, you’ll need to send a request of type multipart/form-data.
Request parameters
| Field | Required | Type | Description |
|---|---|---|---|
name |
Yes | String | Name of the attachment |
type |
Yes | String | Transaction attachment type |
file |
Yes | File | File to upload as an attachment |
Returns
Transaction Attachment object.
Confirm a transaction by id
POST /v2/money-transfer/transactions/1/confirm HTTP/1.1
200 OK{
"id": 1,
"status": "20000",
"status_message": "CONFIRMED",
"status_class": "2",
"status_class_message": "CONFIRMED",
"external_id": "1478078339357",
"external_code": null,
"transaction_type": "C2C",
"payer_transaction_reference": null,
"payer_transaction_code": null,
"creation_date": "2016-11-02T09:19:15",
"expiration_date": "2016-11-03T09:07:44",
"credit_party_identifier": {
"msisdn": "+263775892100",
"bank_account_number": "0123456789",
"swift_bic_code": "ABCDEFGH"
},
"source": {
"country_iso_code": "FRA",
"currency": "EUR",
"amount": 10
},
"destination": {
"currency": "USD",
"amount": 10.69
},
"payer": {
"id": 1,
"name": "Sample Payer",
"currency": "USD",
"country_iso_code": "ZWE",
"service": {
"id": 1,
"name": "MobileWallet"
}
},
"sender": {
"lastname": "Doe",
"lastname2": null,
"middlename": null,
"firstname": "John",
"nativename": null,
"nationality_country_iso_code": "FRA",
"code": null,
"date_of_birth": "1970-01-01",
"country_of_birth_iso_code": "FRA",
"gender": "MALE",
"address": "42 Rue des fleurs",
"postal_code": "75000",
"city": "Paris",
"country_iso_code": "FRA",
"msisdn": "33712345678",
"email": "john.doe@mail.com",
"id_type": "SOCIAL_SECURITY",
"id_country_iso_code": null,
"id_number": "502-42-0158",
"id_delivery_date": "2016-01-01",
"id_expiration_date": null,
"occupation": "Residential Advisor",
"province_state": null,
"beneficiary_relationship": null,
"source_of_funds": null,
"bank_account_number": null
},
"beneficiary": {
"lastname": "Doe",
"lastname2": null,
"middlename": null,
"firstname": "Jane",
"nativename": null,
"nationality_country_iso_code": "FRA",
"code": null,
"date_of_birth": "1971-01-01",
"country_of_birth_iso_code": "ZWE",
"gender": "MALE",
"address": "3 Norfolk Road",
"postal_code": "4581",
"city": "Harare",
"country_iso_code": "ZWE",
"msisdn": "263775892364",
"email": "jane.doe@mail.com",
"id_type": "SOCIAL_SECURITY",
"id_country_iso_code": "ZWE",
"id_number": "178027317681327",
"id_delivery_date": null,
"id_expiration_date": null,
"occupation": "Sales Executive",
"bank_account_holder_name": null,
"province_state": null
},
"callback_url": "{URL_PLACEHOLDER}",
"sent_amount": {
"currency": "EUR",
"amount": 10
},
"wholesale_fx_rate": 1.06891969534071,
"retail_rate": null,
"retail_fee": 1,
"retail_fee_currency": "EUR",
"fee": {
"currency": "EUR",
"amount": 1.88
},
"purpose_of_remittance": "FAMILY_SUPPORT",
"document_reference_number": null,
"additional_information_1": null,
"additional_information_2": null,
"additional_information_3": null
}POST /v2/money-transfer/transactions/{id}/confirm
Confirm a previously-created transaction to initiate processing. The id of the transaction must be supplied replacing {id} in the URI path.
Returns
Transaction object.
Confirm a transaction by external id
POST /v2/money-transfer/transactions/ext-1478078339357/confirm HTTP/1.1
200 OK{
"id": 1,
"status": "20000",
"status_message": "CONFIRMED",
"status_class": "2",
"status_class_message": "CONFIRMED",
"external_id": "1478078339357",
"external_code": null,
"transaction_type": "C2C",
"payer_transaction_reference": null,
"payer_transaction_code": null,
"creation_date": "2016-11-02T09:19:15",
"expiration_date": "2016-11-03T09:07:44",
"credit_party_identifier": {
"msisdn": "+263775892100",
"bank_account_number": "0123456789",
"swift_bic_code": "ABCDEFGH"
},
"source": {
"country_iso_code": "FRA",
"currency": "EUR",
"amount": 10
},
"destination": {
"currency": "USD",
"amount": 10.69
},
"payer": {
"id": 1,
"name": "Sample Payer",
"currency": "USD",
"country_iso_code": "ZWE",
"service": {
"id": 1,
"name": "MobileWallet"
}
},
"sender": {
"lastname": "Doe",
"lastname2": null,
"middlename": null,
"firstname": "John",
"nativename": null,
"nationality_country_iso_code": "FRA",
"code": null,
"date_of_birth": "1970-01-01",
"country_of_birth_iso_code": "FRA",
"gender": "MALE",
"address": "42 Rue des fleurs",
"postal_code": "75000",
"city": "Paris",
"country_iso_code": "FRA",
"msisdn": "33712345678",
"email": "john.doe@mail.com",
"id_type": "SOCIAL_SECURITY",
"id_country_iso_code": null,
"id_number": "502-42-0158",
"id_delivery_date": "2016-01-01",
"id_expiration_date": null,
"occupation": "Residential Advisor",
"province_state": null,
"beneficiary_relationship": null,
"source_of_funds": null,
"bank_account_number": null
},
"beneficiary": {
"lastname": "Doe",
"lastname2": null,
"middlename": null,
"firstname": "Jane",
"nativename": null,
"nationality_country_iso_code": "FRA",
"code": null,
"date_of_birth": "1971-01-01",
"country_of_birth_iso_code": "ZWE",
"gender": "MALE",
"address": "3 Norfolk Road",
"postal_code": "4581",
"city": "Harare",
"country_iso_code": "ZWE",
"msisdn": "263775892364",
"email": "jane.doe@mail.com",
"id_type": "SOCIAL_SECURITY",
"id_country_iso_code": "ZWE",
"id_number": "178027317681327",
"id_delivery_date": null,
"id_expiration_date": null,
"occupation": "Sales Executive",
"bank_account_holder_name": null,
"province_state": null
},
"callback_url": "{URL_PLACEHOLDER}",
"sent_amount": {
"currency": "EUR",
"amount": 10
},
"wholesale_fx_rate": 1.06891969534071,
"retail_rate": null,
"retail_fee": 1,
"retail_fee_currency": "EUR",
"fee": {
"currency": "EUR",
"amount": 1.88
},
"purpose_of_remittance": "FAMILY_SUPPORT",
"document_reference_number": null,
"additional_information_1": null,
"additional_information_2": null,
"additional_information_3": null
}POST /v2/money-transfer/transactions/ext-{external_id}/confirm
Confirm a previously-created transaction, through an external ID, to initiate processing. The external ID of the quotation must be supplied replacing {external_id} in the URI path.
Returns
Transaction object.
Retrieve transaction information by transaction id
GET /v2/money-transfer/transactions/1 HTTP/1.1
200 OK{
"id": 1,
"status": "50000",
"status_message": "SUBMITTED",
"status_class": "5",
"status_class_message": "SUBMITTED",
"external_id": "1478078339357",
"external_code": null,
"transaction_type": "C2C",
"payer_transaction_reference": null,
"payer_transaction_code": null,
"creation_date": "2016-11-02T09:19:15",
"expiration_date": "2016-11-03T09:07:44",
"credit_party_identifier": {
"msisdn": "+263775892100",
"bank_account_number": "0123456789",
"swift_bic_code": "ABCDEFGH"
},
"source": {
"country_iso_code": "FRA",
"currency": "EUR",
"amount": 10
},
"destination": {
"currency": "USD",
"amount": 10.69
},
"payer": {
"id": 1,
"name": "Sample Payer",
"currency": "USD",
"country_iso_code": "ZWE",
"service": {
"id": 1,
"name": "MobileWallet"
}
},
"sender": {
"lastname": "Doe",
"lastname2": null,
"middlename": null,
"firstname": "John",
"nativename": null,
"nationality_country_iso_code": "FRA",
"code": null,
"date_of_birth": "1970-01-01",
"country_of_birth_iso_code": "FRA",
"gender": "MALE",
"address": "42 Rue des fleurs",
"postal_code": "75000",
"city": "Paris",
"country_iso_code": "FRA",
"msisdn": "33712345678",
"email": "john.doe@mail.com",
"id_type": "SOCIAL_SECURITY",
"id_country_iso_code": null,
"id_number": "502-42-0158",
"id_delivery_date": "2016-01-01",
"id_expiration_date": null,
"occupation": "Residential Advisor",
"province_state": null,
"beneficiary_relationship": null,
"source_of_funds": null,
"bank_account_number": null
},
"beneficiary": {
"lastname": "Doe",
"lastname2": null,
"middlename": null,
"firstname": "Jane",
"nativename": null,
"nationality_country_iso_code": "FRA",
"code": null,
"date_of_birth": "1971-01-01",
"country_of_birth_iso_code": "ZWE",
"gender": "MALE",
"address": "3 Norfolk Road",
"postal_code": "4581",
"city": "Harare",
"country_iso_code": "ZWE",
"msisdn": "263775892364",
"email": "jane.doe@mail.com",
"id_type": "SOCIAL_SECURITY",
"id_country_iso_code": "ZWE",
"id_number": "178027317681327",
"id_delivery_date": null,
"id_expiration_date": null,
"occupation": "Sales Executive",
"bank_account_holder_name": null,
"province_state": null
},
"callback_url": "{URL_PLACEHOLDER}",
"sent_amount": {
"currency": "EUR",
"amount": 10
},
"wholesale_fx_rate": 1.06891969534071,
"retail_rate": null,
"retail_fee": 1,
"retail_fee_currency": "EUR",
"fee": {
"currency": "EUR",
"amount": 1.88
},
"purpose_of_remittance": "FAMILY_SUPPORT",
"document_reference_number": null,
"additional_information_1": null,
"additional_information_2": null,
"additional_information_3": null
}GET /v2/money-transfer/transactions/{id}
Retrieve information for a given transaction. The id of the transaction must be supplied replacing {id} in the URI path.
Returns
Transaction object.
Retrieve transaction information by external id
GET /v2/money-transfer/transactions/ext-1478078339357 HTTP/1.1
200 OK{
"id": 1,
"status": "50000",
"status_message": "SUBMITTED",
"status_class": "5",
"status_class_message": "SUBMITTED",
"external_id": "1478078339357",
"external_code": null,
"transaction_type": "C2C",
"payer_transaction_reference": null,
"payer_transaction_code": null,
"creation_date": "2016-11-02T09:19:15",
"expiration_date": "2016-11-03T09:07:44",
"credit_party_identifier": {
"msisdn": "+263775892100",
"bank_account_number": "0123456789",
"swift_bic_code": "ABCDEFGH"
},
"source": {
"country_iso_code": "FRA",
"currency": "EUR",
"amount": 10
},
"destination": {
"currency": "USD",
"amount": 10.69
},
"payer": {
"id": 1,
"name": "Sample Payer",
"currency": "USD",
"country_iso_code": "ZWE",
"service": {
"id": 1,
"name": "MobileWallet"
}
},
"sender": {
"lastname": "Doe",
"lastname2": null,
"middlename": null,
"firstname": "John",
"nativename": null,
"nationality_country_iso_code": "FRA",
"code": null,
"date_of_birth": "1970-01-01",
"country_of_birth_iso_code": "FRA",
"gender": "MALE",
"address": "42 Rue des fleurs",
"postal_code": "75000",
"city": "Paris",
"country_iso_code": "FRA",
"msisdn": "33712345678",
"email": "john.doe@mail.com",
"id_type": "SOCIAL_SECURITY",
"id_country_iso_code": null,
"id_number": "502-42-0158",
"id_delivery_date": "2016-01-01",
"id_expiration_date": null,
"occupation": "Residential Advisor",
"province_state": null,
"beneficiary_relationship": null,
"source_of_funds": null,
"bank_account_number": null
},
"beneficiary": {
"lastname": "Doe",
"lastname2": null,
"middlename": null,
"firstname": "Jane",
"nativename": null,
"nationality_country_iso_code": "FRA",
"code": null,
"date_of_birth": "1971-01-01",
"country_of_birth_iso_code": "ZWE",
"gender": "MALE",
"address": "3 Norfolk Road",
"postal_code": "4581",
"city": "Harare",
"country_iso_code": "ZWE",
"msisdn": "263775892364",
"email": "jane.doe@mail.com",
"id_type": "SOCIAL_SECURITY",
"id_country_iso_code": "ZWE",
"id_number": "178027317681327",
"id_delivery_date": null,
"id_expiration_date": null,
"occupation": "Sales Executive",
"bank_account_holder_name": null,
"province_state": null
},
"callback_url": "{URL_PLACEHOLDER}",
"sent_amount": {
"currency": "EUR",
"amount": 10
},
"wholesale_fx_rate": 1.06891969534071,
"retail_rate": null,
"retail_fee": 1,
"retail_fee_currency": "EUR",
"fee": {
"currency": "EUR",
"amount": 1.88
},
"purpose_of_remittance": "FAMILY_SUPPORT",
"document_reference_number": null,
"additional_information_1": null,
"additional_information_2": null,
"additional_information_3": null
}GET /v2/money-transfer/transactions/ext-{external_id}
Retrieve information for a given transaction from an external ID. The external ID of the quotation must be supplied replacing {external_id} in the URI path.
Returns
Transaction object.
List attachments of a transaction by id
GET /v2/money-transfer/transactions/1/attachments HTTP/1.1
200 OK[
{
"id": 1,
"content_type": "application/pdf",
"name": "invoice.pdf",
"transaction_id": 1,
"type": "invoice"
},
{
"id": 2,
"content_type": "application/pdf",
"name": "po.pdf",
"transaction_id": 1,
"type": "purchase_order"
}
]GET /v2/money-transfer/transactions/{id}/attachments
List attachments related to a transaction. The id of the transaction must be supplied replacing {id} in the URI path.
Returns
List of Transaction Attachment object.
List attachments of a transaction by external id
GET /v2/money-transfer/transactions/ext-ABC123/attachments HTTP/1.1
200 OK[
{
"id": 1,
"content_type": "application/pdf",
"name": "invoice.pdf",
"transaction_id": 1,
"type": "invoice"
},
{
"id": 2,
"content_type": "application/pdf",
"name": "po.pdf",
"transaction_id": 1,
"type": "purchase_order"
}
]GET /v2/money-transfer/transactions/ext-{external-id}/attachments
List attachments related to a transaction. The external ID of the quotation must be supplied replacing {external_id} in the URI path.
Returns
List of Transaction Attachment object.
Cancel a transaction by id
POST /v2/money-transfer/transactions/1/cancel HTTP/1.1
200 OK{
"id": 1,
"status": "40000",
"status_message": "CANCELLED",
"status_class": "4",
"status_class_message": "CANCELLED",
"external_id": "1478078339357",
"external_code": null,
"transaction_type": "C2C",
"payer_transaction_reference": null,
"payer_transaction_code": null,
"creation_date": "2016-11-02T09:19:15",
"expiration_date": "2016-11-03T09:07:44",
"credit_party_identifier": {
"msisdn": "+263775892100",
"bank_account_number": "0123456789",
"swift_bic_code": "ABCDEFGH"
},
"source": {
"country_iso_code": "FRA",
"currency": "EUR",
"amount": 10
},
"destination": {
"currency": "USD",
"amount": 10.69
},
"payer": {
"id": 1,
"name": "Sample Payer",
"currency": "USD",
"country_iso_code": "ZWE",
"service": {
"id": 1,
"name": "MobileWallet"
}
},
"sender": {
"lastname": "Doe",
"lastname2": null,
"middlename": null,
"firstname": "John",
"nativename": null,
"nationality_country_iso_code": "FRA",
"code": null,
"date_of_birth": "1970-01-01",
"country_of_birth_iso_code": "FRA",
"gender": "MALE",
"address": "42 Rue des fleurs",
"postal_code": "75000",
"city": "Paris",
"country_iso_code": "FRA",
"msisdn": "33712345678",
"email": "john.doe@mail.com",
"id_type": "SOCIAL_SECURITY",
"id_country_iso_code": null,
"id_number": "502-42-0158",
"id_delivery_date": "2016-01-01",
"id_expiration_date": null,
"occupation": "Residential Advisor",
"province_state": null,
"beneficiary_relationship": null,
"source_of_funds": null,
"bank_account_number": null
},
"beneficiary": {
"lastname": "Doe",
"lastname2": null,
"middlename": null,
"firstname": "Jane",
"nativename": null,
"nationality_country_iso_code": "FRA",
"code": null,
"date_of_birth": "1971-01-01",
"country_of_birth_iso_code": "ZWE",
"gender": "MALE",
"address": "3 Norfolk Road",
"postal_code": "4581",
"city": "Harare",
"country_iso_code": "ZWE",
"msisdn": "263775892364",
"email": "jane.doe@mail.com",
"id_type": "SOCIAL_SECURITY",
"id_country_iso_code": "ZWE",
"id_number": "178027317681327",
"id_delivery_date": null,
"id_expiration_date": null,
"occupation": "Sales Executive",
"bank_account_holder_name": null,
"province_state": null
},
"callback_url": "{URL_PLACEHOLDER}",
"sent_amount": {
"currency": "EUR",
"amount": 10
},
"wholesale_fx_rate": 1.06891969534071,
"retail_rate": null,
"retail_fee": 1,
"retail_fee_currency": "EUR",
"fee": {
"currency": "EUR",
"amount": 1.88
},
"purpose_of_remittance": "FAMILY_SUPPORT",
"document_reference_number": null,
"additional_information_1": null,
"additional_information_2": null,
"additional_information_3": null
}POST /v2/money-transfer/transactions/{id}/cancel
When sending a cash pickup transaction, and a transaction is in status CONFIRMED-WAITING-FOR-PICKUP, a partner can call the API to cancel the previously-created transaction. The ID of transaction must be supplied replacing {id} in the URI path.
Returns
Transaction object.
If the action can’t be performed, an error 1007014 (Transaction can not be cancelled) will be returned
Cancel a transaction by external id
POST /v2/money-transfer/transactions/ext-1478078339357/cancel HTTP/1.1
200 OK{
"id": 1,
"status": "40000",
"status_message": "CANCELLED",
"status_class": "4",
"status_class_message": "CANCELLED",
"external_id": "1478078339357",
"external_code": null,
"transaction_type": "C2C",
"payer_transaction_reference": null,
"payer_transaction_code": null,
"creation_date": "2016-11-02T09:19:15",
"expiration_date": "2016-11-03T09:07:44",
"credit_party_identifier": {
"msisdn": "+263775892100",
"bank_account_number": "0123456789",
"swift_bic_code": "ABCDEFGH"
},
"source": {
"country_iso_code": "FRA",
"currency": "EUR",
"amount": 10
},
"destination": {
"currency": "USD",
"amount": 10.69
},
"payer": {
"id": 1,
"name": "Sample Payer",
"currency": "USD",
"country_iso_code": "ZWE",
"service": {
"id": 1,
"name": "MobileWallet"
}
},
"sender": {
"lastname": "Doe",
"lastname2": null,
"middlename": null,
"firstname": "John",
"nativename": null,
"nationality_country_iso_code": "FRA",
"code": null,
"date_of_birth": "1970-01-01",
"country_of_birth_iso_code": "FRA",
"gender": "MALE",
"address": "42 Rue des fleurs",
"postal_code": "75000",
"city": "Paris",
"country_iso_code": "FRA",
"msisdn": "33712345678",
"email": "john.doe@mail.com",
"id_type": "SOCIAL_SECURITY",
"id_country_iso_code": null,
"id_number": "502-42-0158",
"id_delivery_date": "2016-01-01",
"id_expiration_date": null,
"occupation": "Residential Advisor",
"province_state": null,
"beneficiary_relationship": null,
"source_of_funds": null,
"bank_account_number": null
},
"beneficiary": {
"lastname": "Doe",
"lastname2": null,
"middlename": null,
"firstname": "Jane",
"nativename": null,
"nationality_country_iso_code": "FRA",
"code": null,
"date_of_birth": "1971-01-01",
"country_of_birth_iso_code": "ZWE",
"gender": "MALE",
"address": "3 Norfolk Road",
"postal_code": "4581",
"city": "Harare",
"country_iso_code": "ZWE",
"msisdn": "263775892364",
"email": "jane.doe@mail.com",
"id_type": "SOCIAL_SECURITY",
"id_country_iso_code": "ZWE",
"id_number": "178027317681327",
"id_delivery_date": null,
"id_expiration_date": null,
"occupation": "Sales Executive",
"bank_account_holder_name": null,
"province_state": null
},
"callback_url": "{URL_PLACEHOLDER}",
"sent_amount": {
"currency": "EUR",
"amount": 10
},
"wholesale_fx_rate": 1.06891969534071,
"retail_rate": null,
"retail_fee": 1,
"retail_fee_currency": "EUR",
"fee": {
"currency": "EUR",
"amount": 1.88
},
"purpose_of_remittance": "FAMILY_SUPPORT",
"document_reference_number": null,
"additional_information_1": null,
"additional_information_2": null,
"additional_information_3": null
}POST /v2/money-transfer/transactions/ext-{external_id}/cancel
When sending a cash pickup transaction, and a transaction is in status CONFIRMED-WAITING-FOR-PICKUP, a partner can call the API to cancel the previously-created transaction, through its external ID, to initiate processing. The external ID of transaction must be supplied replacing {external_id} in the URI path.
Returns
Transaction object.
If the action can’t be performed, an error 1007014 (Transaction can not be cancelled) will be returned
Resources
Resources
Designed around REST principles, data are passed to and from endpoints of the API as resources. These resources are expressed as objects in JSON, and are described in more detail below.
Service
{
"id": 1,
"name": "MobileWallet"
}Represents a money transfer service. For an example of such a service, refer to the JSON object.
| Field | Type | Description |
|---|---|---|
id |
Integer | Service ID |
name |
String | Service name |
Payer
{
"id": 3,
"name": "Sample Payer",
"precision": 0,
"increment": 1,
"currency": "IDR",
"country_iso_code": "IDN",
"minimum_transaction_amount": 0,
"maximum_transaction_amount": null,
"service": {
"id": 1,
"name": "MobileWallet"
},
"transaction_types": {
"C2C" : {
"credit_party_identifiers_accepted": [
[
"msisdn"
]
],
"required_sending_entity_fields": [
[
"firstname",
"date_of_birth",
"lastname"
]
],
"required_receiving_entity_fields": [
[
"firstname",
"lastname"
]
],
"required_documents": [
[
"invoice",
"purchase_order",
"contract"
]
],
"credit_party_information": {
"credit_party_identifiers_accepted": [
[]
]
},
"credit_party_verification": {
"credit_party_identifiers_accepted": [
[]
],
"required_receiving_entity_fields": [
[]
]
},
"purpose_of_remittance_values_accepted": [
]
}
}
}A payer in Thunes system represents the targeted destination crediting the money into the beneficiary account. For bank account, it would be the bank where the beneficiary of a transaction holds his account, for mobile wallet, the payer will be the mobile wallet receiving the transaction.
| Field | Type | Description |
|---|---|---|
id |
Integer | Payer ID |
name |
String | Payer name |
precision |
Integer | Number of digits after decimal point |
increment |
Number | Unit of increment for transaction amounts |
currency |
String | Currency in ISO-4217 format |
country_iso_code |
String | Country in ISO 3166-1 alpha-3 format |
service |
Object | Service information |
transaction_types |
Object | List of transaction types supported with relevant information |
Additional Information
Click here to view more information on some of our selected payers
Payer summary view
{
"id": 3,
"name": "Sample Payer",
"currency": "IDR",
"country_iso_code": "IDN",
"service": {
"id": 1,
"name": "MobileWallet"
}
}Represents payer information, in summary view. For instance, the summary view excludes transaction types.
| Field | Type | Description |
|---|---|---|
id |
Integer | Payer ID |
name |
String | Payer name |
currency |
String | Currency in ISO-4217 format |
country_iso_code |
String | Country in ISO 3166-1 alpha-3 format |
service |
Object | Service information |
Transaction type information list
{
"C2C" : {
"credit_party_identifiers_accepted": [
[
"msisdn"
]
],
"required_sending_entity_fields": [
[
"firstname",
"date_of_birth",
"lastname"
]
],
"required_receiving_entity_fields": [
[
"firstname",
"lastname"
]
],
"credit_party_information": {
"credit_party_identifiers_accepted": [
[]
]
},
"credit_party_verification": {
"credit_party_identifiers_accepted": [
[]
],
"required_receiving_entity_fields": [
[]
]
}
},
"B2B" : { "...": "..." }
}List of transaction types supported by the Thunes money transfer platform.
| Field | Type | Description |
|---|---|---|
C2C |
Object | Transaction type information relevant to C2C |
C2B |
Object | Transaction type information relevant to C2B |
B2C |
Object | Transaction type information relevant to B2C |
B2B |
Object | Transaction type information relevant to B2B |
Transaction type information
{
"credit_party_identifiers_accepted": [
[
"msisdn"
]
],
"required_sending_entity_fields": [
[
"firstname",
"date_of_birth",
"lastname"
]
],
"required_receiving_entity_fields": [
[
"firstname",
"lastname"
]
],
"required_documents": [
[
"contract",
"invoice"
]
],
"credit_party_information": {
"credit_party_identifiers_accepted": [
[]
]
},
"credit_party_verification": {
"credit_party_identifiers_accepted": [
[]
],
"required_receiving_entity_fields": [
[]
]
},
"purpose_of_remittance_values_accepted": [
]
}Defines the data which are required for a particular transaction type.
| Field | Type | Description |
|---|---|---|
minimum_transaction_amount |
Number | Minimum transaction amount |
maximum_transaction_amount |
Number | Maximum transaction amount |
credit_party_identifiers_accepted |
Array | List of accepted credit party identifiers |
required_sending_entity_fields |
Array | List of required sender information |
required_receiving_entity_fields |
Array | List of required beneficiary information |
required_documents |
Array | List of required document types |
credit_party_information |
Object | Required credit party information |
credit_party_verification |
Object | Required credit party verification information |
purpose_of_remittance_values_accepted |
Array | List of accepted Purpose of Remittance |
An empty list of accepted Purpose of Remittance means this Payer can accept all values. Otherwise, this Payer can only accept the values populated in the list.
Rates Per Transaction Type
{
"C2C": {
"EUR": [
{
"source_amount_min": 0,
"source_amount_max": 88,
"wholesale_fx_rate": 1.10847692409526
},
{
"source_amount_min": 88,
"source_amount_max": 8800,
"wholesale_fx_rate": 1.10847692409526
}
]
},
"B2B": {
"EUR": [
"...": "..."
],
}
}Represents the rates information per transaction type for a given payer.
| Field | Type | Description |
|---|---|---|
transaction_type |
Object | a object rates for the specfic transaction type of payer |
Rates
{
"EUR": [
{
"source_amount_min": 0,
"source_amount_max": 88,
"wholesale_fx_rate": 1.10847692409526
},
{
"source_amount_min": 88,
"source_amount_max": 8800,
"wholesale_fx_rate": 1.10847692409526
}
]
}Represents all rate information for a given payer.
| Field | Type | Description |
|---|---|---|
{currency} |
Array | List of payer rate information |
Rate
{
"source_amount_min": 0,
"source_amount_max": 88,
"wholesale_fx_rate": 1.10847692409526
}Describes the range of source amounts that a rate applies to for a given payer.
| Field | Type | Description |
|---|---|---|
source_amount_min |
Number | Minimum source amount value |
source_amount_max |
Number | Maximum source amount value |
wholesale_fx_rate |
Number | Wholesale FX rate |
Balance
{
"id": 1,
"currency": "EUR",
"balance": 10000000,
"pending": 0,
"available": 10000000,
"credit_facility": 0
}Represents the account balance for a given currency.
available = balance - pending + credit_facility
| Field | Type | Description |
|---|---|---|
id |
Integer | Balance ID |
currency |
String | Currency in ISO 4217 format |
balance |
Number | Current balance |
pending |
Number | Amount in transit (Transaction confirmed, not completed nor decliend yet) |
available |
Number | Available amount for transacting |
credit_facility |
Number | Credit facility |
Balance Movement
{
"balance_operation_number": 4376,
"creation_date": "2022-12-01T16:28:03Z",
"movement_type": "PAYOUT_FEES",
"amount": -1.25,
"currency": "USD",
"transaction_reference_id": 123,
"operation": "AUTHORIZE",
"balance": 1162.56,
"pending_balance": -120.39
}Represents a balance movement for a given balance id.
| Field | Type | Description |
|---|---|---|
balance_operation_number |
Integer | Balance Operation number |
creation_date |
Integer | Creation date in HTTP format |
movement_type |
String | Balance Movement Type |
amount |
Number | Amount of the balance movement |
currency |
String | Currency in ISO 4217 format |
transaction_reference_id |
Number | Transaction ID that generated this balance movement. |
operation |
String | Operation on balance |
balance |
Number | Current balance |
pending_balance |
Number | Amount in transit at the time of this recorded movement for Transaction(s) that have not reached a final status |
Balance Topup Instruction
{
"account_code": "GT_XOF1234",
"account_number": "AA0000000000000000000000",
"account_name": "Sample account name",
"iban": "CI00CI0000000000000000000000",
"account_address": "Account address",
"local_account_identifier_type": null,
"local_account_identifier": "",
"bank_name": "Sample bank",
"bank_address": "Bank address",
"swift_code": "ABCDEFGH",
"local_code_type": null,
"local_code": null,
"intermediary_bank_name": null,
"intermediary_bank_swift_code": null,
"correspondant_code": null,
"update_date": "2022-12-01T16:28:03Z",
"creation_date": "2022-12-01T16:28:03Z"
}Represents a balance topup instruction for a given balance id.
| Field | Type | Description |
|---|---|---|
account_code |
String | Account code |
account_number |
String | Bank account number |
iban |
String | Bank account number in IBAN format |
account_address |
String | Account address |
local_account_identifier_type |
String | Local Account Identifier Type |
local_account_identifier |
String | Value of the local account identifer |
bank_name |
String | Bank name |
bank_address |
String | Bank address |
swift_code |
String | SWIFT-BIC code |
local_code_type |
String | Local Code Type |
local_code |
String | Value of the local code |
intermediary_bank_name |
String | Intermediary bank name |
intermediary_bank_swift_code |
String | Intermediary bank SWIFT code |
correspondant_code |
String | Correspondant code |
creation_date |
Integer | Creation date in HTTP format |
update_date |
Integer | Update date in HTTP format |
Quotation
{
"id": 1,
"external_id": "1481184321405",
"payer": {
"id": 1,
"name": "Sample Payer",
"currency": "USD",
"country_iso_code": "ZWE",
"service": {
"id": 1,
"name": "MobileWallet"
}
},
"mode": "SOURCE_AMOUNT",
"transaction_type": "C2C",
"source": {
"country_iso_code": "FRA",
"currency": "EUR",
"amount": 10
},
"destination": {
"currency": "USD",
"amount": 10.69
},
"sent_amount": {
"currency": "EUR",
"amount": 10
},
"wholesale_fx_rate": 1.06891969534071,
"fee": {
"currency": "EUR",
"amount": 1.88
},
"creation_date": "2016-11-02T09:07:44",
"expiration_date": "2016-11-03T09:07:44"
}Represents quotation information used to create transactions.
| Field | Type | Description |
|---|---|---|
id |
Integer | Quotation ID |
external_id |
String | External reference ID. This is the reference for this quotation from the external system. |
payer |
Object | Payer information |
mode |
String | Quotation mode |
transaction_type |
String | Transaction type |
source |
Object | Source information |
destination |
Object | Destination information |
sent_amount |
Object | Sent amount information |
wholesale_fx_rate |
Number | Wholesale FX rate |
fee |
Object | Fee information |
creation_date |
String | Creation date in HTTP format |
expiration_date |
String | Expiration date in HTTP format |
Transaction
{
"id": 1,
"status": "10000",
"status_message": "CREATED",
"status_class": "1",
"status_class_message": "CREATED",
"external_id": "1478078339357",
"external_code": null,
"transaction_type": "C2C",
"payer_transaction_reference": null,
"payer_transaction_code": null,
"creation_date": "2016-11-02T09:19:15",
"expiration_date": "2016-11-03T09:07:44",
"credit_party_identifier": {
"msisdn": "+263775892100",
"bank_account_number": "0123456789",
"swift_bic_code": "ABCDEFGH"
},
"source": {
"country_iso_code": "FRA",
"currency": "EUR",
"amount": 10
},
"destination": {
"currency": "USD",
"amount": 10.69
},
"payer": {
"id": 1,
"name": "Sample Payer",
"currency": "USD",
"country_iso_code": "ZWE",
"service": {
"id": 1,
"name": "MobileWallet"
}
},
"sender": {
"lastname": "Doe",
"lastname2": null,
"middlename": null,
"firstname": "John",
"nativename": null,
"nationality_country_iso_code": "FRA",
"code": null,
"date_of_birth": "1970-01-01",
"country_of_birth_iso_code": "FRA",
"gender": "MALE",
"address": "42 Rue des fleurs",
"postal_code": "75000",
"city": "Paris",
"country_iso_code": "FRA",
"msisdn": "33712345678",
"email": "john.doe@mail.com",
"id_type": "SOCIAL_SECURITY",
"id_country_iso_code": null,
"id_number": "502-42-0158",
"id_delivery_date": "2016-01-01",
"id_expiration_date": null,
"occupation": "Residential Advisor",
"province_state": null,
"beneficiary_relationship": null,
"source_of_funds": null,
"bank_account_number": null
},
"beneficiary": {
"lastname": "Doe",
"lastname2": null,
"middlename": null,
"firstname": "Jane",
"nativename": null,
"nationality_country_iso_code": "FRA",
"code": null,
"date_of_birth": "1971-01-01",
"country_of_birth_iso_code": "ZWE",
"gender": "MALE",
"address": "3 Norfolk Road",
"postal_code": "4581",
"city": "Harare",
"country_iso_code": "ZWE",
"msisdn": "263775892364",
"email": "jane.doe@mail.com",
"id_type": "SOCIAL_SECURITY",
"id_country_iso_code": "ZWE",
"id_number": "178027317681327",
"id_delivery_date": null,
"id_expiration_date": null,
"occupation": "Sales Executive",
"bank_account_holder_name": null,
"province_state": null
},
"callback_url": "{URL_PLACEHOLDER}",
"sent_amount": {
"currency": "EUR",
"amount": 10
},
"wholesale_fx_rate": 1.06891969534071,
"retail_rate": null,
"retail_fee": 1,
"retail_fee_currency": "EUR",
"fee": {
"currency": "EUR",
"amount": 1.88
},
"purpose_of_remittance": "FAMILY_SUPPORT",
"document_reference_number": "12345678",
"additional_information_1": null,
"additional_information_2": null,
"additional_information_3": null,
"reference": null
}Represents transaction information for a transfer request.
| Field | Type | Description |
|---|---|---|
id |
Integer | Transaction ID |
status |
String | Transaction status code |
status_message |
String | Transaction status description |
status_class |
String | Transaction status class |
status_class_message |
String | Transaction status class description |
external_id |
String | External ID |
external_code |
String | External reference code |
transaction_type |
String | Transaction type |
payer_transaction_reference |
String | Payer transaction reference |
payer_transaction_code |
String | Payer transaction code |
creation_date |
String | Creation date in HTTP format |
expiration_date |
String | Expiration date in HTTP format |
credit_party_identifier |
Object | Credit party information |
source |
Object | Source information |
destination |
Object | Destination information |
payer |
Object | Payer information |
sender |
Object | Sender information |
beneficiary |
Object | Beneficiary information |
sending_business |
Object | Sending business information |
receiving_business |
Object | Receiving business information |
callback_url |
String | Callback URL |
sent_amount |
Object | Sent amount information |
wholesale_fx_rate |
Number | Wholesale FX rate |
retail_rate |
Number | Retail rate |
retail_fee |
Number | Retail fee |
retail_fee_currency |
String | Retail fee currency in ISO 4217 format |
fee |
Object | Fee information |
purpose_of_remittance |
String | Purpose of remittance |
document_reference_number |
String | Reference number of document related to the transaction |
additional_information_1 |
String | Additional information |
additional_information_2 |
String | Additional information |
additional_information_3 |
String | Additional information |
reference |
String | Reference value that will be reflected on the Beneficiary’s/Receiving Business’ statement |
Fields sender, beneficiary, sending_business, receiving_business will be present depending on the transaction type.
Transaction attachment
{
"id": 1,
"content_type": "application/pdf",
"name": "invoice.pdf",
"transaction_id": 1,
"type": "invoice"
}Represents an attachment which has been added to a transaction.
| Field | Type | Description |
|---|---|---|
id |
Integer | Transaction Attachment ID |
transaction_id |
Integer | Transaction ID of related Transaction |
name |
String | Name of the attachment |
content_type |
String | Content type of the attachment |
type |
String | Transaction attachment type |
Source
{
"country_iso_code": "FRA",
"currency": "EUR",
"amount": 10
}Represents source amount details for a given transaction.
| Field | Required | Type | Description |
|---|---|---|---|
country_iso_code |
Yes | String | Country code in ISO 3166-1 alpha-3 format |
currency |
Yes | String | Source currency in ISO 4217 format |
amount |
Yes† | Number | Source amount |
† : Required when chosen mode is SOURCE_AMOUNT
Destination
{
"currency": "USD",
"amount": 10
}Represents destination amount details for a given transaction.
| Field | Required | Type | Description |
|---|---|---|---|
currency |
Yes | String | Destination currency in ISO 4217 format |
amount |
Yes† | Number | Destination amount |
†: Required when chosen mode is DESTINATION_AMOUNT
Credit Party Identifier
{
"msisdn": "263775892100",
"bank_account_number": "0123456789",
"swift_bic_code": "ABCDEFGH"
}Represents identification details for a given credit party.
| Field | Required | Type | Description |
|---|---|---|---|
msisdn |
No† | String | MSISDN in international format |
bank_account_number |
No† | String | Bank account number |
iban |
No† | String | Bank account number in IBAN format |
clabe |
No† | String | Bank account number in CLABE format |
cbu |
No† | String | Bank account number in CBU format |
cbu_alias |
No† | String | Bank account number in CBU ALIAS format |
swift_bic_code |
No† | String | SWIFT-BIC code |
bik_code |
No† | String | Russian BIK code |
ifs_code |
No† | String | IFSC code |
sort_code |
No† | String | Sort code |
aba_routing_number |
No† | String | ABA Routing Transfer Number |
bsb_number |
No† | String | BSB number |
branch_number |
No† | String | Branch number |
routing_code |
No† | String | Routing code |
entity_tt_id |
No† | Int | Entity ID |
account_type |
No† | String | Account type |
account_number |
No† | String | Account number |
email |
No† | String | Email address |
card_number |
No† | String | Card Number |
†: Requiredness will depend on the payer configuration
Required Credit Party Information
{
"credit_party_identifiers_accepted": [
[
"msisdn"
]
]
}Represents required credit party identifiers to perform a credit party information request.
| Field | Required | Type | Description |
|---|---|---|---|
credit_party_identifiers_accepted |
Yes | Array | List of credit party identifier fields |
Required Credit Party Verification
{
"credit_party_verification": {
"credit_party_identifiers_accepted": [
[
"msisdn"
]
],
"required_receiving_entity_fields": [
[
"msisdn",
"firstname",
"lastname"
]
]
}
}Represents required credit party identifiers to perform a credit party verification request.
| Field | Required | Type | Description |
|---|---|---|---|
credit_party_identifiers_accepted |
Yes | Array | List of credit party identifier fields |
required_receiving_entity_fields |
Yes | Array | List of required receiving entity information |
Sender
{
"lastname": "Doe",
"lastname2": null,
"middlename": null,
"firstname": "John",
"nativename": null,
"nationality_country_iso_code": "FRA",
"code": null,
"date_of_birth": "1970-01-01",
"country_of_birth_iso_code": "FRA",
"gender": "MALE",
"address": "42 Rue des fleurs",
"postal_code": "75000",
"city": "Paris",
"country_iso_code": "FRA",
"msisdn": "33712345678",
"email": "john.doe@mail.com",
"id_type": "SOCIAL_SECURITY",
"id_country_iso_code": null,
"id_number": "502-42-0158",
"id_delivery_date": "2016-01-01",
"id_expiration_date": null,
"occupation": "Residential Advisor",
"province_state": null,
"beneficiary_relationship": null,
"source_of_funds": null
}Represents sender information for a given transaction of type C2C or C2B.
| Field | Required | Type | Description |
|---|---|---|---|
lastname |
No† | String | Last name |
lastname2 |
No† | String | Additional last name(s) |
middlename |
No† | String | Middle name |
firstname |
No† | String | First name |
nativename |
No† | String | Full name in native characters |
nationality_country_iso_code |
No† | String | Nationality in ISO 3166-1 alpha-3 format |
code |
No† | String | Sender identification code |
date_of_birth |
No† | String | Date of birth in ISO 8601 format |
country_of_birth_iso_code |
No† | String | Country of birth in ISO 3166-1 alpha-3 format |
gender |
No† | String | Gender |
address |
No† | String | Address |
postal_code |
No† | String | Postal code |
city |
No† | String | City |
country_iso_code |
No† | String | Address country in ISO 3166-1 alpha-3 format |
msisdn |
No† | String | MSISDN in international format |
email |
No† | String | Email address |
id_type |
No† | String | Presented identification type |
id_country_iso_code |
No† | String | ID country in ISO 3166-1 alpha-3 format |
id_number |
No† | String | Presented identification number |
id_delivery_date |
No† | String | ID delivery date in ISO 8601 format |
id_expiration_date |
No† | String | ID expiration date in ISO 8601 format |
occupation |
No† | String | Occupation |
bank_account_number |
No† | String | Bank account number |
province_state |
No† | String | Address province/state |
beneficiary_relationship |
No† | String | Relationship to beneficiary |
source_of_funds |
No† | String | Source of funds |
†: Requiredness will depend on payer configuration
Sending business
{
"registered_name": "Company ABC",
"trading_name": "Brand name",
"address": "12, Victoria Lane",
"postal_code": "12345",
"city": "Singapore",
"province_state": null,
"country_iso_code": "SGP",
"msisdn": "33712345678",
"email": "john.doe@mail.com",
"registration_number": null,
"code": null,
"tax_id": null,
"date_of_incorporation": "2014-10-01",
"representative_lastname": "Doe",
"representative_lastname2": null,
"representative_firstname": "John",
"representative_middlename": null,
"representative_nativename": null,
"representative_id_type": null,
"representative_id_country_iso_code": "SGP",
"representative_id_number": null,
"representative_id_delivery_date": null,
"representative_id_expiration_date": null,
"business_relationship": null
}Represents sending business information for a given transaction of type B2C or B2B.
| Field | Required | Type | Description |
|---|---|---|---|
registered_name |
No† | String | Registered name of the business |
trading_name |
No† | String | Trading name of the business |
address |
No† | String | Adress |
postal_code |
No† | String | Postal code |
city |
No† | String | City |
province_state |
No† | String | Address province/state |
country_iso_code |
No† | String | Country of the business in ISO 3166-1 alpha-3 format |
msisdn |
No† | String | MSISDN in international format |
email |
No† | String | Email address |
registration_number |
No† | String | Registration number |
code |
No† | String | Sending Business identification code |
tax_id |
No† | String | Tax identifier |
date_of_incorporation |
No† | String | Date of incorporation of the business in ISO 8601 format |
representative_lastname |
No† | String | Last name of the representative of the business |
representative_lastname2 |
No† | String | Additional last name(s) of the representative of the business |
representative_firstname |
No† | String | First name of the representative of the business |
representative_middlename |
No† | String | Middle name of the representative of the business |
representative_nativename |
No† | String | Full name in native characters of the representative of the business |
representative_id_type |
No† | String | Presented identification type of the representative of the business |
representative_id_country_iso_code |
No† | String | ID delivery date in ISO 8601 format |
representative_id_number |
No† | String | Presented identification number |
representative_id_delivery_date |
No† | String | ID delivery date in ISO 8601 format |
representative_id_expiration_date |
No† | String | ID expiration date in ISO 8601 format |
business_relationship |
No† | String | Business relationship to beneficiary |
†: Requiredness will depend on payer configuration
Beneficiary
{
"lastname": "Doe",
"lastname2": null,
"middlename": null,
"firstname": "Jane",
"nativename": null,
"nationality_country_iso_code": "FRA",
"code": null,
"date_of_birth": "1971-01-01",
"country_of_birth_iso_code": "ZWE",
"gender": "MALE",
"address": "3 Norfolk Road",
"postal_code": "4581",
"city": "Harare",
"country_iso_code": "ZWE",
"msisdn": "263775892364",
"email": "jane.doe@mail.com",
"id_type": "SOCIAL_SECURITY",
"id_country_iso_code": "ZWE",
"id_number": "178027317681327",
"id_delivery_date": null,
"id_expiration_date": null,
"occupation": "Sales Executive",
"bank_account_holder_name": null,
"province_state": null
}Represents beneficiary information for a given transaction of type C2C or B2C.
| Field | Required | Type | Description |
|---|---|---|---|
lastname |
No† | String | Last name |
lastname2 |
No† | String | Additional last name(s) |
middlename |
No† | String | Middle name |
firstname |
No† | String | First name |
nativename |
No† | String | Full name in native characters |
nationality_country_i |
No† | String | Nationality in ISO 3166-1 alpha-3 format so_code |
code |
No† | String | Beneficiary identification code |
date_of_birth |
No† | String | Date of birth in ISO 8601 format |
country_of_birth_iso_code |
No† | String | Country of birth in ISO 3166-1 alpha-3 format |
gender |
No† | String | Gender |
address |
No† | String | Address |
postal_code |
No† | String | Postal code |
city |
No† | String | City |
country_iso_code |
No† | String | Address country in ISO 3166-1 alpha-3 format |
msisdn |
No† | String | MSISDN in international format |
email |
No† | String | Email address |
id_type |
No† | String | Presented identification type |
id_country_iso_code |
No† | String | ID country in ISO 3166-1 alpha-3 format |
id_number |
No† | String | Presented identification number |
id_delivery_date |
No† | String | ID delivery date in ISO 8601 format |
id_expiration_date |
No† | String | ID expiration date in ISO 8601 format |
occupation |
No† | String | Occupation |
bank_account_holder_name |
No† | String | Bank account holder name |
province_state |
No† | String | Address province/state |
†: Requiredness will depend on payer configuration
Receiving business
{
"registered_name": "Company ABC",
"trading_name": "Brand name",
"address": "12, Victoria Lane",
"postal_code": "12345",
"city": "Singapore",
"province_state": null,
"country_iso_code": "SGP",
"msisdn": "33712345678",
"email": "john.doe@mail.com",
"registration_number": null,
"tax_id": null,
"date_of_incorporation": "2014-10-01",
"representative_lastname": "Doe",
"representative_lastname2": null,
"representative_firstname": "John",
"representative_middlename": null,
"representative_nativename": null,
"representative_id_type": null,
"representative_id_country_iso_code": "SGP",
"representative_id_number": null,
"representative_id_delivery_date": null,
"representative_id_expiration_date": null
}Represents receiving business information for a given transaction of type C2B or B2B.
| Field | Required | Type | Description |
|---|---|---|---|
registered_name |
No† | String | Registered name of the business |
trading_name |
No† | String | Trading name of the business |
address |
No† | String | Adress |
postal_code |
No† | String | Postal code |
city |
No† | String | City |
province_state |
No† | String | Address province/state |
country_iso_code |
No† | String | Country of the business in ISO 3166-1 alpha-3 format |
msisdn |
No† | String | MSISDN in international format |
email |
No† | String | Email address |
registration_number |
No† | String | Registration number |
tax_id |
No† | String | Tax identifier |
date_of_incorporation |
No† | String | Date of incorporation of the business in ISO 8601 format |
representative_lastname |
No† | String | Last name of the representative of the business |
representative_lastname2 |
No† | String | Additional last name(s) of the representative of the business |
representative_firstname |
No† | String | First name of the representative of the business |
representative_middlename |
No† | String | Middle name of the representative of the business |
representative_nativename |
No† | String | Full name in native characters of the representative of the business |
representative_id_type |
No† | String | Presented identification type of the representative of the business |
representative_id_country_iso_code |
No† | String | ID delivery date in ISO 8601 format |
representative_id_number |
No† | String | Presented identification number |
representative_id_delivery_date |
No† | String | ID delivery date in ISO 8601 format |
representative_id_expiration_date |
No† | String | ID expiration date in ISO 8601 format |
†: Requiredness will depend on payer configuration
Sent Amount
{
"currency": "EUR",
"amount": 10
}Represent sent amount details for a given transaction.
| Field | Type | Description |
|---|---|---|
currency |
String | Sent amount currency in ISO 4217 format |
amount |
Number | Sent amount value |
Value within these fields will correspond to values in source amount.
Fee
{
"currency": "EUR",
"amount": 1.50
}Represents fee information for a given transaction.
| Field | Type | Description |
|---|---|---|
currency |
String | Fee amount currency in ISO 4217 format |
amount |
Number | Fee amount value |
Country
{
"iso_code": "SGP",
"name": "Singapore"
}Represents country information.
| Field | Type | Description |
|---|---|---|
iso_code |
String | Country in ISO 3166-1 alpha-3 format |
name |
String | Country name |
Administrative Division Category
{
"id": 1,
"name": "Province"
}Represents administrative division category information.
| Field | Type | Description |
|---|---|---|
id |
Integer | Category ID |
name |
String | Category name |
Administrative Division
{
"id": 1,
"name": "Artemisa Province",
"depth": 1,
"parent_id": null,
"category": {
"id": 1,
"name": "Province"
}
}Represents administrative division information.
| Field | Type | Description |
|---|---|---|
id |
Integer | Division ID |
name |
String | Division name |
depth |
Integer | Depth relative to hierarchy |
parent_id |
Integer | Division parent (if any) |
category |
Object | Administrative division category information |
Entity
{
"id": 328,
"name": "DBS",
"depth": 1,
"address": null,
"country_iso_code": "IND",
"parent_id": null,
"identifiers": [],
"payment_systems": [],
"payers": [
{
"id": 358,
"name": "All Banks",
"currency": "INR"
}
],
"category": {
"id": 1,
"name": "Bank"
},
"administrative_division": {
"id": 315,
"name": "Delhi",
"depth": 1,
"parent_id": null,
"category": {
"id": 5,
"name": "Union Territory"
}
}
}Represents entity information.
| Field | Type | Description |
|---|---|---|
id |
Integer | Entity ID |
name |
String | Entity name |
depth |
Integer | Depth relative to hierarchy |
address |
String | Registered address |
country_iso_code |
String | Address country in ISO 3166-1 alpha-3 format |
parent_id |
Integer | Division parent (if any) |
identifiers |
Array | List of entity identifier objects |
payment_systems |
Array | List of entity payment system objects |
payers |
Array | List of entity payer objects |
category |
Object | Entity category information |
administrative_division |
Object | Administrative division information |
Entity Identifier
{
"id": 2,
"code": "IFS_CODE",
"values": [
"SBIN0007336"
]
}Represents entity identifier information.
| Field | Type | Description |
|---|---|---|
id |
Integer | Entity identifier ID |
code |
String | Entity identifier code |
values |
Array | List of entity identifier values |
Entity Payment System
{
"id": 2,
"code": "IFS_CODE",
"values": [
"SBIN0007336"
]
}Represents entity identifier information.
| Field | Type | Description |
|---|---|---|
id |
Integer | Entity identifier ID |
code |
String | Entity identifier code |
values |
Array | List of entity identifier values |
Entity Payer
{
"id": 358,
"name": "All Banks",
"currency": "INR"
}Represents entity payer information.
| Field | Type | Description |
|---|---|---|
id |
Integer | Entity payer ID |
name |
String | Entity payer name |
currency |
String | Currency in ISO-4217 format |
Entity Category
{
"id": 1,
"name": "Bank"
}Represents entity category information.
| Field | Type | Description |
|---|---|---|
id |
Integer | Entity category IDname |
Report
{
"id": 123,
"type": "PARTNER_TRANSACTION_REPORT_DAILY",
"timezone": "UTC",
"cut_off_time": "00:00:00",
"report_date": "2023-10-17",
"period_start": "2023-10-17T00:00:00Z",
"period_end": "2023-10-18T00:00:00Z",
"files": [
{
"id": 4567,
"report_type": "PARTNER_TRANSACTION_REPORT_DAILY",
"file_type": "TRANSACTION_STATS",
"name": "daily_transaction_report_2023-10-17.csv"
}
]
}Represents a report.
| Field | Type | Description |
|---|---|---|
id |
Integer | Report ID |
type |
String | Report type |
timezone |
String | timezone |
cut_off_time |
String | cut off time |
report_date |
String | Report date in HTTP format |
period_start |
String | Period start date in HTTP format |
period_end |
String | Period end date in HTTP format |
files |
Array | list of Report File |
Report File
{
"id": 7890,
"report_type": "PARTNER_TRANSACTION_REPORT_DAILY",
"file_type": "TRANSACTION_STATS",
"name": "daily_transaction_report_2023-10-17.csv"
}Represents a report file
| Field | Type | Description |
|---|---|---|
id |
Integer | Report file ID |
name |
String | File name |
report_type |
String | Report Type |
file_type |
String | Report File Type |
Enumerations
Enumerations
A number of resource fields will only accept a list of known values, as outlined in this section.
Quotation Mode
| Mode | Description |
|---|---|
SOURCE_AMOUNT |
Quotation created by specifying desired source |
DESTINATION_AMOUNT |
Quotation created by specifying desired destination |
Transaction Type
| Mode | Description |
|---|---|
C2C |
Quotation or Transaction is from an individual end user to an individual end user |
C2B |
Quotation or Transaction is from an individual end user to a business |
B2C |
Quotation or Transaction is from a business to an individual end user |
B2B |
Quotation or Transaction is from a business to a business |
Gender
| Gender | Description |
|---|---|
MALE |
Male |
FEMALE |
Female |
Transaction Status Class
| Status Class | Message |
|---|---|
1 |
CREATED |
2 |
CONFIRMED |
3 |
REJECTED |
4 |
CANCELLED |
5 |
SUBMITTED |
6 |
AVAILABLE |
7 |
COMPLETED |
8 |
REVERSED |
9 |
DECLINED |
Transaction Status
| Status | Message | Details |
|---|---|---|
10000 |
CREATED | The transaction is created. |
20000 |
CONFIRMED | The transaction is confirmed. |
20110 |
CONFIRMED-UNDER-REVIEW-SLS | The transaction is under sanctions list screening for sender or beneficiary. |
20150 |
CONFIRMED-WAITING-FOR-PICKUP | The transaction is available for cash pick up by the beneficiary. Applicable for universal cash pick up only. |
30000 |
REJECTED | The transaction is rejected. |
30110 |
REJECTED-SLS-SENDER | The transaction is rejected as the sender failed the sanctions list screening. |
30120 |
REJECTED-SLS-BENEFICIARY | The transaction is rejected as the beneficiary failed the sanctions list screening. |
30200 |
REJECTED-INVALID-BENEFICIARY | The transaction is rejected as the beneficiary account is invalid. |
30201 |
REJECTED-BARRED-BENEFICIARY | The transaction is rejected as the beneficiary is blacklisted. |
30202 |
REJECTED-BARRED-SENDER | The transaction is rejected as the sender is blacklisted. |
30210 |
REJECTED-INVALID-BENEFICIARY-DETAILS | The transaction is rejected as the beneficiary details are invalid, e.g. name, email, phone number. |
30305 |
REJECTED-LIMITATIONS-ON-TRANSACTION-VALUE | The transaction is rejected as the transaction value exceeds the transaction value limit. |
30310 |
REJECTED-LIMITATIONS-ON-SENDER-VALUE | The transaction is rejected as the transaction value exceeds the value that the sender can send. |
30320 |
REJECTED-LIMITATIONS-ON-BENEFICIARY-VALUE | The transaction is rejected as the transaction value exceeds the value that the beneficiary can receive. |
30330 |
REJECTED-LIMITATIONS-ON-ACCOUNT-VALUE | The transaction is rejected as the transaction value exceeds the value that the account can receive. |
30350 |
REJECTED-LIMITATIONS-ON-SENDER-QUANTITY | The transaction is rejected as the sender exceeded the number of transactions that the sender can send. |
30360 |
REJECTED-LIMITATIONS-ON-BENEFICIARY-QUANTITY | The transaction is rejected as the beneficiary exceeded the number of transactions that the beneficiary can receive. |
30370 |
REJECTED-LIMITATIONS-ON-ACCOUNT-QUANTITY | The transaction is rejected as the account exceeded the number of transactions that the account can receive. |
30392 |
REJECTED-COMPLIANCE-REASON | The transaction is rejected due to compliance reason. |
30400 |
REJECTED-PAYER-CURRENTLY-UNAVAILABLE | The transaction is rejected as the payer is either under payer maintenance or currently unavailable. |
30500 |
REJECTED-INSUFFICIENT-BALANCE | The transaction is rejected due to insufficient balance on the pay-in partner’s account. |
40000 |
CANCELLED | The transaction is cancelled upon request. |
50000 |
SUBMITTED | The transaction is submitted to the pay-out partner for processing. |
60000 |
AVAILABLE | The transaction is available for cash pick up by the beneficiary. |
70000 |
COMPLETED | The transaction is completed and payout has been made to the beneficiary. |
80000 |
REVERSED | The transaction is reversed. |
90000 |
DECLINED | The transaction is declined by the pay-out partner. |
90110 |
DECLINED-SLS-SENDER | The transaction is declined by the pay-out partner as the sender failed the sanctions list screening. |
90120 |
DECLINED-SLS-BENEFICIARY | The transaction is declined by the pay-out partner as the beneficiary failed the sanctions list screening. |
90200 |
DECLINED-INVALID-BENEFICIARY | The transaction is declined by the pay-out partner due to invalid beneficiary, e.g. bank account number. |
90201 |
DECLINED-BARRED-BENEFICIARY | The transaction is declined by the pay-out partner as the beneficiary is blacklisted. |
90202 |
DECLINED-UNSUPPORTED-BENEFICIARY | The transaction is declined by the pay-out partner as the beneficary does not allow overseas transaction or payer is unavailable for pay out. |
90210 |
DECLINED-INVALID-BENEFICIARY-DETAILS | The transaction is declined by the pay-out partner as the beneficiary’s details is invalid, e.g. name or address. |
90211 |
DECLINED-INVALID-SENDER-DETAILS | The transaction is declined by the pay-out partner as the sender details is in wrong format per pay-out partners’ rules on sender. eg: character type length. |
90305 |
DECLINED-LIMITATIONS-ON-TRANSACTION-VALUE | The transaction is declined by the pay-out partner as the value exceeds the amount allowed per transaction. |
90310 |
DECLINED-LIMITATIONS-ON-SENDER-VALUE | The transaction is declined by the pay-out partner as the transaction value exceeds the value that the sender can send per transaction. |
90320 |
DECLINED-LIMITATIONS-ON-BENEFICIARY-VALUE | The transaction is declined by the pay-out partner as the transaction value exceeds the total value that the beneficiary can receive. |
90330 |
DECLINED-LIMITATIONS-ON-ACCOUNT-VALUE | The transaction is declined by the pay-out partner as the transaction value exceeds the total value that the beneficiary can receive per account. |
90331 |
DECLINED-LIMITATIONS-ON-ACCOUNT-VALUE-DAILY | The transaction is declined by the pay-out partner as the transaction value exceeds the total value that the beneficiary can receive per day. |
90332 |
DECLINED-LIMITATIONS-ON-ACCOUNT-VALUE-WEEKLY | The transaction is been declined by the pay-out partner as the transaction value exceeds the total value that the beneficiary can receive per week. |
90333 |
DECLINED-LIMITATIONS-ON-ACCOUNT-VALUE-MONTHLY | The transaction is declined by the pay-out partner as the transaction value exceeds the total value that the beneficiary can receive per month. |
90334 |
DECLINED-LIMITATIONS-ON-ACCOUNT-VALUE-YEARLY | The transaction is declined by the pay-out partner as the transaction value exceeds the total value that the beneficiary can receive per year. |
90350 |
DECLINED-LIMITATIONS-ON-SENDER-QUANTITY | The transaction is declined by the pay-out partner as the sender has exceeded the number of transactions that the sender can send. |
90360 |
DECLINED-LIMITATIONS-ON-BENEFICIARY-QUANTITY | The transaction is declined by the pay-out partner as the beneficiary exceeds the total number of transactions that the beneficiary can receive. |
90370 |
DECLINED-LIMITATIONS-ON-ACCOUNT-QUANTITY | The transaction is declined by the pay-out partner as the beneficiary’s account exceeds the total number of transactions that the account can receive. |
90380 |
DECLINED-DUPLICATED-TRANSACTION | The transaction is declined by the pay-out partner due to duplication in the transaction. |
90390 |
DECLINED-CANCELLED | The transaction is declined by the pay-out partner as the pay-in partner contacted support and asked for the transaction to be cancelled. |
90391 |
DECLINED-REFUSED | The transaction is declined by the pay-out partner as the beneficiary has actively refused to perform the required onboarding, the time has elapsed or the beneficiary was unresponsive. |
90392 |
DECLINED-COMPLIANCE-REASON | The transaction is declined by the pay-out partner due to compliance reason. |
90393 |
DECLINED-INVALID-PURPOSE-OF-REMITTANCE | The transaction is declined by the pay-out partner due to invalid purpose of remittance, e.g. pay-out partner does not allow gifts/donations. |
90400 |
DECLINED-PAYER-CURRENTLY-UNAVAILABLE | The transaction is declined by the pay-out partner as their system are not available. |
Transaction attachment type
| Type | Description |
|---|---|
invoice |
Attachment is an invoice |
purchase_order |
Attachment is a purchase order |
delivery_slip |
Attachment is a delivery slip |
contract |
Attachment is a contract |
customs_declaration |
Attachment is a customs declaration |
bill_of_landing |
Attachment is a bill of landing |
others |
Anything else not covered in this list |
Transaction attachment allowed file types
| Extension | Description | File Mime Type |
|---|---|---|
.txt |
Plain Text | text/plain |
.pdf |
Adobe Portable Document Format | application/pdf |
.doc |
Microsoft Word Document | application/msword |
.docx |
Microsoft Word (OpenXML) | application/vnd.openxmlformats-officedocument.wordprocessingml.document |
.jpg, .jpeg |
JPEG images | image/jpeg |
.png |
Portable Network Graphics | image/png |
.bmp |
Windows OS/2 Bitmap Graphics | image/bmp |
.rtf |
Rich Text Format (RTF) | application/rtf |
.xls |
Microsoft Excel | application/vnd.ms-excel |
.xlsx |
Microsoft Excel (OpenXML) | application/vnd.openxmlformats-officedocument.spreadsheetml.sheet |
Account Status
| Status | Message |
|---|---|
AVAILABLE |
Credit party account is available and can receive a transfer |
UNREGISTERED |
Credit party account is not registered but can still receive a transfer |
UNAVAILABLE |
Credit party account is not available and will not receive a transfer |
UNAVAILABLE-BENEFICIARY-MISMATCH |
Credit party account does not match the beneficiary details |
UNAVAILABLE-INVALID-ACCOUNT |
Credit party account number is invalid |
UNAVAILABLE-BARRED-ACCOUNT |
Credit party account number is barred |
Beneficiary Relationship
| Relationship | Description |
|---|---|
AUNT |
Aunt |
BROTHER |
Brother |
BROTHER_IN_LAW |
Brother-in-law |
COUSIN |
Cousin |
DAUGHTER |
Daughter |
FATHER |
Father |
FATHER_IN_LAW |
Father-in-law |
FRIEND |
Friend |
GRAND_FATHER |
Grandfather |
GRAND_MOTHER |
Grandmother |
HUSBAND |
Husband |
MOTHER |
Mother |
MOTHER_IN_LAW |
Mother-in-law |
NEPHEW |
Nephew |
NIECE |
Niece |
SELF |
Self (i.e. the sender, himself) |
SISTER |
Sister |
SISTER_IN_LAW |
Sister-in-law |
SON |
Son |
UNCLE |
Uncle |
WIFE |
Wife |
OTHER |
Others not listed |
Business Relationship
| Relationship | Description |
|---|---|
EMPLOYEE |
Employee |
CUSTOMER |
Customer |
VENDOR_SERVICE |
Vendor Service |
PROVIDER |
Provider |
BUSINESS_PARTNER |
Business Partner |
INVESTOR |
Investor |
THIRD_PARTY |
Third Party |
AFFILIATED_ENTITY |
Affiliated Entity |
AFFILIATED_BUSINESS |
Affiliated Business |
Source of Funds
| Source | Description |
|---|---|
CASH |
Cash |
BUSINESS |
Business |
GIFT |
Gift |
SALARY |
Salary |
LOTTERY |
Lottery |
SAVINGS |
Savings |
OTHER |
Others not listed |
ID Type
| Type | Description |
|---|---|
PASSPORT |
Passport |
NATIONAL_ID |
National Identification Card |
DRIVING_LICENSE |
Driving License |
SOCIAL_SECURITY |
Social Security Card/Number |
TAX_ID |
Tax Payer Identification Card/Number |
SENIOR_CITIZEN_ID |
Senior Citizen Identification Card |
BIRTH_CERTIFICATE |
Birth Certificate |
VILLAGE_ELDER_ID |
Village Elder Identification Card |
RESIDENT_CARD |
Permanent Residency Identification Card |
ALIEN_REGISTRATION |
Alien Registration Certificate/Card |
PAN_CARD |
PAN Card |
VOTERS_ID |
Voter’s Identification Card |
HEALTH_CARD |
Health Insurance Card/Number |
EMPLOYER_ID |
Employer Identification Card |
OTHER |
Others not listed |
Purpose of Remittance
| Purpose | Description |
|---|---|
COMPUTER_SERVICES |
Computer service |
FAMILY_SUPPORT |
Family support |
EDUCATION |
Education |
GIFT_AND_DONATION |
Gift and other donations |
MEDICAL_TREATMENT |
Medical treatment |
MAINTENANCE_EXPENSES |
Maintenance or other expenses |
TRAVEL |
Travel |
SMALL_VALUE_REMITTANCE |
Small value remittance |
LIBERALIZED_REMITTANCE |
Liberalized remittance |
CONSTRUCTION_EXPENSES |
Construction expenses |
HOTEL_ACCOMMODATION |
Hotel accommodation |
ADVERTISING_EXPENSES |
Advertising and/or public relations related expenses |
ADVISORY_FEES |
Fees for advisory or consulting service |
BUSINESS_INSURANCE |
Business related insurance payment |
INSURANCE_CLAIMS |
Insurance claims payment |
DELIVERY_FEES |
Delivery fees |
EXPORTED_GOODS |
Payments for exported goods |
SERVICE_CHARGES |
Payment for services |
LOAN_PAYMENT |
Payment of loans |
OFFICE_EXPENSES |
Office expenses |
PROPERTY_PURCHASE |
Residential property purchase |
PROPERTY_RENTAL |
Property rental payment |
ROYALTY_FEES |
Royalty, trademark, patent and copyright fees |
SHARES_INVESTMENT |
Investment in shares |
FUND_INVESTMENT |
Fund investment |
TAX_PAYMENT |
Tax payment |
TRANSPORTATION_FEES |
Transportation fees |
UTILITY_BILLS |
Utility bills |
PERSONAL_TRANSFER |
Personal transfer |
SALARY_PAYMENT |
Payment of salary |
REWARD_PAYMENT |
Payment of rewards |
INFLUENCER_PAYMENT |
Payment of Influencer |
OTHER_FEES |
Broker, commitment, guarantee and other fees |
OTHER |
Other purposes |
Bank Account Type
| Value | Description |
|---|---|
CHECKING |
Checking Account |
SAVINGS |
Savings Account |
DEPOSIT |
Deposit Account |
OTHERS |
Other type of account |
Balance Movement Type
| Value | Description |
|---|---|
PAYOUT |
Payout transaction |
PAYOUT_FEES |
Fee for payout transaction |
RETAIL_FEE_SHARING |
Retail fee sharing |
COMMISSION_ON_SPREAD |
Commission on spread |
RETAIL_RATE_SHARING |
Retail rate sharing |
WITHDRAWAL |
Withdrawal from balance |
MINIMUM_COMMITMENT_FEE |
Minimum commitment fee |
TRANSFER |
Credit to balance |
CO_MARKETING_SUPPORT_FEE |
Co-marketing support fee |
REVERSAL |
Reversal of payout transaction |
TRADE_CREDIT |
Credit of funds via trading desk |
TRADE_DEBIT |
Debit of funds via trading desk |
Local Code Type
| Value | Description |
|---|---|
Branch Code |
Branch Code |
CHIPS Member |
CHIPS Member ID |
Local Account Identifier Type
| Value | Description |
|---|---|
BSB |
BSB |
PayNow |
PayNow |
Sort Code |
Sort Code |
CLABE |
CLABE |
Balance Operation
| Value | Description |
|---|---|
AUTHORIZE |
Authorizes amount from balance |
CAPTURE |
Captures Authorised amount |
REVERSAL |
Reversal balance movement |
VOID |
Cancels authorization |
Report Type
| Value | Description |
|---|---|
PARTNER_ACCOUNT_STATEMENT_DAILY |
Daily account statement report |
PARTNER_ACCOUNT_STATEMENT_MONTHLY |
Monthly account statement report |
PARTNER_TRANSACTION_REPORT_DAILY |
Daily transaction report |
PARTNER_TRANSACTION_REPORT_MONTHLY |
Monthly transaction report |
Report File Type
| Value | Description |
|---|---|
UNDERLYING_STATS |
Individual account statement record(s) |
TRANSACTION_STATS |
Individual Transaction record(s) |
AGGREGATED_STATS |
Aggregated account statement record(s) |
Payer Information
Payer Information
Additional information on some selected payers are outlined in this section.
WeChat Pay
What is WeChat Pay
WeChat Pay is a mobile payment and digital wallet service by WeChat based in China that allows users to make mobile payments and online transactions. In addition to that, WeChat Pay allows users to receive money in their wallet or their Chinese bank accounts (if selected as the receiving account) for cross-border remittance.
Our Service with WeChat Pay
- MobileWallet
Note: A user must have a valid account with WeChat pay first before being able to receive a cross-border remittance. However, Thunes still has the capability to reach more than 95% of bank accounts in China depending on the beneficiary’s settings. See the “Beneficiary Experience” section below for more details.
Beneficiary Experience
- A beneficiary receives a payment notification
- If this is the first time a beneficiary receives a cross-border remittance:
- The beneficiary receives a SMS with a URL for the payment
- Clicking on the URL would redirect the beneficiary to the mobile application
- Follow the steps in the app for authorization
- Funds will arrive in the wallet balance (User selected Wallet as the receiving account) OR
- Funds will arrive in the bank account (User selected BA as the receiving account)
Alipay
What is Alipay
Alipay is a digital eWallet that allows users to make payments on their phone by storing their debit or credit card or bank account. In addition to that, Alipay allows users to receive money directly to their Chinese bank accounts (if successfully linked) for cross-border remittance.
Our Service with Alipay
- MobileWallet
Note: A user must have a valid account with Alipay first before being able to receive a cross-border remittance. However, Thunes still has the capability to reach more than 95% of bank accounts in China if the beneficiary has successfully linked his/her bank account. See the “Beneficiary Experience” section below for more details.
Beneficiary Experience
- A beneficiary receives a payment notification
- The beneficiary accepts the payment
- Funds will arrive in the linked Bank account (User has successfully linked a BA) OR
- Beneficiary is given 72hrs to link a bank account (User has not linked a BA)