Payouts

1 Authentication

The client authenticates by OAuth standard by downloading a token, which is used to create the payout and download its status.

1.1 Where to find authentication credentials?

Authentication data can be found in client panel.

Note: you need to have POS in the REST API (Checkout) type.

Data is visible under: My Shops -> Shop details -> Point of sales -> Details:

  • client_id: POS ID (OAuth protocol - client_id)
  • client_secret: Key MD5 (OAuth protocol - client_secret)

1.2 Downloading the authentication token

User can get authentication token using OAuth standard. Token is necessary to have access to Payout API. See:

Downloading the authorization token.

apiary

1.3 Authentication header in Payout API request

Both available methods (creating a payout and downloading payout data) are authorized by adding the header:

                Authentication: Bearer [access_token]
            

Bearer means OAuth authentication, access_token is token received in response to the OAuth service, see section 1.2.

2 Creating a payout

The payment is made to the bank account defined at the level of the Shop or the Company.

Specification of message which create payout:

Field Required Comment
payout/extPayoutId no External payout identifier assigned by the customer. The customer can order only one payout per specified external ID. A unique extPayoutId is required for payouts within the same store
payout/amount no If given, the Store balance will be charged with a payout for a given Payout amount (only if the Store balace allows it).
payout/description no Payout description
shopId yes Identification of the Store from which the funds will be transfered

2.1 Examples

Every request should contain the authorization header shown in section 1.3 and the definition of the type of transmitted data Content-Type application/json.

Payout of the 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  
                    }
                }'
            
Field description:
  • shopId is a shop identifier in PayU from which the payment is made
  • amount is the payment amount in pennies
In particular, if the store wants to make a full payout of all available funds, is sufficient to send an HTTP request containing only the shopId to the following URL:

Authentication methods are described in: Signing API calls parameters.

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

Payout of the full 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"
                 }'
            
Field description:
  • shopId is a shop identifier in PayU from which the payment is made.

The remaining data will be supplemented with information stored in PayU.

Example of response:

                {
                  "payout": {
                    "payoutId": "133bfe5f400e4b2c8da44abfdf753d79",
                    "extCustomerId": "123123",
                    "status": "PENDING"
                  },
                  "status": {
                    "statusCode": "SUCCESS"
                  }
                }
                
            
Field description:
  • payoutId is a public identifier of payment, which must be used in payment status queries (see section 4)
  • extCustomerId is a user identifier (an optional field, it is returned if provided in the request)
  • status indicates the current status of the payout
  • statusCode in the status section indicates the status of the request

apiary

3 Creating a payout to a given bank account

A payment to a designated bank account can be ordered at:

  • a domestic bank account
  • a foreign bank account
  • as a mail transfer order (only for Polish stores),

which affects the scope of information transferred in the input message. Validation of the input range for payouts to a given bank account is completely different than the standard Payout.

Warning! The creation of a payout that indicate the bank account is available only for the stores that meet the verification criteria. Contact PayU support to start the verification process via email: handlowy@payu.pl or phone: +48 61 630 60 05.

Specification of the message creating the payout to the designated bank account:

Field Required Comment
payout/extPayoutId no External payout identifier assigned by the customer. The customer can order only one payout per specified external ID. A unique extPayoutId is required for payouts within the same store
payout/amount yes Payout amount
payout/description no Payout description
payout/foreign The flag is not set by default Flag defining foreign payouts
payout/postalOrder The flag is not set by default Flag defining if the payout is a postal order. Setting this flag forces filling in of address fields and removes the obligation to fill in account number field
account/accountNumber Optional field for the postalOrder flag set. In other cases it is not required Bank account numer field. Required formats for foreign transfers:
  • Polish accounts: NRB, IBAN
  • Czech accounts: IBAN, internal in form of: ([0-9]{1,6}[ -])?[0-9]{2,10}[ /][0-9]{4})
For domestic transfers there are currently no restrictions as to formatting
account/bankName Field required for payouts to foreign accounts (foreign flag set). In other cases it is not required Bank name
account/swiftCode Field required for payouts to foreign accounts (foreign flag set). In other cases it is not required Bank SWIFT code
customerAddress/street Field required for:
  • payouts to foreign accounts (foreign flag set)
  • postal order transfers (postalOrder flag set)
Address data of the payout recipient
customerAddress/postalCode Field required for postal order transfers (postalOrder flag set). In other cases it is not required Address data of the payout recipient
customerAddress/city Field required for:
  • payouts to foreign accounts (foreign flag set)
  • postal order transfers (postalOrder flag set)
Address data of the payout recipient
customerAddress/countryCode Field required for payouts to foreign accounts (foreign flag set). In other cases it is not required Address data of the payout recipient
customerAddress/name yes Address data of the payout recipient
bankAddress/street Field required for payouts to foreign accounts (foreign flag set). In other cases it is not required Bank address data
bankAddress/postalCode Optional field. If known, it should be given for payouts to foreign accounts (foreign flag set) Bank address data
bankAddress/city Field required for payouts to foreign accounts (foreign flag set). In other cases it is not required Bank address data
bankAddress/countryCode Field required for payouts to foreign accounts (foreign flag set). In other cases it is not required Bank address data

Specification of respone message:

Field Comment
payout/payoutId Unique payout ID given by PayU
payout/extPayoutId External Payout Identification – echo of information sent in the input message
payout/status Payout status Value domain:
  • PENDING - waiting for completion,
  • WAITING - completion in progress,
  • CANCELLED - payout cancelled,
  • REALIZED - completed.

3.1 Examples

Every request should contain the authorization header shown in section 1.3 and the definition of the type of transmitted data Content-Type application/json.

Payout to a domestic 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 are described in: Signing API calls parameters.

Payout to a foreign bank account with the use of 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 Downloading payout data

To get the payout data please send an HTTP GET request to the URL constructed in the following way:

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

payoutId is a public payout identifier returned in response to the request for the payout creation.

Note: payout data retrieve is limited to last 2 weeks.

Specification of the message retrieving payout data:

Field Comment
payout/payoutId Unique patout identificator given by PayU
payout/extPayoutId External payout identificator – echo of information sent by the Store during the creation of the payout
payout/amount Payout amount
payout/description Payout description
payout/status Payout statuses:
  • PENDING - waiting for completion,
  • WAITING - completion in progress,
  • CANCELLED - payout cancelled,
  • REALIZED - completed.

Every request should contain the authorization header shown in section 1.3 and the definition of the type of transmitted 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"
                  }
                }                
            
Field description:
  • payoutId unique payout ID given by PayU
  • amount is the payment amount in pennies
  • description payout description
  • status payout status
  • statusCode see table in the end of section 4

Example of response on request with wrong data:

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

Specification of the status section of the response message:

Field Comment
status/statusCode Request progress status
status/severity Error level:
  • INFO
  • WARNING
  • ERROR
status/code See section 5
status/codeLiteral Error code description

5 Error codes

Error codes in message processing are sent in response messages in the status section.

Error code Status 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_PAYOUT_AMOUNT 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