Payouts

To authorize your transaction with OAuth standard you have to retrieve a token, which will be used to create the refund and retrieve its status.

Authorization data can be retrieved from clients panel:

To retrieve authorization data, please go to: My shops -> Enter given shop for details -> POS -> Enter given POS for details.

• client_id: POS id ( OAuth protocol - client_id)
• client_secret: MD5 key (OAuth protocol - client_secret)

User can retrieve authorization token from OAuth service. Retrieving token will allow access to Payout API. Instruction for retrieving token can be found in:

Authorization token retrieve.

Both methods (payout creation and retrieving payout data) are authorized by adding authorization header:

                Authorization: Bearer [access_token]
            

Bearer means OAuth authorization, access_token is a token retrieved in OAuth service response (point 1.2).

The payout is made to the Bank Account defined at the shop or company level.

Payout request specification:

Each request should containt authorization header (point 1.3) and definition of sent data Content-Type application/json.

Payout of given amount:

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

Authentication methods can be found in Signing API Calls section of Rest API documentation.

If you want to create payout for all available funds you can send HTTP request, containing only shopId, to the URL:

http://secure.payu.com/api/v2_1/payouts

Payout for all available funds:

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

Other data will be supplemented from information stored in the PayU system.

Example of the payout with the Variable symbol (additionalVariables):

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

Example of the payout creation response:

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

Response fields description:

Payout to designated bank account can be ordered to:

• national bank account,
• foreign bank account,
• as a postal transfer order (only for Polish shops).

The type of bank account affects the scope of the information that should be provided in the request. The validation of the input data for a payout to a specified bank account is completely different from that for a standard payout.

Creating a payout to the specified bank account is available exclusively for shops meeting the verification criteria. In order to start the verification process, contact us through our contact page.

Bank account payout fields specification:

Payout creation response specification:

Each request should containt authorization header (point 1.3) and definition of sent data Content-Type application/json.

Payout to national bank account:

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

Authentication methods can be found in Signing API Calls section of Rest API documentation.

Payout to foreign bank account with SWIFT code and bank name:

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

This service allows you to quickly payout funds from your shop balance to the payment card indicated in the request. Payouts will be made via Visa Direct (for Visa cards).

Card Payout service is available only for shops that meet verification criteria. To start the verification process, contact your PayU sales representative, or via the contact form.

The card to which the funds are supposed to be transferred should be sent to PayU in the form of a card token. Token can be obtained from PayU after card is tokenised by the cardholder.

Its also possible to send card data in text form (only for entities approved to process card data on their side).

The validation of the input data scope for a Card Payout is completely different from that for a standard Payout.

Response structure was described in point 2.2.

Each request should containt authorization header (point 1.3) and definition of sent data Content-Type application/json.

Recommended integration method is to send (in the request) card token which represents the payment card, to which payout will be made.

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

            

The card token for the payout may be the same as the one previously used to make the payment, or it may be created specifically for this purpose. In order to obtain a new token, the cardholder must be guided through the tokenisation process with the type=MULTI parameter, which will allow them to save the card, make a payment with it and obtain a multiuse token which can be used to perform a payout from the shop balance.

Due to security requirements, it is necessary to confirm the identity of the cardholder. The card token to which the payout is to be ordered must be verified beforehand, for example in a payment process with strong authentication.

In order to guarantee strong authentication of the cardholder you should include following code snippet in the request while creating REST API order:

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

Detailed description of all REST API parameters can be found in JSON parameters.

Tokens with strong authentication (response ECI code with value of 5) can be used to authenticate payouts. Level of authentication is indicated by the value of cardEciCode parameter, and can be accessed after retrieving transaction data.

In case when payment card do not support strong authentication or for some other reason it can't be performed, merchant is obliged to verify the payment card in other way, for example by charging the card for a random amount and asking the customer to provide this value. In order to activate such a solution, please contact your PayU sales representative, or via the contact form.

This integration type is available only for entities meeting PCI DSS requirements and are aproved to process card data on their side. Also this integration requires additional configuration. Therefore, please contact your sales representative in PayU before the integration.

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

            

We prepared two card numbers for testing purposes:

To retrieve payout data you should send HTTP GET request to URL structured as:

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

payoutId is public payout identifier returned in response to create payout request.

Warning: retrieving payout data is limited to the last 2 weeks.

Retrieving payout data request specification:

Each request should containt authorization header (point 1.3) and definition of sent data Content-Type application/json.

Request example:

                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"
            

Response example:

                {
                  "payout": {
                    "payoutId": "133bfe5f400e4b2c8da44abfdf753d79",
                    "amount": "1100",
                    "description": "Billing: 169602484",
                    "status": "PENDING"
                  },
                  "status": {
                    "statusCode": "SUCCESS"
                  }
                }                
            

Fields description:

Example of error response (incorrect payoutId in payout request):

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

Specification of status section in response:

Error codes are presented in response, in status section.