Wypłaty wielowalutowe

Usługa wypłat wielowalutowych jest rozszerzeniem API przeznaczonego do wypłat. Usługa ta pozwala na realizację wypłat w walucie innej niż waluta sklepu. Aktualnie możliwe jest przewalutowanie w zakresie kombinacji walut: PLN, CZK, EUR, HUF.

Wymagania

Aby korzystać z wypłat wielowalutowych, konieczna jest specjalna konfiguracja po stronie PayU i należy spełnić określone wymagania formalne.

Obsługa wypłat wielowalutowych aktualnie jest dostępna jedynie w przypadku wypłaty na rachunek bankowy submerchanta marketplace.

Pobieranie tabeli kursów

Do przewalutowania wypłat powinieneś użyć kursów udostępnianych przez PayU. W celu pobrania tabeli kursów, musisz wygenerować token OAuth, a następnie wykonać żądanie z metodą HTTP GET na endpoint /api/v2_1/mcp-partners/{fxPartnerId}/fx-table.

Ciało żądania metody GET

Wysyłając żądania z metodą GET upewnij się, że w ciele żądania nie przesyłasz żadnych danych. Zgodnie ze standardem RFC 9110 żądania, które nie spełniają tego wymogu, zostaną odrzucone przez PayU i zwrócony zostanie kod HTTP 403.

Przykład żądania pobrania tabeli kursów
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"

Szczegóły parametrów znajdziesz w sekcji Retrieve Rate Table w naszej referencji API.

W odpowiedzi na żądanie, PayU zwraca obiekt z zawierający pary walutowe razem z kursem ich przewalutowania.

Odświeżanie tabeli kursów

Należy zawsze korzystać z najnowszej tabeli kursów wymiany. Nową tabelę pobieraj natychmiast po wygaśnięciu starej.

Przykład odpowiedzi na żądanie pobrania tabeli kursów
{
    "id": "3050",
    "validTo": "2024-05-12T20:20:00Z",
    "currencyPairs": [
        {
            "baseCurrency": "EUR",
            "exchangeRate": 4.2556,
            "termCurrency": "PLN"
        }
        ...
    ]
}

Rozszerzenie żądania wypłaty

Aby wykonać wypłatę z przewalutowaniem, musisz wysłać rozszerzone żądanie wypłaty, przy użyciu metody POST, na endpoint /api/v2_1/payouts. Żądanie należy rozszerzyć o sekcje:

account - zawierającą identyfikator submerchanta,
payout - zawierającą walutę sklepu i kwotę wypłaty,
fxData - zawierającą dane potrzebne do przewalutowania.

Przykład żądania wypłaty wraz z przewalutowaniem
{
    "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",
    }
}

Szczegółowe informacje na temat parametrów znajdziesz w sekcji Create a Payout w naszej referencji API.

Odpowiedź na żądanie wypłaty wielowalutowej

Jeżeli wypłata została zlecona poprawnie, w odpowiedzi otrzymasz potwierdzenie wysłania żądania z danymi wypłaty.

{
    "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",
        }
    }
}

Pobieranie danych wypłaty wielowalutowej

Aby pobrać dane wypłaty wielowalutowej musisz wysłać żądanie, przy użyciu metody GET, na endpoint /api/v2_1/payouts/{payoutId}. Użyty w żądaniu parametr payoutId zwracany jest w odpowiedzi do żądania zlecenia wypłaty.

W odpowiedzi zwrócone zostaną informacje o danej wypłacie wraz z jej obecnym statusem.

Odpowiedź na żądanie pobrania danych wypłaty
{
    "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"
    }
}

Szczegółowe informacje na temat parametrów znajdziesz w sekcji Retrieve a Payout w naszej referencji API.