Utworzenie wypłaty na kartę
Wypłata na kartę umożliwia przekazanie środków z salda sklepu na kartę płatniczą wskazaną w żądaniu. Wypłaty są realizowane przez Visa Direct (karty Visa) i Mastercard Send (karty Mastercard).
Kartę docelową przesyłasz do PayU w postaci tokena. Token otrzymasz od PayU po tokenizacji karty przez jej właściciela za pomocą formularza Secure Form.
Możliwe jest również przesyłanie danych karty w formie tekstowej (tylko dla podmiotów zatwierdzonych do przetwarzania danych karty po ich stronie).
Usługa wypłaty na kartę jest dostępna tylko dla sklepów spełniających kryteria weryfikacyjne. Aby rozpocząć proces weryfikacji, skontaktuj się z przedstawicielem handlowym PayU lub skorzystaj z formularza kontaktowego.
Wypłata na kartę przy użyciu tokena kartowego
curl -X POST https://secure.payu.com/api/v2_1/payouts \
-H "Content-Type: application/json" \
-H "Authorization: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd" \
-d '{
"shopId":"n7Cd7y1U",
"payout": {
"extPayoutId":"externalId12345",
"amount":"1000",
"description":"Some payout"
},
"payee": {
"extCustomerId": "Customer1",
"accountCreationDate": "2025-03-27T00:00:00.000Z",
"phoneNumber": "48 225108001",
"email": "email@email.com"
},
"customerAddress": {
"name":"Stefan Jaracz"
},
// highlight-start
"cardToken": {
"value":"TOKC_2IHRST6HKSST3H62K2GS8pElI862"
}
// highlight-end
}'
Żądanie musi zawierać obiekt payee z parametrami extCustomerId, accountCreationDate i email (phoneNumber jest opcjonalny) oraz obiekt customerAddress z parametrem name odbiorcy wypłaty.
Walidacja danych wejściowych dla wypłaty na określoną kartę płatniczą jest zupełnie inna niż w przypadku standardowej wypłaty. Szczegółowe informacje na temat parametrów znajdziesz w sekcji Create a Payout w naszej referencji API.
Token kartowy do zlecenia wypłaty może być tym samym, który był wcześniej używany do realizacji płatności, lub może zostać utworzony specjalnie w tym celu. Aby uzyskać nowy token, przeprowadź właściciela karty przez proces tokenizacji z parametrem type: MULTI. Właściciel zapisuje kartę i płaci nią, a Ty otrzymujesz wielorazowy token, którego możesz użyć do wypłaty środków z salda sklepu.
Ze względu na wymagania bezpieczeństwa konieczne jest potwierdzenie tożsamości właściciela karty. Token kartowy, na który ma zostać zlecona wypłata środków, musi zostać wcześniej zweryfikowany, na przykład w procesie płatności z silnym uwierzytelnieniem.
Aby zagwarantować silne uwierzytelnienie posiadacza karty podczas tworzenia nowego zamówienia, dołącz do żądania następujący obiekt:
"threeDsAuthentication": {
"challengeRequested": "MANDATE"
}
Tokeny z silnym uwierzytelnianiem (kod ECI odpowiedzi o wartości 5) mogą być używane do uwierzytelniania wypłat. Poziom uwierzytelnienia jest wskazywany przez wartość parametru cardEciCode i jest dostępny po pobraniu danych transakcji.
Mimo że token został wcześniej silnie uwierzytelniony, w celu zapewnienia najwyższego poziomu bezpieczeństwa może wystąpić konieczność jego ponownego uwierzytelnienia. W takim przypadku PayU odrzuca wypłatę i zwraca następujący kod błędu:
| Status HTTP | Kod błędu | Status | Opis błędu |
|---|---|---|---|
403 Forbidden | 8364 | BUSINESS_ERROR | PAYOUT_TOKEN_INSUFFICIENT_AUTHENTICATION_LEVEL |
W takiej sytuacji zalecamy utworzenie nowego zamówienia z użyciem tokena wymagającego silnego uwierzytelnienia oraz ustawieniem parametru threeDsAuthentication.challengeRequested na wartość MANDATE.
Po wykonaniu ponownego uwierzytelnienia musisz obsłużyć odpowiedź zwracającą parametr redirectUri.
Jeśli karta płatnicza nie obsługuje silnego uwierzytelniania lub z innego powodu nie można go przeprowadzić, sprzedawca jest zobowiązany do weryfikacji karty płatniczej w inny sposób, na przykład przez obciążenie karty losową kwotą i poproszenie klienta o podanie tej wartości. Aby aktywować takie rozwiązanie, skontaktuj się z PayU przez przedstawiciela handlowego lub skorzystaj z naszego formularza kontaktowego.
Wypłata na kartę z wykorzystaniem danych karty
Ten typ integracji jest dostępny tylko dla podmiotów spełniających wymagania PCI DSS i zatwierdzonych do przetwarzania danych kart po swojej stronie. Integracja ta wymaga również dodatkowej konfiguracji. Dlatego przed integracją skontaktuj się z przedstawicielem handlowym PayU.
Aby utworzyć wypłatę z danymi karty, dodaj do żądania wypłaty obiekt card z danymi karty.
curl -X POST https://secure.payu.com/api/v2_1/payouts \
-H "Content-Type: application/json" \
-H "Authorization: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd" \
-d '{
"shopId":"n7Cd7y1U",
"payout": {
"extPayoutId":"externalId12345",
"amount":"1000",
"description":"Some payout"
},
"payee": {
"extCustomerId": "Customer1",
"accountCreationDate": "2025-03-27T00:00:00.000Z",
"phoneNumber": "48 225108001",
"email": "email@email.com"
},
"customerAddress": {
"name":"Stefan Jaracz"
},
// highlight-start
"card": {
"number":"4444333322221111",
"expirationMonth":"11",
"expirationYear":"2029"
}
// highlight-end
}'
Walidacja danych wejściowych dla wypłaty na określoną kartę płatniczą jest zupełnie inna niż w przypadku standardowej wypłaty. Szczegółowe informacje na temat parametrów znajdziesz w sekcji Create a Payout w naszej referencji API.
Testowanie wypłat na kartę
Do testowania wypłat na kartę w środowisku Sandbox możesz użyć kart z poniższej tabeli. Kolumna Status wypłaty pokazuje wynik wypłaty na daną kartę.
| Numer | Data ważności | Marka | Status wypłaty |
|---|---|---|---|
4655413107713609 | 12/2030 | Visa | REALIZED |
4302193177728334 | 12/2030 | Visa | CANCELLED |
5575278649907280 | 12/2030 | Mastercard | REALIZED |
5436518288281326 | 12/2030 | Mastercard | CANCELLED |