| `ClientId`:`ApiKey` |
| RXhhbXBsZUNsaWVudElkOlBFQkIwVkRoRkVOZkVoWFRVeW9yVFlqNmhDVm1xTDBIUmJ3WTRnNU4xN3J1aVBqbVFu |
| Endpoint | POST `/v2.01/oauth/token` |
|---|---|
| Authorization | Basic RXhhbXBsZUNsaWVudElkOlBFQkIwVkRoRkVOZkVoWFRVeW9yVFlqNmhDVm1xTDBIUmJ3WTRnNU4xN3J1aVBqbVFu |
| Content-Type | application/x-www-form-urlencoded |
| Request body | grant\_type=client\_credentials |
| Property | Description |
|---|---|
| `access_token` | The access token to use to authenticate. |
| `token_type` | The type of token: Bearer. |
| `expires_in` | The number of seconds until the `access_token` expires and a new token needs to be generated. **Default values:** 3600 (in Production), 1200 (in Sandbox) **Note:** The value may differ from the default values, therefore you should not rely on hard-coded defaults but on the `expires_in` value returned. |
| **Authorization** | Bearer 094696b3724d4aa5a182eac360dcd537 |
|---|
| **Dates** | Dates and times are defined as **Unix timestamps**, which are integers representing the number of seconds since the Unix Epoch **in UTC** (January 1, 1970, 00:00:00 UTC). For birth dates, ensure you convert the individual's timezone to UTC to avoid midnight being interpreted as the day before and causing issues with verification checks. |
|---|---|
| **Object IDs** | The unique identifier returned for an object (its `Id`) is a case-sensitive **string** and must be handled as such. You must store and use the ID with the same letter casing that was originally returned. The maximum length that can be returned is **128 characters**. Several variants exist for the value of this string. The most recently adopted variant is a ULID (universally unique lexicographically sortable identifier) with one or more prefixes separated by an underscore: * `cvr_01HN0FR5371TCNEF305P97D8Q9` * `user_m_01J82SPSKW53XZM936PDVN76W0` * `po_b_02HMVJH4ZJWX9E5K66KTN9H118` * `xfer_refund_c_01JX28BTTWQMR1TXH4TC87D7NA` Other variants are also in use depending on the API feature and when the object was created: * `wt_287afe02-498a-4076-b022-42e8997a172f` – UUID (universally unique identifier, also called a globally unique identifier or GUID) with one or more prefixes * `2774fac1-d33f-4c5a-8e21-88b772ec2943` – UUID without prefix * `card_m_vHrtUIVelDzkPmdL`– prefixed alphanumeric string * `4659626451` – string containing only digits |
| **Amounts** | All monetary amounts must be passed as **integers** and not strings. Amounts are expressed in the currency's **minor unit** (the smallest sub-division). So for example: * EUR 12.60 is represented as `1260` * JPY 12 is represented as `12` |
| **Currencies** | Currency codes follow the three-letter ISO 4217 format. The full list of possible supported values across all API features is: `AED`, `AUD`, `CAD`, `CHF`, `CZK`, `DKK`, `EUR`, `GBP`, `HKD`, `JPY`, `NOK`, `PLN`, `SEK`, `USD`, `ZAR`. The available currencies vary across payment methods, cards, wallets, and payouts, and according to your contract. For more information, see the Currencies article. |
| **Countries** | Country codes follow the ISO 3166-1 alpha-2 format (two letters, e.g. US, GB, FR). The three-letter format is used exceptionally. Ensure you follow guidance in the endpoint. Accepted values are the following: AD, AE, AF, AG, AI, AL, AM, AO, AQ, AR, AS, AT, AU, AW, AX, AZ, BA, BB, BD, BE, BF, BG, BH, BI, BJ, BL, BM, BN, BO, BQ, BR, BS, BT, BV, BW, BY, BZ, CA, CC, CD, CF, CG, CH, CI, CK, CL, CM, CN, CO, CR, CU, CV, CW, CX, CY, CZ, DE, DJ, DK, DM, DO, DZ, EC, EE, EG, EH, ER, ES, ET, FI, FJ, FK, FM, FO, FR, GA, GB, GD, GE, GF, GG, GH, GI, GL, GM, GN, GP, GQ, GR, GS, GT, GU, GW, GY, HK, HM, HN, HR, HT, HU, ID, IE, IL, IM, IN, IO, IQ, IR, IS, IT, JE, JM, JO, JP, KE, KG, KH, KI, KM, KN, KP, KR, KW, KY, KZ, LA, LB, LC, LI, LK, LR, LS, LT, LU, LV, LY, MA, MC, MD, ME, MF, MG, MH, MK, ML, MM, MN, MO, MP, MQ, MR, MS, MT, MU, MV, MW, MX, MY, MZ, NA, NC, NE, NF, NG, NI, NL, NO, NP, NR, NU, NZ, OM, PA, PE, PF, PG, PH, PK, PL, PM, PN, PR, PS, PT, PW, PY, QA, RE, RO, RS, RU, RW, SA, SB, SC, SD, SE, SG, SH, SI, SJ, SK, SL, SM, SN, SO, SR, SS, ST, SV, SX, SY, SZ, TC, TD, TF, TG, TH, TJ, TK, TL, TM, TN, TO, TR, TT, TV, TW, TZ, UA, UG, UM, US, UY, UZ, VA, VC, VE, VG, VI, VN, VU, WF, WS, YE, YT, ZA, ZM, ZW. |
| **Languages** | Language codes generally follow the ISO 639-1 alpha-2 format (two letters, e.g. EN, FR) but ensure you follow guidance in the relevant endpoint. |
| Production | Sandbox |
|---|---|
| https://api.mangopay.com | https://api.sandbox.mangopay.com |
| **Content-Type** | application/json |
|---|---|
| **Encoding** | UTF-8 JSON |
| Key | Value |
|---|---|
| x-tenant-id | uk |
| Parameter | Values |
|---|---|
| `page` | Indicates the index of the page. Start value: 1 Default value: 1 |
| `per_page` | Indicates the number of items returned in each page. Maximum value: 100 Default value: 10 |
| Link to | Example |
|---|---|
| First page | \ |
| Previous page | \ |
| Next page | \ |
| Last page | \ |
| Time period | Maximum number of API calls allowed |
|---|---|
| 15 minutes | 2,300 |
| 30 minutes | 4,500 |
| 1 hour | 8,800 |
| 24 hours | 105,600 |
| Pay-in with Mangopay | Simplify your payment integration and use Mangopay’s payment methods with the Connector to automate captures and refunds. * Pay by card (preauth), direct debit, virtual IBAN, bank wire * Supports all Mirakl Payment Workflows * Automate capture, refund, and transfers * Payment Matching and reconciliation of bank wires made to virtual IBAN |
|---|---|
| Pay-in with third party PSPs | Acquire the funds with your existing PSP for pay-ins, in part or entirely. * Direct settlement or Marketplace Payment Extension * 1P/3P: Mixed basket management by the marketplace |
| Seller onboarding | Manage the onboarding of your sellers in your Mirakl Dashboard or your custom seller dashboard. * User creation and updates * Wallet creation * Bank Account creation * KYB Document & KYB management * Display of KYB status (including errors) to sellers |
| Payout | Manage the split payout for the marketplace and sellers after each billing cycle. * Daily invoice synchronization (including manual invoices) * Transfer management * Split payout management * Commission management (optional) * Isolation of VAT in dedicated wallets (optional) |
| **Property** | **Type** | **Description and value** |
|---|---|---|
| `Message` | string | The description of the error. |
| `Type` | string | The type of the error (e.g., `param_error`, `ressource_not_found`, etc.) |
| `Id` | string | The unique identifier of the error. This information may be requested by our Support team when investigating an issue. |
| `Date` | Unix timestamp | The date and time at which the error occurred. |
| `Errors` | object | The list of issues that triggered the HTTP error. |
| **Response code** | **Status** | **Description** |
|---|---|---|
| 200 | OK | Request successful. |
| 204 | No content | Request successful with no information returned. |
| 400 | Bad request | Request impossible to process due to a logical error (e.g., missing parameter, invalid operation, constraint violation, etc.) |
| 401 | Unauthorized | Access to the API resource is not authorized due to an authentication failure (e.g., incorrect client ID, API Key, or URL). |
| 403 | Forbidden | Access to the API resource is forbidden, due to an authorization failure (e.g., deactivation of the account or a permission issue regarding a specific feature). |
| 404 | Not Found | The requested resource cannot be found. |
| 405 | Method Not Allowed | HTTP method is not allowed (e.g., trying a GET instead of a POST). |
| 409 | Conflict | The request is not processed due to an identical [idempotency key](/api-reference/overview/idempotency). |
| 411 | Length Required | The Content-Length header field is not defined and the server requires it. |
| 413 | Payload Too Large | The request entity is larger than the server is able to process (e.g., KYC document file larger than 10MB). |
| 415 | Unsupported Media Type | The format of the media sent is not supported by the server (e.g., wrong file format for KYC document file). |
| 422 | Unprocessable Entity | The request cannot be fulfilled due to semantic errors. |
| 429 | Too Many Requests | Too many requests have been sent in a given period of time ([rate limiting](/api-reference/overview/rate-limiting)). |
| 500 | Internal Server Error | We invite you to try again later or to contact Support [via the Dashboard](https://hub.mangopay.com/) if the problem persists. |
| Currency | Card pay-ins | Banking pay-ins | APM pay-ins | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Mastercard, Visa | AMEX | CB, Maestro | Bank wire - Intl. |
Bank wire - Local |
Virtual IBAN - Intl. |
Virtual IBAN - Local |
Pay by Bank | Direct debit | Apple Pay | Bancontact | BLIK | Giropay | Google Pay | iDEAL | Klarna | MB WAY | Multibanco | Payconiq | PayPal | Satispay | Swish | TWINT | |
| **AED** UAE dirham |
{IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGreenCheck} | {IconGrayCross} | *On request* | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} |
| **AUD** Australian dollar |
{IconGreenCheck} | {IconGreenCheck} | {IconGrayCross} | {IconGreenCheck} | {IconGrayCross} | *On request* | *Planned* | {IconGrayCross} | {IconGrayCross} | {IconGreenCheck} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGreenCheck} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} |
| **CAD** Canadian dollar |
{IconGreenCheck} | {IconGreenCheck} | {IconGrayCross} | {IconGreenCheck} | *Planned* | *On request* | {IconGreenCheck} | {IconGrayCross} | {IconGrayCross} | {IconGreenCheck} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGreenCheck} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} |
| **CHF** Swiss franc |
{IconGreenCheck} | {IconGreenCheck} | {IconGrayCross} | {IconGreenCheck} | {IconGrayCross} | *On request* | *Planned* | {IconGrayCross} | {IconGrayCross} | {IconGreenCheck} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGreenCheck} | {IconGrayCross} | {IconGreenCheck} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGreenCheck} | {IconGrayCross} | {IconGrayCross} | {IconGreenCheck} |
| **CNH** Chinese yuan renminbi |
{IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGreenCheck} | {IconGrayCross} | *On request* | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} |
| **CZK** Czech koruna |
{IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGreenCheck} | {IconGrayCross} | *On request* | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} |
| **DKK** Danish kroner |
{IconGreenCheck} | {IconGreenCheck} | {IconGrayCross} | {IconGreenCheck} | *Planned* | {IconGreenCheck} | {IconGreenCheck} | {IconGreenCheck} | {IconGrayCross} | {IconGreenCheck} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGreenCheck} | {IconGrayCross} | {IconGreenCheck} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} |
| **EUR** Euro |
{IconGreenCheck} | {IconGreenCheck} | {IconGreenCheck} | {IconGreenCheck} | {IconGreenCheck} | {IconGreenCheck} | {IconGreenCheck} | {IconGreenCheck} | {IconGreenCheck} | {IconGreenCheck} | {IconGreenCheck} | {IconGrayCross} | {IconGreenCheck} | {IconGreenCheck} | {IconGreenCheck} | {IconGreenCheck} | {IconGreenCheck} | {IconGreenCheck} | {IconGreenCheck} | {IconGreenCheck} | {IconGreenCheck} | {IconGrayCross} | {IconGrayCross} |
| **GBP** Pound sterling |
{IconGreenCheck} | {IconGreenCheck} | {IconGrayCross} | {IconGreenCheck} | {IconGreenCheck} | {IconGreenCheck} | {IconGreenCheck} | {IconGreenCheck} | {IconGreenCheck} | {IconGreenCheck} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGreenCheck} | {IconGrayCross} | {IconGreenCheck} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGreenCheck} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} |
| **HKD** Hong kong dollar |
{IconGreenCheck} | {IconGreenCheck} | {IconGrayCross} | {IconGreenCheck} | {IconGrayCross} | *On request* | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGreenCheck} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGreenCheck} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} |
| **HUF** Hungarian forint |
{IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGreenCheck} | {IconGrayCross} | *On request* | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | |
| **ILS** Israeli new shekel |
{IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGreenCheck} | {IconGrayCross} | *On request* | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} |
| **JPY** Japanese yen |
{IconGreenCheck} | {IconGreenCheck} | {IconGrayCross} | {IconGreenCheck} | {IconGrayCross} | *On request* | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGreenCheck} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGreenCheck} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} |
| **MXN** Mexican peso |
{IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGreenCheck} | {IconGrayCross} | *On request* | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} |
| **NOK** Norwegian kroner |
{IconGreenCheck} | {IconGreenCheck} | {IconGrayCross} | {IconGreenCheck} | {IconGrayCross} | *On request* | *Planned* | {IconGreenCheck} | {IconGrayCross} | {IconGreenCheck} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGreenCheck} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} |
| **NZD** New Zealand dollar |
{IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGreenCheck} | {IconGrayCross} | *On request* | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} |
| **PLN** Polish zloty |
{IconGreenCheck} | {IconGreenCheck} | {IconGrayCross} | {IconGreenCheck} | *Planned* | *On request* | *Planned* | {IconGreenCheck} | {IconGrayCross} | {IconGreenCheck} | {IconGrayCross} | {IconGreenCheck} | {IconGrayCross} | {IconGreenCheck} | {IconGrayCross} | {IconGreenCheck} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} |
| **RON** Romanian leu |
{IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGreenCheck} | {IconGrayCross} | *On request* | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} |
| **SAR** Saudi riyal |
{IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGreenCheck} | {IconGrayCross} | *On request* | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} |
| **SEK** Swedish kroner |
{IconGreenCheck} | {IconGreenCheck} | {IconGrayCross} | {IconGreenCheck} | *Planned* | *On request* | *Planned* | {IconGrayCross} | {IconGrayCross} | {IconGreenCheck} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGreenCheck} | {IconGrayCross} | {IconGreenCheck} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGreenCheck} | {IconGrayCross} |
| **SGD** Singapore dollar |
{IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGreenCheck} | {IconGrayCross} | *On request* | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} |
| **TRY** Turkish lira |
{IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGreenCheck} | {IconGrayCross} | *On request* | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} |
| **USD** US dollar |
{IconGreenCheck} | {IconGreenCheck} | {IconGrayCross} | {IconGreenCheck} | *Planned* | *On request* | {IconGreenCheck} | {IconGreenCheck} | {IconGrayCross} | {IconGreenCheck} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGreenCheck} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGreenCheck} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} |
| **ZAR** South African rand |
{IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGreenCheck} | {IconGrayCross} | *On request* | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} | {IconGrayCross} |
| Currency | Wallets | FX | Payouts | |
|---|---|---|---|---|
| International | Local | |||
| **AED** UAE dirham |
{IconGreenCheck} | {IconGreenCheck} | {IconGreenCheck} | *Planned* |
| **AUD** Australian dollar |
{IconGreenCheck} | {IconGreenCheck} | {IconGreenCheck} | *Planned* |
| **CAD** Canadian dollar |
{IconGreenCheck} | {IconGreenCheck} | {IconGreenCheck} | {IconGreenCheck} |
| **CHF** Swiss franc |
{IconGreenCheck} | {IconGreenCheck} | {IconGreenCheck} | {IconGreenCheck} |
| **CNH** Chinese yuan renminbi |
{IconGreenCheck} | {IconGreenCheck} | {IconGreenCheck} | {IconGrayCross} |
| **CZK** Czech koruna |
{IconGreenCheck} | {IconGreenCheck} | {IconGreenCheck} | {IconGreenCheck} |
| **DKK** Danish kroner |
{IconGreenCheck} | {IconGreenCheck} | {IconGreenCheck} | {IconGreenCheck} |
| **EUR** Euro |
{IconGreenCheck} | {IconGreenCheck} | {IconGreenCheck} | {IconGreenCheck} |
| **GBP** Pound sterling |
{IconGreenCheck} | {IconGreenCheck} | {IconGreenCheck} | {IconGreenCheck} |
| **HKD** Hong Kong dollar |
{IconGreenCheck} | {IconGreenCheck} | {IconGreenCheck} | *Planned* |
| **HUF** Hungarian forint |
{IconGreenCheck} | {IconGreenCheck} | {IconGreenCheck} | {IconGreenCheck} |
| **ILS** Israeli new shekel |
{IconGreenCheck} | {IconGreenCheck} | {IconGreenCheck} | {IconGrayCross} |
| **JPY** Japanese yen |
{IconGreenCheck} | {IconGreenCheck} | {IconGreenCheck} | {IconGrayCross} |
| **MXN** Mexican peso |
{IconGreenCheck} | {IconGreenCheck} | {IconGreenCheck} | {IconGrayCross} |
| **NOK** Norwegian kroner |
{IconGreenCheck} | {IconGreenCheck} | {IconGreenCheck} | {IconGreenCheck} |
| **NZD** New Zealand dollar |
{IconGreenCheck} | {IconGreenCheck} | {IconGreenCheck} | {IconGrayCross} |
| **PLN** Polish zloty |
{IconGreenCheck} | {IconGreenCheck} | {IconGreenCheck} | {IconGreenCheck} |
| **RON** Romanian leu |
{IconGreenCheck} | {IconGreenCheck} | {IconGreenCheck} | {IconGreenCheck} |
| **SAR** Saudi riyal |
{IconGreenCheck} | {IconGreenCheck} | {IconGreenCheck} | *Planned* |
| **SEK** Swedish kroner |
{IconGreenCheck} | {IconGreenCheck} | {IconGreenCheck} | {IconGreenCheck} |
| **SGD** Singapore dollar |
{IconGreenCheck} | {IconGreenCheck} | {IconGreenCheck} | *Planned* |
| **TRY** Turkish lira |
{IconGreenCheck} | {IconGreenCheck} | {IconGreenCheck} | {IconGrayCross} |
| **USD** US dollar |
{IconGreenCheck} | {IconGreenCheck} | {IconGreenCheck} | {IconGreenCheck} |
| **ZAR** South African rand |
{IconGreenCheck} | {IconGreenCheck} | {IconGreenCheck} | {IconGrayCross} |
| Contestable | Dispute for which the chargeback can be contested by providing proof (i.e., Dispute Documents) justifying the original transaction. |
|---|---|
| Not‑contestable | Dispute that is automatically closed after its creation, without any action possible for the platform. |
| Retrieval | Dispute that is actually a chargeback warning issued by the bank. The platform is required to provide documents, but no funds will be taken from the Repudiation Wallet. |
| DisputeReasonType | Action |
|---|---|
| AUTHORISATION\_DISPUTED | **Evidence to provide** A document with: * The amount debited * The date * The nature of the payment (here the name of the platform must be visible) * The proof that the product was received or service provided |
| AUTHORISATION\_DISPUTED | **What to do** Contact the Mangopay Fraud team through the Dashboard for more information. |
| DUPLICATE | **What to do** Prove that the two transactions are both legitimate, and that you didn’t charge the customer twice for the same goods or service. **Evidence to provide** Two separate invoices must therefore be provided. |
| FRAUD | **What to do** Prove that the transaction was initiated by the cardholder. **Evidence to provide** * Invoice or any document with the name of the user, the amount paid, and the details of the purchase. * Optionally, screenshots of the exchanges between the user and the platform or between the paying user and the recipient user. If there are two or more transactions for the same user that were not contested nor reported as fraudulent in the past 120 to 365 days before the contested payment, you also need to provide at least two of the following elements about the user who initiated the chargeback: * The IP address * The shipping address * The device ID (for the phone, computer, etc. used for the payment). One of the two pieces of information provided must be the IP address or the device ID. |
| OTHER | **What to do** Contact the Mangopay Fraud team through the Dashboard for more information. |
| PRODUCT\_NOT\_PROVIDED | **What to do** Prove that the product was delivered. **Evidence to provide** * Invoice * Signed proof of delivery |
| PRODUCT\_UNACCEPTABLE | **What to do** Prove that the product is not a counterfeit. **Evidence to provide** * The certificate of authenticity * The Terms and Conditions that highlight the return policy. * A screenshot of a good review, if the customer writes one after receiving the good or service. Also, if the cardholder has been reimbursed or compensated, then proof must be provided. |
| REFUND\_CONVERSION\_RATE | **What to do** Prove that the charged amount was the right one, regardless of the currency exchange rate applied. **Evidence to provide** The Terms and Conditions that highlight the refund policy mentioning that foreign currency exchange rates are subject to fluctuations. |
| REFUND\_NOT\_PROCESSED | **What to do** Prove that the cardholder has been reimbursed or compensated, or that the refund doesn’t apply. **Evidence to provide** * Proof of the refund transaction. * Clear cancellation or return policy, with proof that it has been communicated to the customer prior to the purchase. |
| TRANSACTION\_NOT\_RECOGNIZED | **What to do** Prove that the transaction was initiated by the cardholder. **Evidence to provide** * Invoice, or any document with the name of the user, the amount paid and the details of the purchase. * Optionally, screenshots of the exchanges between the buyer and the platform or the buyer and the seller. |
| UNKNOWN | **Evidence to provide** A document with: * The amount debited * The date * The nature of the payment (here the name of the platform must be visible) * The proof that the product was received or service provided |
| Pay-in |
Funds arrive in the Mangopay environment in what we call a pay-in. The funds might be acquired by us or another third-party |
|---|---|
| Wallet | The pay-in arrives on a user’s wallet. Funds can then be moved around according to your business model, flexibly from wallet to wallet (we call these transfers). You can take fees, split funds between users, convert currencies, and integrate other service partners. Platforms can create an unlimited number of wallets to hold funds as long as needed. Mangopay's virtual IBANs and currency conversion services supercharge wallet capabilities. |
| Payout |
To get the money from their Mangopay wallet to their bank account, the user needs to make a payout. Strict |
| Fees Wallet | Repudiation Wallet |
|---|---|
| The platform’s Fees Wallet is where any fees taken are sent. You can collect fees on any pay-in, transfer, or payout. Your fees are automatically wired to your bank account every month. Learn more → |
When an end user contests a pay-in with their bank (known as a |
The rest of this guide refers to the numbers in the diagram above, along the main stages.
## Declare payment authorization
Mangopay Echo allows your platform to compliantly declare transactions acquired by third-party PSPs as **Intents**. The Intent API object represents a payment authorization processed by a third-party PSP, and can subsequently be used to track the full lifecycle of the transaction.
### Intent
The Intent represents the successful *authorization* of the transaction (**1A**), while its *capture* represents the acquisition of the funds by the PSP.
To create an Intent (**1B**), call the endpoint:
> [**POST Create an Intent**](/api-reference/intents/create-intent)
Include the following information:
* Payment details – Amount, currency, payment method
* External provider – Provider name, unique identifier of the transaction, date
* Buyer (optional) – If the user is also registered with Mangopay, the Mangopay UserId that made the payment
* Line items – A list of items purchased by the buyer. Each line item identifies the seller (Mangopay user and wallet) and the item purchased (amount, SKU, etc.). Future actions declared for the intent It also tracks the amount of the line item that is subsequently captured, refunded, disputed, and so on.
The seller details of a line item are different depending on whether the transaction is 1P or 3P.
### First-party transactions (1P)
First-party (1P) flows refer to transactions where your platform sells directly to the user on your website: an e-commerce transaction. In a 1P scenario, your platform operator is the beneficiary of the transaction.
For a 1P Line Item, your platform is the line item's `Seller`: your `ClientId` is the `AuthorId`, and your Fees Wallet is the `WalletId`.
### Third-party transactions (3P)
Third-party flows refer to transactions where your platform acts as an intermediary between the buyer and a seller. In a 3P scenario, the Seller is the beneficiary.
For a 3P line item, The seller on your platform is the line item's `Seller`: their `UserId` is the `AuthorId` and their wallet is the `WalletId`.
## Declare capture or cancel
When the third-party PSP captures the funds (**2A**), you need to declare this to Mangopay (**2B**).
### Intent Capture
To declare the capture, call the endpoint using the Intent’s `Id`:
> [POST Create a Capture of an Intent](/api-reference/intents/create-intent-capture)
In all cases, the capture of an Intent is a separate Mangopay API call from the Intent creation.
There are three possible scenarios:
* Authorization simultaneous with capture – No new data required because the external data is the same as the authorization, so the call has an empty body.
* Authorization and delayed full capture (e.g. preauthorization) – New data is required for the external PSP reference and amount, because a delayed capture is necessarily a different object.
* Authorization and partial captures – New external data is required along with the amount for each line item that is being captured.
### Intent Cancel
If an payment authorization (or part of it) is not used, then the Intent can be fully or partially cancelled. To do so, call the endpoint:
> [POST Create a Cancel of an Intent](/api-reference/intents/create-intent-cancel)
Cancellations can be partial. In a cancellation scenario, new external data is necessarily required as the action must require a new object with the third-party PSP.
## Declare future split transfer to seller
In Echo, the future transfer of funds to seller's Mangopay wallet is called a **Split**, and you need to create this request in the Mangopay API.
To create a Split (**3**), call the endpoint:
> [POST Create a Split of an Intent](/api-reference/intents/create-intent-split)
| Code | Description | Type (Mirakl Dashboard) |
|---|---|---|
| `mgp-external-provider-name` | The name of the external provider processing the transaction. | ***Single values list*** containing the relevant value(s) exactly as they appear in the [supported external providers](/guides/echo/supported-providers). |
| `mgp-external-processing-date` | The date at which the transaction was created. | ***Date (ISO 8601 format)*** |
| `mgp-external-provider-reference` | The unique identifier of the transaction at the provider level. | ***Text (Max: 2000 char.)*** |
| `mgp-external-merchant-reference` | The unique identifier of the transaction at the merchant level. | ***Text (Max: 2000 char.)*** |
| `mgp-external-provider-payment-method` | One of the [supported payment methods](/guides/echo/supported-payment-methods) used to process the transaction. | ***Single values list*** containing the relevant values exactly as they appear in the [supported payment methods](/guides/echo/supported-payment-methods). |
| Field | Required | Expected values |
|---|---|---|
| `mgp-external-provider-name` | Yes | One of the [supported external providers](/guides/echo/supported-providers). |
| `mgp-external-processing-date` | Yes | ISO 8601 date time in UTC (YYYY-MM-DDTHH:MM:SSZ) |
| `mgp-external-provider-reference` | Yes | String |
| `mgp-external-merchant-reference` | No | String |
| `mgp-external-provider-payment-method` | No | One of the [supported payment methods](/guides/echo/supported-payment-methods). If the payment method is not supported, this field can be left blank (provided you created it as not required). |
| Column name | Description | Format | Example |
|---|---|---|---|
| `ExternalProviderReference` | The unique identifier of the transaction at the provider level. | string | `auth-stripe-633781e6-bb10-4484-8a29-ff6da7d7464a` |
| `ExternalTransactionType` | The type of transaction using Mangopay's accepted values: * `PAYMENT` * `REFUND` * `DISPUTE` | string | `PAYMENT` |
| `ExternalTransactionStatus` | The status of the transaction. The accepted values listed can only apply to the `ExternalTransactionType` mentioned: * `SETTLED` – `PAYMENT` successfully processed: funds are expected to be received. * `REFUNDED` – `REFUND` fully processed: funds were returned to the buyer. * `REFUND_REVERSED` – `REFUND` processed but reversed: funds were returned to the platform. * `DISPUTED` – Funds deducted due to a `DISPUTE`: not available for settlement. * `DEFENDED` – Funds temporarily returned to the platform as part of the `DISPUTE` defense process. * `DISPUTED_WON` – `DISPUTE` resolved in favor of the platform. * `DISPUTED_LOST` – `DISPUTE` resolved against the platform: funds permanently withdrawn to buyer. | string | `SETTLED` |
| `ExternalProcessingDate` | The date on which the transaction was created. | date (DD-MM-YYYY) | `19-06-2025` |
| `Amount` | The amount of the transaction in the currency's minor unit. | string | `50000` (500) |
| `Currency` | The currency of the transaction. | string | `EUR` |
| Footer row name | Description | Format | Example |
|---|---|---|---|
| `SettlementDate` | The creation date of the settlement from the provider. | date (DD-MM-YYYY) | `19-06-2025` |
| `ExternalProviderName` | The name of the third-party PSP. | string | `Stripe` |
| `TotalSettlementFeesAmount` | The total amount of fees taken by the provider from the settlement in the currency's minor unit. This amount match the sum of all `ExternalProviderFees` values in the file, if they are provided. | string | `500` |
| `TotalSettlementAmount` | Net settlement amount in the currency's minor unit, which must be the sum of the `Amount` values of all transaction lines, minus the `TotalSettlementFeesAmount`. | string | `50000` |
| Column name | Description | Format | Example |
|---|---|---|---|
| `IntentId` | The unique identifier of the associated Intent in Mangopay's ecosystem. | string | `int_01978259-e06b-758c-8cd5-888cee9dd669` |
| `ExternalPaymentMethod` | The [supported payment method](/guides/echo/supported-payment-methods) used to process the transaction. | string | `int_01978259-e06b-758c-8cd5-888cee9dd669` |
| `ExternalInitialReference` | The unique identifier of the original transaction authorization or capture at the acquirer's level. Required only when `ExternalTransactionType` is `REFUND` or `DISPUTE`. | string | `capture-stripe-d5fad854-117c-4b1a-bf15-d8e2846749c7` |
| `ExternalProviderFees` | The amount of fees deducted by the provider from the transaction `Amount` in the currency's minor unit. | string | `150` |
| Footer line name | Description | Format | Example |
|---|---|---|---|
| `SettlementCurrency` | The currency of the settlement file. | string | `EUR` |
| Category | Payment method value | Description |
|---|---|---|
| Card networks | `VISA` | Visa |
| `MASTERCARD` | Mastercard | |
| `CB` | Carte bancaire | |
| `AMERICAN_EXPRESS` | American Express | |
| `DISCOVER` | Discover | |
| `DINERS_CLUB` | Diners Club | |
| `JCB` | JCB | |
| `UNIONPAY` | UnionPay | |
| Digital wallets (external) | `APPLE_PAY` | Apple Pay |
| `GOOGLE_PAY` | Google Pay | |
| `SAMSUNG_PAY` | Samsung Pay | |
| `PAYPAL` | PayPal | |
| `VENMO` | Venmo | |
| `CASH_APP` | Cash App | |
| Bank wire transfers and open banking | `SEPA_CREDIT_TRANSFER` | SEPA Credit Transfer |
| `SEPA_DIRECT_DEBIT` | SEPA Direct Debit | |
| `SWIFT` | SWIFT | |
| `WIRE_TRANSFER` | Wire Transfer | |
| `FASTER_PAYMENTS` | Faster Payments | |
| `BACS` | BACS | |
| `CHAPS` | CHAPS | |
| `ACH_CREDIT_TRANSFER` | ACH Credit Transfer | |
| `ACH_DIRECT_DEBIT` | ACH Direct Debit | |
| `RTP` | Real-Time Payments (RTP) | |
| `FEDNOW` | FedNow | |
| `OPEN_BANKING_UK` | Open Banking UK | |
| `OPEN_BANKING_EU` | Open Banking EU | |
| Buy Now, Pay Later (BNPL) | `KLARNA` | Klarna |
| `AFTERPAY` | Afterpay | |
| `CLEARPAY` | Clearpay | |
| `ZIP` | Zip | |
| `AFFIRM` | Affirm | |
| `PAYPAL_PAY_LATER` | PayPal Pay Later | |
| `SCALAPAY` | Scalapay | |
| Local payment methods – Europe | `BANCONTACT` | Bancontact |
| `BLIK` | BLIK | |
| `GIROPAY` | Giropay | |
| `EPS` | EPS | |
| `PRZELEWY24` | Przelewy24 (P24) | |
| `MULTIBANCO` | Multibanco | |
| `MBWAY` | MB Way | |
| `SOFORT` | Sofort | |
| `IDEAL` | iDEAL | |
| `TRUSTLY` | Trustly | |
| `SWISH` | Swish | |
| `TWINT` | Twint | |
| `BIZUM` | Bizum | |
| `MOBILEPAY` | MobilePay | |
| `POSTPAY` | PostPay | |
| `PAYSAFECARD` | Paysafecard | |
| `POSTFINANCE` | PostFinance | |
| `WERO` | Wero | |
| `PAYCONIQ` | Payconiq | |
| `ALIPAY` | Alipay | |
| `WECHATPAY` | WechatPa | |
| Local payment methods – UK and US | `ZELLE` | Zelle |
| `VENMO` | Venmo | |
| `CASH_APP` | Cash App | |
| Checks and cash-based | `CHECK` | Check |
| `CASH` | Cash | |
| `PAYSAFECARD_VOUCHER` | Paysafecard Voucher |
| Provider value | Description |
|---|---|
| `ADYEN` | Adyen |
| `BANKART` | Bankart d.o.o |
| `BBVA` | BBVA |
| `BUCKAROO` | Buckaroo |
| `CAIXA` | Caixa |
| `CHECKOUT` | Checkout |
| `HIPAY` | Hipay |
| `INGENICO` | Ingenico |
| `KLARNA` | Klarna |
| `MARKETPAY` | Marketpa |
| `MINSAIT_PAYMENTS` | Min |