Payouts

1 Authorization

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.

1.1 Where to find data needed for authorization?

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)

1.2 Retrieving OAuth token

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.

apiary

1.3 Payout API request authorization header

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).

2 Payout Creation

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

Payout request specification:

Field Required Comment
payout.extPayoutId no External Payout Identifier, given by the merchant. Merchant can create only one payout with given extPayoutId within one shop.
payout.amount no Payout amount in smallest unit of given currency (e.g. 'grosz', 'cent', etc.). If specified, payout for given amount will be requested from shop balance - only if shop balance allows it.
payout.description no Payout description.
payout.additionalVariables no Allows sending additional information to the system (Variable Symbol). This parameter should be in VS=888111 format. Data from this field is send only to the supporting banks. This solution is dedicated only for Czech market.
shopId yes Shop identifier from which the payout will be made.

2.1 Examples of payout request

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

2.2 Response example

Example of the payout creation response:

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

Response fields description:

Field Comment
payout.payoutId Public Payout Identifier, which should be used when retrieving payout status (Downloading payout data section).
payout.extCustomerId User identifier (optional field; will be returned if provided in request).
payout.status Current payout status.
status.statusCode In status section it should be read as a request status.

apiary

3 Bank account payout creation

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:

Field Required Comment
payout.extPayoutId no External Payout Identifier, given by the merchant. Merchant can create only one payout with given extPayoutId within one shop.
payout.amount yes Payout amount.
payout.description no Payout description.
payout.foreign By default flag is not set. Flag indicating whether payout was was made to a foreign account.
payout.postalOrder By default flag is not set. Flag indicating whether the payout was in the form of a postal transfer order. Setting this flag forces the completion of address fields and removes the requirement for the account number field.
account.accountNumber Optional when postalOrder flag is set, otherwise required. Bank account number. Required account formats for foreign transfers:
  • Polish account: NRB, IBAN.
  • Czech account: IBAN, internal in ([0-9]{1,6}[ -])?[0-9]{2,10}[ /][0-9]{4}) format.
As for now, there is no format restrictions for national bank transfers.
account.bankName Required in case of payouts to foreing bank account (foreign flag is set), otherwise optional. Name of the bank.
account.swiftCode Required in case of payouts to foreing bank account (foreign flag is set), otherwise optional. Bank's SWIFT code.
customerAddress.street Field required for:
  • payouts for foreign bank accounts (foreign flag is set);
  • payouts as postal transfer orders (postalOrder flag is set).
Payout recipient's address details.
customerAddress.postalCode Required for postal transfer orders (postalOrder flag is set), otherwise optional. Payout recipient's address details.
customerAddress.city Field required for:
  • payouts for foreign bank accounts (foreign flag is set);
  • payouts as postal transfer orders (postalOrder flag is set).
Payout recipient's address details.
customerAddress.countryCode Required in case of payouts to foreing bank account (foreign flag is set), otherwise optional. Payout recipient's address details. Two-letter country code compliant with ISO-3166.
customerAddress.name yes Payout recipient's name.
bankAddress.street Required in case of payouts to foreing bank account (foreign flag is set), otherwise optional. Bank address information.
bankAddress.postalCode Required in case of payouts to foreing bank account (foreign flag is set), otherwise optional. Bank address information.
bankAddress.city Required in case of payouts to foreing bank account (foreign flag is set), otherwise optional. Bank address information.
bankAddress.countryCode Required in case of payouts to foreing bank account (foreign flag is set), otherwise optional. Bank address information. Two-letter country code compliant with ISO-3166.

Payout creation response specification:

Field Comment
payout.payoutId Unique Payout Identifier given by PayU.
payout.extPayoutId External Payout Identifier - echo of the data sent in the request.
payout.status Payout status (value domain):
  • PENDING - waiting for processing,
  • WAITING - processing,
  • CANCELLED - cancelled,
  • REALIZED - completed.

3.1 Examples

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

4 Creating Card Payout

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).

4.1 Request structure

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

Field Required Comment
shopId yes Shop identifier from which you want to payout funds.
payout.extPayoutId no External Payout Identifier, given by the merchant. Merchant can create only one payout with given extPayoutId within one shop.
payout.amount yes Payout amount.
payout.description no Payout description.
customerAddress.name yes Name and surname / Payout recipient's name.
cardToken.value yes in case of payout to card token Card token.
card.number yes in case of payout to card number Card number.
card.expirationMonth yes in case of payout to card number Expiration date - month.
card.expirationYear yes in case of payout to card number Expiration date - year.

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.

4.2 Card token payout

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.

4.3 Payout to card number

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

            

4.4 Testing card payouts

We prepared two card numbers for testing purposes:

Number Expiration date Payout Status
4655413107713609 12/2030 REALIZED
4302193177728334 12/2030 CANCELLED

5 Retrieving payout data

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:

Field Comment
payout.payoutId Unique Payout Identifier given by PayU.
payout.extPayoutId External Payout Identifier - echo of the data sent in the request.
payout.amount Payout amount.
payout.description Payout description.
payout.status Payout status:
  • PENDING - waiting for processing,
  • WAITING - processing,
  • CANCELLED - cancelled,
  • REALIZED - completed.
payout.fast Flag indicating whether a payment card payout will be processed in fast mode.

Optional field. If this flag is missing, it means that information on the payment card payout processing mode by payment card issuer is not available.

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:

Field Comment
payout.payoutId Public payout identifier.
payout.amount Payout amount in 'cents'.
payout.description Generated payout title.
payout.status Current payout status.
status.statusCode Request status.

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:

Field Comment
status.statusCode Request status.
status.severity Severity of the error:
  • INFO
  • WARNING
  • ERROR
status.code One fo the error codes from section Error codes.
status.codeLiteral Description of error code.

6 Error codes

Error codes are presented in response, in status section.

Error code Status Error code description HTTP Status
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
8362 ERROR_VALUE_MISSING PAYOUT_TOKEN_MISSING 400 Bad Request
8363 ERROR_VALUE_INVALID PAYOUT_TOKEN_WITH_SHARING
_AGREEMENT
400 Bad Request
8364 BUSINESS_ERROR PAYOUT_TOKEN_INSUFFICIENT
_AUTHENTICATION_LEVEL
403 Forbidden