Overview
Introduction
Welcome to the Thunes Collection API reference
This API serves as the primary gateway to accept payments through Thunes’ platform.
The Thunes Collection API is organized according to REST principles and provides the following functionalities:
- Process payment request and retrieve payment details
- Onboard accounts and merchants
- Retrieve accounting information and make transfer requests from your collection account
Environments
This API is available in 2 environments: production and sandbox (test), 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 sandbox environments.
Versioning
Endpoints of the API are prefixed with a corresponding version number. This documentation describes the latest version of the API, the version 2. Documentation for previous version 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 to not 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 payment order statuses within a status class
- 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 payment
- 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
Onboarding of new partner
First, you will need to follow the KYC compliance process by using Fangs platform. Once this process is done, you will be able to unlock credentials.
Tests in Sandbox environment
You can request our Solution Delivery team to provide you with a Postman or Swagger link to test all the different endpoints of the API, all you need is an APIkey for Sandbox environment, generated from the back-office.
Tests in Production environment
If you want to conduct real payment tests in a production environment, you should ask the Solution Delivery team to give you access to the back-office in that environment, and you’ll be able to genreate APIkeys.
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.
Payment Orchestration
Transaction states and possible actions
During the course of a payment, a payment order will undergo various status changes as illustrated in the diagram.
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.
You can create a payment order (or transaction) in Thunes platform by using a POST Payment Order. On that payment order, you can make different operations of Cancel, Charge and Refunds.
| Command | Status in which the command can be done | Action |
|---|---|---|
| POST Cancel | AUTHORIZING (if the configuration allows it), AUTHORIZED | Cancels the transaction. No extra step can be taken after. The buyer will not be debited. |
| POST Charge | AUTHORIZED | This operation confirms that the buyer will be debited from the amount of the operation. Depending on the configuration with the payment method, it can be automated. |
| POST Refund | CHARGED, AUTHORIZED (in case of a partial POST Charge has been done, that amount can be refunded) | The amount of the operation will be refunded to the buyer who made the payment order. The refund process depends on the payment method. |
Quotations: mandatory first step in accept currency conversion (ACC) mode
Accept currency conversion mode enables the merchant to make requests using his own currency, while the buyer pays with another currency. Before requesting a POST Payment Order in ACC mode, you must create a quotation using POST Quotation. A quotation can be linked to a payment order to secure a rate. Usually, it will be used to show the buyer how much he will pay in his own currency. The rate is secured for 24 hours to make a POST Payment Order. When creating a payment order, use the id of the quotation to link it to the payment order you want to create.
Callback
POST /callback HTTP/1.1
Date: Wed, 02 Nov 2016 09:17:54 GMT
Content-Type: application/json{
}While the payment order is processed, changes in status will be notified in realtime to the provided callback URL (if provided).
The customer must implement this endpoint to receive these status changes. The endpoint should expect an HTTP POST request containing a payment order 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.
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 |
403 |
Access to the ressource is forbiden |
404 |
Not Found: Resource doesn’t exist |
500 |
Internal Server Error: An internal server error occurred processing the request |
Details will always be contained within the HTTP body.
API Error Codes
| Code | Description |
|---|---|
1000400 |
Invalid or malformed request message |
1000401 |
Unauthorized access |
1000403 |
Access to the resource is forbidden |
1000404 |
Ressource not found |
1000500 |
Technical error |
1001001 |
Parameter ‘requested_parameter’ is invalid - ‘valueasked’ does not exist |
2001101 |
INVALID DATA: One of the parameters included in the request is not compatible with Thunes’s system (e.g., incorrect length, negative value, invalid email format). Please check the accompanying message for further information. Revise integration of the Thunes API before sending the request again. |
2001201 |
OPERATION NOT ALLOWED: The request is syntactically correct, but it does not comply with Thunes’s business rules (e.g., incompatible payment order status, insufficient charge amount remaining). Please check the accompanying message for further information. Review the integration of the Thunes API before sending the request again. |
2001301 |
OPERATION REFUSED: The request is correct, but one of the remote payment servers has refused the operation (e.g., card limit exceeded). We recommend that you do not reattempt the call since a change in the situation is unlikely for a certain period. |
2001401 |
DISTANT SERVER TECHNICAL ERROR: The request is correct, but one of the remote payment servers has reported a technical error, or the connection with this server has been interrupted. The request status is unknown. Do not reattempt the call. |
2001501 |
DISTANT SERVER NOT AVAILABLE: The request is correct, but one of the remote payment servers is temporarily unavailable. Please try again later. |
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.
Health check
Ping
GET v1/payment/ping HTTP/1.1
200 OKReturns
{
"status": "up"
}Payments
Payment Orders
Create a Payment Order
When a user selects a payment method managed by Thunes, you must ask for a payment order to be created. We provide the POST Payment Order web service for this purpose. As a partner/merchant, this request will allow you to request a payment page URL link (in redirection mode) or payment information (in host to host mode).
POST /v1/payment/payment-orders HTTP/1.1
201 Success{
"requested": {
"amount": 2000.00,
"currency": "MXN"
},
"type": "B2B",
"merchant_id": "mymerchant",
"merchant_external_id": "my_company_id",
"external_id": "987654",
"merchant_urls": {
"aborted_url": "aborted.com",
"error_url": "error.com",
"return_url": "return.com",
"notification_url": "notification.com"
},
"payment_page_id": "paymentpage12345",
"merchant_order": {
"total": {
"amount": 10.00,
"currency": "EUR"
},
"tax": {
"amount": 0.50,
"currency": "EUR"
},
"searchable_custom_data_1": null,
"searchable_custom_data_2": null,
"custom_data": null,
"billing_address": {
"address_line_1": "47 avenue de l'opera",
"address_line_2": null,
"city": "Paris",
"company_name": "Thunes",
"country_iso_code": "FRA",
"custom_data": null,
"first_name": "Jean",
"home_phone": null,
"last_name": "Dupont",
"mobile_phone": null,
"region": "Ile-de-France",
"title": null,
"zip_code": "75002"
},
"shipping_address": {
"address_line_1": "47 avenue de l'opera",
"address_line_2": null,
"city": "Paris",
"company_name": "Thunes",
"country_iso_code": "FRA",
"custom_data": null,
"first_name": "Jean",
"home_phone": null,
"last_name": "Dupont",
"mobile_phone": null,
"region": "Ile-de-France",
"title": null,
"zip_code": "75002"
},
"customer": {
"account_creation_date": "2023-10-26T14:24:31",
"date_of_birth": "1990-01-31",
"company_name": null,
"culture": "fr-FR",
"custom_data": null,
"email": "jean.dupont@mail.com",
"first_name": "Jean",
"home_phone": null,
"id": null,
"last_name": "Dupont",
"mobile_phone": "string",
"title": null
},
"cart_items": [
{
"brand": "yourbrand",
"category": "cathegory1",
"label": "object123",
"custom_data": null,
"merchant_category_1": null,
"merchant_category_2": null,
"merchant_item_id": null,
"quantity": 1,
"type": null,
"unit_price": {
"amount": 10.00,
"currency": "EUR"
},
"url": null,
"vat": {
"amount": 10.00,
"currency": "EUR"
},
"delivery": {
"label": null,
"type": null,
"speed": "2",
"expected_date": "2023-10-26T14:24:31",
"expected_delay": 0,
"custom_data": null
}
}
]
},
"integration_mode": "REDIRECT",
"payment_information": {
"card_number": "6541778898761532",
"card_cvv": "123",
"card_expiration_year": "2050",
"card_expiration_month": "01",
"card_holder_name": "Jean Dupont",
"email": "jean.dupont@mail.com",
"phone_number": "0033612345678",
"token_id": null,
"bank_account_number": null,
"account_holder_name": null,
"otp": "123456",
"msisdn": "263775892364",
"qrcode": "324032942309",
"bank_id": "123"
}
}Request parameters
| Field | Required | Type | Description |
|---|---|---|---|
type |
Yes | String | Indicates if transaction in B2B if the payer is a business, or C2B if the payer is a consumer |
requested |
Yes | Amount | Amount of the transaction for the merchant. Amount information |
merchant_id |
Yes(1) | String | Merchant identifier |
merchant_external_id |
Yes(1) | String | Unique external merchant id |
external_id |
Yes | String | Payment Order reference, from the merchant’s side |
merchant_urls |
Yes(2) | Merchant redirection URLs | Merchant redirection URLs information. To indicate what pages must be used for redirection, for every use case |
payment_page_id |
Yes | String | Targeted payment method ID |
merchant_order |
No(3) | Merchant order | Merchant order information |
integration_mode |
Yes | String | Indicates if the payment is made in “REDIRECTION” mode (thunes or the payment method host the payment page) or in “HOST_TO_HOST” mode (the merchant hosts the payment page) |
payment_information |
Yes(4) | Payment information | Payment information |
(1): Only one of the 2 values should be put in the request body, the merchant_id OR merchant_external_id
(2): In HOST_TO_HOST mode, only the notification_url is required
(3): Requiredness will depend on the chosen payment method (payment_page_id).
(4): Mandatory in HOST_TO_HOST mode only
Returns
{
"id": "433282730000",
"requested": {
"amount": 10.00,
"currency": "EUR"
},
"processed": {
"amount": 10.00,
"currency": "EUR"
},
"creation_date": "2024-01-08T15:51:54",
"merchant_id": "mymerchant",
"external_id": "987654",
"merchant_external_id": "my_company_id",
"merchant_urls": {
"aborted_url": "aborted.com",
"error_url": "error.com",
"return_url": "return.com",
"notification_url": "notification.com"
},
"payment_integrator_id": "string",
"payment_page_id": "paymentpage12345",
"payment_url": "payment.com",
"status": "Authorized",
"update_date": "2024-01-08T15:51:54",
"merchant_order": {
"total": {
"amount": 10.00,
"currency": "EUR"
},
"tax": {
"amount": 0.50,
"currency": "EUR"
},
"searchable_custom_data_1": null,
"searchable_custom_data_2": null,
"custom_data": null,
"billing_address": {
"address_line_1": "47 avenue de l'opera",
"address_line_2": null,
"city": "Paris",
"company_name": "Thunes",
"country_iso_code": "FRA",
"custom_data": null,
"first_name": "Jean",
"home_phone": null,
"last_name": "Dupont",
"mobile_phone": null,
"region": "Ile-de-France",
"title": null,
"zip_code": "75002"
},
"shipping_address": {
"address_line_1": "47 avenue de l'opera",
"address_line_2": null,
"city": "Paris",
"company_name": "Thunes",
"country_iso_code": "FRA",
"custom_data": null,
"first_name": "Jean",
"home_phone": null,
"last_name": "Dupont",
"mobile_phone": null,
"region": "Ile-de-France",
"title": null,
"zip_code": "75002"
},
"customer": {
"account_creation_date": "2023-10-26T14:24:31",
"date_of_birth": "1990-01-31",
"company_name": null,
"culture": "fr-FR",
"custom_data": null,
"email": "jean.dupont@mail.com",
"first_name": "Jean",
"home_phone": null,
"id": null,
"last_name": "Dupont",
"mobile_phone": "string",
"title": null
},
"cart_items": [
{
"brand": "yourbrand",
"category": "cathegory1",
"label": "object123",
"custom_data": null,
"merchant_category_1": null,
"merchant_category_2": null,
"merchant_item_id": null,
"quantity": 1,
"type": null,
"unit_price": {
"amount": 10.00,
"currency": "EUR"
},
"url": null,
"vat": {
"amount": 10.00,
"currency": "EUR"
},
"delivery": {
"label": null,
"type": null,
"speed": "2",
"expected_date": "2023-10-26T14:24:31",
"expected_delay": 0,
"custom_data": null
}
}
]
},
"type": "B2B",
"integration_mode": "REDIRECT",
"payment_methods": [
{
"amounts": {
"authorizing": {
"amount": 10.00,
"currency": "EUR"
},
},
"brand": "Paypal",
"custom_data": null,
"holder_id": "123",
"holder_email": "jean.dupont@mail.com",
"payment_instruction": {
"url": "redirecturl3ds.com",
"display_message": "Please proceed to do A, B and C to complete the payment"
},
"payment_method_order_id": "123",
"payment_method_reference": "jeandupont123",
"type": "wallet"
}
]
}Payment Order object.
Quotations
for ACCEPT Currency Conversion mode
Create a Quotation
In a case where the buyer/user will pay in a different currency from the merchant (the ACCEPT Currency Conversion mode), a quotation has to be requested before the creation of a payment order. A quotation will allow you to know in advance a rate, and secure it to make a transaction request afterwards. You’ll just have to indicate the id or external_id of your quotation when making a POST Payment Order.
Request parameters
POST /v1/payment/quotations HTTP/1.1
201 Success{
"external_id": "123456789",
"merchant_id": "mymerchant",
"payment_page_id": "paymentpage12345",
"requested": {
"amount": 10.00,
"currency": "EUR"
},
"processed": {
"currency": "MXN"
},
"quotation_mode": "REQUESTED_AMOUNT",
}| Field | Required | Type | Description |
|---|---|---|---|
external_id |
No | String | To link your own id to that quotation |
merchant_id |
Yes | String | Your merchant id in Thunes platform |
payment_page_id |
Yes | String | The payment page that you wnat to use for the transaction |
requested.amount |
Yes(1) | Decimal | The value of the amount that you want to convert for processing. |
requested.currency |
Yes | String | Your currency |
processed.amount |
Yes(1) | Decimal | The value of the amount that will be processed in the platform. It’s the amount that will be taken into account by the payment method, and the amount that the buyer will pay. |
processed.currency |
Yes | String | The buyer’s currency |
quotation_mode |
Yes | String | “REQUESTED_AMOUNT” or “PROCESSED_AMOUNT” . Indicates what is the amount provided as an input to calculate the other amount |
(1) : The requested_amount or processed_amount is mandatory depending on the quotation_mode. If quotation_mode is REQUESTED_AMOUNT, then requested_amount is mandatory, and if quotation_mode is PROCESSED_AMOUNT, then processed_amount is mandatory
Returns
Quotation object.
{
"id" : "121afd71-4444-4bdd-9999-d8c1c50dc6b6",
"external_id": "123456789",
"merchant_id": "mymerchant",
"payment_page_id": "paymentpage12345",
"requested": {
"amount": 10.00,
"currency": "EUR"
},
"processed": {
"amount": 2000.00,
"currency": "MXN"
},
"wholesale_fx_rate": 200.000000000000000000,
"creation_date": "2024-03-16T16:36:04",
"expiration_date": "2024-03-23T16:36:04",
"quotation_mode": "REQUESTED_AMOUNT"
}Create a Payment Order from a quotation id or a quotation external id
You can also create a payment order by using the id or external_id of a quotation you created previously. This will allow you to do a transaction in Accept Currency Conversion (ACC) context. Note : if your payment page in our platform is configured in ACC, then this is the only route to create a payment order.
POST /v1/payment/quotations/{id}/payment-orders HTTP/1.1
201 SuccessPOST /v1/payment/quotations/ext-{external_id}/payment-orders HTTP/1.1
201 Success{
"type": "B2B",
"external_id": "987654",
"merchant_urls": {
"aborted_url": "aborted.com",
"error_url": "error.com",
"return_url": "return.com",
"notification_url": "notification.com"
},
"merchant_order": {
"total": {
"amount": 10.00,
"currency": "EUR"
},
"tax": {
"amount": 0.50,
"currency": "EUR"
},
"searchable_custom_data_1": null,
"searchable_custom_data_2": null,
"custom_data": null,
"billing_address": {
"address_line_1": "47 avenue de l'opera",
"address_line_2": null,
"city": "Paris",
"company_name": "Thunes",
"country_iso_code": "FRA",
"custom_data": null,
"first_name": "Jean",
"home_phone": null,
"last_name": "Dupont",
"mobile_phone": null,
"region": "Ile-de-France",
"title": null,
"zip_code": "75002"
},
"shipping_address": {
"address_line_1": "47 avenue de l'opera",
"address_line_2": null,
"city": "Paris",
"company_name": "Thunes",
"country_iso_code": "FRA",
"custom_data": null,
"first_name": "Jean",
"home_phone": null,
"last_name": "Dupont",
"mobile_phone": null,
"region": "Ile-de-France",
"title": null,
"zip_code": "75002"
},
"customer": {
"account_creation_date": "2023-10-26T14:24:31",
"date_of_birth": "1990-01-31",
"company_name": null,
"culture": "fr-FR",
"custom_data": null,
"email": "jean.dupont@mail.com",
"first_name": "Jean",
"home_phone": null,
"id": null,
"last_name": "Dupont",
"mobile_phone": "string",
"title": null
},
"cart_items": [
{
"brand": "yourbrand",
"category": "cathegory1",
"label": "object123",
"custom_data": null,
"merchant_category_1": null,
"merchant_category_2": null,
"merchant_item_id": null,
"quantity": 1,
"type": null,
"unit_price": {
"amount": 10.00,
"currency": "EUR"
},
"url": null,
"vat": {
"amount": 10.00,
"currency": "EUR"
},
"delivery": {
"label": null,
"type": null,
"speed": "2",
"expected_date": "2023-10-26T14:24:31",
"expected_delay": 0,
"custom_data": null
}
}
]
},
"integration_mode": "REDIRECT",
"payment_information": {
"card_number": "6541778898761532",
"card_cvv": "123",
"card_expiration_year": "2050",
"card_expiration_month": "01",
"card_holder_name": "Jean Dupont",
"email": "jean.dupont@mail.com",
"phone_number": "0033612345678",
"token_id": null,
"bank_account_number": null,
"account_holder_name": null,
"otp": "123456",
"msisdn": "263775892364",
"qrcode": "324032942309",
"bank_id": "123"
}
}Request parameters
| Field | Required | Type | Description |
|---|---|---|---|
type |
Yes | String | Indicates if transaction in B2B if the payer is a business, or C2B if the payer is a consumer |
external_id |
Yes | String | Payment Order reference, from the merchant’s side |
merchant_urls |
Yes(1) | Merchant redirection URLs | Merchant redirection URLs information. To indicate what pages must be used for redirection, for every use case |
merchant_order |
No(2) | Merchant order | Merchant order information |
integration_mode |
Yes | String | Indicates if the payment is made in “REDIRECTION” mode (thunes or the payment method host the payment page) or in “HOST_TO_HOST” mode (the merchant hosts the payment page) |
payment_information |
No(3) | Payment information | Payment information |
(1): In HOST_TO_HOST mode, only the notification_url is required (2): Requiredness will depend on the chosen payment method (3): Mandatory in HOST_TO_HOST mode only
Returns
{
"id": "433282730000",
"requested": {
"amount": 10.00,
"currency": "EUR"
},
"processed": {
"amount": 40381.92,
"currency": "UGX"
},
"creation_date": "2024-01-08T15:51:54",
"quotation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"merchant_id": "mymerchant",
"external_id": "987654",
"merchant_external_id": "my_company_id",
"merchant_urls": {
"aborted_url": "aborted.com",
"error_url": "error.com",
"return_url": "return.com",
"notification_url": "notification.com"
},
"payment_integrator_id": "string",
"payment_page_id": "paymentpage12345",
"payment_url": "payment.com",
"status": "Authorized",
"update_date": "2024-01-08T15:51:54",
"merchant_order": {
"total": {
"amount": 10.00,
"currency": "EUR"
},
"tax": {
"amount": 0.50,
"currency": "EUR"
},
"searchable_custom_data_1": null,
"searchable_custom_data_2": null,
"custom_data": null,
"billing_address": {
"address_line_1": "47 avenue de l'opera",
"address_line_2": null,
"city": "Paris",
"company_name": "Thunes",
"country_iso_code": "FRA",
"custom_data": null,
"first_name": "Jean",
"home_phone": null,
"last_name": "Dupont",
"mobile_phone": null,
"region": "Ile-de-France",
"title": null,
"zip_code": "75002"
},
"shipping_address": {
"address_line_1": "47 avenue de l'opera",
"address_line_2": null,
"city": "Paris",
"company_name": "Thunes",
"country_iso_code": "FRA",
"custom_data": null,
"first_name": "Jean",
"home_phone": null,
"last_name": "Dupont",
"mobile_phone": null,
"region": "Ile-de-France",
"title": null,
"zip_code": "75002"
},
"customer": {
"account_creation_date": "2023-10-26T14:24:31",
"date_of_birth": "1990-01-31",
"company_name": null,
"culture": "fr-FR",
"custom_data": null,
"email": "jean.dupont@mail.com",
"first_name": "Jean",
"home_phone": null,
"id": null,
"last_name": "Dupont",
"mobile_phone": "string",
"title": null
},
"cart_items": [
{
"brand": "yourbrand",
"category": "cathegory1",
"label": "object123",
"custom_data": null,
"merchant_category_1": null,
"merchant_category_2": null,
"merchant_item_id": null,
"quantity": 1,
"type": null,
"unit_price": {
"amount": 10.00,
"currency": "EUR"
},
"url": null,
"vat": {
"amount": 10.00,
"currency": "EUR"
},
"delivery": {
"label": null,
"type": null,
"speed": "2",
"expected_date": "2023-10-26T14:24:31",
"expected_delay": 0,
"custom_data": null
}
}
]
},
"type": "B2B",
"integration_mode": "REDIRECT",
"payment_methods": [
{
"amounts": {
"authorizing": {
"amount": 10.00,
"currency": "EUR"
},
},
"brand": "Paypal",
"custom_data": null,
"holder_id": "123",
"holder_email": "jean.dupont@mail.com",
"payment_instruction": {
"url": "redirecturl3ds.com",
"display_message": "Please proceed to do A, B and C to complete the payment"
},
"payment_method_order_id": "123",
"payment_method_reference": "jeandupont123",
"type": "wallet"
}
]
}Payment Order object.
Retrieve a payment order by id
Retrieve information for a given payment order id. The id of the payment order must be supplied replacing {id} in the URI path.
GET /v1/payment/payment-orders/{id} HTTP/1.1
200 OKReturns
Payment Order object.
Payment Operation - Cancel
Once a payment order is created, you may cancel it before its status get changed to Charged. If you cannot meet all or part of the order, we recommend that you contact us to cancel the corresponding amount. This enables us to promptly refund prepaid payment methods, such as gift cards or loyalty points, which were charged when the order was placed, and cancel any authorisations for other payment methods.
Cancel a payment order by Payment Order id
POST /v1/payment/payment-orders/{paymentOrderId}/cancellations HTTP/1.1
200 Success{
"requested": {
"amount": 10.00,
"currency": "USD"
},
"external_id": "operation1234",
"custom_data": null
}Request parameters
| Field | Required | Type | Description |
|---|---|---|---|
requested |
Yes | Object | Amount information |
external_id |
No | String | Payment Operation reference, from the merchant’s side |
custom_data |
No | String | To link any additional data to this operation |
Returns
{
"id": 1,
"payment_order_id": "1",
"status": "DONE",
"requested": {
"amount": 10.00,
"currency": "USD"
},
"external_id": "operation1234",
"creation_date": "2023-12-07T15:27:17",
"update_date": "2023-12-07T15:27:17",
"custom_data": null,
"payment_methods_responses": [
{
"operation_id": "123",
"payment_method_operation_id": "pmid123",
"response_code": "200",
"response_message": null
}
]
}Payment Operation object.
Retrieve a cancel operation by operation id
Retrieve information for a given payment operation id. The id of the payment operation must be supplied replacing {id} in the URL path.
GET /v1/payment/charges/{id} HTTP/1.1
200 OKReturns
Payment Operation object.
{
"id": 1,
"payment_order_id": "1",
"status": "DONE",
"requested": {
"amount": 10.00,
"currency": "USD"
},
"external_id": "operation1234",
"creation_date": "2023-12-07T15:25:03",
"update_date": "2023-12-07T15:25:03",
"custom_data": null,
"payment_methods_responses": [
{
"operation_id": "123",
"payment_method_operation_id": "pmid123",
"response_code": "200",
"response_message": null
}
]
}Payment Operation - Charge
Once a payment order is Authorized, you may charge all or part of the payment order. To do this, push the amount you wish to charge as a parameter. To charge for the entire order, enter the full amount.
Charge a payment order by Payment Order id
POST /v1/payment/payment-orders/{paymentOrderId}/charges HTTP/1.1
200 SuccessRequest parameters
{
"requested": {
"amount": 10.00,
"currency": "USD"
},
"external_id": "operation1234",
"custom_data": null
}| Field | Required | Type | Description |
|---|---|---|---|
requested |
Yes | Object | Amount information |
external_id |
No | String | Payment Operation reference, from the merchant’s side |
custom_data |
No | String | To link any additional data to this operation |
Returns
{
"id": 1,
"payment_order_id": "1",
"status": "DONE",
"requested": {
"amount": 10.00,
"currency": "USD"
},
"external_id": "operation1234",
"creation_date": "2023-12-07T15:26:40",
"update_date": "2023-12-07T15:26:40",
"custom_data": null,
"payment_methods_responses": [
{
"operation_id": "123",
"payment_method_operation_id": "pmid123",
"response_code": "200",
"response_message": null
}
]
}Payment Operation object.
Retrieve a charge operation by operation id
Retrieve information for a given payment operation id. The id of the payment operation must be supplied replacing {id} in the URL path.
GET /v1/payment/charges/{id} HTTP/1.1
200 OKReturns
Payment Operation object.
{
"id": 1,
"payment_order_id": "1",
"status": "DONE",
"requested": {
"amount": 10.00,
"currency": "USD"
},
"external_id": "operation1234",
"creation_date": "2023-12-07T15:25:03",
"update_date": "2023-12-07T15:25:03",
"custom_data": null,
"payment_methods_responses": [
{
"operation_id": "123",
"payment_method_operation_id": "pmid123",
"response_code": "200",
"response_message": null
}
]
}Payment Operation - Refund
Once a payment order is charged, you may refund it if the option is available for this payment method. To do this, push the amount you wish to refund as a parameter. To refund for the entire order, enter the full amount.
Refund a payment order by Payment Order id
POST /v1/payment/payment-orders/{paymentOrderId}/refunds HTTP/1.1
200 SuccessRequest parameters
{
"requested": {
"amount": 10.00,
"currency": "USD"
},
"external_id": "operation1234",
"custom_data": null
}| Field | Required | Type | Description |
|---|---|---|---|
requested |
Yes | Object | Amount information |
external_id |
No | String | Payment Operation reference, from the merchant’s side |
custom_data |
No | String | To link any additional data to this operation |
Returns
{
"id": 1,
"payment_order_id": "1",
"status": "DONE",
"requested": {
"amount": 10.00,
"currency": "USD"
},
"external_id": "operation1234",
"creation_date": "2023-12-07T15:27:17",
"update_date": "2023-12-07T15:27:17",
"custom_data": null,
"payment_methods_responses": [
{
"operation_id": "123",
"payment_method_operation_id": "pmid123",
"response_code": "200",
"response_message": null
}
]
}Payment Operation object.
Retrieve a refund operation by operation id
Retrieve information for a given payment operation id. The id of the payment operation must be supplied replacing {id} in the URL path.
GET /v1/payment/refunds/{id} HTTP/1.1
200 OKReturns
Payment Operation object.
{
"id": 1,
"payment_order_id": "1",
"status": "DONE",
"requested": {
"amount": 10.00,
"currency": "USD"
},
"processed": {
"amount": 10.00,
"currency": "USD"
},
"external_id": "operation1234",
"creation_date": "2023-12-07T15:25:03",
"update_date": "2023-12-07T15:25:03",
"custom_data": null,
"payment_methods_responses": [
{
"operation_id": "123",
"payment_method_operation_id": "pmid123",
"response_code": "200",
"response_message": null
}
]
}Account Management
The Account endpoint allows you to :
- Get information about your current balance
- Get informations about the entries of your account
- Request for an internal transfer or a payout
Balances
The Balance object is an information about an account balance at a specified date.
Retrieve an available balance
Available balance : to transfer money from an account. This is all the validated money but it could exist a reserve to for asked debits (e.g. to finance a refund).
GET /v1/account/accounts/{accountExternalId}/balances/available HTTP/1.1
201 SuccessRetrieve information for a given account the available balance from an Account external ID. The Account external ID must be supplied replacing {accountExternalId} in the URI path.
Returns
Balance object, with the type “AVAILABLE”.
{
"type": "AVAILABLE",
"date": "2024-01-11T14:56:51",
"last_change_date": "2024-01-10T13:13:23",
"balance": {
"amount": 10234.97,
"currency": "EUR"
}
}Retrieve an expected balance
Expected balance : balance expected once all the pending transfers will be validated.
GET /v1/account/accounts/{accountExternalId}/balances/expected HTTP/1.1
201 SuccessRetrieve information for a given account the available balance from an Account external ID. The Account external ID must be supplied replacing {accountExternalId} in the URI path.
Returns
Balance object, with the type “EXPECTED”.
{
"type": "EXPECTED",
"date": "2024-01-11T14:56:51",
"last_change_date": "2024-01-10T13:13:23",
"balance": {
"amount": 11667.51,
"currency": "EUR"
}
}Retrieve a balance waiting for validation
Balance waiting for validation : balance containing all transfers awaiting validation
GET /v1/account/accounts/{accountExternalId}/balances/waitingforvalidation HTTP/1.1
201 SuccessRetrieve information for a given account the balance waiting for validation from an Account external ID. The Account external ID must be supplied replacing {accountExternalId} in the URI path.
Returns
Balance object, with the type “WAITING_FOR_VALIDATION”.
{
"type": "WAITING_FOR_VALIDATION",
"date": "2024-01-11T14:56:51",
"last_change_date": "2024-01-10T13:13:23",
"balance": {
"amount": 1432.54,
"currency": "EUR"
}
}Retrieve an up to date balance
Up to date balance : balance counting all the validated transfers.
GET /v1/account/accounts/{accountExternalId}/balances/uptodate HTTP/1.1
201 SuccessRetrieve information for a given account the up to date balance from an Account external ID. The Account external ID must be supplied replacing {accountExternalId} in the URI path.
Returns
Balance object, with the type “UP_TO_DATE”.
{
"type": "UP_TO_DATE",
"date": "2024-01-11T14:56:51",
"last_change_date": "2024-01-10T13:13:23",
"balance": {
"amount": 10234.97,
"currency": "EUR"
}
}Retrieve all balances
Retrieve all 4 types of balances for one account with this call.
GET /v1/account/accounts/{accountExternalId}/balances HTTP/1.1
201 SuccessRetrieve information for a given account the up to date balance from an Account external ID. The Account external ID must be supplied replacing {accountExternalId} in the URI path.
Returns
List of Balance object, one of each type : Available, Expected, Waiting for validation, and Up to date.
{
"balances": [
{
"type": "AVAILABLE",
"date": "2024-01-11T14:56:51",
"last_change_date": "2024-01-10T13:13:23",
"balance": {
"amount": 10234.97,
"currency": "EUR"
}
},
{
"type": "EXPECTED",
"date": "2024-01-11T14:56:51",
"last_change_date": "2024-01-10T13:13:23",
"balance": {
"amount": 11667.51,
"currency": "EUR"
}
},
{
"type": "UP_TO_DATE",
"date": "2024-01-11T14:56:51",
"last_change_date": "2024-01-10T13:13:23",
"balance": {
"amount": 10234.97,
"currency": "EUR"
}
},
{
"type": "WAITING_FOR_VALIDATION",
"date": "2024-01-11T14:56:51",
"last_change_date": "2024-01-10T13:13:23",
"balance": {
"amount": 1432.54,
"currency": "EUR"
}
}
]
}Accounts : Entries
The Entry object is a line of an account statement. It represents one side of a transfer. For one transfer between two accounts, there are two entries, one on the sourceaccount and one on the targetaccount.
Retrieve an entry
GET /v1/account/accounts/{accountExternalId}/entries HTTP/1.1
201 SuccessReturns
Entries object.
[
{
"account_id": "999922490000",
"entry": {
"amount": 0.19,
"currency": "EUR"
},
"counterpart_account_id": "999925700000",
"creation_date": "2024-01-02T09:32:32",
"credit_debit_indicator": "credit",
"label": "Whatever",
"status": "WAITINGFORVALIDATION",
"transfer_request_id": "425439380000",
"validation_date": null
},
{
"account_id": "999922490000",
"entry": {
"amount": 0.74,
"currency": "EUR"
},
"counterpart_account_id": "999925700000",
"creation_date": "2024-01-02T13:42:26",
"credit_debit_indicator": "credit",
"label": "Whatever",
"status": "WAITINGFORVALIDATION",
"transfer_request_id": "975477660000",
"validation_date": null
},
]Transfer Requests
The TransferRequests object is a request to transfer money between two accounts on our platform.
Create a transfer request
Request parameters
POST /v1/account/transfer-requests HTTP/1.1
201 Success{
"transfer": {
"amount": 10.00,
"currency": "USD"
},
"external_reference": "transfer123456",
"label": "transfer123456",
"source_account_id": "123456789123",
"target_account_id": "123111111111",
"type": "ScheduledTransferOut",
"custom_data": null
}| Field | Required | Type | Description |
|---|---|---|---|
transfer |
Yes | Object | Amount information |
external_reference |
Yes | String | Reference of the transfer on your side |
label |
Yes | String | Label of the transfer |
source_account_id |
Yes | String | From where the money is being transfered |
target_account_id |
Yes | String | To where the money is being transfered |
type |
Yes | String | Transfer request type information |
custom_data |
No | String | Any additional information |
Returns
Transfer request object.
{
"id": "1",
"transfer": {
"amount": 10.00,
"currency": "USD"
},
"creation_date": "2023-12-07T16:00:27",
"external_reference": "transfer123456",
"label": "transfer123456",
"status": "WaitingForValidation",
"source_account_id": "123456789123",
"target_account_id": "123111111111",
"type": "ScheduledTransferOut",
"validation_date": "2023-12-07T16:00:27",
"related": [
{
"resource_type": "PaymentOrder",
"resource_id": "740822050000"
}
],
"custom_data": null
}Retrieve a transfer request
GET /v1/account/transfer-requests/{externalId} HTTP/1.1
201 SuccessRetrieve information for a given transfer request. The id of the transfer request must be supplied replacing {id} in the URI path.
Returns
Transfer request object.
{
"id": "1",
"transfer": {
"amount": 10.00,
"currency": "USD"
},
"creation_date": "2023-12-07T16:00:27",
"external_reference": "transfer123456",
"label": "transfer123456",
"status": "WaitingForValidation",
"source_account_id": "123456789123",
"target_account_id": "123111111111",
"type": "ScheduledTransferOut",
"validation_date": "2023-12-07T16:00:27",
"related": [
{
"resource_type": "PaymentOrder",
"resource_id": "740822050000"
}
],
"custom_data": null
}Payout Requests
The PayoutRequest object is a withdrawal request to get funds managed by our platform.
Create a payout
Request parameters
POST /v1/account/payout-requests HTTP/1.1
201 Success{
"payout": {
"amount": 10.00,
"currency": "USD"
},
"source_account_id": "123456789123",
"external_reference": "externalref123",
"label": "payout 1",
"payout_bank_account_id": "123456789123",
"custom_data": null
}| Field | Required | Type | Description |
|---|---|---|---|
payout |
Yes | Object | Amount information |
external_reference |
Yes | String | Reference of the transfer on your side |
label |
Yes | String | Label of the payout |
source_account_id |
Yes | String | From where the money is being transfered |
payout_bank_account_id |
yes | String | To where the money is being transfered |
custom_data |
No | String | Any additional information |
Returns
{
"id": 1,
"payout": {
"amount": 10.00,
"currency": "USD"
},
"creation_date": "2023-12-07T16:01:46",
"external_reference": "externalref123",
"label": "payout 1",
"payout_bank_account_id": "123456789123",
"source_account_id": "123456789123",
"status": "charged",
"target": {
"amount": 10.00,
"currency": "USD"
},
"transfer_request_id": "000098021150",
"validation_date": "2023-12-07T16:01:46",
"custom_data": null
}Payout request object.
Retrieve a payout
GET /v1/account/payout-requests/{externalId} HTTP/1.1
201 SuccessRetrieve information for a given payout. The id of the payout must be supplied replacing {id} in the URI path.
Returns
{
"id": 1,
"payout": {
"amount": 10.00,
"currency": "USD"
},
"creation_date": "2023-12-07T16:00:06",
"external_reference": "externalref123",
"label": "payout 1",
"payout_bank_account_id": "123456789123",
"source_account_id": "123456789123",
"status": "charged",
"target": {
"amount": 10.00,
"currency": "USD"
},
"transfer_request_id": "000098021150",
"validation_date": "2023-12-07T16:00:06",
"custom_data": null
}Payout request object.
Onboardings
To onboard a new merchant on our platform, it’s important to respect this creation flow.
To get started, we will give you a template id. This id will apply a specific configuration to your onboarding so that you do not have to enter a large number of technical details yourself.
First, you have to create the company. A “company” corresponds to an organization (an integrator, a merchant, a marketplace, a payment institution, a PSP, a means of payment). Thunes Collections Back-office users are always attached to a company. Several payment methods or several merchants can be attached to the same company.
Next, you have to create the merchant. A “merchant” is the commercial entity which can make calls directly or via its PSP or its integrator to the Payment API to create transactions.
If you are in a fund collection context, you have to create an “acccount”. An “account” allows you to collect remittance from payment methods and allow a company to do payouts.
Finally, you have to create the merchant payment page association. To be able to create transactions (via the Payment API) a merchant must be associated with a payment page.
It’s possible to edit information of an account to change fees or the bank account coordinates for payouts.
Companies
As said previously, a “company” corresponds to an organization (an integrator, a merchant, a marketplace, a payment institution, a PSP, a means of payment). Thunes Collections Back-office users are always attached to a company. Several payment methods or several merchants can be attached to the same company.
Create a company
POST /v1/onboarding/companies HTTP/1.1
201 SuccessRequest parameters
{
"template_id": "My Company Name",
"name": "my-template-id"
}| Field | Required | Type | Description |
|---|---|---|---|
template_id |
Yes | String | Id of the model that will be used to create the company |
name |
Yes | String | Name of the company to be created |
Returns
{
"id": 1,
"name": "My Company Name",
"creation_date": "2023-12-07T16:09:48",
"update_date": "2023-12-07T16:09:48"
}Company object.
Retrieve a company by id
GET /v1/onboarding/companies/{nameId} HTTP/1.1
201 SuccessReturns
{
"id": 1,
"name": "My Company Name",
"creation_date": "2023-12-07T16:09:48",
"update_date": "2023-12-07T16:09:48"
}Company object.
Merchants
A “merchant” is the commercial entity which can make calls directly or via its PSP or its integrator to the Payment API to create transactions.
Create a merchant
Request parameters
POST /v1/onboarding/merchants HTTP/1.1
201 Success{
"company_id": "1",
"merchant_external_id": "my_merchant_id",
"name": "My Merchant Name",
"template_id": "my_merchant_template_id",
"custom_data": null
}| Field | Required | Type | Description |
|---|---|---|---|
company_id |
Yes | String | Id of the company that will own the merchant |
merchant_external_id |
Yes | String | Your own id to be linked to the merchant |
name |
Yes | String | Name of the merchant to be created |
template_id |
Yes | String | Id of the model that will be used to create the merchant |
custom_data |
No | JSON | Any type of information to help validation from entities |
Returns
Merchant object.
{
"id": 1,
"company_id": "1",
"currency": "USD",
"merchant_external_id": "my_merchant_id",
"name": "My Merchant Name",
"template_id": "my_merchant_template_id",
"custom_data": null,
"creation_date": "2023-12-07T16:09:08",
"update_date": "2023-12-07T16:09:08"
}Retrieve a merchant by id
GET /v1/onboarding/merchants/{nameId} HTTP/1.1
201 SuccessReturns
Merchant object.
{
"id": 1,
"company_id": "1",
"currency": "USD",
"merchant_external_id": "my_merchant_id",
"name": "My Merchant Name",
"template_id": "my_merchant_template_id",
"custom_data": null,
"creation_date": "2023-12-07T16:09:08",
"update_date": "2023-12-07T16:09:08"
}Accounts
An “account” allows you to collect remittance from payment methods and allow a company to do payouts.
Create an account
Request parameters
POST /v1/onboarding/accounts HTTP/1.1
201 Success{
"template_id": "1",
"label": "MyAccount",
"company_id": "my_company_id",
"recipient_email": "jean.dupont@mail.com",
"fees": [
"fee_id"
],
"payout_bank_accounts": [
{
"address_line_1": "47 Av. de l'Opéra, 75002 Paris, France",
"address_line_2": null,
"bank_name": "Bank Name",
"bank_address": "1 Av. des Champs-Élysées75008 Paris",
"bank_country_iso_code": "FRA",
"bank_routing_code": "000123456",
"bank_branch_code": "00001",
"bic": "AAAAAAA4B",
"card_number": "0000111122223333",
"external_id": "external_id",
"external_account_id": "external_account_id",
"external_account_type": "B2B",
"iban": "ES0000000000050200050000",
"holder_name": "Jean Dupres",
"holder_email": "jean.dupres@mail.com",
"holder_phone": "0102030405",
"format": "IBAN",
"label": "Payout Bank Account Name",
"registration_number": "123",
"representative_id_number": "1234",
"representative_name": "Jean Dubois",
"target_currency": "USD",
"tax_id": "tax_id",
}
]
}| Field | Required | Type | Description |
|---|---|---|---|
company_id |
Yes | String | Id of the company that will own the account |
fees |
No | Table | Fees related to account creation |
label |
Yes | String | Name of the account |
payout_bank_accounts |
No | Table | Object to describe the bank account that will be the destination of the payout |
address_line_1 |
No | String | Adress line 1 of the owner of the payout bank account |
address_line_2 |
No | String | Adress line 2 of the owner of the payout bank account |
bank_name |
No | String | Name of the bank of the payout bank account |
bank_address |
No | String | Adress of the payout bank |
bank_country_iso_code |
No | String (ISO 3166-1 alpha-3) | Country of the payout bank |
bank_routing_code |
No | String | Routing code of the payout bank |
bank_branch_code |
No | String | Branch code of the payout bank |
bic |
Yes | String | Bic of the payout bank |
card_number |
No | String | Card number of the merchant that will receive the payout |
external_id |
No | String | Thunes unique identifier of the payout bank account |
external_account_id |
No | String | Identifier of the account at the bank or in the target payout system |
external_account_type |
No | String | Type of account : SAVINGS, DEPOSIT, CHECKING, or OTHERS |
iban |
Yes | String | IBAN of the payout bank account |
holder_name |
No | String | Name of the holder of the payout bank account |
holder_email |
No | String | Email of the holder of the payout bank account |
holder_phone |
No | String | Phone number of the holder of the payout bank account |
format |
Yes | String | Allow to know if we are storing IBAN, CLABE account, US account, etc. |
label |
Yes | String | Name of the payout bank account |
registration_number |
No | String | Registration number |
representative_id_number |
No | String | Presented identification number |
representative_name |
No | String | Name of the representative of the business |
target_currency |
No | String | Currency of the payout bank account |
tax_id |
No | String | Tax identifier |
recipient_email |
No | String | Email used to sent some accouting documentation |
template_id |
Yes | String | Tto apply same configuration for multiple account creation |
Returns
Account object.
{
"template_id": "1",
"label": "MyAccount",
"company_id": "my_company_id",
"recipient_email": "jean.dupont@mail.com",
"fees": [
"fee_id"
],
"payout_bank_accounts": [
{
"id": 1,
"address_line_1": "47 Av. de l'Opéra, 75002 Paris, France",
"address_line_2": null,
"bank_name": "Bank Name",
"bank_address": "1 Av. des Champs-Élysées75008 Paris",
"bank_country_iso_code": "FRA",
"bank_routing_code": "000123456",
"bank_branch_code": "00001",
"bic": "AAAAAAA4B",
"card_number": "0000111122223333",
"external_id": "external_id",
"external_account_id": "external_account_id",
"external_account_type": "B2B",
"iban": "ES0000000000050200050000",
"holder_name": "Jean Dupres",
"holder_email": "jean.dupres@mail.com",
"holder_phone": "0102030405",
"format": "IBAN",
"label": "Payout Bank Account Name",
"registration_number": "123",
"representative_id_number": "1234",
"representative_name": "Jean Dubois",
"status": "charged",
"target_currency": "USD",
"tax_id": "tax_id",
"is_blocked": true,
"is_default": true,
"creation_date": "2023-12-07T16:10:16",
"update_date": "2023-12-07T16:10:16"
}
],
"balances": [
{
"type": "B2B",
"date": "2023-12-07T16:11:57",
"last_change_date": "2023-12-07T16:11:57",
"balance": {
"amount": 10.00,
"currency": "USD"
}
}
]
}Modify an account
Request parameters
PATCH /v1/onboarding/accounts HTTP/1.1
201 Success{
"recipient_email": "jean.dupont@mail.com",
"fees": [
"fee_id"
],
"payout_bank_accounts": [
{
"address_line_1": "47 Av. de l'Opéra, 75002 Paris, France",
"address_line_2": null,
"bank_name": "Bank Name",
"bank_address": "1 Av. des Champs-Élysées75008 Paris",
"bank_country_iso_code": "FRA",
"bank_routing_code": "000123456",
"bank_branch_code": "00001",
"bic": "AAAAAAA4B",
"card_number": "0000111122223333",
"external_id": "external_id",
"external_account_id": "external_account_id",
"external_account_type": "B2B",
"iban": "ES0000000000050200050000",
"holder_name": "Jean Dupres",
"holder_email": "jean.dupres@mail.com",
"holder_phone": "0102030405",
"format": "IBAN",
"label": "Payout Bank Account Name",
"registration_number": "123",
"representative_id_number": "1234",
"representative_name": "Jean Dubois",
"target_currency": "USD",
"tax_id": "tax_id",
}
]
}| Field | Required | Type | Description |
|---|---|---|---|
fees |
No | Table | Fees related to account creation |
payout_bank_accounts |
No | Table | Object to describe the bank account that will be the destination of the payout |
address_line_1 |
No | String | Adress line 1 of the owner of the payout bank account |
address_line_2 |
No | String | Adress line 2 of the owner of the payout bank account |
bank_name |
No | String | Name of the bank of the payout bank account |
bank_address |
No | String | Adress of the payout bank |
bank_country_iso_code |
No | String (ISO 3166-1 alpha-3) | Country of the payout bank |
bank_routing_code |
No | String | Routing code of the payout bank |
bank_branch_code |
No | String | Branch code of the payout bank |
bic |
Yes | String | Bic of the payout bank |
card_number |
No | String | Card number of the merchant that will receive the payout |
external_id |
No | String | Thunes unique identifier of the payout bank account |
external_account_id |
No | String | Identifier of the account at the bank or in the target payout system |
external_account_type |
No | String | Type of account : SAVINGS, DEPOSIT, CHECKING, or OTHERS |
iban |
Yes | String | IBAN of the payout bank account |
holder_name |
No | String | Name of the holder of the payout bank account |
holder_email |
No | String | Email of the holder of the payout bank account |
holder_phone |
No | String | Phone number of the holder of the payout bank account |
format |
Yes | String | Allow to know if we are storing IBAN, CLABE account, US account, etc. |
label |
Yes | String | Name of the payout bank account |
registration_number |
No | String | Registration number |
representative_id_number |
No | String | Presented identification number |
representative_name |
No | String | Name of the representative of the business |
target_currency |
No | String | Currency of the payout bank account |
tax_id |
No | String | Tax identifier |
recipient_email |
No | String | Email used to send some accouting documentation |
Returns
Account object.
{
"template_id": "1",
"label": "MyAccount",
"company_id": "my_company_id",
"recipient_email": "jean.dupont@mail.com",
"fees": [
"fee_id"
],
"payout_bank_accounts": [
{
"id": 1,
"address_line_1": "47 Av. de l'Opéra, 75002 Paris, France",
"address_line_2": null,
"bank_name": "Bank Name",
"bank_address": "1 Av. des Champs-Élysées75008 Paris",
"bank_country_iso_code": "FRA",
"bank_routing_code": "000123456",
"bank_branch_code": "00001",
"bic": "AAAAAAA4B",
"card_number": "0000111122223333",
"external_id": "external_id",
"external_account_id": "external_account_id",
"external_account_type": "B2B",
"iban": "ES0000000000050200050000",
"holder_name": "Jean Dupres",
"holder_email": "jean.dupres@mail.com",
"holder_phone": "0102030405",
"format": "IBAN",
"label": "Payout Bank Account Name",
"registration_number": "123",
"representative_id_number": "1234",
"representative_name": "Jean Dubois",
"status": "charged",
"target_currency": "USD",
"tax_id": "tax_id",
"is_blocked": true,
"is_default": true,
"creation_date": "2023-12-07T16:10:16",
"update_date": "2024-01-07T16:11:57"
}
],
"balances": [
{
"type": "B2B",
"date": "2023-12-07T16:11:57",
"last_change_date": "2024-01-07T16:11:57",
"balances": {
"amount": 10.00,
"currency": "USD"
}
}
]
}Retrieve an account using your id
GET/v1/onboarding/accounts/{id} HTTP/1.1
201 SuccessReturns
Account object.
{
"template_id": "1",
"label": "MyAccount",
"company_id": "my_company_id",
"recipient_email": "jean.dupont@mail.com",
"fees": [
"fee_id"
],
"payout_bank_accounts": [
{
"id": 1,
"address_line_1": "47 Av. de l'Opéra, 75002 Paris, France",
"address_line_2": null,
"bank_name": "Bank Name",
"bank_address": "1 Av. des Champs-Élysées75008 Paris",
"bank_country_iso_code": "FRA",
"bank_routing_code": "000123456",
"bank_branch_code": "00001",
"bic": "AAAAAAA4B",
"card_number": "0000111122223333",
"external_id": "external_id",
"external_account_id": "external_account_id",
"external_account_type": "B2B",
"iban": "ES0000000000050200050000",
"holder_name": "Jean Dupres",
"holder_email": "jean.dupres@mail.com",
"holder_phone": "0102030405",
"format": "IBAN",
"label": "Payout Bank Account Name",
"registration_number": "123",
"representative_id_number": "1234",
"representative_name": "Jean Dubois",
"status": "charged",
"target_currency": "USD",
"tax_id": "tax_id",
"is_blocked": true,
"is_default": true,
"creation_date": "2023-12-07T16:10:16",
"update_date": "2024-01-07T16:11:57"
}
],
"balances": [
{
"type": "B2B",
"date": "2023-12-07T16:11:57",
"last_change_date": "2024-01-07T16:11:57",
"balance": {
"amount": 10.00,
"currency": "USD"
}
}
]
}Merchant Payment Pages Configuration
Create a Merchant Payment Page Configuration
Request parameters
POST /v1/onboarding/merchant-payment-pages/{merchantId}/{paymentPageId} HTTP/1.1
201 Success{
"payment_page_id": "paymentpage1",
"merchant_id": "mymerchant",
"merchant_external_id": "my_merchant_id",
"status": "activated",
"specific_parameters" : {
"myspecparam" : "value1",
"otherparam" : "123456"
},
"custom_data" : {
"mydata" : "123",
"myotherdata" : "abdc"
}
}| Field | Required | Type | Description |
|---|---|---|---|
payment_page_id |
Yes | String | Id of the payment page |
merchant_id |
Yes* | Yes | Id of the merchant |
merchant_external_id |
Yes* | Yes | External Id of the merchant |
status |
No | String | To activate or deactivate a merchant payment page configuration |
specific_parameters |
No | JSON | Specific parameters for a merchant payment page configuration in a marketplace context |
custom_data |
No | String | To provide information to help for validation |
*Only merchant_id OR merchant_external_id are required
Returns
Merchant Payment Page Configuration object.
{
"creation_date": "2023-12-07T16:08:47",
"merchant_id": "mymerchant",
"merchant_external_id": "my_merchant_id",
"payment_integrator_id": "paymentintegrator1",
"payment_page_id": "paymentpage1",
"specific_parameters" : {
"myspecparam" : "value1",
"otherparam" : "123456"
},
"status": "activated",
"update_date": "2023-12-07T16:08:47",
"custom_data" : {
"mydata" : "123",
"myotherdata" : "abdc"
}
}Modify a Merchant Payment Page Configuration
Request parameters
PATCH /v1/onboarding/merchant-payment-pages/{merchantId}/{paymentPageId} HTTP/1.1
201 Success{
"status": "activated",
"specific_parameters" : {
"myspecparam" : "value1",
"otherparam" : "123456"
},
"custom_data" : {
"mydata" : "123",
"myotherdata" : "abdc"
}
}| Field | Required | Type | Description |
|---|---|---|---|
status |
No | String | To activate or deactivate a merchant payment page configuration |
specific_parameters |
No | JSON | Specific parameters for a merchant payment page configuration in a marketplace context |
custom_data |
No | String | To provide information to help for validation |
Returns
Merchant Payment Page Configuration object.
{
"creation_date": "2023-12-07T16:08:47",
"merchant_id": "mymerchant",
"merchant_external_id": "my_merchant_id",
"payment_integrator_id": "paymentintegrator1",
"payment_page_id": "paymentpage1",
"specific_parameters" : {
"myspecparam" : "value1",
"otherparam" : "123456"
},
"status": "activated",
"update_date": "2023-12-07T16:08:47",
"custom_data" : {
"mydata" : "123",
"myotherdata" : "abdc"
}
}Retrieve a Merchant Payment Page Configuration by id
GET /v1/onboarding/merchant-payment-pages/{merchantNameId}/{paymentPageNameId} HTTP/1.1
201 SuccessReturns
A list of Merchant Payment Page Configuration object.
{
"creation_date": "2023-12-07T16:08:47",
"merchant_id": "mymerchant",
"merchant_external_id": "my_merchant_id",
"payment_integrator_id": "paymentintegrator1",
"payment_page_id": "paymentpage1",
"specific_parameters": null,
"status": "charged",
"update_date": "2023-12-07T16:08:47",
"custom_data": null
}Retrieve a list of Merchant Payment Page
GET /v1/onboarding/merchant-payment-pages HTTP/1.1
201 SuccessReturns
A list of Merchant Payment Page Configuration object.
[
{
"creation_date": "2023-12-07T16:08:47",
"merchant_id": "mymerchant",
"merchant_external_id": "my_merchant_id",
"payment_integrator_id": "paymentintegrator1",
"payment_page_id": "paymentpage1",
"specific_parameters": null,
"status": "charged",
"update_date": "2023-12-07T16:08:47",
"custom_data": null
}
]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.
Payment Order
{
"id": "433282730000",
"requested": {
"amount": 2000.00,
"currency": "MXN"
},
"processed": {
"amount": 10.00,
"currency": "EUR"
},
"creation_date": "2024-01-08T15:51:54",
"quotation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"merchant_id": "mymerchant",
"external_id": "987654",
"merchant_external_id": "my_company_id",
"merchant_urls": {
"aborted_url": "aborted.com",
"error_url": "error.com",
"return_url": "return.com",
"notification_url": "notification.com"
},
"payment_integrator_id": "string",
"payment_page_id": "paymentpage12345",
"payment_url": "payment.com",
"status": "Authorized",
"update_date": "2024-01-08T15:51:54",
"merchant_order": {
"total": {
"amount": 10.00,
"currency": "EUR"
},
"tax": {
"amount": 0.50,
"currency": "EU"
},
"searchable_custom_data_1": null,
"searchable_custom_data_2": null,
"custom_data": null,
"billing_address": {
"address_line_1": "47 avenue de l'opera",
"address_line_2": null,
"city": "Paris",
"company_name": "Thunes",
"country_iso_code": "FRA",
"custom_data": null,
"first_name": "Jean",
"home_phone": null,
"last_name": "Dupont",
"mobile_phone": null,
"region": "Ile-de-France",
"title": null,
"zip_code": "75002"
},
"shipping_address": {
"address_line_1": "47 avenue de l'opera",
"address_line_2": null,
"city": "Paris",
"company_name": "Thunes",
"country_iso_code": "FRA",
"custom_data": null,
"first_name": "Jean",
"home_phone": null,
"last_name": "Dupont",
"mobile_phone": null,
"region": "Ile-de-France",
"title": null,
"zip_code": "75002"
},
"customer": {
"account_creation_date": "2023-10-26T14:24:31",
"date_of_birth": "1990-01-31",
"company_name": null,
"culture": "fr-FR",
"custom_data": null,
"email": "jean.dupont@mail.com",
"first_name": "Jean",
"home_phone": null,
"id": null,
"last_name": "Dupont",
"mobile_phone": "string",
"title": null
},
"cart_items": [
{
"brand": "yourbrand",
"category": "cathegory1",
"label": "object123",
"custom_data": null,
"merchant_category_1": null,
"merchant_category_2": null,
"merchant_item_id": null,
"quantity": 1,
"type": null,
"unit_price": {
"amount": 10.00,
"currency": "EUR"
},
"url": null,
"vat": {
"amount": 10.00,
"currency": "EUR"
},
"delivery": {
"label": null,
"type": null,
"speed": "2",
"expected_date": "2023-10-26T14:24:31",
"expected_delay": 0,
"custom_data": null
}
}
]
},
"type": "B2B",
"integration_mode": "REDIRECT",
"payment_methods": [
{
"amounts": {
"authorizing": {
"amount": 10.00,
"currency": "EUR"
},
},
"brand": "string",
"custom_data": "string",
"holder_id": "string",
"holder_email": "string",
"payment_instruction": {
"url": "redirecturl3ds.com",
"display_message": "Please proceed to do A, B and C to complete the payment"
},
"payment_method_order_id": "string",
"payment_method_reference": "string",
"type": "string"
}
]
"payment_information": {
"card_number": "6541778898761532",
"card_cvv": "123",
"card_expiration_year": "2050",
"card_expiration_month": "01",
"card_holder_name": "Jean Dupont",
"email": "jean.dupont@mail.com",
"phone_number": "0033612345678",
"token_id": null,
"bank_account_number": null,
"account_holder_name": null,
"otp": "123456",
"msisdn": "263775892364",
"qrcode": "324032942309",
"bank_id": "123"
}
}Represents a transaction, between a buyer and a merchant.
| Field | Required | Type | Description |
|---|---|---|---|
id |
No | String | Identifier of the payment order |
quotation_id |
No | GUID | Allows to create a transaction based on the amounts on a quotation made before |
type |
Yes | String | Indicates if transaction in B2B or C2B |
requested |
No | Object | Amount of the transaction for the merchant. Is optionnal if a quotation is used to create a transaction instead. Amount information |
merchant_id |
Yes | String | Merchant identifier |
merchant_external_id |
Yes | String | Unique external payment order id |
external_id |
No | String | Payment Operation reference, from the merchant’s side |
merchant_urls |
Yes | Object | Merchant redirection URLs information |
payment_page_id |
Yes | String | Targeted payment method ID |
merchant_order |
No | Object | Merchant order information |
integration_mode |
Yes | String | Indicates if the payment is made in redirection mode (thunes or the payment method host the payment page) or in host to host mode (the merchant hosts the payment page) |
payment_methods |
No | Object | In the response of a POST Payment Order or a GET Payment Order, represents info related to a specific payment method of the transaction (# Payment_Methods) |
payment_information |
No | Object | Payment information |
Quotation
{
"external_id": "123456789",
"id": "3fa85f64-5717-4562-c3fc-2c963f66afa9",
"merchant_id": "mymerchant",
"payment_page_id": "paymentpage12345",
"requested": {
"amount": 10.00,
"currency": "EUR"
},
"processed": {
"amount": 2000.00,
"currency": "MXN"
},
"wholesale_fx_rate": 200.000000000000000000,
"creation_date": "2024-03-11T16:36:04",
"expiration_date": "2024-03-12T16:36:04",
"quotation_mode": "REQUESTED_AMOUNT"
}A quotation defines a rate between an amount for the merchant (requested) in currency A and an amount for the buyer (processed), in currency B
| Field | Type | Description |
|---|---|---|
id |
GUID | Id of the quotation. Allows to create a transaction based on the amounts of that quotation |
external_id |
String | Allows the merchant to link his own unique id to a quotation |
payment_page_id |
String | Allows to create a transaction based on the amounts of that quotation |
requested |
Amount | Amount of the quotation from the merchant point of view. |
processed |
Amount | Amount of the quotation from the buyer point of view. |
wholesale_fx_rate |
Double | Rate used to convert the requested amount into the process amount |
creation_date |
Date | Date of the creation |
expiration_date |
Date | Limit when the quotation can be used |
quotation_mode |
String | “REQUESTED_AMOUNT” or “PROCESSED_AMOUNT” . Indicates what is the input provided |
Requested
"requested": {
"amount": 2000.00,
"currency": "MXN"
},Amount of the quotation from the merchant point of view. It defines the amount that will be the base to make a transaction. If the transaction is created in ACC mode, then the requested amount will be converted in the processed amount. If the mode is non-ACC (the merchant and the buyer are using the same currency), then both amounts are equals, in the same currency.
| Field | Type | Description |
|---|---|---|
amount |
String | The value of the amount |
currency |
Decimal | The currency of the amount |
Processed
"processed": {
"amount": 10.00,
"currency": "EUR"
}Amount of the quotation from the buyer point of view. It defines the amount that will be paid by the buyer. If the transaction is created in a context configured in ACC, then the requested amount will be converted in the processed amount. If the mode is non-ACC (the merchant and the buyer are using the same currency), then both amounts are equals, in the same currency.
| Field | Type | Description |
|---|---|---|
amount |
String | The value of the amount |
currency |
Decimal | The currency of the amount |
Merchant Order
The merchant order part of a transaction allows the merchant to store data related to this transaction, that he can retrieve.
"merchant_order": {
"total": {
"amount": 10.00,
"currency": "EUR"
},
"tax": {
"amount": 0.50,
"currency": "EU"
},
"searchable_custom_data_1": null,
"searchable_custom_data_2": null,
"custom_data": null,
"billing_address": {
"address_line_1": "47 avenue de l'opera",
"address_line_2": null,
"city": "Paris",
"company_name": "Thunes",
"country_iso_code": "FRA",
"custom_data": null,
"first_name": "Jean",
"home_phone": null,
"last_name": "Dupont",
"mobile_phone": null,
"region": "Ile-de-France",
"title": null,
"zip_code": "75002"
},
"shipping_address": {
"address_line_1": "47 avenue de l'opera",
"address_line_2": null,
"city": "Paris",
"company_name": "Thunes",
"country_iso_code": "FRA",
"custom_data": null,
"first_name": "Jean",
"home_phone": null,
"last_name": "Dupont",
"mobile_phone": null,
"region": "Ile-de-France",
"title": null,
"zip_code": "75002"
},
"customer": {
"account_creation_date": "2023-10-26T14:24:31",
"date_of_birth": "1990-01-31",
"company_name": null,
"culture": "fr-FR",
"custom_data": null,
"email": "jean.dupont@mail.com",
"first_name": "Jean",
"home_phone": null,
"id": null,
"last_name": "Dupont",
"mobile_phone": "string",
"title": null
},
"cart_items": [
{
"brand": "yourbrand",
"category": "cathegory1",
"label": "object123",
"custom_data": null,
"merchant_category_1": null,
"merchant_category_2": null,
"merchant_item_id": null,
"quantity": 1,
"type": null,
"unit_price": {
"amount": 10.00,
"currency": "EUR"
},
"url": null,
"vat": {
"amount": 10.00,
"currency": "EUR"
},
"delivery": {
"label": null,
"type": null,
"speed": "2",
"expected_date": "2023-10-26T14:24:31",
"expected_delay": 0,
"custom_data": null
}
}
]
},| Field | Type | Description |
|---|---|---|
total |
Amount | Full order amount, including tax and delivery costs |
tax |
Amount | Is used to keep track of the tax on this transaction |
searchable_custom_data_1 |
String | Free text zone and can be retrieve during different Retrieve Operation or Orders call |
searchable_custom_data_2 |
String | Free text zone and can be retrieve during different Retrieve Operation or Orders call |
billing_address |
Object | Billing address information |
shipping_address |
Object | Shipping address information |
customer |
Object | Customer information |
cart_items |
List of objects | List of Cart items information |
custom_data |
JSON | Free text field. This field will be use for payment method specific usage |
Billing Address
"billing_address": {
"address_line_1": "47 avenue de l'opera",
"address_line_2": null,
"city": "Paris",
"company_name": "Thunes",
"country_iso_code": "FRA",
"custom_data": null,
"first_name": "Jean",
"home_phone": null,
"last_name": "Dupont",
"mobile_phone": null,
"region": "Ile-de-France",
"title": null,
"zip_code": "75002"
},| Field | Type | Description |
|---|---|---|
address_line_1 |
String | Billing address line 1 |
address_line_2 |
String | Billing address line 2 |
city |
String | Billing city |
company_name |
String | Name of the company |
country_iso_code |
String (ISO 3166-1 alpha-3) | Billing Country |
first_name |
String | First name of the representative |
home_phone |
String | Home phone of the billing address |
last_name |
String | Last name of the representative |
mobile_phone |
String | Mobile phone of the representative |
region |
String | Region of the billing address |
title |
String | Title of the billing address |
zip_code |
String | Zip code of the billing address |
custom_data |
JSON | Any custom data related to the billing address |
Shipping Address
"shipping_address": {
"address_line_1": "47 avenue de l'opera",
"address_line_2": null,
"city": "Paris",
"company_name": "Thunes",
"country_iso_code": "FRA",
"custom_data": null,
"first_name": "Jean",
"home_phone": null,
"last_name": "Dupont",
"mobile_phone": null,
"region": "Ile-de-France",
"title": null,
"zip_code": "75002"
},| Field | Type | Description |
|---|---|---|
address_line_1 |
String | Shipping address line 1 |
address_line_2 |
String | Shipping address line 2 |
city |
String | Shipping city |
company_name |
String | Name of the company |
country_iso_code |
String (ISO 3166-1 alpha-3) | Shipping Country |
first_name |
String | First name of the representative |
home_phone |
String | Home phone of the shipping address |
last_name |
String | Last name of the representative |
mobile_phone |
String | Mobile phone of the representative |
region |
String | Region of the shipping address |
title |
String | Title of the shipping address |
zip_code |
String | Zip code of the shipping address |
custom_data |
JSON | Any custom data related to the shipping address |
Customer
"customer": {
"account_creation_date": "2023-10-26T14:24:31",
"date_of_birth": "1990-01-31",
"company_name": null,
"culture": "fr-FR",
"custom_data": null,
"email": "jean.dupont@mail.com",
"first_name": "Jean",
"home_phone": null,
"id": null,
"last_name": "Dupont",
"mobile_phone": "string",
"title": null
},| Field | Type | Description |
|---|---|---|
id |
String | id of the customer |
account_creation_date |
Date | Creation date of the account |
date_of_birth |
Date (yyyy-MM-dd) | Date of birth of the customer |
company_name |
String | Company name of the customer |
culture |
BCP 47 (ISO 639-1) | Culture of the customer in format language-REGION. Example : fr-FR, or en-US |
email |
String | Email of the customer |
first_name |
String | First name of the customer |
home_phone |
String | Home phone of the customer |
last_name |
String | Last name of the customer |
mobile_phone |
String | Mobile phone of the customer |
title |
String | Title of the customer |
custom_data |
JSON | Any custom data related to the customer |
Cart Items
"cart_items": [
{
"brand": "yourbrand",
"category": "cathegory1",
"label": "object123",
"custom_data": null,
"merchant_category_1": null,
"merchant_category_2": null,
"merchant_item_id": null,
"quantity": 1,
"type": null,
"unit_price": {
"amount": 10.00,
"currency": "EUR"
},
"url": null,
"vat": {
"amount": 10.00,
"currency": "EUR"
},
"delivery": {
"label": null,
"type": null,
"speed": "2",
"expected_date": "2023-10-26T14:24:31",
"expected_delay": 0,
"custom_data": null
}
}
]| Field | Type | Description |
|---|---|---|
brand |
String | Brand of the item |
category |
String | Category of the item |
label |
String | Label of the item |
merchant_category_1 |
String | Category 1 of the merchant |
merchant_category_2 |
String | Category 2 of the merchant |
merchant_item_id |
String | Item id of the merchant |
quantity |
String | Quantity of items |
type |
String | Type of the item |
unit_price |
Amount | Unit price of the item |
url |
String | Url of the item |
vat |
Amount | VAT amount of the item |
custom_data |
JSON | Any custom data related to the item |
delivery |
Object | Delivery |
Delivery
"delivery": {
"label": null,
"type": null,
"speed": "2",
"expected_date": "2023-10-26T14:24:31",
"expected_delay": 0,
"custom_data": null
}| Field | Type | Description |
|---|---|---|
type |
String | Type of delivery |
label |
String | Label of the delivery |
speed |
String | Speed of the delivery |
expected_date |
Date | Expected date of delivery |
expected_delay |
Integer | Expected delay of delivery |
custom_data |
JSON | Any custom data related to the delivery |
Merchant URL
"merchant_urls": {
"aborted_url": "aborted.com",
"error_url": "error.com",
"return_url": "return.com",
"notification_url": "notification.com"
},| Field | Type | Description |
|---|---|---|
aborted_url |
String | URL to which our platform should redirect users if they cancel their payment. We recommend using the payment method selection page to allow users to finalize their order using a different payment method. |
error_url |
String | URL to which our platform should redirect users if an error occurs in the payment flow. We recommend using the payment method selection page to allow users to finalize their order using a different payment method. |
return_url |
String | URL to which our platform should redirect users if the authorisation request is confirmed . If you have not yet received server-to-server notification (or if you don’t use it), you must check the status of the payment order via the PaymentOrder/Detail web service (WS) before confirming the order. This is for security reasons and because the order status may be Authorized or Authorizing, accordingly. |
notification_url |
String | The notification URL allows you to recover the payment order status in any circumstances, even if the browser disconnects after leaving the payment page. You can also obtain notification when the status is updated from Authorizing to Authorized, if a payment method cannot give immediate authorization |
Payment Methods
Contains details on the payment methods used. There can be several payment methods used and therefore shown in that node. For example, one section for credit card and a second one for a gift card.
"payment_methods": [
{
"amounts": {
"authorizing": {
"amount": 10.00,
"currency": "EUR"
},
},
"brand": "Paypal",
"custom_data": null,
"holder_id": "123",
"holder_email": "jean.dupont@mail.com",
"payment_instruction": {
"url": "redirecturl3ds.com",
"display_message": "Please proceed to do A, B and C to complete the payment"
},
"payment_method_order_id": "123",
"payment_method_reference": "jeandupont123",
"type": "wallet"
}
]| Field | Type | Description |
|---|---|---|
amounts |
String | Amounts related to that specific payment method |
brand |
String | Payment method name: Visa, illicado, Cdgp, Paypal, etc. |
custom_data |
JSON | Any custom data provided by the payment method |
holder_id |
String | Id of the payer |
holder_email |
String | Email of the payer |
payment_method_order_id |
String | Order id provided by the payment method |
payment_method_reference |
String | Reference number: 4587 5496 xxxx xxxx |
type |
String | Payment method type: CreditCard, GiftCard, Discount, Wallet |
payment_instruction |
Object | Payment Instruction |
Payment Instruction
In a HOST_TO_HOST payment order, the payment method can send instruction related to an additional payment step
"payment_instruction": {
"url": "redirecturl3ds.com",
"display_message": "Please proceed to do A, B and C to complete the payment"
}| Field | Type | Description |
|---|---|---|
url |
String | Eventual URL for OTP (one time password) |
display_message |
String | Eventual instructions to be displayed to the payer to show next steps related to the payment |
Payment Information
All payment information and credentials provided by the payer to make the payment, in a host-to-host mode.
"payment_information": {
"card_number": "6541778898761532",
"card_cvv": "123",
"card_expiration_year": "2050",
"card_expiration_month": "01",
"card_holder_name": "Jean Dupont",
"email": "jean.dupont@mail.com",
"phone_number": "0033612345678",
"token_id": null,
"bank_account_number": null,
"account_holder_name": null,
"otp": "123456",
"msisdn": "263775892364",
"qrcode": "324032942309",
"bank_id": "123"
}| Field | Type | Description |
|---|---|---|
card_number |
String | Card number of the payer |
card_cvv |
String | Card CVV of the payer |
card_expiration_year |
String | Card expiration year of the payer |
card_expiration_month |
String | Card expiration month of the payer |
card_holder_name |
String | Card holder name of the payer |
email |
String | Email of the payer |
phone_number |
String | Phone number of the payer |
token_id |
String | Token id of the payer |
bank_account_number |
String | Bank account number of the payer |
account_holder_name |
String | Account’s holder name |
otp |
String | OTP of the payer |
msisdn |
String | MSISDN of the payer |
qrcode |
String | Qrcode of the payer |
bank_id |
String | Bank id of the bank of the payer |
Payment Operation
{
"id": 1,
"payment_order_id": "1",
"status": "validated",
"requested": {
"amount": 10.00,
"currency": "USD"
},
"processed": {
"amount": 10.00,
"currency": "USD"
},
"external_id": "operation1234",
"creation_date": "2023-12-07T15:26:40",
"update_date": "2023-12-07T15:26:40",
"custom_data": null,
"payment_methods_responses": [
{
"operation_id": "123",
"payment_method_operation_id": "pmid123",
"response_code": "200",
"response_message": null
}
]
}| Field | Type | Description |
|---|---|---|
id |
String | Identifier of the operation |
payment_order_id |
String | Identifier of the payment order associated to the operation |
status |
String | Status of the operation |
requested |
Object | Amount of the operation for the merchant. Amount information |
processed |
Object | Amount of the operation for the buyer. Amount information |
external_id |
String | Payment Operation reference, from the merchant’s side |
creation_date |
Date | Date of the creation of the operation |
update_date |
Date | Date of the update of the operation |
custom_data |
JSON | Additional information for this operation in a JSON tree you choose |
payment_methods_responses |
String | Responses from the payment methods |
Fees
| Field | Type | Description |
|---|---|---|
id |
String | Id of the fee |
value |
Decimal | Value of the fee |
behavior |
String |
Entries
The Entry object is a line of an account statement. It represents one side of a transfer. For one transfer between two accounts, there are two entries, one on the sourceaccount and one on the targetaccount.
[
{
"account_id": "999922490000",
"amount": {
"amount": 0.19,
"currency": "EUR"
},
"counterpart_account_id": "999925700000",
"creation_date": "2024-01-02T09:32:32",
"credit_debit_indicator": "credit",
"label": "Whatever",
"status": "WAITINGFORVALIDATION",
"transfer_request_id": "425439380000",
"validation_date": null
},
{
"account_id": "999922490000",
"amount": {
"amount": 0.74,
"currency": "EUR"
},
"counterpart_account_id": "999925700000",
"creation_date": "2024-01-02T13:42:26",
"credit_debit_indicator": "credit",
"label": "Whatever",
"status": "WAITINGFORVALIDATION",
"transfer_request_id": "975477660000",
"validation_date": null
},
]| Field | Type | Description |
|---|---|---|
account_id |
String | Unique identifier for the account for this entry |
amount |
Amount | Amount of the entry |
counterpart_account_id |
String | The unique identifier of the account which is also concerned by the transfer represented by this entry. |
creation_date |
Date | Create date of the entry |
credit_debit_indicator |
String | Credit - if the balance increases with this entry . Debit - if the balance reduces with this entry |
label |
String | Information about the entry |
status |
String | Current status of the transfer. Pending : transfer waiting to be validated by Thunes. Done : transfer validated |
transfer_request_id |
String | TransferRequest related to this entry |
validation_date |
Date | Date at which the transfer was validated by Thunes |
Balance
The Balance object is an information about an account balance at a specified date.
{
"type": "AVAILABLE",
"date": "2024-01-11T14:56:51",
"last_change_date": "2024-01-10T13:13:23",
"amount": {
"amount": 10234.97,
"currency": "EUR"
}
}| Field | Type | Description |
|---|---|---|
type |
String | UpToDate - balance counting all the validated transfers. WaitingForValidation - balance containing all transfers awaiting validation. Available - balance available to transfer money from this account. This is all the validated money but it could exist a reserve to for asked debits (e.g. to finance a refund). Expected - balance expected once all the pending transfers will be validated. |
date |
Date | Date at which this balance is asked |
amount |
Amount | Amount of the balance |
last_change_date |
Date | Date at which this balance has changed for the last time |
Transfer request
The TransferRequests object is a request to transfer money between two accounts on our platform.
{
"amount": {
"amount": 10.00,
"currency": "USD"
},
"external_reference": "transfer123456",
"label": "transfer123456",
"source_account_id": "123456789123",
"target_account_id": "123111111111",
"type": "ScheduledTransferOut",
"custom_data": null
}| Field | Type | Description |
|---|---|---|
type |
String | UpToDate - balance counting all the validated transfers. WaitingForValidation - balance containing all transfers awaiting validation. Available - balance available to transfer money from this account. This is all the validated money but it could exist a reserve to for asked debits (e.g. to finance a refund). Expected - balance expected once all the pending transfers will be validated. |
date |
Date | Date at which this balance is asked |
amount |
Amount | Amount of the balance |
lastChangeDate |
Date | Date at which this balance has changed for the last time |
Payout Request
The PayoutRequest object is a withdrawal request to get funds managed by our platform.
{
"amount": {
"amount": 10.00,
"currency": "USD"
},
"source_account_id": "123456789123",
"external_reference": "externalref123",
"label": "payout 1",
"payout_bank_account_id": "123456789123",
"custom_data": null
}| Field | Type | Description |
|---|---|---|
id |
String | Unique identifier for the object. |
amount |
Amount | Amount that will be removed from your account in our platform |
creation_date |
Date | Create date of the payout request. |
external_reference |
String | Reference of the request in user system. |
label |
String | Information about the transfer to be displayed in the targeted bank account. |
payout_bank_account_id |
String | Unique identifier of the bank account information targeted for this payout request. |
source_account_id |
String | Unique identifier of the source account on the Thunes platform. |
status |
String | Current status of the payout. Sent: payout created and sent to Thunes. WaitingForValidation: payout waiting to be validated by Thunes and to be sent to the bank. Validated: payout sent to the bank. External: payout that no needs validation. Error: payout rejected and not sent to the bank |
target |
Amount | Amount to be transferred to your bank account. The currency can be different from the amount removed from your account in Thunes platform. |
transfer_request_id |
String | For all payout requests, a transfer is created between the source account and a technical account. This is the unique identifier of this transfer. |
validation_date |
Date | Date at which the payout request is validated |
custom_data |
JSON | Additional information for this payout request in a JSON tree you chose |
Company
A “company” corresponds to an organization (an integrator, a merchant, a marketplace, a payment institution, a PSP, a means of payment). Thunes Collections Back-office users are always attached to a company. Several payment methods or several merchants can be attached to the same company.
{
"id": 1,
"name": "My Company Name",
"creation_date": "2023-12-07T16:09:48",
"update_date": "2023-12-07T16:09:48"
}| Field | Type | Description |
|---|---|---|
id |
String | Unique identifier for the object. |
name |
String | Name of the company to be created |
creation_date |
Date | Date of the creation |
update_date |
Date | Date of the update |
Merchant
A “merchant” is the commercial entity which can make calls directly or via its PSP or its integrator to the Payment API to create transactions.
{
"id": 1,
"company_id": "1",
"currency": "USD",
"merchant_external_id": "my_merchant_id",
"name": "My Merchant Name",
"custom_data": null,
"creation_date": "2023-12-07T16:09:08",
"update_date": "2023-12-07T16:09:08"
}| Field | Type | Description |
|---|---|---|
id |
String | Unique identifier for the object. |
company_id |
String | Id of the company that will own the merchant |
currency |
String | Currency that will be used by the merchant |
merchant_external_id |
String | Your own id to be linked to the merchant |
name |
String | Name of the merchant to be created |
custom_data |
JSON | Any type of information to help validation from entities |
creation_date |
Date | Date of the creation |
update_date |
Date | Date of the update |
Account
An “account” allows you to collect remittance from payment methods and allow a company to do payouts.
{
"template_id": "1",
"label": "MyAccount",
"company_id": "my_company_id",
"recipient_email": "jean.dupont@mail.com",
"fees": [
"fee_id"
],
"payout_bank_accounts": [
{
"id": 1,
"address_line_1": "47 Av. de l'Opéra, 75002 Paris, France",
"address_line_2": null,
"bank_name": "Bank Name",
"bank_address": "1 Av. des Champs-Élysées75008 Paris",
"bank_country_iso_code": "FRA",
"bank_routing_code": "000123456",
"bank_branch_code": "00001",
"bic": "AAAAAAA4B",
"card_number": "0000111122223333",
"external_id": "external_id",
"external_account_id": "external_account_id",
"external_account_type": "B2B",
"iban": "ES0000000000050200050000",
"holder_name": "Jean Dupres",
"holder_email": "jean.dupres@mail.com",
"holder_phone": "0102030405",
"format": "IBAN",
"label": "Payout Bank Account Name",
"registration_number": "123",
"representative_id_number": "1234",
"representative_name": "Jean Dubois",
"status": "charged",
"target_currency": "USD",
"tax_id": "tax_id",
"is_blocked": true,
"is_default": true,
"creation_date": "2023-12-07T16:10:16",
"update_date": "2023-12-07T16:10:16"
}
],
"balances": [
{
"type": "B2B",
"date": "2023-12-07T16:11:57",
"last_change_date": "2023-12-07T16:11:57",
"amount": {
"amount": 10.00,
"currency": "USD"
}
}
]
}| Field | Type | Description |
|---|---|---|
company_id |
String | Id of the company that will own the account |
label |
String | Name of the account |
recipient_email |
String | Email used to sent some accouting documentation |
fees |
Table | Fees related to account creation |
payout_bank_accounts |
Table | Payount Bank Account object. |
creation_date |
Date | Date of the creation |
update_date |
Date | Date of the update |
balances |
Table | Balance object. |
Payout Bank Account
Object to describe the bank account that will be the destination of the payout.
"payout_bank_accounts": [
{
"id": 1,
"address_line_1": "47 Av. de l'Opéra, 75002 Paris, France",
"address_line_2": null,
"bank_name": "Bank Name",
"bank_address": "1 Av. des Champs-Élysées75008 Paris",
"bank_country_iso_code": "FRA",
"bank_routing_code": "000123456",
"bank_branch_code": "00001",
"bic": "AAAAAAA4B",
"card_number": "0000111122223333",
"external_id": "external_id",
"external_account_id": "external_account_id",
"external_account_type": "B2B",
"iban": "ES0000000000050200050000",
"holder_name": "Jean Dupres",
"holder_email": "jean.dupres@mail.com",
"holder_phone": "0102030405",
"format": "IBAN",
"label": "Payout Bank Account Name",
"registration_number": "123",
"representative_id_number": "1234",
"representative_name": "Jean Dubois",
"status": "charged",
"target_currency": "USD",
"tax_id": "tax_id",
"is_blocked": true,
"is_default": true,
"creation_date": "2023-12-07T16:10:16",
"update_date": "2023-12-07T16:10:16"
}
],| Field | Type | Description |
|---|---|---|
id |
String | Unique identifier for the object. |
address_line_1 |
String | Adress line 1 of the owner of the payout bank account |
address_line_2 |
String | Adress line 2 of the owner of the payout bank account |
bank_name |
String | Name of the bank of the payout bank account |
bank_address |
String | Adress of the payout bank |
bank_country_iso_code |
String (ISO 3166-1 alpha-3) | Country of the payout bank |
bank_routing_code |
String | Routing code of the payout bank |
bank_branch_code |
String | Branch code of the payout bank |
bic |
String | Bic of the payout bank |
card_number |
String | Card number of the merchant that will receive the payout |
external_id |
String | Thunes unique identifier of the payout bank account |
external_account_id |
String | Identifier of the account at the bank or in the target payout system |
external_account_type |
String | Type of account : SAVINGS, DEPOSIT, CHECKING, or OTHERS |
iban |
String | IBAN of the payout bank account |
holder_name |
String | Name of the holder of the payout bank account |
holder_email |
String | Email of the holder of the payout bank account |
holder_phone |
String | Phone number of the holder of the payout bank account |
format |
String | Allow to know if we are storing IBAN, CLABE account, US account, etc. |
label |
String | Name of the payout bank account |
registration_number |
String | Registration number |
representative_id_number |
String | Presented identification number |
representative_name |
String | Name of the representative of the business |
target_currency |
String | Currency of the payout bank account |
tax_id |
String | Tax identifier |
Merchant Payment Page Configuration
To be able to create transactions (via the Payment API) a merchant must be associated with a payment page, through a merchant payment page configuration.
{
"creation_date": "2023-12-07T16:08:47",
"merchant_id": "mymerchant",
"merchant_external_id": "my_merchant_id",
"payment_integrator_id": "paymentintegrator1",
"payment_page_id": "paymentpage1",
"specific_parameters" : {
"myspecparam" : "value1",
"otherparam" : "123456"
},
"status": "activated",
"update_date": "2023-12-07T16:08:47",
"custom_data" : {
"mydata" : "123",
"myotherdata" : "abdc"
}
}| Field | Type | Description |
|---|---|---|
creation_date |
Date | Date of the creation |
merchant_id |
Yes | String |
merchant_external_id |
Yes | String |
payment_page_id |
String | Id of the payment page |
payment_integrator_id |
String | Id of the payment integrator linked to the payment page |
specific_parameters |
JSON | Specific parameters object. |
status |
No | String |
update_date |
Date | Date of the update |
custom_data |
JSON | Any custom data |
Enumerations
Enumerations
A number of resource fields will only accept a list of known values, as outlined in this section.
Quotation mode
| Mode | Description |
|---|---|
REQUESTED_AMOUNT |
Quotation created with the amount of the merchant (requested) as an input, and as a result the amount of the buyer (processed) is calculated for the quotation |
PROCESSED_AMOUNT |
Quotation created with the amount of the buyer (processed) as an input, and as a result the amount of the merchant (requested) is calculated for the quotation |
Transaction type
| Type | Description |
|---|---|
B2B |
Transaction created for B2B |
C2B |
Transaction created for C2B |
Integration mode
| Mode | Description |
|---|---|
HOST_TO_HOST |
Transaction created in host to host mode |
REDIRECT |
Transaction created in redirection mode |
Payment Order Status
| Status | Description |
|---|---|
CREATED |
The retailer has created the payment order. The retailer must redirect the user to the payment page URL provided in our response (PaymentPageUrl) if the integration_mode is ‘REDIRECT’. In integration_mode ‘HOST_TO_HOST’, the payment informations are directly received in the POST Payment Order API request and processed by thunes. |
ADDING_PAYMENT_METHODS |
The platform is currently processing the payment. |
AUTHORIZING |
The customer has confirmed the payment but one of the payment methods involved requires more time to confirm authorisation. You must wait for the status to change. |
REFUSED |
One of the payment methods involved in the transaction has refused the payment. |
ABORTED |
The customer has clicked on Cancel or closed the browser : the payer did not finlalize the payment on his side. |
AUTHORIZED |
The customer has confirmed the payment and all payment methods have authorized the payment. The payment order status will not change until the entire order has been charged/cancelled. |
CHARGING |
The charge request is being processed. If the charge is partial (amount less than the authorized amount) then the transaction status will go back to authorized when done |
CHARGED |
The entire order amount has been charged, or part of the order amount charged and the remaining cancelled. |
CANCELLING |
The cancel request is being processed |
CANCELLED |
The retailer has cancelled the entire order. |
REFUNDING |
The refund request is being processed. If the refund is partial (amount less than the charged amount) then the transaction status will go back to charged when done |
REFUNDED |
The entire amount charged has then been refunded. |
ERROR |
A processing error has occurred. |
Payment Operation Status
| Status | Description |
|---|---|
INITIAL |
The retailer has created the payment operation. |
RUNNING |
The platform is currently processing the payment operaion |
DONE |
The payment operation has been processed |
EXTERNAL |
The payment operation is ongoing, waiting for an anser from our partner |
ERROR |
A processing error has occured |
CANCELLED |
The payment operation has not been completed |
Payment Methods Amounts
Provides information about the different amounts related to each payment method used for the order
| Amount | Description |
|---|---|
AUTHORIZING_AMOUNT |
Indicates the amount currently being in course of authorization |
AUTHORIZED_AMOUNT |
Indicates the amount that has been authorized |
DEBITED_AMOUNT |
Indicates the amount that has been charged (debited) |
RECREDITED_AMOUNT |
Indicates the amount that has been refunded (recredited) |
Category
Provides information about the category of the cart_items, in the merchant_order
| Category |
|---|
APPLIANCES |
AUCTION_AND_GROUP_BUYING |
CARS_AND_MOTORBIKES |
ELECTRONICS |
ENTERTAINMENT |
FASHION |
FOOD_AND_DRINK |
FURNITURE |
GIFT_AND_FLOWERS |
HEALTH_AND_BEAUTY |
HOME_AND_GARDEN |
JEWELLERY |
KIDS_AND_BABY |
LEISURE_AND_HOBBIES |
PETS |
PHONES |
SERVICES_FOR_INDIVIDUALS |
SERVICES_FOR_PROFESSIONALS |
SPORT |
TOYS_AND_GAMES |
TRAVEL |
VIDEO_GAMES_AND_CONSOLES |
COMPUTERS_AND_SOFTWARE |
Type
Provides information about the type of delivery in the merchant_order
| Type |
|---|
STORE_PICKUP |
NETWORK_PICKUP |
TRAVEL_PICKUP |
CARRIER |
E_DELIVERY |
OTHER |
Speed
Provides information about the speed of delivery in the merchant_order
| Speed |
|---|
EXPRESS |
STANDARD |
CLICK_AND_COLLECT |
SAME_DAY |
Transfer request type
| Mode | Description |
|---|---|
ACQUIRER_REMITTANCE |
Remittance sent by the Acquirer to Thunes platform |
ACQUIRER_REMITTANCE_FEES |
Fees applied by the acquirer on the remittance |
ACQUIRER_REMITTANCE_FEES_CANCELLATION |
Fees cancellation or refund related to a remittance that indicates refunds |
ACQUIRER_CHARGEBACK |
Chargeback information provided by the acquirer |
CHARGE_OPERATION_PAYMENT_METHOD_SETTLEMENT |
Charge settlement to the merchant account in the Platform |
REFUND_OPERATION_PAYMENT_METHOD_SETTLEMENT |
Refund settlement from the merchant account in the Platform |
CHARGE_OPERATION_FEES |
Fees associated with a charge operation |
CHARGE_OPERATION_FEES_CANCELLATION |
Fees associated with a refund operation |
TRANSFER_OUT |
Payout - Transfer out of Thunes platform |
SCHEDULED_TRANSFER_OUT |
Periodic transfer out of Thunes platform, at a scheduled period (daily, weekly, monthly) |
TRANSFER_OUT_CANCELLATION |
Cancellation of a transfer out |
TRANSFER_OUT_REJECTION |
TransferOut that went wrong, return of funds |
TRANSFER_OUT_FEES |
Fees associated with a transfer out |
TRANSFER_OUT_FEESC_ANCELLATION |
Cancellation of fees associated with a cancelled, rejected transfer out |
TRANSFER |
Basic financial movement between an account to another in the Thunes Platform |
TRANSFER_IN |
Funding a merchant account on the Thunes platform via an incoming transfer |
ACCOUNT_MANAGEMENT_FEE |
Fees on merchant account management |
ACCOUNT_MANAGEMENT_FEE_CANCELLATION |
Cancel an account management fees |
TRANSACTION_FEES |
Other types of fees that may apply to orders within the Thunes platform (not on charge/refund or via acquirer remittance) |
TRANSACTION_FEES_CANCELLATION |
Cancellation of Transaction fees |