Skip to main content

Fx-payouts

The Fx-Payouts service is an extension of the Payouts API. This service enables payouts to be conducted in a currency other than the shop's native currency. Currency conversion is currently available for currency combinations: PLN, CZK, EUR, HUF.

Requirements

In order to use Fx-Payouts, a special configuration is required on the PayU side and certain formal requirements must be met.

Fx-Payouts support is only available for withdrawals to a marketplace seller's bank account.

Retrieving Rate Table​

To convert withdrawals, you should use the rates provided by PayU. To retrieve the rate table you will need to generate an OAuth token and then make a request with the HTTP GET method to the /api/v2_1/mcp-partners/{fxPartnerId}/fx-table endpoint.

GET Request Body

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.

Retrieving Rate Table Example
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"

Details of the parameters can be found in the Retrieve Rate Table section of our API Reference.

In response to a request, PayU returns an object containing currency pairs along with their exchange rate.

Refreshing the rate table

Always use the latest exchange rate table. Retrieve the new table as soon as the old one expires.

Example of a Response to a Retrieve Rate Table Request
{
    "id": "3050",
    "validTo": "2024-05-12T20:20:00Z",
    "currencyPairs": [
        {
            "baseCurrency": "EUR",
            "exchangeRate": 4.2556,
            "termCurrency": "PLN"
        }
        ...
    ]
}

Payment Request Extension​

To perform a payout with currency conversion, you must send an extended payout request using the POST method to the /api/v2_1/payouts endpoint. The request should be extended to include sections:

  • 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.
Example of Payout Request Body with 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 on the parameters, please refer to Create a Payout section in our API Reference.

Response to an Fx-payout Request​

Once the payout has been correctly ordered, we will send you a confirmation of the request along with the withdrawal details.

{
    "payout": {
        "payoutId": "bd71af6089ed4723b8699a9b4d14432c",
        "extPayoutId": "my_payout_id_123455",
        "extCustomerId": "my_payout_id_123455",
        "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 a GET request to the endpoint /api/v2_1/payouts/{payoutId}. The payoutId parameter is returned in the response to the payout request.

In the response, you will receive information about the payout and its current status.

Fx-payout Data Request Response Example
{
    "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 on the parameters, please refer to Retrieve a Payout section in our API Reference.

Fx-payout in Seller's Operation History​

The fx-payout retrieved from the seller's operation history does not contain conversion data. In addition to other data, only the amount that was deducted from the seller's balance is shown. Below is an example of a fx-payout retrieved together with the operation history:

Fx-payout seen in Retrieved 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"
        }
    ],
    ...
}

You can find more information about retrieving seller's operation history on the Marketplace documentation page.

The same applies to statements generated from the administration panel. The statement will show the amount deducted from the seller's balance without the conversion details.

Error Codes for Fx-payouts​

The following is a list of errors related to fx-payouts.

Fx-payouts Error Codes
Http StatusStatusError CodeDescription
400
BUSINESS_ERROR
FX_PAYOUT_NOT_ALLOWED
The Fx-payout service is not available for a given merchant. Special configuration on the PayU side is required.
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.

On this page