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:
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:
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. |
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:
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. |
Payout to designated bank account can be ordered to:
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:
|
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:
|
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:
|
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):
|
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.
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 dataContent-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:
Number | Expiration date | Payout Status |
---|---|---|
4655413107713609 | 12/2030 | REALIZED |
4302193177728334 | 12/2030 | CANCELLED |
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:
|
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:
|
status.code | One fo the error codes from section Error codes. |
status.codeLiteral | Description of error code. |
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 |