FX Payouts
The FX payouts service is an extension of the Payouts API. It lets you pay out funds in a currency other than the native currency of the shop. Currency conversion is available between PLN, CZK, EUR and HUF.
To use FX payouts, PayU must enable a special configuration, and you must meet certain formal requirements.
FX payouts are available only for payouts to a marketplace seller's bank account.
Retrieving Rate Table
To convert payouts, use the rates provided by PayU. To retrieve the rate table, generate an OAuth token and send an HTTP GET request to the /api/v2_1/mcp-partners/{fxPartnerId}/fx-table endpoint.
When making GET requests, please remember not to include any data in the request body, as specified in the RFC 9110 standard. Requests that do not adhere to this requirement will be rejected by PayU with an HTTP 403 status.
curl -X GET https://secure.payu.com/api/v2_1/mcp-partners/9999e44b-f68f-42e1-ad6c-3735ba1e2954/fx-table \
-H "Authorization: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd"
For details about the parameters, see the Retrieve Rate Table section in our API Reference.
In response to a request, PayU returns an object containing currency pairs along with their exchange rate.
Always use the latest exchange rate table. Retrieve the new table as soon as the old one expires.
{
"id": "3050",
"validTo": "2024-05-12T20:20:00Z",
"currencyPairs": [
{
"baseCurrency": "EUR",
"exchangeRate": 4.2556,
"termCurrency": "PLN"
}
...
]
}
Payout Request Extension
To make a payout with currency conversion, send an extended payout request as an HTTP POST request to the /api/v2_1/payouts endpoint. Include the following objects:
account- containing the identifier of the submerchant,payout- containing the currency of the shop and the amount of the withdrawal,fxData- containing the data needed for currency conversion.
{
"shopId": "JahDKDVm",
"account": {
"extCustomerId": "submerchant1"
},
"payout": {
"currencyCode": "PLN",
"description": "Some payout",
"extPayoutId": "my_payout_id_123455",
"amount": 49
},
"fxData": {
"partnerId": "9999e44b-f68f-42e1-ad6c-3735ba1e2954",
"currencyCode": "EUR",
"amount": 11,
"rate": 0.22458,
"tableId": "2055"
}
}
For details about the parameters, see the Create a Payout section in our API Reference.
Response to an FX Payout Request
If the payout is ordered correctly, PayU returns a confirmation with the payout details.
{
"payout": {
"payoutId": "bd71af6089ed4723b8699a9b4d14432c",
"extPayoutId": "my_payout_id_123455",
"extCustomerId": "submerchant1",
"amount": 49,
"currencyCode": "PLN",
"status": "PENDING",
"fxData": {
"currencyCode": "EUR",
"amount": 11,
"rate": 0.22458,
"partnerId": "9999e44b-f68f-42e1-ad6c-3735ba1e2954",
"tableId": "2055"
}
},
"status": {
"statusCode": "SUCCESS"
}
}
Retrieving FX Payout Data
To retrieve FX payout data, send an HTTP GET request to the /api/v2_1/payouts/{payoutId} endpoint. The payoutId is returned in the response to the payout request. The response contains the payout details and its current status.
{
"payout": {
"payoutId": "bd71af6089ed4723b8699a9b4d14432c",
"extPayoutId": "my_payout_id_123455",
"amount": 49,
"currencyCode": "PLN",
"description": "Billing: 5000000444",
"status": "PENDING",
"fxData": {
"currencyCode": "EUR",
"amount": 11,
"rate": 0.22458,
"partnerId": "9999e44b-f68f-42e1-ad6c-3735ba1e2954",
"tableId": "2055"
}
},
"status": {
"statusCode": "SUCCESS"
}
}
For details about the parameters, see the Retrieve a Payout section in our API Reference.
FX Payout in Seller's Operation History
An FX payout retrieved from the seller's operation history does not contain conversion data. Of the payout amounts, only the amount deducted from the seller's balance is shown. Below is an example of an FX payout retrieved with the operation history:
{
"operations": [
...
{
"currencyCode": "PLN",
"amount": 49,
"type": "PAYOUT",
"description": "Billing: 5000000444",
"status": "COMPLETED",
"details": {
"payoutId": "bd71af6089ed4723b8699a9b4d14432c",
"extPayoutId": "my_payout_id_123455",
"accountNumber": "PL76804610704885900358890402",
"counterparties": [],
"funds": []
},
"eventDate": "2024-05-09T11:10:35+02:00",
"creationDate": "2024-05-09T11:09:39+02:00"
}
],
...
}
For more information about retrieving the seller's operation history, see the Marketplace page.
The same applies to statements generated in the Management Panel. The statement shows the amount deducted from the seller's balance without the conversion details.
Error Codes for FX Payouts
The following errors are specific to FX payouts.
| HTTP Status | Status | Description | |
|---|---|---|---|
400 | BUSINESS_ERROR | FX_PAYOUT_NOT_ALLOWED | The FX payout service is not available for the merchant. It requires a special configuration on the PayU side. |
400 | ERROR_VALUE_INVALID | FX_PARTNER_NOT_FOUND | The partner ID specified does not exist. |
400 | ERROR_VALUE_INVALID | FX_TABLE_OUTDATED | The exchange rate table used is already out of date. |
400 | ERROR_VALUE_INVALID | FX_TERM_AMOUNT_INVALID | Incorrectly calculated withdrawal amount after currency conversion. |
400 | ERROR_VALUE_INVALID | FX_TABLE_NOT_FOUND | No rate table with the specified ID was found within the specified partner. |
400 | ERROR_VALUE_INVALID | FX_RATE_INVALID | The rate provided is incorrect for the specified currency pair. |
400 | ERROR_VALUE_INVALID | FX_CURRENCY_PAIR_NOT_SUPPORTED | The currency pair used is unsupported or unavailable. |
400 | ERROR_VALUE_INVALID | FX_TERM_CURRENCY_NOT_SUPPORTED | The currency code specified for the currency conversion is not supported. |
400 | ERROR_VALUE_INVALID | FX_BASE_CURRENCY_NOT_SUPPORTED | The specified currency code from which the currency conversion should be made is not supported. |
400 | ERROR_VALUE_INVALID | INCONSISTENT_PAYOUT_CURRENCY | The specified currency is not compatible with the defined currency of the shop. |
400 | ERROR_VALUE_INVALID | MISSING_<fieldName> | The specified field is missing. |
400 | ERROR_VALUE_INVALID | INVALID_<fieldName> | The specified field is incorrect. |
400 | ERROR_VALUE_INVALID | <fieldName>_TOO_LONG | The specified field is too long. |