Wypłaty

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

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)

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 w sekcji Pobranie tokena autoryzacyjnego.

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.

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

Specyfikacja komunikatu tworzącego Wypłatę:

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.

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:

https://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"
                 }'
            

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

Przykładowe utworzenie wypłaty z Variable symbol:

                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,
                        "additionalVariables": "VS=888111"  
                    }
                }'
                
            

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

                {
                    "payout": {
                        "payoutId": "133bfe5f400e4b2c8da44abfdf753d79",
                        "extCustomerId": "123123",
                        "status": "PENDING"
                    },
                    "status": {
                        "statusCode": "SUCCESS"
                    }
                }
                
            

Opis pól odpowiedzi:

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. W celu rozpoczęcia procesu weryfikacyjnego skontaktuj się z PayU poprzez naszą stronę kontaktową.

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

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

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"
                    }
                }'
            

Usługa pozwala na szybką wypłatę środków z salda sklepu na wskazaną w żądaniu kartę płatniczą. Wypłaty zostaną zrealizowane za pośrednictwem usług Visa Direct (dla kart Visa).

Uwaga! Utworzenie Wypłaty na kartę płatniczą jest dostępne wyłącznie dla sklepów spełniających kryteria weryfikacyjne. W celu rozpoczęcia procesu weryfikacyjnego należy skontaktować się ze swoim opiekunem handlowym w PayU, lub przez formularz kontaktowy.

Karta, na którą mają trafić środki, powinna zostać przesłana do PayU w postaci tokena kartowego uzyskanego od PayU po dokonaniu tokenizacji przez właściciela karty.

Możliwe jest również przesłanie danych kartowych w postaci tekstowej (tylko dla podmiotów uprawnionych do przetwarzania danych kartowych po swojej stronie).

Walidacja zakresu danych wejściowych dla Wypłaty na kartę płatniczą jest zupełnie inna niż dla standardowej Wypłaty.

Struktura odpowiedzi opisana jest w punkcie 2.2.

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

Zalecany sposób integracji polega na przesłaniu w żądaniu tokenu kartowego, który reprezentuje kartę płatniczą, na którą następnie zostanie zlecona wypłata środków.

                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" 
                        },  
                        "customerAddress": {    
                            "name":"Stefan Jaracz"  
                        },
                        "cardToken": {    
                            "value":"TOKC_2IHRST6HKSST3H62K2GS8pElI862"  
                        }  
                    }'

            

Token kartowy do zlecenia wypłaty może być tym samym, który był wcześniej używany do realizacji płatności, lub też może zostać utworzony specjalnie w tym celu. Aby uzyskać nowy token należy przeprowadzić właściciela karty przez proces jej tokenizacji z parametrem type=MULTI który pozwoli na zapisanie karty, wykonanie nią płatności i uzyskanie tokenu wielorazowego, który może posłużyć do realizacji 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.

W celu zagwarantowania silnego uwierzytelnienia właściciela karty należy przy tworzeniu zamówienia REST API dołączyć następujący fragment:

                "threeDsAuthentication": {
                    "challengeRequested": "MANDATE"
                }
             
            

Szczegółowy opis wszystkich parametrów REST API znajduje się w sekcji Parametry JSON.

Tokeny silnie uwierzytelnione (kod odpowiedzi ECI o wartości 5) mogą być wykorzystywane do wypłaty środków. Poziom uwierzytelnienia transakcji można odczytać z pola cardEciCode po pobraniu danych transakcji.

W przypadku, gdy karta nie wspiera silnego uwierzytelnienia, lub z jakiegoś innego powodu niemożliwe jest jego przeprowadzenie, merchant zobowiązany jest do przeprowadzenia weryfikacji w inny sposób, na przykład poprzez obciążenie karty na losową kwotę i poproszenie klienta o podanie tej wartości. W celu uruchomienia takiego rozwiązania należy skontaktować się ze swoim opiekunem handlowym w PayU, lub przez formularz kontaktowy.

Uwaga! Ten sposób integracji jest przeznaczony tylko dla podmiotów, które spełniają wymogi określone przez PCI DSS i są uprawnione do przetwarzania danych kartowych po swojej stronie. Wymagają również dodatkowej konfiguracji. Dlatego przed przystąpieniem do integracji należy skontaktować się z opiekunem handlowym w PayU.

                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" 
                        },  
                        "customerAddress": {    
                            "name":"Stefan Jaracz"  
                        },
                        "card": {    
                            "number":"4444333322221111",  
                            "expirationMonth":"11",  
                            "expirationYear":"2029"  
                        }  
                    }'    

            

Przygotowaliśmy kilka numerów kart na potrzeby testów na środowisku Sandbox. Numery kart i skutki zakończenia procesu wypłaty przy ich użyciu znajdują się w tabeli poniżej.

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

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

payoutId jest publicznym identyfikatorem Wypłaty zwróconym w odpowiedzi na żadanie utworzenia wypłaty.

Pobieranie danych o wypłatach jest ograniczone do ostatnich 2 tygodni.

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:

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:

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