PayU GPO Europe REST API (2.1.0)

Download OpenAPI specification:Download

Overview

This reference is designed to assist you in effectively utilizing the PayU REST API to enhance your online payment capabilities. Whether you're running an e-commerce store or developing applications that require secure and seamless payment processing, our API offers a range of features to meet your needs.

Our API offers a comprehensive set of endpoints to empower you with full control over your payment processes. With these endpoints, you can seamlessly create, capture, cancel, and retrieve orders, conduct payouts, and access essential reports.

For more details on the integration, please refer to the official PayU documentation. It provides comprehensive explanations, code samples, and best practices for seamless integration of the PayU API into your applications.

Testing

Production Environment

For a basic integration, including only a redirection to PayU hosted payment page, it is perfectly enough to use the public test point of sale. However, if you would like to test a full set of endpoints, including e.g. refunds, consider registering for a sandbox account.

Public Test POS (point of sale)

Key name	Value
POS ID (pos_id)	145227
OAuth protocol - client_id	145227
Second key (MD5)	13a980d4f851f3d9a1cfc792fb1f5e50
OAuth protocol - client_secret	12f071174cb7eb79d4aac5bc2f07563f

Sandbox Environment

Sandbox is an almost identical copy of PayU production system. It can be used for integration and testing purposes.

Public Test POS (Point of Sale)

Although it is best to create your own account to later be able to configure it as needed, you may also use a public sandbox test POS without registering:

Key name	Value
POS ID (pos_id)	300746
OAuth protocol - client_id	300746
Second key (MD5)	b6ca15b0d1020e8094d9b5f8d163db54
OAuth protocol - client_secret	2ee86a66e5d97e3fadc400c9f19b065d

The availability of the sandbox environment can be checked on the Status page.

Testing Card Payments

In order to test card payments on sandbox, please use credentials displayed on the Sandbox documentation page.

Authorize

Authentication involves generating an OAuth token, which is used for further communication with PayU servers. To create a standard OAuth token, you will need client_id and client_secret keys, which can be found in your merchant panel, in the POS.

Create OAuth Token

Each payment should be authorized in one of three available modes:

client_credentials - used for standard integration,
trusted_merchant - used for authentication of requests made for logged-in shop/application users with fixed extCustomerId,
partner - special type of a token meant for creating entities (e.g. Shop, POS, URL) within partner firm.

Generated access token is valid for 43199 seconds.

Request Body schema: application/x-www-form-urlencoded

grant_type required	string Authorization mode client_credentials
client_id required	string Merchant's POS identifier in PayU's system. Can be found in PayU's merchant panel
client_secret required	string Merchant's secret key. Can be found in PayU's merchant panel

Responses

Response samples

200
400
401

Content type

application/json

{"access_token": "7eb55bcf-6593-4040-afac-252ee1f78e20",
"token_type": "bearer",
"refresh_token": "120c200e-32b3-497f-b267-07b30cc24052",
"expires_in": 43199,
"grant_type": "client_credentials"
}

Payment Methods

Retrieving payment methods allows you to remove the threat of presenting a disabled payment method with white-label integration. It also gives you the ability to retrieve stored tokens and customer card data.

Retrieve All Available Payment Methods.

Authorizations:

Bearer

query Parameters

lang	string Examples: lang=pl - lang parameter value example Language code, ISO-639-1 compliant, determins language of description in `name` field

header Parameters

Content-Type required	string Example: application/json Content type
Authorization required	string Example: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd Auth token

Responses

Response samples

200
401

Content type

application/json

{"blikTokens": [{"value": "SIMULATE_ALIAS_AMBIGUITY-5690871207003",
"type": "UID",
"brandImageUrl": "https://static.payu.com/images/mobile/logos/pbl_blik.png",
"bankApplicationReferences": [{"key": 11111,
"label": "BLIK label"
}
]
}
],
"cardTokens": [{"value": "TOKC_XATB7DF8ACXYTVQIPLWTVPFRKQE",
"brandImageUrl": "https://static.payu.com/images/mobile/visa.png",
"preferred": true,
"status": "ACTIVE",
"cardExpirationYear": 2026,
"cardExpirationMonth": 7,
"cardNumberMasked": "411111******1111",
"cardScheme": "VS",
"cardBrand": "VISA"
}
],
"pexTokens": [{"accountNumber": "5311...7744",
"payType": "mtex",
"value": "TOKE_XPJ4UKJGHVRPMQPGB6X1JJQCUSS",
"name": "account name set by the user",
"brandImageUrl": "https://static.payu.com/images/mobile/logos/pex_mbank.png",
"preferred": true,
"status": "ACTIVE"
}
],
"payByLinks": [{"value": "sgb",
"brandImageUrl": "https://static.payu.com/images/mobile/logos/pbl_sgb_off.png",
"name": "SGB Bank",
"status": "DISABLED",
"minAmount": 50,
"maxAmount": 99999999
}
],
"status": {"statusCode": "SUCCESS"
}
}

Order

Order is the basic payment request for the standard integration with PayU.

Create an Order

Create a new order request.

Authorizations:

Bearer

header Parameters

Content-Type required	string Example: application/json Content type
Authorization required	string Example: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd Auth token

Request Body schema: application/json

continueUrl	string <= 1024 characters Address for redirecting the customer after payment is commenced.
notifyUrl	string <= 1024 characters The address for sending notifications
customerIp required	string Payer's IP address. Value is accepted in following formats: IPv4 - address represented in the dotted decimal format of 4 sets of decimal numbers separated by dots. The decimal number in each and every set is in the range 0 - 255. Example: 1.12.123.255. IPv6 - address represented as eight groups of four hexadecimal digits, each group representing 16 bits (two octets). The groups are separated by colons (:). Example: 2011:0db8:85a3:0101:0101:8a2e:0370:7334.
merchantPosId required	string Point of sale ID.
description required	string <= 4000 characters Description of the order.
additionalDescription	string <= 1024 characters Additional description of the order.
visibleDescription	string <= 80 characters Order/Payment description visible for Buyer on the PayU payment page.
statementDescription	string <= 22 characters Payment recipient name followed by payment description (order ID, ticket number etc) visible on card statement. The name should be easy to recognize by the cardholder. If field is not provided, static name configured by PayU will be used.
extOrderId	string <= 1024 characters ID of an order used in merchant system. Order identifier assigned by the merchant. It enables merchants to find a specific order in their system. This value must be unique within a single POS.
currencyCode required	string Currency code compliant with ISO 4217 (e.g EUR).
totalAmount required	string Total price of the order in pennies (e.g. 1000 is 10.00 EUR). Applies also to currencies without subunits (e.g. 1000 is 10 HUF).
validityTime	string Duration for the validity of an order (in seconds), during which time payment must be made. Default value 86400.
cardOnFile	string Enum: "FIRST" "STANDARD_CARDHOLDER" "STANDARD_MERCHANT" Information about party initializing order or a transaction with Buyer consent to save card token. "cardOnFile" parameter cannot be used with "recurring" parameter.
recurring	string Enum: "FIRST" "STANDARD" Marks the order as recurring payment: FIRST - payment initialized by the card owner who agreed to save card for future use in recurring plan. You can expect full authentication (3D Secure and/or CVV). If you want to use multi-use token (TOKC_) later, you have to be confident, that first recurring payment was successful. STANDARD - subsequent recurring payment (user is not present). This transaction has multi use token (TOKC_). You cannot use it if FIRST recurring payment failed. `recurring` parameter cannot be used with `cardOnFile` parameter .
	object (donation) Section containing data of donation added to the order.
	object (buyer) Section containing buyer data.
	Array of objects (shoppingCarts) Array of objects related to transaction identification.
required	Array of objects (products) Section containing data of the ordered products. Section `products` is an array of objects of type product.
	object (payMethods) Section allows to directly invoke payment method. Section `payMethods` is one object of `payMethod` type.
	object (mcpData) Section allows to pass currency conversion details if you chose to use Multi-Currency Pricing.
	object (threeDsAuthentication) Contains optional fields required by 3DS 2 authentication protocol.
	object (credit) Section containing credit data. This information is not required, but it is strongly recommended to include it. Otherwise the buyer will be prompted to provide missing data on provider page when payment by Installments or Pay later.
	object (submerchant)
deviceFingerprint	string <= 255 characters Hashed identifier of the user or its device.

Responses

Request samples

Payload

Content type

application/json

{"continueUrl": "www.example.com/path",
"notifyUrl": "https://your.eshop.com/notify",
"customerIp": "127.0.0.1",
"merchantPosId": "140332",
"description": "string",
"additionalDescription": "string",
"visibleDescription": "string",
"statementDescription": "string",
"extOrderId": "string",
"currencyCode": "EUR",
"totalAmount": "1000",
"validityTime": "100000",
"cardOnFile": "FIRST",
"recurring": "FIRST",
"donation": {"amount": 500,
"organizationId": "string"
},
"buyer": {"extCustomerId": "string",
"email": "email@email.com",
"phone": "+48 225108001",
"firstName": "John",
"lastName": "Doe",
"nin": 123456789,
"language": "pl",
"delivery": {"street": "string",
"postalBox": "string",
"postalCode": "string",
"city": "string",
"state": "30",
"countryCode": "string",
"name": "string",
"recipientName": "string",
"recipientEmail": "string",
"recipientPhone": "string"
}
},
"shoppingCarts": [{"extCustomerId": "ext-customer-1",
"amount": 24950,
"fee": 250,
"shippingMethods": [{"country": "PL",
"price": 250,
"name": "Postal package"
}
],
"products": [{"name": "My product",
"unitPrice": 999,
"quantity": 4,
"virtual": true
}
]
}
],
"products": [{"name": "My product",
"unitPrice": 999,
"quantity": 4,
"virtual": true
}
],
"payMethods": {"payMethod": {"type": "PBL",
"value": "c",
"authorizationCode": "777123",
"authorizationType": "PRE_AUTHORIZATION",
"card": {"number": "5100052384536818",
"expirationMonth": "02",
"expirationYear": "29",
"cvv": "123",
"firstTransactionId": "MCC0111LL1121"
},
"specificData": [{"name": "string",
"value": "string"
}
],
"amount": "string",
"blikData": {"aliasLabelProposal": "string",
"registerTokenValue": "string",
"register": true,
"appKey": "string",
"recommendedAuthLevel": "NO_CONFIRMATION",
"countryCode": "PL"
},
"threeDsData": {"status3Ds": "Y",
"status3DsDescription": "Authentication successful",
"xid": "string",
"dsTransactionId": "3b31b19d-1c06-4ea4-a85a-00af10c66588",
"eciCode": 5,
"cavv": "AAABBBEAUAAAABgICABQAAAAAAA=",
"tavv": "AgAAABBEAUAAAABg8CABQAAQEAAA="
},
"sourcePaymentFlow": "VISA_MOBILE"
}
},
"mcpData": {"mcpCurrency": "EUR",
"mcpAmount": 10000,
"mcpRate": 4.2556,
"mcpFxTableId": 132331,
"mcpPartnerId": "6283a549-8b1a-430d-8a62-eea64327440e"
},
"threeDsAuthentication": {"challengeRequested": "YES",
"exemption": {"value": "LOW_RISK",
"rejectionHandling": "PERFORM_AUTHENTICATION",
"riskScore": "120 - low risk score calculated in Merchants antifraud tool"
},
"browser": {"acceptHeaders": "string",
"requestIP": "127.0.0.1",
"screenWidth": 1920,
"javaEnabled": false,
"timezoneOffset": 1,
"screenHeight": 1280,
"userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36",
"colorDepth": 32,
"language": "pl_PL"
},
"sdk": {"sdkReferenceNumber": "DS_LOA_SDK_ADBV_739485_94783",
"sdkMaxTimeout": 30,
"sdkAppID": "9063b12c-fcde-43c7-b28e-8d0af5520e8a",
"sdkEncData": "9063b12c-fcde-43c7-b28e-8d0af5520e8a",
"sdkTransID": "b60c9879-ac77-4918-a317-7b01c4317053/8Q==.",
"sdkEphemPubKey": {"y": "MRy7wofaw77myc7hZef23hmmEOE",
"x": "MRy7wofaw77myc7hZef23hmmEOE",
"kty": "EC",
"crv": "P-256"
}
},
"merchantRiskIndicator": {"orderType": "LOAN",
"shipIndicator": "TICKETS",
"preOrdered": false,
"preOrderedDate": "2019-03-27T10:57:59.000+01:00",
"deliveryTimeFrame": "OVERNIGHT",
"reordered": false,
"merchantFunds": {"amount": 100,
"currencyCode": "PLN"
}
},
"recurring": {"frequency": "7",
"expiry": "2025-03-27T00:00:00.000Z"
},
"cardholder": {"name": "John Doe",
"accountInformation": {"createDate": "2019-03-27T10:57:59.000+01:00",
"suspiciousActivity": false,
"deliveryAddressFirstUsedDate": "2019-03-27T10:57:59.000+01:00",
"deliveryAdressUsageIndicator": "THIS_TRANSACTION",
"pastOrdersYear": 46,
"pastOrdersDay": 125,
"purchasesLastSixMonths": 12,
"changeDate": "2019-03-27T10:57:59.000+01:00",
"changeIndicator": "THIS_TRANSACTION",
"passwordChanged": "2019-03-27T10:57:59.000+01:00",
"passwordChangeIndicator": "NO_CHANGE",
"nameToRecipientMatch": true,
"addCardAttemptsDay": 3,
"authMethod": "GUEST",
"authDateTime": "2019-03-27T10:57:59.000+01:00",
"cardAddedDate": "2019-03-27T10:57:59.000+01:00",
"cardAddedIndicator": "THIS_TRANSACTION"
},
"billingAddress": {"street": "Test Street",
"postalCode": "01-000",
"city": "Test City",
"state": 30,
"countryCode": "PL"
}
}
},
"credit": {"shoppingCarts": [{"shippingMethod": {"type": "COURIER",
"price": "string",
"address": {"pointId": "Parcel locker POZ29A",
"street": "string",
"streetNo": "string",
"flatNo": "string",
"postalCode": "string",
"city": "string",
"countryCode": "string"
}
},
"products": [{"name": "string",
"unitPrice": "string",
"quantity": "string",
"virtual": true,
"listingDate": "string"
}
],
"extCustomerId": "string"
}
],
"applicant": {"email": "test@test.com",
"phone": 123456789,
"firstName": "Joe",
"lastName": "Doe",
"language": "pl",
"nin": 123456789,
"address": {"street": "Test Street",
"streetNo": 123,
"flatNo": 987,
"postalCode": "01-000",
"city": "Test City",
"countryCode": "PL"
},
"additionalInfo": {"hasSuccessfullyFinishedOrderInShop": "YES"
}
},
"klarnaAttachment": {"content_type": "string",
"body": "string"
}
},
"submerchant": {"id": "string"
},
"deviceFingerprint": "3e9fae0b3e6003a4093358167bc1079e"
}

Response samples

Content type

application/json

{"status": {"statusCode": "string",
"redirectUri": "string",
"orderId": "WZHF5FFDRJ140731GUEST000P01",
"iframeAllowed": true,
"threeDsProtocolVersion": "3DS2",
"extOrderId": "string",
"challengeParameters": {"threeDsServerTransactionId": "0016f22b-f988-4358-b2c6-8917bba22037",
"acsTransID": "d7c1ee99-9478-44a6-b1f2-391e29c6b340",
"acsReferenceNumber": "3DS_LOA_ACS_201_13579",
"acsSignedContent": "c29tZUJhc2U2NGVuY29kZWRTdHJpbmc="
}
}
}

Retrieve an Order

Retrieve the status and details of an order.

Authorizations:

Bearer

path Parameters

orderId

required

string

Example: "WZHF5FFDRJ140731GUEST000P01"

Order ID generated by the PayU system

header Parameters

Content-Type required	string Example: application/json Content type
Authorization required	string Example: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd Auth token

Responses

Response samples

200
400
401
404

Content type

application/json

{"orders": [{"shippingMethod": {"country": "PL",
"price": 2000,
"name": "parcell"
},
"orderId": "VVLR1HXK2S160929GUEST000P01",
"extOrderId": "343242",
"orderCreateDate": "2023-01-03T14:58:17.443+01:00",
"notifyUrl": "http://localhost/OrderNotify/",
"customerIp": "127.0.0.1",
"merchantPosId": "145227",
"description": "New Order",
"additionalDescription": "New Order",
"validityTime": "86400",
"currencyCode": "PLN",
"totalAmount": "3200",
"buyer": {"extCustomerId": "string",
"email": "email@email.com",
"phone": "+48 225108001",
"firstName": "John",
"lastName": "Doe",
"nin": 123456789,
"language": "pl",
"delivery": {"street": "string",
"postalBox": "string",
"postalCode": "string",
"city": "string",
"state": "30",
"countryCode": "string",
"name": "string",
"recipientName": "string",
"recipientEmail": "string",
"recipientPhone": "string"
}
},
"payMethod": {"amount": 20000,
"type": "PBL"
},
"products": [{"name": "My product",
"unitPrice": 999,
"quantity": 4,
"virtual": true
}
],
"shoppingCarts": [{"extCustomerId": "ext-customer-1",
"amount": 24950,
"fee": 250,
"shippingMethods": [{"country": "PL",
"price": 250,
"name": "Postal package"
}
],
"products": [{"name": "My product",
"unitPrice": 999,
"quantity": 4,
"virtual": true
}
]
}
],
"status": "COMPLETED"
}
],
"properties": [{"name": "PAYMENT_ID",
"value": "1234567890"
}
]
}

Cancel an Order

Cancel (reject) orders processed by the PayU system.

Authorizations:

Bearer

path Parameters

orderId

required

string

Example: "WZHF5FFDRJ140731GUEST000P01"

Order ID generated by the PayU system

header Parameters

Content-Type required	string Example: application/json Content type
Authorization required	string Example: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd Auth token

Responses

Response samples

Content type

application/json

{"orderId": "WZHF5FFDRJ140731GUEST000P01",
"extOrderId": "3e5cac39-7e38-4139-8fd6-30adc06a61bd",
"status": {"statusCode": "SUCCESS"
}
}

Capture Authorized Order

Capture whole order and update its status to COMPLETED (ended).

Authorizations:

Bearer

path Parameters

orderId

required

string

Example: "WZHF5FFDRJ140731GUEST000P01"

Order ID generated by the PayU system

header Parameters

Content-Type required	string Example: application/json Content type
Authorization required	string Example: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd Auth token

Request Body schema: application/json

One of

null (Full)

Responses

Request samples

Payload

Content type

application/json

Example

Full

null

Response samples

200
400
401
500

Content type

application/json

{"status": {"statusCode": "SUCCESS",
"statusDesc": "Status was updated"
}
}

(deprecated) Capture Authorized Order

Capture an order and update its status to COMPLETED (ended).

Authorizations:

Bearer

path Parameters

orderId

required

string

Example: "WZHF5FFDRJ140731GUEST000P01"

Order ID generated by the PayU system

header Parameters

Content-Type required	string Example: application/json Content type
Authorization required	string Example: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd Auth token

Request Body schema: application/json

orderId required	string Identifier of the order you want to update.
orderStatus required	string Status of the order after update.

Responses

Request samples

Payload

Content type

application/json

{"orderId": "VVLR1HXK2S160929GUEST000P01",
"orderStatus": "COMPLETED"
}

Response samples

200
400
401
500

Content type

application/json

{"status": {"statusCode": "SUCCESS",
"statusDesc": "Status was updated"
}
}

Retrieve a Transaction

Retrieve the details of transactions created for an order with specified orderId.

Authorizations:

Bearer

path Parameters

orderId

required

string

Example: "WZHF5FFDRJ140731GUEST000P01"

Order ID generated by the PayU system

header Parameters

Content-Type required	string Example: application/json Content type
Authorization required	string Example: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd Auth token

Responses

Response samples

200
400
401
404

Content type

application/json

Example

card

{"transactions": [{"payMethod": {"value": "c"
},
"paymentFlow": "CARD",
"validUntil": "2024-06-20T09:05:44.238+02:00",
"card": {"cardData": {"cardNumberMasked": "543402******4014",
"cardScheme": "MC",
"cardProfile": "CONSUMER",
"cardClassification": "DEBIT",
"cardResponseCode": "000",
"cardResponseCodeDesc": "000 - OK",
"cardEciCode": "2",
"card3DsStatus": "Y",
"card3DsFrictionlessIndicator": "YES",
"card3DsStatusDescription": "MessageVersion=2.1.0,browser flow,3DS method not available,dynamic authentication,no cancel indicator,no status reason",
"cardBinCountry": "PL",
"firstTransactionId": "MCC0111LL1121"
}
},
"resultCode": "AUT_ERROR_NO_AUTHORIZATION"
}
]
}

Shop

Shop is the main entity in the management panel. It is the place where you can manage incoming transactions processed by PayU.

Retrieve Shop Data

Retrieve your PayU shop balance, id, etc.

Authorizations:

Bearer

path Parameters

shopId

required

string

Example: "a1B2C3x"

ShopId value generated by PayU assigned to Shop

header Parameters

Content-Type required	string Example: application/json Content type
Authorization required	string Example: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd Auth token

Responses

Response samples

200
400
401
404

Content type

application/json

{"shopId": "a1B2C3x",
"name": "Test Shop",
"currencyCode": "PLN",
"balance": {"currencyCode": "PLN",
"total": 1234567890,
"available": 987654321
}
}

Refund

The PayU system fully supports refunds for the processed payments, the balance of which is transferred directly to the buyer's account.

Create a Refund

Create new refund - this request is idempotent, so if exactly same data will be provided, response will return data of already previously created refund instead of creating new refund.

Authorizations:

Bearer

path Parameters

orderId

required

string

Example: WZGF5FFDRJ140731GUEST000P01

Order ID generated by the PayU system

header Parameters

Content-Type required	string Example: application/json Content type
Authorization required	string Example: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd Auth token

Request Body schema: application/json

required

object

Contains detailed information about a refund.

description required	string Refund description.
amount	string Amount of the refund. If this is left blank, all funds will be returned to the buyer.
extRefundId	string External refund ID.
currencyCode	string Currency code compliant with ISO 4217.
bankDescription	string Bank operation description.
type	string Value: "REFUND_PAYMENT_STANDARD" Operation type.

Responses

Request samples

Payload

Content type

application/json

{"refund": {"description": "Test refund",
"amount": "10000",
"extRefundId": "3e5cac39-7e38-4139-8fd6-30adc06a61bd",
"currencyCode": "PLN",
"bankDescription": "Bank transfer refund",
"type": "REFUND_PAYMENT_STANDARD"
}
}

Response samples

200
400
401

Content type

application/json

{"orderId": "WZGF5FFDRJ140731GUEST000P01",
"refund": {"refundId": "5000000142",
"description": "Test refund",
"amount": "10000",
"extRefundId": "3e5cac39-7e38-4139-8fd6-30adc06a61bd",
"currencyCode": "PLN",
"bankDescription": "Bank transfer refund",
"creationDateTime": "2020-07-02T09:19:03.896+02:00",
"status": "PENDING",
"statusDatetime": "2020-07-02T09:19:04.013+02:00"
},
"status": {"statusCode": "SUCCESS",
"statusDesc": "Refund queued for processing"
}
}

Retrieve ALL Refunds Data for the Specified Order

Authorizations:

Bearer

path Parameters

orderId

required

string

Example: WZHF5FFDRJ140731GUEST000P01

Order ID generated by the PayU system

header Parameters

Content-Type required	string Example: application/json Content type
Authorization required	string Example: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd Auth token

Responses

Response samples

200
404

Content type

application/json

[{"refundId": "5000000142",
"extRefundId": "hdjJduUEEH2",
"amount": 10000,
"description": "Refund for order <orderId>",
"creationDateTime": "2020-07-02T09:19:03.896+02:00",
"currencyCode": "string",
"statusDatetime": "2020-07-02T09:19:04.016+02:00",
"status": "PENDING"
},
{"refundId": "5000000142",
"extRefundId": "hdjJduUEEH2",
"amount": 10000,
"description": "Refund for order <orderId>",
"creationDateTime": "2020-07-02T09:19:03.896+02:00",
"currencyCode": "string",
"statusDatetime": "2020-07-02T09:19:04.016+02:00",
"status": "string",
"statusError": {"code": "string",
"description": "string"
}
}
]

Retrieve Specific Refund Data

Authorizations:

Bearer

path Parameters

orderId required	string Example: WZHF5FFDRJ140731GUEST000P01 Order ID generated by the PayU system
refundId required	string Example: 5000000142 Refund identifier in the PayU system.

header Parameters

Content-Type required	string Example: application/json Content type
Authorization required	string Example: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd Auth token

Responses

Response samples

200
401
404

Content type

application/json

Example

FINALIZED

{"refundId": "5000000142",
"extRefundId": "hdjJduUEEH2",
"amount": 10000,
"description": "Refund for order <orderId>",
"creationDateTime": "2020-07-02T09:19:03.896+02:00",
"currencyCode": "string",
"statusDatetime": "2020-07-02T09:19:04.016+02:00",
"status": "FINALIZED"
}

Payout

To widthraw funds from the PayU account you need to create a payout.

Create a Payout

Create a payout with the selected destination of funds.

Authorizations:

Bearer

header Parameters

Content-Type required	string Example: application/json Content type
Authorization required	string Example: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd Auth token

Request Body schema: application/json

Parameters for creating payouts.

One of

shopId required	string Public identifier for the shop within PayU, under which payout will be executed.
	object Payout information.

Responses

Request samples

Payload

Content type

application/json

Example

Standard Payout

{"shopId": "1a2B3Cx",
"payout": {"description": "string",
"extPayoutId": "string",
"amount": 987654321,
"additionalVariables": "VS=888111"
}
}

Response samples

201
400
401
403
404

Content type

application/json

{"payout": {"payoutId": "string",
"extPayoutId": "string",
"extCustomerId": "string",
"amount": 10000,
"currencyCode": "PLN",
"status": "PENDING",
"fxData": {"currencyCode": "EUR",
"amount": 2500,
"rate": 0.25,
"partnerId": "string",
"tableId": "string"
}
},
"status": {"statusCode": "string"
}
}

Retrieve a Payout

Retrieve data of a specified payout.

Authorizations:

Bearer

path Parameters

payoutId

required

string

Example: "fefa25e021b14970bfac9ebfb20761dc"

Payout ID generated by the PayU system

header Parameters

Content-Type required	string Example: application/json Content type
Authorization required	string Example: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd Auth token

Responses

Response samples

200
400
401
403
404

Content type

application/json

{"payout": {"payoutId": "string",
"extPayoutId": "string",
"amount": 10000,
"description": "string",
"status": "PENDING",
"fxData": {"currencyCode": "string",
"amount": 2500,
"rate": 0.25,
"partnerId": "string",
"tableId": "string"
}
},
"status": {"statusCode": "string"
}
}

Token

With tokenization, we are confident that your customers' card data is protected from third parties.

Delete a Token

In case the customer terminates the user account in your shop or chooses to remove the stored card from the user account, you need to delete the token.

Authorizations:

Bearer

path Parameters

token

required

string

Example: "TOKC_XATB7DF8ACXYTVQIPLWTVPFRKQE"

header Parameters

Content-Type required	string Example: application/json Content type
Authorization required	string Example: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd Auth token with `grant_type=trusted_merchant`.

Responses

Response samples

400
401

Content type

application/json

{"status": {"statusCode": "string",
"severity": "string",
"code": "string",
"codeLiteral": "string",
"statusDesc": "string"
}
}

Multi-Currency Pricing

We can convert your customers' payments to the currency of your shop set up with PayU.

Retrieve Rate Table

Retrieve current table with the conversion rates for the currencies.

Authorizations:

Bearer

path Parameters

mcpPartnerId

required

string

Example: "6283a549-8b1a-430d-8a62-eea64327440e"

header Parameters

Content-Type required	string Example: application/json Content type
Authorization required	string Example: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd Auth token

Responses

Response samples

200
400
401
404

Content type

application/json

{"id": 802438,
"validTo": "2023-01-02T20:18:00Z",
"currencyPairs": [{"baseCurrency": "PLN",
"exchangeRate": 0.23753,
"termCurrency": "USD"
}
]
}

FX Reference

According to regulations in the European Union countries, payment service providers and parties providing currency conversion services at the point of sale are obliged to express the total currency conversion charges as a percentage mark-up over the latest available euro foreign exchange reference rates issued by the European Central Bank (ECB).

Retrieve Reference Rates

You can retrieve a reference rate table that is updated daily. This table encompasses rates released by the European Central Bank (ECB) against EUR, as well as additional rates that are triangulated using EUR (e.g., PLN/USD, CZK/GBP, etc.).

Authorizations:

Bearer

query Parameters

termCurrency

required

string

Examples:

termCurrency=PLN - Currency code compliant with ISO 4217

header Parameters

Content-Type required	string Example: application/json Content type
Authorization required	string Example: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd Auth token

Responses

Response samples

200
401

Content type

application/json

{"effectiveDate": "2023-01-03",
"fxRates": [{"baseCurrency": "string",
"termCurrency": "string",
"midRate": 3.141
}
]
}

Marketplace Seller

In PayU, as a marketplace, you have the capability to manage various aspects of your submerchants.

Retrieve Seller Status

You can check the verification status of your submerchants.

Authorizations:

Bearer

path Parameters

extCustomerId

required

string

Submerchant identifier.

query Parameters

currencyCode

required

string

Example: currencyCode=PLN

Currency code according to ISO-4217.

header Parameters

Content-Type required	string Example: application/json Content type
Authorization required	string Example: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd Auth token

Responses

Response samples

200
401

Content type

application/json

{"customVerificationStatus": "Verified",
"name": "string",
"taxId": "string",
"regon": "string"
}

Retrieve Seller Balance

Authorizations:

Bearer

path Parameters

extCustomerId

required

string

Submerchant identifier.

query Parameters

currencyCode

required

string

Example: currencyCode=PLN

Currency code according to ISO-4217.

header Parameters

Content-Type required	string Example: application/json Content type
Authorization required	string Example: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd Auth token

Responses

Response samples

200
401

Content type

application/json

{"balance": {"availableAmount": "string",
"totalAmount": "string"
},
"status": {"statusCode": "string"
}
}

Retrieve Seller Operation History

Authorizations:

Bearer

path Parameters

extCustomerId

required

string

Submerchant identifier.

query Parameters

currencyCode	string Currency code according to ISO-4217. You can enter multiple values. Subsequent entries should be separated by a comma.
type	string Enum: "PAYMENT_SENT" "PAYMENT_RECEIVED" "PAYOUT" "REFUND_SENT" "REFUND_RECEIVED" "RETURN" "ADMIN_TRANSFER_SENT" "ADMIN_TRANSFER_RECEIVED" "FEE_TRANSFER_SENT" "FEE_TRANSFER_RECEIVED" Operation type. You can enter multiple values. Subsequent entries should be separated by a comma.
eventDateFrom required	string <2019-01-30T20%3A59%3A00%2B02%3A00> Start of the search range for "eventDate". Date must be url encoded.
eventDateTo required	string <2019-04-30T20%3A59%3A00%2B02%3A00> End of the search range for "eventDate". Date must be url encoded.
creationDateFrom	string <2019-04-30T20%3A59%3A00%2B02%3A00> Start of the search range for "creationDate". Date must be url encoded.
creationDateTo	string <2019-04-30T20%3A59%3A00%2B02%3A00> End of the search range for "creationDate". Date must be url encoded.
limit	string Number of records per page.
offset	string Page number (indexing from 0).
sortBy	string Enum: "eventDate" "creationDate" "type" "currencyCode" Examples: sortBy=+eventDate - sorting ascending by eventDate. sortBy=-eventDate - sorting descending by eventDate. Sorting field. Additional sign "+" or "-" before field name defines sorting order. Default is ascending.

header Parameters

Content-Type required	string Example: application/json Content type
Authorization required	string Example: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd Auth token

Responses

Response samples

200
401

Content type

application/json

Example

PAYMENT_RECEIVED

{"operations": [{"type": "PAYMENT_RECEIVED",
"amount": "string",
"currencyCode": "PLN",
"description": "string",
"status": "COMPLETED",
"creationDate": "string",
"eventDate": "string",
"details": {"orderId": "string",
"extOrderId": "string",
"feeAmount": "string",
"counterparties": {"extCustomerId": "string",
"name": "string",
"email": "string",
"products": [{"name": "string",
"unitPrice": "string",
"quantity": "string"
}
]
}
},
"funds": [{ }
]
}
],
"pageResponse": {"records": "string",
"size": "string",
"pageCount": "string"
}
}

Transfer Funds from Seller to Marketplace Balance

Authorizations:

Bearer

path Parameters

extCustomerId

required

string

Submerchant identifier.

header Parameters

Content-Type required	string Example: application/json Content type
Authorization required	string Example: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd Auth token

Request Body schema: application/json

amount	number Transfer amount.
currencyCode	string Currency code according to ISO-4217.
description	string Description of the operation.
extTransferId	string Unique transfer identifier for given marketplace.

Responses

Request samples

Payload

Content type

application/json

{"amount": 0,
"currencyCode": "PLN",
"description": "string",
"extTransferId": "string"
}

Response samples

200
401

Content type

application/json

{"extCustomerId": "string",
"extTransferId": "string",
"status": {"statusCode": "SUCCESS"
}
}

Transfer Funds from Marketplace to Seller Balance

Authorizations:

Bearer

path Parameters

extCustomerId

required

string

Unique submerchant identifier.

header Parameters

Content-Type required	string Example: application/json Content type
Authorization required	string Example: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd Auth token

Request Body schema: application/json

amount	number Transfer amount.
currencyCode	string Currency code according to ISO-4217.
description	string Description of the operation.
extTransferId	string Unique transfer identifier for given marketplace.

Responses

Request samples

Payload

Content type

application/json

{"amount": 0,
"currencyCode": "PLN",
"description": "string",
"extTransferId": "string"
}

Response samples

200
401

Content type

application/json

{"extCustomerId": "string",
"extTransferId": "string",
"status": {"statusCode": "SUCCESS"
}
}

Marketplace Verification

PayU is required by the Anti-Money Laundering Act to verify customers in this context. For this purpose, we provide a collection of endpoints to make it easier for you to verify sellers.

Retrieve Verification Advice

Verify, on the basis of a Personal Identification Number or NIP number, whether a given individual/company has already been registered in the PayU system.

Authorizations:

Bearer

query Parameters

companyTaxId required	string Company tax id of a entity. Required if you want to check a status of a company.
pesonalIdentificationNumber required	string Personal identification number of individual. Required if you want to check a status of a private person.

header Parameters

Content-Type required	string Example: application/json Content type
Authorization required	string Example: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd Auth token

Responses

Response samples

200
400
404

Content type

application/json

{"advice": "FULL_ONBOARDING_REQUIRED"
}

Retrieve Marketplace Verification Status

Retrieve the status of the verification with the specific Id.

Authorizations:

Bearer

query Parameters

id

required

string

Example: id="aZl6Ja"

Value of the query id parameter is the same as the verificationId.

header Parameters

Content-Type required	string Example: application/json Content type
Authorization required	string Example: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd Auth token

Responses

Response samples

200
404

Content type

application/json

{"verificationId": "5002500000BVmycAAD",
"verificationType": "FULL",
"verificationTransferStatus": "null",
"processType": "OCCASIONAL",
"status": "REJECTED",
"sellerId": "123456test12",
"note": null,
"errors": [{"content": {"itemType": "SELLER_DOCUMENT",
"itemProperties": {"documentType": "PEP_STATEMENT",
"documentId": "2",
"associateId": null
}
},
"code": "006"
}
],
"updateDate": "2020-04-03T09:14:06.000Z",
"createDate": "2020-04-03T06:36:15.000Z"
}

Create Marketplace Verification

Initialize the verification process of the seller.

Authorizations:

Bearer

header Parameters

Content-Type required	string Example: application/json Content type
Authorization required	string Example: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd Auth token

Request Body schema: application/json

sellerId required	string <= 50 characters Unique id of seller (submerchant) given by marketplace side. This id must be constant for every verification concerning the same seller (submerchant).
type	string Enum: "PAYOUT_ACCOUNT_DATA" "FULL" "UPDATE" "REVERIFICATION" "PERSONAL_ID_TAX_ID_CHANGE" "CONVERSION" Verification type. Possible values descriptions: PAYOUT_ACCOUNT_DATA- initialized by marketplace side. The verification with this type should contain the data of payout account and seller (submerchant). If this verification initializes seller in PayU then seller data are required. If it is just account update, then only account data are required. FULL - verification which requires providing by seller all data for AML4 and payouts, typically initialized by marketplace side. UPDATE - verification which requires providing by seller all data for AML4 and payouts, typically initialized by marketplace side. REVERIFICATION - verification which requires providing by seller all data for AML4 and payouts, typically initialized by marketplace side. PERSONAL_ID_TAX_ID_CHANGE- initialized by marketplace side. This allows to change PERSONAL_ID for private person or TAX_IDs for legal entity. Once the KYC verification process begins, the current account and payouts are blocked until verification is completed. If the process is interrupted (e.g. the company is unable to verify itself), PayU restores the old merchant account, thus unlocking the payouts on it. CONVERSION- initialized by marketplace side. This allows to change PERSONAL_ID for private person or TAX_IDs for legal entity. Once the KYC verification process begins, the current account and payouts are blocked until verification is completed. If the process is interrupted (e.g. the company is unable to verify itself), PayU restores the old merchant account, thus unlocking the payouts on it.
overridePayouts	boolean

Responses

Request samples

Payload

Content type

application/json

{"sellerId": "string",
"type": "PAYOUT_ACCOUNT_DATA",
"overridePayouts": true
}

Response samples

200
400
409

Content type

application/json

{"verificationId": "aZl6Ja",
"status": "WAITING_FOR_DATA",
"sellerId": "seller_27"
}

Add Seller's Data

This method allows to send data of the seller (submerchant).

Authorizations:

Bearer

header Parameters

Content-Type required	string Example: application/json Content type
Authorization required	string Example: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd Auth token

Request Body schema: application/json

One of

verificationId required	string <= 18 characters Unique id of the verification provided by PayU.
sellerId required	string <= 50 characters Unique id of seller (submerchant) given by marketplace side. This id must be constant for every verification concerning the same (submerchant).
email required	string [ 5 .. 80 ] characters Contact email.
phone	string <= 40 characters Contact phone.
taxId required	string <no spaces, eg. 1122334455> <= 60 characters Tax id.
companyName required	string <= 80 characters Name of the company.
legalForm required	string Enum: "AGENCY_OF_FOREIGN_COMPANY" "ASSOCIATION" "CHURCH_LEGAL_PERSON" "CIVIL_LAW_PARTNERSHIP" "COOPERATIVE" "EDUCATIONAL_INSTITUTION" "FOUNDATION" "GENERAL_PARTNERSHIP" "JOINT_STOCK_COMPANY" "LIMITED_JOINT_STOCK_PARTNERSHIP" "LIMITED_LIABILITY_COMPANY" "LIMITED_LIABILITY_PARTNERSHIP" "LIMITED_PARTNERSHIP" "LOCAL_GOVERNMENT_UNIT" "PRIVATE_PERSON" "PROFESSIONAL_PARTNERSHIP" "LOCAL_GOVERNMENT_CULTURE_INSTITUTION" "RESEARCH_INSTITUTE" "SOLE_TRADER" "OTHER" FOREIGN_COMPANY type has been deprecated.
gusCode	string <= 50 characters Code relating to the legal form. For more information see the site of the Główny Urząd Statystyczny.
registryNumber	string <= 40 characters Company registry number (eg REGON in Poland).
registrationDate	string <YYYY-MM-DD> Company registration date in the registries.
required	object Address of the company.
isAccountCloned	string Enum: "true" "false" Information if the account was cloned for the same seller form the already exiting and verified one. Used when marketplace allows the account cloning operation.

Responses

Request samples

Payload

Content type

application/json

Example

CompanyData

{"verificationId": "aZx65uY",
"sellerId": "seller_1\"",
"email": "company@test.com",
"phone": "111222333",
"taxId": "1122334455",
"companyName": "Company 1",
"legalForm": "CIVIL_LAW_PARTNERSHIP",
"gusCode": "string",
"registryNumber": "string",
"registrationDate": "2019-07-07",
"address": {"street": "Grunwaldzka 186",
"zipcode": "60-166",
"city": "Poznan",
"country": "PL"
},
"isAccountCloned": "false"
}

Response samples

400
404
409

Content type

application/json

{"status": {"statusCode": "string",
"severity": "string",
"code": "string",
"codeLiteral": "string",
"statusDesc": "string"
}
}

Add Seller's Documents

This method allows to load company related documents.

Authorizations:

Bearer

header Parameters

Content-Type required	string Example: application/json Content type
Authorization required	string Example: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd Auth token

Request Body schema: application/json

verificationId required	string <= 18 characters Id of verification in context of which data are provided.
documentId required	string <= 100 characters
type	string Enum: "REGISTRY_DOCUMENT" "BANK_ACCOUNT_AGREEMENT" "INVOICE" "UBO_STATEMENT" "CIVIL_LAW_AGREEMENT" "PROXY_DOCUMENT" "OTHER_DOCUMENT" Document types.
files	Array of strings List of file ids given in a response to the dataloading/files request. There can be many IDs in this field when one document contains many files.
note	string <= 255 characters
transactionFiles	Array of strings `fileId` of translation of documents (Polish or English documents do not need to be translated).

Responses

Request samples

Payload

Content type

application/json

{"verificationId": "string",
"documentId": "string",
"type": "REGISTRY_DOCUMENT",
"files": ["string"
],
"note": "string",
"transactionFiles": ["string"
]
}

Response samples

400
404
409

Content type

application/json

{"status": {"statusCode": "string",
"severity": "string",
"code": "string",
"codeLiteral": "string",
"statusDesc": "string"
}
}

Add Associates Data

Send the data of the associates (representatives and beneficiaries according to the relevant instructions from PayU).

Authorizations:

Bearer

header Parameters

Content-Type required	string Example: application/json Content type
Authorization required	string Example: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd Auth token

Request Body schema: application/json

verificationId required	string <= 18 characters Unique id of the verification provided by PayU.
associateId required	string <= 100 characters Associate id. Unique on seller level.
associateType required	string Enum: "BENEFICIARY" "REPRESENTATIVE" Type of the associate.
associateName required	string <= 200 characters Associate first name.
associateSurname required	string <= 200 characters Associate last name.
associateBirthDate	string <YYYY-MM-DD> Associate date of birth. Required for non-polish associates.
associateIdentityNumber	string <= 150 characters Unique associate identification number. PESEL in Poland. Required for polish associates.
associateCitizenship required	string <ISO Country Code> <= 255 characters Two letter ISO country code.
associateCountryOfBirth	string <= 255 characters Two letter ISO country code.
pepStatement	string Enum: "true" "false"
verified	string Enum: "true" "false"
	object Object containing Authologic data.

Responses

Request samples

Payload

Content type

application/json

{"verificationId": "aZx65uY",
"associateId": "dsada65",
"associateType": "BENEFICIARY",
"associateName": "Jan",
"associateSurname": "Kowalski",
"associateBirthDate": "1980-01-27",
"associateIdentityNumber": "90120789112",
"associateCitizenship": "PL",
"associateCountryOfBirth": "PL",
"pepStatement": "true",
"verified": "true",
"externalVerificationData": {"externalVerificationType": "MOJEID_PL",
"documentNumber": "ABC123456",
"documentType": "ID_CARD",
"documentExpiryDate": "2030-09-23",
"identityNumber": "94091100007",
"nationality": "PL",
"dateOfBirth": "2000-09-11",
"secondDocumentNumber": "DFE123456",
"secondDocumentType": "PASSPORT",
"secondDocumentExpiryDate": "2030-09-23",
"identityNumberSecondDocument": "94091100007",
"nationalitySecondDocument": "PL",
"dateOfBirthSecondDocument": "2030-09-23",
"authologicConversationID": "string"
}
}

Response samples

400
404
409

Content type

application/json

{"status": {"statusCode": "string",
"severity": "string",
"code": "string",
"codeLiteral": "string",
"statusDesc": "string"
}
}

Add Associates Documents

Upload required documents for associates (representatives or beneficiaries).

Authorizations:

Bearer

header Parameters

Content-Type required	string Example: application/json Content type
Authorization required	string Example: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd Auth token

Request Body schema: application/json

verificationId required	string <= 18 characters Unique id of the verification provided by PayU.
associateId required	string <= 100 characters Unique id of an associate assigned by the Marketplace.
type required	string Enum: "ID_CARD" "PASSPORT" "DRIVING_LICENCE" "RESIDENCE_PERMIT" "OTHER_DOCUMENT" "PEP_STATEMENT" Document type.
files required	Array of strings List of file ids given in a response to the dataloading/files request. Can be many IDs in this field when one document contains many files.
documentId required	string <= 100 characters Unique document ID assigned by the Marketplace.
documentNumber	string <= 100 characters Serial number of the provided document.
issueDate	string <YYYY-MM-DD> Issue date of the document.
expireDate required	string <YYYY-MM-DD> Expiry date of the document.
note	string <= 255 characters
translationFiles	Array of strings `fileId` of translation of documents (Polish or English documents do not need to be translated)

Responses

Request samples

Payload

Content type

application/json

{"verificationId": "string",
"associateId": "string",
"type": "ID_CARD",
"files": ["string"
],
"documentId": "string",
"documentNumber": "string",
"issueDate": "string",
"expireDate": "string",
"note": "string",
"translationFiles": ["string"
]
}

Response samples

400
404
409

Content type

application/json

{"status": {"statusCode": "string",
"severity": "string",
"code": "string",
"codeLiteral": "string",
"statusDesc": "string"
}
}

Add Files

Upload documents to the server.

Authorizations:

Bearer

header Parameters

Content-Type required	string Example: application/json Content type
Authorization required	string Example: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd Auth token

Request Body schema: application/json

verificationId required	string <= 18 characters Unique id of the verification provided by PayU.
filename required	string
content	string

Responses

Request samples

Payload

Content type

application/json

{"verificationId": "string",
"filename": "string",
"content": "string"
}

Response samples

200
400
404
409

Content type

application/json

{"verifictionId": "aZx65uY",
"fileId": "string"
}

Create Order for Verification Transfer

Create an order for the verification transfer service. In response you will be provided with the bank account details to make the transfer.

Authorizations:

Bearer

header Parameters

Content-Type required	string Example: application/json Content type
Authorization required	string Example: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd Auth token

Request Body schema: application/json

verificationId required	string <= 18 characters Unique id of the verification provided by PayU.
transferCurrency	string
email	string
language	string Changes the language of the sent email message. Possible values you can find in languages table.

Responses

Request samples

Payload

Content type

application/json

{"verificationId": "verification-123",
"transferCurrency": "PLN",
"email": "user@example.com",
"language": "string"
}

Response samples

201
400
403
404

Content type

application/json

{"verificationTransferId": "5f7007da-8e05-4f0f-9503-05c053034bde",
"expirationTime": "2020-08-20T14:03:44.473Z",
"transferData": {"bankName": "mBank S.A.",
"accountNumber": "PL12114011243630011718031748",
"swiftCode": "BREXPLPW",
"recipientName": "PayU S.A.",
"recipientAddress": "ul. Grunwaldzka 186, 60-166 Poznań",
"transferTitle": "Verification transfer XX1718031748XX",
"transferAmount": 101,
"transferCurrency": "PLN"
}
}

Add Bank Account for Payouts

Send bank account data for the payouts.

Authorizations:

Bearer

header Parameters

Content-Type required	string Example: application/json Content type
Authorization required	string Example: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd Auth token

Request Body schema: application/json

One of

bankDataId required	string <= 100 characters Id of the bank account details assigned by marketplace.
verificationId required	string <= 18 characters Id of verification in context of which data are provided.
accountNumberRequested required	string <IBAN> <= 255 characters Bank account number declared for withdrawals by submerchant.
hasDocument	string Enum: true false Flag informing that this bank account for payouts should be verified on base of bank document. It must be set to true when the method used is "BANK_STATEMENT".
payoutDataVerificationType required	string Enum: "LIAN_LIAN" "PINGPONG" "OFX" "BANK_STATEMENT" "BANK_TRANSFER" "NO_VERIFICATION_NEEDED" Type of verification used for the provided payout details verification. Different for each verification type: LIAN_LIAN - special type for Chinese submerchants, PINGPONG - special type for Chinese submerchants, OFX - special type for Chinese submerchants, BANK_STATEMENT - used if all data are present on the document (`hasDocument` must be true), BANK_TRANSFER, NO_VERIFICATION_NEEDED - used if the provided bank account number was not yet verified by 3rd party but it doesn't have to be verified at the time of providing the bank details. It is used for the occasional transaction process when the bank account number is provided at the beginning of the process.
foreign required	string Enum: true false Foreign Transfer Indicator. Has to be `true` for all cross-border payouts and payouts in EUR. For domestic transfers set this parameter to `false`, specifically: Payouts in CZK (Czech Koruna) to an account held in the Czech Republic. Payouts in PLN (Polish Złoty) to an account held in Poland.
verificationTransferId required	string <= 255 characters Have to be indicated in request with declared payouts data. Payouts data need to be declared in 72 hours from above request/response.
verified required	string parameter indicating whether the bank account number was already verified e.g. by another provider. If set to false and the verification type is other than "NO_VERIFICATION_NEEDED" PayU must verify the bank account details.

Responses

Request samples

Payload

Content type

application/json

Example

PayoutWithVerificationTransfer

{"bankDataId": "01102020",
"verificationId": "verification-123",
"accountNumberRequested": "PL1122334455667788991010111223345",
"hasDocument": "true",
"payoutDataVerificationType": "BANK_STATEMENT",
"foreign": "false",
"verificationTransferId": "5f7007da-8e05-4f0f-9503-05c053034bde",
"verified": "false"
}

Response samples

400
403
404
409

Content type

application/json

{"status": {"statusCode": "string",
"severity": "string",
"code": "string",
"codeLiteral": "string",
"statusDesc": "string"
}
}

Add Payoneer Account for Payouts

Send bank account data for the payouts. Method is reserved for the users who have verified Payoneer account.

Authorizations:

Bearer

header Parameters

Content-Type required	string Example: application/json Content type
Authorization required	string Example: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd Auth token

Request Body schema: application/json

bankDataId required	string <= 100 characters Id of the bank account details assigned by marketplace.
verificationId required	string <= 18 characters Unique id of the verification provided by PayU.
payoneerId required	string <= 50 characters Id of the account of the submerchant in the Payoneer.

Responses

Request samples

Payload

Content type

application/json

{"bankDataId": "acc1sd",
"verificationId": "hfs6sfa",
"payoneerId": "string"
}

Response samples

400
404
409

Content type

application/json

{"status": {"statusCode": "string",
"severity": "string",
"code": "string",
"codeLiteral": "string",
"statusDesc": "string"
}
}

Add Worldfirst Account for Payouts

Send bank account data for the payouts. Method is reserved for the users who have verified Worldfirst account.

Authorizations:

Bearer

header Parameters

Content-Type required	string Example: application/json Content type
Authorization required	string Example: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd Auth token

Request Body schema: application/json

bankDataId required	string <= 100 characters Id of the bank account details assigned by marketplace.
verificationId required	string <= 18 characters Unique id of the verification provided by PayU.
referenceCustomerId required	string Id of the account binding between the marketplace and the WorldFirst.

Responses

Request samples

Payload

Content type

application/json

{"bankDataId": "acc1sd",
"verificationId": "hfs6sfa",
"referenceCustomerId": "string"
}

Response samples

400
404
409

Content type

application/json

{"status": {"statusCode": "string",
"severity": "string",
"code": "string",
"codeLiteral": "string",
"statusDesc": "string"
}
}

Complete Marketplace Verification

Inform PayU about completing verification process.

Authorizations:

Bearer

header Parameters

Content-Type required	string Example: application/json Content type
Authorization required	string Example: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd Auth token

Request Body schema: application/json

verificationId

required

string <= 18 characters

Unique id of the verification provided by PayU.

Responses

Request samples

Payload

Content type

application/json

{"verificationId": "hfs6sfa"
}

Response samples

400
404
409

Content type

application/json

{"status": {"statusCode": "string",
"severity": "string",
"code": "string",
"codeLiteral": "string",
"statusDesc": "string"
}
}

Cancel Verification

Cancel verification on every step of verification providing the reason.

Authorizations:

Bearer

header Parameters

Content-Type required	string Example: application/json Content type
Authorization required	string Example: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd Auth token

Request Body schema: application/json

verificationId required	string <= 18 characters Unique id of the verification provided by PayU.
rejectionReasonComment	string Reason for cancelling verification.

Responses

Request samples

Payload

Content type

application/json

{"verificationId": "hfs6sfa",
"rejectionReasonComment": "string"
}

Response samples

404
409

Content type

application/json

{"status": {"statusCode": "string",
"severity": "string",
"statusDesc": "string"
}
}

Statements

Statements in PayU are comprehensive reports that provide a detailed summary of completed purchase transactions, refunds, and payouts.

Retrieve Statement

In response to retrieving a statement via the API, PayU returns a statement file (as indicated by the Content-Type=application/octet-stream) in the Content-Disposition header. You should take this attached binary data and save it with the same name and file extension.

For example, if the value of the Content-Disposition header is attachment; filename="69e45495-bed9-4824-ace9-f7c191449bbb.zip", then you should save the attached data on your computer with the same name 69e45495-bed9-4824-ace9-f7c191449bbb.zip.

Authorizations:

Basic

path Parameters

reportId

required

string

Example: "4a3534fb-85b5-4f29-9da8-a6d73b34d528"

header Parameters

Content-Type required	string Example: application/json Content type
Authorization required	string Example: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd Auth token

Partner Merchant Registration

Below are the endpoints that enable you to create the necessary entities (Firm, Url, Shop, POS) for your partner.

Create a Firm

Create a Firm entity for your partner.

Authorizations:

Bearer

header Parameters

Content-Type required	string Example: application/json Content type
Authorization required	string Example: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd Auth token with `grant_type=client_credentials`.

Request Body schema: application/json

name required	string Full legal name.
type required	string Dictionary value - legal entity type. Dictionaries for specific origin are available here. For a firm which `address.country` code is not equal to `businessArea.origin` please use FZ type. Providing accurate type speeds up merchant verification.
taxId required	string Tax identification.
taxIdType required	string Enum: "NIP" "VAT_EU" "TAX_ID" Type of tax identification.
cin required	string Business identification. IČ (CZ) or REGON (PL).
bankAccount required	string <IBAN> Primary bank account to receive payouts for payments. Will be inherited by all shops created for this firm. Must be a valid IBAN number in case of firms with PL origin. Different bank account maybe defined at shop level manually, via PayU merchant panel.
partnerId required	string Your partner id.
required	object Business area of the registered firm.
required	Array of objects Array of PayU panel users. At least 1 must be provided.
required	Array of objects Array of firm legal representatives. At least 1 must be provided.
required	object Object containing firm's contact details.
technicalContactData	object Object containing firm's technical contact details (e.g. to the developer responsible for integration with PayU).
required	object Firm's registration address.
	object Firm's correspondence address (if other than registration address). This object the same fields as address.

Responses

Request samples

Payload

Content type

application/json

{"name": "Test sp. z o.o.",
"type": "SO",
"taxId": "3771910486",
"taxIdType": "NIP",
"cin": "138237420",
"bankAccount": "PL92906300080597567560803897",
"partnerId": "egmcvdo5",
"businessArea": {"origin": "PL"
},
"users": [{"name": "Jan",
"surname": "Nowak",
"email": "jan.nowak@testowa.pl",
"phone": 123123123,
"role": "MANAGER"
}
],
"representatives": [{"name": "Jan",
"surname": "Nowak",
"nin": 80010104578,
"countryCode": "PL",
"birthDate": null
}
],
"contactData": {"phone": 123123123,
"email": "biuro@testowa.pl"
},
"technicalContactData": { },
"address": {"street": "Grunwaldzka",
"houseNo": 186,
"apartmentNo": 1,
"postalCode": "61-166",
"city": "Poznań",
"countryCode": "PL"
},
"correspondenceAddress": {"street": "Grunwaldzka",
"houseNo": 186,
"apartmentNo": 1,
"postalCode": "61-166",
"city": "Poznań",
"countryCode": "PL"
}
}

Response samples

200
401

Content type

application/json

{"firmId": "KzXy4ZzD"
}

Create a URL for the Partner's Firm

Create a URL for the specified firmId.

Authorizations:

Bearer

path Parameters

firmId

required

string

Example: "KzXy4ZzD"

Firm identifier retrieved after firm creation.

header Parameters

Content-Type required	string Example: application/json Content type
Authorization required	string Example: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd Auth token with `grant_type=partner`.

Request Body schema: application/json

value required	string URL address.
mcc	string Merchant Category Code (value is validated). Data type
required	Array of objects Array of service types.

Responses

Request samples

Payload

Content type

application/json

{"value": "http://www.test-url.com",
"mcc": "0742",
"services": [{"type": "TRANSFERS"
}
]
}

Response samples

200
401

Content type

application/json

{"urlId": "PItR5x0v"
}

Create a Shop for the Partner

Create a Shop for the specified firmId.

Authorizations:

Bearer

path Parameters

firmId

required

string

Example: "KzXy4ZzD"

Firm identifier retrieved after firm creation.

header Parameters

Content-Type required	string Example: application/json Content type
Authorization required	string Example: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd Auth token with `grant_type=partner`.

Request Body schema: application/json

name required	string Shop name - will be visible in the merchant panel.
description	string Shop description - more detailed info, visible in the merchant panel.
currencyCode required	string Must be a three-letter ISO 4217 currency code. Please contact your key account manager to get more information about available currencies.
urlId required	string Reference to previously created URL.

Responses

Request samples

Payload

Content type

application/json

{"name": "Shop name",
"description": "Shop description",
"currencyCode": "EUR",
"urlId": "PItR5x0v"
}

Response samples

200
401

Content type

application/json

{"shopId": "ycmGyfCv"
}

Create POS for Partner

Create a POS, for your partner, for the specified shopId.

Authorizations:

Bearer

path Parameters

shopId

required

string

Example: "Shop identifier retrieved after shop creation."

header Parameters

Content-Type required	string Example: application/json Content type
Authorization required	string Example: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd Auth token with `grant_type=partner`.

Request Body schema: application/json

name required	string Name of the created POS.
type required	string Type of the created POS.

Responses

Request samples

Payload

Content type

application/json

{"name": "Test POS",
"type": "REST"
}

Response samples

200
401

Content type

application/json

{"posId": "JyoMIVTY"
}

Retrieve Partner's POS Data

Retrieve data of the POS with specified posId.

Authorizations:

Bearer

path Parameters

posId

required

string

Example: "POS identifier retrieved after POS creation."

header Parameters

Content-Type required	string Example: application/json Content type
Authorization required	string Example: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd Auth token with `grant_type=partner`.

Responses

Response samples

200
401

Content type

application/json

{"posId": "JyoMIVTY",
"type": "REST",
"name": "Test POS",
"encoding": "UTF-8",
"authorization": {"standard": {"merchantPosId": "385234",
"key": "9c0041e05fdee99749de4c2d2ce4c66e\"",
"secondKey": "f096a39d78fbe03b8d23dde43b728cfd",
"authKey": "uHcZ9Ly"
}
}
}

Payment Facilitator Submerchant Registration

Payment Facilitator (PF) is an advanced form of partnership where PayU cedes much of its own responsibilities, like e.g. Know Your Customer (KYC) and verification, customer support and settlement (payouts) to the PF. Below are the endpoints for registering and handling PF submerchants.

Create a Submerchant

Authorizations:

Bearer

path Parameters

firmPublicId

required

string

Firm id in alphanumeric format, visible in the merchant panel.

header Parameters

Content-Type required	string Example: application/json Content type
Authorization required	string Example: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd Auth token

Request Body schema: application/json

payTypeCategories	Array of strings Array of enumerated values: `Card`, `PBL`. Both can be used at the same time - minimum one is required. Card
externalId required	string Id assigned by the Payment Facilitator.
notifyUrl required	string Notifications regarding submerchant status change will be sent to address provided in this field.
legalName required	string Full legal (registration) name.
dbaName required	string "Doing business as" name, usually simplified website address which can be recognized by customer (e.g. when displayed on card statement).
required	object Legal address object.
phone required	string Contact phone number.
websiteUrl required	string A valid URL address of merchant's website.
mcc required	number Accurate Merchant Category Code established during KYC process by the PF.
riskClass required	string Enum: "LOW" "NORMAL" "HIGH" Risk class assigned by Payment Facilitator (basing on requirements provided by PayU).
required	Array of objects Array of either principals or enterprise owners (depends on legal form). Minimum one is required.
legalForm required	string Enum: "FU" "FZ" "IB" "JST" "KOP" "PO" "PP" "PPZ" "PRPA" "SA" "SC" "SD" "SIK" "SJ" "SK" "SO" "SP" "SPOL" "ST" Dictionary value - legal entity type. Check dictionaries for specific origin.
taxId required	string Tax identification (e.g. NIP in Poland) or business identification (e.g. IČ in Czechia).
agreementDate required	string <yyyy-mm-dd> Date when PF signed agreement with the submerchant (required by Visa for reporting purposes).

Responses

Request samples

Payload

Content type

application/json

Example

Card

{"payTypeCategories": "Card",
"externalId": "string",
"notifyUrl": "string",
"legalName": "string",
"dbaName": "string",
"address": {"street": "string",
"city": "string",
"postalCode": "string",
"countryCode": "string"
},
"phone": "string",
"websiteUrl": "string",
"mcc": 0,
"riskClass": "LOW",
"representatives": [{"name": "string",
"phone": "string"
}
],
"legalForm": "FU",
"taxId": "string",
"agreementDate": "string"
}

Response samples

200
401

Content type

application/json

{"id": "string",
"externalId": "string",
"status": "NOT_ACTIVE",
"lastUpdated": "string",
"notifyUrl": "string",
"legalName": "string",
"dbaName": "string",
"address": {"street": "string",
"city": "string",
"postalCode": "string",
"countryCode": "string"
},
"phone": "string",
"websiteUrl": "string",
"mcc": 0,
"riskClass": "LOW",
"taxId": "string",
"representatives": [{"name": "string",
"phone": "string"
}
],
"legalForm": "string",
"agreementDate": "string",
"payTypeCategories": "string"
}

Update Submerchant Data

Authorizations:

Bearer

path Parameters

firmPublicId required	string Firm id in alphanumeric format, visible in the merchant panel.
submerchantId required	string Id returned by PayU upon submerchant registration.

header Parameters

Content-Type required	string Example: application/json Content type
Authorization required	string Example: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd Auth token

Request Body schema: application/json

payTypeCategories	Array of strings Array of enumerated values: `Card`, `PBL`. Both can be used at the same time - minimum one is required. Card
externalId required	string Id assigned by the Payment Facilitator.
notifyUrl required	string Notifications regarding submerchant status change will be sent to address provided in this field.
legalName required	string Full legal (registration) name.
dbaName required	string "Doing business as" name, usually simplified website address which can be recognized by customer (e.g. when displayed on card statement).
required	object Legal address object.
phone required	string Contact phone number.
websiteUrl required	string A valid URL address of merchant's website.
mcc required	number Accurate Merchant Category Code established during KYC process by the PF.
riskClass required	string Enum: "LOW" "NORMAL" "HIGH" Risk class assigned by Payment Facilitator (basing on requirements provided by PayU).
required	Array of objects Array of either principals or enterprise owners (depends on legal form). Minimum one is required.
legalForm required	string Enum: "FU" "FZ" "IB" "JST" "KOP" "PO" "PP" "PPZ" "PRPA" "SA" "SC" "SD" "SIK" "SJ" "SK" "SO" "SP" "SPOL" "ST" Dictionary value - legal entity type. Check dictionaries for specific origin.
taxId required	string Tax identification (e.g. NIP in Poland) or business identification (e.g. IČ in Czechia).
agreementDate required	string <yyyy-mm-dd> Date when PF signed agreement with the submerchant (required by Visa for reporting purposes).

Responses

Request samples

Payload

Content type

application/json

Example

Card

{"payTypeCategories": "Card",
"externalId": "string",
"notifyUrl": "string",
"legalName": "string",
"dbaName": "string",
"address": {"street": "string",
"city": "string",
"postalCode": "string",
"countryCode": "string"
},
"phone": "string",
"websiteUrl": "string",
"mcc": 0,
"riskClass": "LOW",
"representatives": [{"name": "string",
"phone": "string"
}
],
"legalForm": "FU",
"taxId": "string",
"agreementDate": "string"
}

Response samples

200
401

Content type

application/json

{"id": "string",
"externalId": "string",
"status": "NOT_ACTIVE",
"lastUpdated": "string",
"notifyUrl": "string",
"legalName": "string",
"dbaName": "string",
"address": {"street": "string",
"city": "string",
"postalCode": "string",
"countryCode": "string"
},
"phone": "string",
"websiteUrl": "string",
"mcc": 0,
"riskClass": "LOW",
"taxId": "string",
"representatives": [{"name": "string",
"phone": "string"
}
],
"legalForm": "string",
"agreementDate": "string",
"payTypeCategories": "string"
}

Retrieve Submerchant Data

Authorizations:

Bearer

path Parameters

firmPublicId required	string Firm id in alphanumeric format, visible in the merchant panel.
submerchantId required	string Id returned by PayU upon submerchant registration.

header Parameters

Content-Type required	string Example: application/json Content type
Authorization required	string Example: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd Auth token

Responses

Response samples

200
401

Content type

application/json

{"id": "string",
"externalId": "string",
"status": "NOT_ACTIVE",
"lastUpdated": "string",
"notifyUrl": "string",
"legalName": "string",
"dbaName": "string",
"address": {"street": "string",
"city": "string",
"postalCode": "string",
"countryCode": "string"
},
"phone": "string",
"websiteUrl": "string",
"mcc": 0,
"riskClass": "LOW",
"taxId": "string",
"representatives": [{"name": "string",
"phone": "string"
}
],
"legalForm": "string",
"agreementDate": "string",
"payTypeCategories": "string"
}