Wypłaty

1 Autoryzacja

Klient autoryzuje się przy pomocy standardu OAuth. Pobierając token, który wykorzystuje do utworzenia wypłaty oraz pobrania statusu wypłaty.

1.1 Gdzie znaleźć dane niezbędne do autoryzacji?

Dane autoryzacyjne można pobrać z panelu klienta:

Aby pobrać dane autoryzacyjne należy przejść do następującej lokalizacji: Moje sklepy -> Detale sklepu -> Zakładka punkty płatności -> Detale punktu płatności:

  • client_id: Id punktu płatności (protokół OAuth - client_id)
  • client_secret: Klucz MD5 (protokół OAuth - client_secret)

1.2 Pobranie tokena autoryzacyjnego

Użytkownik może pobrać token autoryzacyjny z usługi autoryzacyjnej OAuth. Pobranie tokena umożliwia dostęp do Payout API. Aby pobrać token postępuj zgodnie z opisem dostępnym pod:

Pobranie tokena autoryzacyjnego.

apiary

1.3 Nagłówek autoryzacyjny w request-cie do Payout API

Obie dostępne metody (utworzenie payouta oraz pobranie danych wypłaty) autoryzujemy przez dodanie nagłówka:

                Authorization: Bearer [access_token]
            

Bearer oznacza autoryzację OAuth, access_token jest tokenem otrzymanym w odpowiedzi od serwisu autoryzacyjnego oauth, patrz 1.2.

2 Utworzenie wypłaty

Wypłata jest wykonywana na Rachunek Bankowy zdefiniowany na poziomie Sklepu bądź Firmy.

Specyfikacja komunikatu tworzącego Wypłatę:

Pole Wymagalność Komentarz
payout/extPayoutId nie Identyfikator Zewnętrzny Wypłaty, nadany przez klienta. Klient może zlecić tylko jedną wypłatę o zadanym identyfikatorze zewnętrznym. Wymagana jest unikalność extPayoutId w obrębie wypłat tego samego sklepu
payout/amount nie Kwota Wypłaty. Jeżeli zostanie podana, to z Salda Sklepu zostanie zlecona Wypłata na podaną Kwotę Wypłaty – oczywiście tylko w przypadku, gdy stan salda Sklepu to umożliwia
payout/description nie Opis Wypłaty
shopId tak Identyfikator sklepu, z którego chcemy wypłacić środki

2.1 Przykłady

Każde żądanie powinno zawierać nagłówek autoryzacyjny pokazany w punkcie 1.3 oraz definicję typu przesyłanych danych Content-Type application/json.

Wypłata podanej kwoty:

                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": 
                    {    
                        "amount": 1100  
                    }
                }'
            

Metody uwierzytelnienia znajdują się w: Uwierzytelnienie użytkownika API.

Opis pól:
  • shopId jest identyfikatorem sklepu w PayU, z którego salda dokonywana będzie wypłata
  • amount jest kwotą wypłaty podaną w groszach
W szczególności, jeżeli Sklep chce dokonać pełnej Wypłaty wszystkich dostępnych środków, to wystarczy, że wyśle żądanie HTTP zawierające tylko shopId na adres URL:
http://secure.payu.com/api/v2_1/payouts

Wypłata całej kwoty:

                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"
                 }'
            
Opis pól:
  • shopId jest identyfikatorem sklepu w PayU, z którego salda dokonywana będzie wypłata

Pozostałe dane zostaną uzupełnione z informacji przechowywanych w systemie PayU.

Przykład odpowiedzi na wysłanie żądania utworzenia Wypłaty:

                {
                  "payout": {
                    "payoutId": "133bfe5f400e4b2c8da44abfdf753d79",
                    "extCustomerId": "123123",
                    "status": "PENDING"
                  },
                  "status": {
                    "statusCode": "SUCCESS"
                  }
                }
                
            
Opis pól:
  • payoutId jest publicznym identyfikatorem wypłaty, który należy wykorzystać odpytując o status wypłaty, patrz punkt 4
  • extCustomerId jest identyfikatorem użytkownika (pole opcjonalne; zostanie zwrócony jeżeli został podany w żądaniu)
  • status oznacza aktualny status wypłaty
  • statusCode w sekcji status oznacza status żądania

apiary

3 Utworzenie wypłaty na podany rachunek bankowy

Wypłatę na wskazany Rachunek Bankowy można zlecić na:

  • rachunek bankowy krajowy
  • rachunek bankowy zagraniczny
  • jako zlecenie przelewu pocztowego (tylko i wyłącznie dla polskich sklepów)

co wpływa na zakres przekazywanych informacji w komunikacie wejściowym. Walidacja zakresu danych wejściowych dla Wypłaty na podany Rachunek Bankowy jest zupełnie inna niż dla standardowej Wypłaty.

Uwaga! Utworzenie Wypłaty ze wskazaniem Rachunku Bankowego jest dostępne tylko i wyłącznie dla sklepów spełniających kryteria weryfikacyjne. Skontaktuj się z PayU w celu rozpoczęcia procesu weryfikacyjnego przez email: handlowy@payu.pl lub telefonicznie na numer: +48 61 630 60 05.

Specyfikacja komunikatu tworzącego Wypłatę na wskazany Rachunek Bankowy:

Pole Wymagalność Komentarz
payout/extPayoutId nie Identyfikator Zewnętrzny Wypłaty, nadany przez klienta. Klient może zlecić tylko jedną wypłatę o zadanym identyfikatorze zewnętrznym. Wymagana jest unikalność extPayoutId w obrębie wypłat tego samego sklepu
payout/amount tak Kwota Wypłaty
payout/description nie Opis Wypłaty
payout/foreign Domyślnie flaga nie jest ustawiona Flaga określająca czy Wypłata na rachunek zagraniczny
payout/postalOrder Domyślnie flaga nie jest ustawiona Flaga określająca czy Wypłata w postaci zlecenia przelewu pocztowego. Ustawienie flagi wymusza uzupełnienie pól adresowych i zdejmuje wymagalność dla pola numer rachunku
account/accountNumber Pole opcjonalne dla ustawionej flagi postalOrder, w pozostałych przypadkach wymagane Numer Rachunku Bankowego. Wymagane formaty rachunków dla przelewów zagranicznych:
  • rachunki polskie: NRB, IBAN
  • rachunki czeskie: IBAN, wewnętrze w formie ([0-9]{1,6}[ -])?[0-9]{2,10}[ /][0-9]{4})
Dla przelewów krajowych aktualnie brak ograniczeń na format
account/bankName Pole wymagane dla Wypłat na rachunek zagraniczny (ustawiona flaga foreign), w pozostałych przypadkach opcjonalne Nazwa Banku
account/swiftCode Pole wymagane dla Wypłat na rachunek zagraniczny (ustawiona flaga foreign), w pozostałych przypadkach opcjonalne Kod SWIFT Banku
customerAddress/street Pole wymagane dla:
  • wypłat na rachunek zagraniczny (ustawiona flaga foreign)
  • dla przekazów pocztowych (ustawiona flaga postalOrder)
Dane adresowe Odbiorcy Wypłaty
customerAddress/postalCode Pole wymagane dla przekazów pocztowych (ustawiona flaga postalOrder), w pozostałych przypadkach opcjonalne Dane adresowe Odbiorcy Wypłaty
customerAddress/city Pole wymagane dla:
  • wypłat na rachunek zagraniczny (ustawiona flaga foreign)
  • dla przekazów pocztowych (ustawiona flaga postalOrder)
Dane adresowe Odbiorcy Wypłaty
customerAddress/country Pole wymagane dla Wypłat na rachunek zagraniczny (ustawiona flaga foreign), w pozostałych przypadkach opcjonalne Dane adresowe Odbiorcy Wypłaty
customerAddress/name tak Nazwa Odbiorcy Wypłaty
bankAddress/street Pole wymagane dla Wypłat na rachunek zagraniczny (ustawiona flaga foreign), w pozostałych przypadkach opcjonalne Dane adresowe Banku
bankAddress/postalCode Pole wymagane dla Wypłat na rachunek zagraniczny (ustawiona flaga foreign), w pozostałych przypadkach opcjonalne Dane adresowe Banku
bankAddress/city Pole wymagane dla Wypłat na rachunek zagraniczny (ustawiona flaga foreign), w pozostałych przypadkach opcjonalne Dane adresowe Banku
bankAddress/countryCode Pole wymagane dla Wypłat na rachunek zagraniczny (ustawiona flaga foreign), w pozostałych przypadkach opcjonalne Dane adresowe Banku

Specyfikacja odpowiedzi na żądanie tworzące Wypłatę:

Pole Komentarz
payout/payoutId Unikalne Id Wypłaty nadane przez PayU
payout/extPayoutId Identyfikator Zewnętrzny Wypłaty – echo informacji przesłanej w komunikacie wejściowym
payout/status Status Wypłaty Dziedzina wartości:
  • PENDING
  • WAITING
  • CANCELLED
  • REALIZED
  • RETURNED

3.1 Przykłady

Każde żądanie powinno zawierać nagłówek autoryzacyjny pokazany w punkcie 1.3 oraz definicję typu przesyłanych danych Content-Type application/json.

Wypłata na rachunek krajowy:

                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": {    
                        "amount":"1000",    
                        "description":"Some payout"  
                    },  
                    "account": {    
                        "accountNumber":"59114072854040477132976504"  
                    },  
                    "customerAddress": {    
                        "name":"Stefan Jaracz"  
                    }
                }'       
            

Metody uwierzytelnienia znajdują się w: Uwierzytelnienie użytkownika API.

Wypłata na rachunek zagraniczny z wykorzystaniem Kodu SWIFT i nazwy banku:

                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": {
                        "amount":"1000",
                        "description":"Some foreign payout",
                    "foreign":"true"
                    },
                    "account": {
                        "accountNumber":"DE610639036594575851447918096101",
                        "swiftCode":"AARBDE5W700",
                        "bankName":"Aareal Bank"
                    },
                    "customerAddress": {
                        "street":"RICHARD STRAUSS STRASSE 24",
                        "city":"MUENCHEN",
                        "countryCode":"DE",
                        "name":"Steffen von Klaus"
                    }
                }'
            

4 Pobranie danych Wypłaty

Aby pobrać dane Wypłaty należy wysłać żądanie HTTP GET na adres URL skonstruowany w postaci:

http://secure.payu.com/api/v2_1/payouts/{payoutId}

payoutId jest publicznym identyfikatorem Wypłaty zwróconym w odpowiedzi na żadanie utworzenia wypłaty. Specyfikacja komunikatu pobierającego dane Wypłaty:

Pole Komentarz
payout/payoutId Unikalne Id Wypłaty nadane przez PayU
payout/extPayoutId Identyfikator Zewnętrzny Wypłaty – echo informacji przesłanej przez sklep w momencie tworzenia Wypłaty
payout/amount Kwota Wypłaty
payout/description Opis Wypłaty
payout/status Statusy Wypłaty:
  • PENDING
  • PROCESSED
  • REALIZED
  • RETURNED

Każde żądanie powinno zawierać nagłówek autoryzacyjny pokazany w punkcie 1.3 oraz definicję typu przesyłanych danych Content-Type application/json.

Przykład żądania:

                curl -X GET https://secure.payu.com/api/v2_1/payouts/133bfe5f400e4b2c8da44abfdf753d79 
                -H "Content-Type: application/json" 
                -H "Authorization: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd"
            

Przykład odpowiedzi:

                {
                  "payout": {
                    "payoutId": "133bfe5f400e4b2c8da44abfdf753d79",
                    "amount": "1100",
                    "description": "Billing: 169602484",
                    "status": "PENDING"
                  },
                  "status": {
                    "statusCode": "SUCCESS"
                  }
                }                
            
Opis pól:
  • payoutId jest publicznym identyfikatorem Wypłaty
  • amount jest kwotą Wypłaty podaną w groszach
  • description jest wygenerowanym tytułem Wypłaty
  • status oznacza obecny status Wypłaty
  • statusCode zawarty w sekcji status zawiera status żądania

Przykład błędnej odpowiedzi (przypadek podania błędnego publicznego identyfikatora Wypłaty):

                {
                  "status": {
                    "statusCode": "DATA_NOT_FOUND",
                    "severity": "ERROR",
                    "code": "8354",
                    "codeLiteral": "INCORRECT_MERCHANT_POS",
                    "statusDesc": "INCORRECT_MERCHANT_POS"
                  }
                }               
            

Specyfikacja sekcji statusowej komunikatów odpowiedzi:

Pole Komentarz
status/statusCode Status realizacji żądania
status/severity Poziom błędu:
  • INFO
  • WARNING
  • ERROR
status/code Kod błędu z sekcji 5
status/codeLiteral Opis kodu błędu

5 Kody błędów

Kody błędów w procesowaniu komunikatu odsyłane są w komunikatach response w sekcji statusowej.

Kod błędu Status Opis kodu błędu Status HTTP
100 GENERAL_ERROR GENERAL_ERROR 500 Internal Server Error
101 ERROR_VALUE_INVALID UNKOWN_MERCHANT 403 Forbidden
102 GENERAL_ERROR SERVICE_TEMPORARY_UNAVAILABLE 500 Internal Server Error
8300 ERROR_VALUE_MISSING MISSING_PAYOUT_AMOUNT 400 Bad Request
8301 ERROR_VALUE_MISSING MISSING_ACCOUNT_NUMBER 400 Bad Request
8302 ERROR_VALUE_MISSING MISSING_CUSTOMER_NAME 400 Bad Request
8303 ERROR_VALUE_MISSING MISSING_BANK_NAME 400 Bad Request
8304 ERROR_VALUE_MISSING MISSING_BANK_ADDRESS 400 Bad Request
8305 ERROR_VALUE_MISSING MISSING_BANK_ADDRESS_STREET 400 Bad Request
8306 ERROR_VALUE_MISSING MISSING_BANK_ADDRESS_CITY 400 Bad Request
8307 ERROR_VALUE_MISSING MISSING_BANK_ADDRESS_COUNTRY 400 Bad Request
8308 ERROR_VALUE_MISSING MISSING_SWIFT_CODE 400 Bad Request
8309 ERROR_VALUE_MISSING MISSING_CUSTOMER_ADDRESS_STREET 400 Bad Request
8310 ERROR_VALUE_MISSING MISSING_CUSTOMER_ADDRESS_CITY 400 Bad Request
8311 ERROR_VALUE_MISSING MISSING_CUSTOMER_ADDRESS_COUNTRY 400 Bad Request
8312 ERROR_VALUE_MISSING MISSING_CUSTOMER_ADDRESS_POSTAL_CODE 400 Bad Request
8313 ERROR_VALUE_MISSING MISSING_MERCHANT_POS_ID 400 Bad Request
8314 ERROR_VALUE_MISSING MISSING_USER_NAME 400 Bad Request
8315 ERROR_VALUE_MISSING MISSING_TIMESTAMP 400 Bad Request
8316 ERROR_VALUE_INVALID PAYOUT_DESCRIPTION_TOO_LONG 400 Bad Request
8317 ERROR_VALUE_INVALID ACCOUNT_NUMBER_TOO_LONG 400 Bad Request
8318 ERROR_VALUE_INVALID BANK_NAME_TOO_LONG 400 Bad Request
8319 ERROR_VALUE_INVALID SWIFT_CODE_TOO_LONG 400 Bad Request
8320 ERROR_VALUE_INVALID CUSTOMER_ADDRESS_STREET_​TOO_LONG 400 Bad Request
8321 ERROR_VALUE_INVALID CUSTOMER_ADDRESS_POSTAL_CODE_​TOO_LONG 400 Bad Request
8322 ERROR_VALUE_INVALID CUSTOMER_ADDRESS_CITY_TOO_LONG 400 Bad Request
8323 ERROR_VALUE_INVALID CUSTOMER_ADDRESS_COUNTRY_CODE_​TOO_LONG 400 Bad Request
8324 ERROR_VALUE_INVALID CUSTOMER_ADDRESS_POSTAL_CITY_​TOO_LONG 400 Bad Request
8325 ERROR_VALUE_INVALID CUSTOMER_ADDRESS_POSTAL_NAME_​TOO_LONG 400 Bad Request
8326 ERROR_VALUE_INVALID CUSTOMER_ADDRESS_NAME_TOO_LONG 400 Bad Request
8327 ERROR_VALUE_INVALID CUSTOMER_NAME_TOO_LONG 400 Bad Request
8328 ERROR_VALUE_INVALID BANK_ADDRESS_STREET_TOO_LONG 400 Bad Request
8329 ERROR_VALUE_INVALID BANK_ADDRESS_POSTAL_CODE_TOO_LONG 400 Bad Request
8330 ERROR_VALUE_INVALID BANK_ADDRESS_POSTAL_CITY_TOO_LONG 400 Bad Request
8331 ERROR_VALUE_INVALID BANK_ADDRESS_POSTAL_NAME_TOO_LONG 400 Bad Request
8332 ERROR_VALUE_INVALID BANK_ADDRESS_CITY_TOO_LONG 400 Bad Request
8333 ERROR_VALUE_INVALID BANK_ADDRESS_COUNTRY_CODE_TOO_LONG 400 Bad Request
8334 ERROR_VALUE_INVALID INCORRECT_DESCRIPTION 400 Bad Request
8335 ERROR_VALUE_INVALID INCORRECT_PUBLIC_ID 400 Bad Request
8336 ERROR_VALUE_INVALID WRONG_CURRENCY 400 Bad Request
8350 ERROR_VALUE_INVALID INCORRECT_PAYOUT_AMOUNT 400 Bad Request
8351 ERROR_VALUE_INVALID INCORRECT_ACCOUNT_NUMBER 400 Bad Request
8352 BUSINESS_ERROR NOT_ENOUGH_FUNDS 403 Forbidden
8353 DATA_NOT_FOUND INCORRECT_PAYOUT 404 Not Found
8354 DATA_NOT_FOUND INCORRECT_MERCHANT_POS 404 Not Found
8355 BUSINESS_ERROR INCORRECT_REQUEST 403 Forbidden
8356 BUSINESS_ERROR PAYOUT_ALREADY_EXISTS 403 Forbidden
8357 UNAUTHORIZED_REQUEST UNAUTHORIZED_REQUEST 401 Unauthorized
8358 BUSINESS_ERROR NO_PERMISSION 403 Forbidden
8359 BUSINESS_ERROR SHOP_NOT_ALLOWED 403 Forbidden
8360 BUSINESS_ERROR FIRM_NOT_ALLOWED 403 Forbidden
8361 ERROR_VALUE_MISSING MISSING_MERCHANT_SHOP_ID 400 Bad Request