If you are interested in cooperation with PayU as marketplace please contact us.
When marketplace company registration process is completed there is a special submerchant registration form available at:
https://secure.payu.com/boarding/#/form?lang=en&nsf=false&partnerId=MARKETPLACE_ID&marketplaceExtCustomerId=EXT_CUSTOMER_ID
MARKETPLACE_ID
is unique marketplace identifier given by PayU.
EXT_CUSTOMER_ID
is unique submerchant identifier given by marketplace.
Every submerchant must be verified by PayU. If submerchant is not verified then order creation for this submerchant is not allowed and error is returned.
Functionality of marketplace can be tested on sandbox environment. Test account is available for anyone testing this service, beacuse of that marketplace or submerchants balances can change without your contribution.
Point of Sale Id (pos_id): 341009 Second key (MD5): 289c28ec590ba6940746266c5d64932f OAuth Protocol (client_id): 341009 OAuth Protocol (client_secret): ff9994baa59b73c7ca56a5480e608f02
//submerchants ext_customer_id submerchant_A submerchant_B submerchant_C submerchant_unverified -- this submerchant is not verified - you can't make some requests such as payout etc.
Note!If you want to perform payout from a test account, you should set value of shopId
parameter to 0pKb1aqC
Integration is consistent with REST API 2.1. There are some API extensions available only for marketplace companies.
Authentication methods are described in: Signing API calls parameters.
This feature is only available for marketplaces boarding submerchants via WEB boarding as described in section 1.1. It is not available for marketplaces using the boarding API (SF).
curl -v -X GET https://secure.payu.com/api/v2_1/customers/ext/<EXT_CUSTOMER_ID>/status?currencyCode=PLN \ -H "Content-Type: application/json" \ -H "Authorization: Bearer <AUTH_TOKEN>"
EXT_CUSTOMER_ID
is submerchant identifier.
Request parameters are:
Parameter | Required | Comment |
---|---|---|
currencyCode | yes | Currency code according to ISO-4217. |
{ "customerVerificationStatus": "Verified", "name": "Example Company", "taxId": "123123123", "regon": "123123123" }
Field | Comment |
---|---|
customerVerificationStatus | Submerchant status. Available values:
|
name | Name of the company |
taxId | Company NIP. For companies registered abroad the field contains: Tax ID or VAT UE. |
regon | Regon number of the company |
Marketplace order creation is consistent with standard integration method via REST API: Creating new order. Below marketplace specific changes are described.
Complex shoppingCarts
element defines distribution to particular submerchants.
... "shoppingCarts": [ { "extCustomerId": "ext-customer-1", "amount": 1800, "fee": 20, "shippingMethods": [ { "country": "EN", "price": 1500, "name": "Shipping Method 1" } ], "products": [ { "name": "product-x", "unitPrice": 100, "quantity": 3, "virtual": false, "listingDate": "2020-09-28T08:17:52Z" } ] }, { "extCustomerId": "ext-customer-2", "amount": 2700, "fee": 27, "shippingMethods": [ { "country": "EN", "price": 2000, "name": "Shipping Method 2" } ], "products": [ { "name": "product-y", "unitPrice": 700, "quantity": 1, "virtual": false, "listingDate": "2018-02-28T09:28:52Z" } ] } ] ...
Field | Required | Comment |
---|---|---|
shoppingCarts.extCustomerId | yes | Submerchant identifier. |
shoppingCarts.amount | yes | Total amount for given submerchant. |
shoppingCarts.fee | no | Marketplace fee. Value should be in range <0, amount > |
shoppingCarts.products | yes | List of products. |
shoppingCarts.products.name | yes | Product name. |
shoppingCarts.products.unitPrice | yes | Product unit price. |
shoppingCarts.products.quantity | yes | Quantity. |
shoppingCarts.products.virtual | nie | Product type, which can be virtual or material; (possible values true or false ). |
shoppingCarts.products.listingDate | nie | Date from which the product (or offer) is available, for example: "2016-01-26T17:35:37+01:00". |
shoppingCarts.shippingMethods | no | Shipping method. |
shoppingCarts.shippingMethods.name | yes, only if field shippingMethods is filled |
Shipping method name. |
shoppingCarts.shippingMethods.price | yes, only if field shippingMethods is filled |
Shipping price. |
shoppingCarts.shippingMethods.country | yes, only if field shippingMethods is filled |
Two-letter shipping country code compliant with ISO-3166. |
Sum of amount
field values in each element of shoppingCarts
should be equal to value of totalAmount
field in order.
If you received the following response to your order please check extCustomerId
parameter.
{ "iFrameAllowed": false, "status": { "statusCode": "DATA_NOT_FOUND", "code": "9999", "codeLiteral": "CUSTOMER_NOT_FOUND" } }
buyer
section was extended with extCustomerId
field which is a buyer identifer defined by marketplace:
... "buyer": { "extCustomerId": "buyer-id-1234", "email": "buyer-id-1234@email.com", ... } ...
Field | Required | Comment |
---|---|---|
buyer.extCustomerId | yes | Buyer identifier. There is no need to create or verify buyer earlier - it will be automatically created when is used first time. |
curl -v -X POST https://secure.payu.com/api/v2_1/orders \ -H "Content-Type: application/json" \ -H "Authorization: Bearer <AUTH_TOKEN>" \ -d '{ "merchantPosId":"341009", "customerIp": "127.0.0.1", "continueUrl": "http://your.eshop.com/continue", "notifyUrl": "https://your.eshop.com/notify", "currencyCode": "PLN", "totalAmount": 5000, "extOrderId": "marketplace-order-xyz-123", "description": "order XYZ-123", "additionalDescription": "additional description", "buyer": { "email": "john.doe@email.com", "phone": "(012)1234567", "firstName": "John", "lastName": "Doe", "language": "pl", "extCustomerId": "john-doe-12345" }, "shoppingCarts": [ { "extCustomerId": "marketplace-submerchant-1", "amount": 200, "fee": 20, "products": [ { "name": "product A", "quantity": 2, "unitPrice": 100, "virtual": false, "listingDate": "2018-01-28T07:17:52Z" } ] }, { "extCustomerId": "marketplace-submerchant-2", "amount": 1300, "products": [ { "name": "product B", "quantity": 2, "unitPrice": 200, "virtual": false, "listingDate": "2021-02-09T12:17:52Z" }, { "name": "product C", "quantity": 3, "unitPrice": 300, "virtual": false, "listingDate": "2017-09-15T08:15:52Z" } ] }, { "extCustomerId": "marketplace-submerchant-3", "amount": 3500, "fee":350, "products": [ { "name": "product D", "quantity": 1, "unitPrice": 3500, "virtual": false, "listingDate": "2020-09-28T08:17:52Z" } ] } ] }'
curl -v -X POST https://secure.payu.com/api/v2_1/orders \ -H "Content-Type: application/json" \ -H "Authorization: Bearer <AUTH_TOKEN>" \ -d '{ "merchantPosId":"341009", "customerIp": "127.0.0.1", "continueUrl": "http://your.eshop.com/continue", "notifyUrl": "https://your.eshop.com/notify", "currencyCode": "PLN", "totalAmount": 5000, "extOrderId": "marketplace-order-xyz-123", "description": "order XYZ-123", "additionalDescription": "additional description", "buyer": { "email": "john.doe@email.com", "phone": "(012)1234567", "firstName": "John", "lastName": "Doe", "language": "pl", "extCustomerId": "john-doe-12345" }, "shoppingCarts": [ { "extCustomerId": "marketplace-submerchant-1", "amount": 200, "fee": 20, "products": [ { "name": "product A", "quantity": 2, "unitPrice": 100, "virtual": false, "listingDate": "2020-09-28T08:17:52Z" } ] }, { "extCustomerId": "marketplace-submerchant-2", "amount": 1300, "products": [ { "name": "product B", "quantity": 2, "unitPrice": 200, "virtual": false, "listingDate": "2018-09-28T08:17:52Z" }, { "name": "product C", "quantity": 3, "unitPrice": 300, "virtual": false, "listingDate": "2019-09-04T08:19:30Z" } ] }, { "extCustomerId": "marketplace-submerchant-3", "amount": 3500, "fee":350, "products": [ { "name": "product D", "quantity": 1, "unitPrice": 3500, "virtual": false, "listingDate": "2020-09-28T08:17:52Z" } ] } ], "payMethods": { "payMethod":{ "type":"PBL", "value":"m", "amount":5000 } } }'
payMethods
section fields description
Field | Required | Comment |
---|---|---|
payMethod.type | Yes | Payment method type. |
payMethod.value | Yes | Payment type. |
payMethod.amount | Yes | Total price of order. Should be equal to totalAmount field, as well as sum of all amount fields in shoppingCarts section. |
StatusCode | Code | CodeLiteral | Description |
---|---|---|---|
DATA_NOT_FOUND | CUSTOMER_NOT_FOUND | 9999 | Submerchant doesn't exist. |
{ "order": { "orderId": "V6V7HHL1H9230518GUEST000P01", "extOrderId": "Marketplace Standard Order", "orderCreateDate": "2023-05-18T16:04:35.660+02:00", "notifyUrl": https://notifyurl.com, "customerIp": "127.0.0.1", "merchantPosId": "199022", "description": "Marketplace Standard Order", "currencyCode": "PLN", "totalAmount": "5000", "buyer": { "customerId": "guest", "email": john.doe@email.com, "phone": "654111654", "firstName": "John", "lastName": "Doe" }, "payMethod": { "amount": "5000", "type": "PBL" }, "status": "COMPLETED", "shoppingCarts": [ { "extCustomerId": "customer1", "amount": "5000", "fee": "1000", "shippingMethods": [ { "country": "PL", "price": "0", "name": "Shipping Method 1" } ], "products": [ { "name": "product-x", "unitPrice": "5000", "quantity": "1" } ] } ] }, "localReceiptDateTime": "2023-05-18T16:04:47.102+02:00", "properties": [ { "name": "PAYMENT_ID", "value": "5007331705" } ] }
You can read more about notifications in Notifications section.
Marketplace refund processing is consistent with standard integration method via REST API: Refunds. Below marketplace specific changes are described.
curl -X POST https://secure.payu.com/api/v2_1/orders/<ORDER_ID>/refunds \ -H "Content-Type: application/json" \ -H "Authorization: Bearer <AUTH_TOKEN>" \ -d '{ "refund": { "description": "Refund", "amount": 1000 "extCustomerId": "ext-customer-1", "extRefundId": "ext-refund-id-1" } }'
ORDER_ID
is order identifier, which refund is created for.
Field | Required | Comment |
---|---|---|
refund.extRefundId | yes | External refund identifier. |
refund.amount | yes |
Refund amount. If amount is equal to totalAmount value from order then full
refund for all submerchants from order is created.
|
refund.extCustomerId | yes, if amount field value is not equal to totalAmount value in order |
Submerchant identifier. |
{ "status": { "statusCode":"SUCCESS", "statusDesc": "Refund queued for processing" }, "orderId":"47FD97QSPL140325GUEST000P01", "refund":{ "dispositions": { "instrumentAmount": "1000", "walletAmount": "0", "couponAmount": "0" }, "refundId": "R84FWMHX6K150901abjtwtchP01", "extRefundId": "ext-refund-id-1" } }
StatusCode | CodeLiteral | Code | Description |
---|---|---|---|
BUSINESS_ERROR | TRANS_NOT_ENDED | 9101 | Transaction is not completed. |
BUSINESS_ERROR | NO_BALANCE | 9102 | Submerchant has no sufficient balance available. |
ERROR_VALUE_INVALID | AMOUNT_TO_BIG | 9103 | Refund amount too large. |
BUSINESS_ERROR | MARKETPLACE_CUSTOMER _IS_NOT_ACTIVE | 9104 | Customer is not active. |
BUSINESS_ERROR | MARKETPLACE_CUSTOMER _IS_LOCKED | 9106 | Customer is locked. |
BUSINESS_ERROR | AMOUNT_EXCEEDED | 9109 | Refund amount exceeds amount for given submerchant in order. |
BUSINESS_ERROR | AMBIGUOUS_REFUND_SOURCE | 9110 | Refund can't be realized from more than one source. |
BUSINESS_ERROR | AMOUNT_MISSING | 9114 | Amount is missing. |
BUSINESS_ERROR | AMOUNT_INVALID | 9115 | extCustomerId is empty and refund amount is not equal to totalAmount in order. |
BUSINESS_ERROR | EXT_REFUND_ID_MISSING | 9116 | extRefundId is missing. |
BUSINESS_ERROR | NO_SHOPPING_CARTS_IN_ORDER | 9118 | Missing shopping carts in order. |
DATA_NOT_FOUND | MARKETPLACE_TRANSACTION _NOT_FOUND | 9119 | Order with given identifier doesn't exist. |
DATA_NOT_FOUND | CUSTOMER_NOT_FOUND | 9999 | Submerchant doesn't exist. |
Marketplace payout processing is consistent with standard integration method via REST API: Payouts. Below marketplace specific changes are described.
curl -X POST https://secure.payu.com/api/v2_1/payouts \ -H "Content-Type: application/json" \ -H "Authorization: Bearer <AUTH_TOKEN>" \ -d '{ "shopId":"shop-id", "payout": { "amount": "1000", "currencyCode": "PLN", "description": "Some payout", "extPayoutId": "my_payout_id_123" }, "account": { "extCustomerId": "ext-customer-id-1" } }'In order to make a payout for the marketplace sandbox account use the parameter
extCustomerId
: MARKETPLACE_K2_FEEField | Required | Comment |
---|---|---|
shopId | Yes | Public shop Id obtained from the PayU panel. |
payout.amount | No | If this field is empty then full payout will be performed. |
payout.currencyCode | Yes | Currency in which payout has been made. |
payout.description | Yes | Description of the payout. |
payout.extPayoutId | No | External Payout Identifier, given by the merchant. Merchant can
create only one payout with given extPayoutId
within one shop. |
account.extCustomerId | Yes | Submerchant identifier. |
{ "payout": { "payoutId": "b3e4fc98c6894239864a9d6941f0fe76", "extPayoutId": "PAYOUT23423423423", "extCustomerId": "12345678", "status": "PENDING" }, "status": { "statusCode": "SUCCESS" } }
StatusCode | CodeLiteral | Code | Description |
---|---|---|---|
BUSINESS_ERROR | NOT_ENOUGH_FUNDS | 8325 | Submerchant has not enough balance available. |
BUSINESS_ERROR | PAYOUT_ALREADY_EXISTS | 8356 | Payout already exists: payoutId=[7b52a5b922a34b978bc112cd64b09caf]. |
BUSINESS_ERROR | MISSING_EXTERNAL _CUSTOMER_ID | 8362 | extCustomerId is missing. |
BUSINESS_ERROR | MISSING_EXTERNAL _PAYOUT_ID | 8363 | extPayoutId is missing. |
ERROR_VALUE_INVALID | AMOUNT_TO_BIG | 9103 | Payout amount too large. |
BUSINESS_ERROR | MARKETPLACE_CUSTOMER _IS_NOT_ACTIVE | 9104 | Customer is not active. |
BUSINESS_ERROR | MARKETPLACE_CUSTOMER _IS_LOCKED | 9106 | Customer is locked. |
ERROR_VALUE_INVALID | MARKETPLACE_CUSTOMER _NOT_VERIFIED | 9132 | Submerchant is not verified by PayU. |
ERROR_VALUE_INVALID | PROVIDING_BANK _ACCOUNT_IS_FORBIDDEN | 9133 | Bank account is forbidden for marketplace payout. |
DATA_NOT_FOUND | CUSTOMER_NOT_FOUND | 9999 | Submerchant doesn't exist. |
curl -X GET \ 'https://secure.payu.com/api/v2_1/customers/ext/<EXT_CUSTOMER_ID>/operations?eventDateFrom=<EVENT_DATE_FROM>&eventDateTo=<EVENT_DATE_TO>' \ -H 'Authorization: Bearer <AUTH_TOKEN>' \ -H 'Content-Type: application/json' \ -H 'cache-control: no-cache'
EXT_CUSTOMER_ID
is submerchant identifier. Parameter | Required | Comment |
---|---|---|
eventDateFrom | yes | Start of the search range for
"eventDate". Format: 2019-01-30T20%3A59%3A00%2B02%3A00 Date must be url encoded. |
eventDateTo | yes | End of the search range for "eventDate". Format: 2019-04-30T20%3A59%3A00%2B02%3A00 Date must be url encoded. |
creationDateFrom | no | Start of the search range for "creationDate". Format: 2019-04-30T20%3A59%3A00%2B02%3A00 Date must be url encoded. |
creationDateTo | no | End of the search range for "creationDate". Format: 2019-04-30T20%3A59%3A00%2B02%3A00 Date must be url encoded. |
type | no | Operation type. Possible values:
|
currencyCode | no | Currency code according to ISO-4217. You can enter multiple values. Subsequent entries should be separated by a comma. |
sortBy | no | Sorting field. Additional sign + or
- before field name defines sorting order.
Default is ascending. Parameters that can be used to sort the
operation history are as follows:
sortBy=-eventDate will sort results
by eventDate descending. |
limit | no | Number of records per page. |
offset | no | Page number (indexing from 0). |
{ "operations": [ { "type": "PAYMENT_RECEIVED", "amount": "1500", "currencyCode": "PLN", "description": "operation description", "status": "COMPLETED", "creationDate": "2016-04-20T11:05:54+02:00", "eventDate": "2016-04-20T12:05:54+02:00", "details": { "orderId": "CWDBL3KD6G170110GUEST000P01", "extOrderId": "105877825874b0c0b47a0", "counterparties": [ { "extCustomerId": "35463545", "name": "Alice", "email": "alice@email.com", "products": [ { "name": "product-x", "unitPrice": "1500", "quantity": "1" } ] } ], "funds": [] } } ], "pageResponse": { "records": "1", "size": "1", "pageCount": "1" } }
Field | Description |
---|---|
operations | List of operations. |
operations.type |
Operation type. Possible values:
|
operations.amount | Amount (of order, refund, payout). |
operations.currencyCode | Currency code according to ISO-4217. |
operations.description | Operation description. |
operations.status | Operation status. |
operations.creationDate | Operation request moment. Format: 2019-11-30T20:33:44+02:00 |
operations.eventDate | Operation ending moment. Format: 2019-11-30T22:33:44+02:00 |
pageResponse.records | Total number of records found. |
pageResponse.size | Number of returned operations. |
pageResponse.pageCount | Page count. |
Additional response fields for PAYMENT_RECEIVED operation:
Field | Description |
---|---|
operations.details.orderId | Order identifier. |
operations.details.extOrderId | External order identifier. |
operations.details.feeAmount | Marketplace fee amount. |
operations.details.counterparties | Order elements. |
operations.details.counterparties.extCustomerId | Buyer identifier. |
operations.details.counterparties.name | Buyer name. |
operations.details.counterparties.email | Buyer email. |
operations.details.counterparties.products | List of products in order. |
operations.details.counterparties.products.name | Product name. |
operations.details.counterparties.products.unitPrice | Unit price of product. |
operations.details.counterparties.products.quantity | Quantity. |
Additional response fields for REFUND_SENT operation:
Field | Description |
---|---|
operations.details.orderId | Order identifier. |
operations.details.extOrderId | External order identifier. |
operations.details.refundId | Refund identifier. |
operations.details.extRefundId | External refund identifier. |
operations.details.counterparties | Order elements. |
operations.details.counterparties.extCustomerId | Buyer identifier. |
operations.details.counterparties.name | Buyer name. |
operations.details.counterparties.email | Buyer email. |
Additional response fields for PAYOUT operation:
Field | Description |
---|---|
operations.details.payoutId | Payout identifier. |
operations.details.extPayoutId | External payout identifier. |
Additional response fields for RETURN operation:
Field | Description |
---|---|
operations.details.payoutId | Payout identifier. |
operations.details.extPayoutId | External payout identifier. |
Additional response fields for CHERGEBACK and ADMIN_CORRECTION operation:
Field | Description |
---|---|
operations.details.correctionId | Correction identifier. |
curl -v -X GET https://secure.payu.com/api/v2_1/customers/ext/<EXT_CUSTOMER_ID>/balances?currencyCode=PLN \ -H "Content-Type: application/json" \ -H "Authorization: Bearer <AUTH_TOKEN>"
EXT_CUSTOMER_ID
is submerchant identifier.
Request parameters are:
Parameter | Required | Comment |
---|---|---|
currencyCode | yes | Currency code according to ISO-4217. |
{ "balance": { "availableAmount": "5494", "totalAmount": "5500" }, "status": { "statusCode": "SUCCESS" } }
Response fields are:
Field | Comment |
---|---|
balance.availableAmount | Available funds. |
balance.totalAmount | Total submerchant funds (including blocked funds). |
status.statusCode | Response status. |
In marketplace exists possibility to transfer funds between submerchant and marketplace balances.
To enable this functionality, configuration on the PayU side and Compliance consent is required. To enable it please contact us.
client_credentials
for given marketplace is required for this
requests.
curl -X POST https://secure.snd.payu.com/api/v2_1/customers/ext/<EXT_CUSTOMER_ID>/feeDebitTransfer \ -H 'Authorization: Bearer 4b29a650-82b7-4c1b-8b6f-2786edd6d2bd' \ -H 'Content-Type: application/json' \ -H 'Postman-Token: dc779a1e-07d4-4998-bbb6-bb7e0bbbf45b' \ -H 'cache-control: no-cache' \ -d '{ "amount": 25, "currencyCode": "PLN", "description": "Get fee for order XX2ORD2", "extTransferId": "debit-9dbc62be-dfc8-401f-a9f4-79e5013cb734" }'
EXT_CUSTOMER_ID
is submerchant identifier.
Request parameters:
Parameter | Comment |
---|---|
amount | Transfer amount. |
currencyCode | Currency code according to ISO-4217. |
description | Description of the operation. |
extTransferId | Unique transfer identifier for given marketplace. |
{ "extCustomerId": "<extCustomerId>", "extTransferId": "debit-9dbc62be-dfc8-401f-a9f4-79e5013cb734", "status": { "statusCode": "SUCCESS" } }
Response parameters:
Parameter | Comment |
---|---|
extCustomerId | Unique submerchant identifier. |
extTransferId | Unique transfer identifier for given marketpalce. |
status.statusCode | Response status. |
curl -X POST https://secure.snd.payu.com/api/v2_1/customers/ext/<EXT_CUSTOMER_ID>/feeCreditTransfer \ -H 'Authorization: Bearer 4b29a650-82b7-4c1b-8b6f-2786edd6d2bd' \ -H 'Content-Type: application/json' \ -H 'Postman-Token: 9f9a1496-1864-4856-9b50-699fc1e0ef1f' \ -H 'cache-control: no-cache' \ -d '{ "amount": 25, "currencyCode": "PLN", "description": "Return fee for order XXX1ORD", "extTransferId": "credit-63a3e837-ba7e-45a0-b1b5-267e2c237cd6" }'
EXT_CUSTOMER_ID
is submerchant identifier. Request parameters:
Parameter | Comment |
---|---|
amount | Transfer amount. |
currencyCode | Currency code according to ISO-4217. |
description | Description of the operation. |
extTransferId | Unique transfer identifier for given marketplace. |
{ "extCustomerId": "<extCustomerId>", "extTransferId": "debit-9dbc62be-dfc8-401f-a9f4-79e5013cb734", "status": { "statusCode": "SUCCESS" } }
Response parameters:
Parameter | Comment |
---|---|
extCustomerId | Unique submerchant identifier. |
extTransferId | Unique transfer identifier for given marketpalce. |
status.statusCode | Response status. |
HttpStatus | StatusCode | CodeLiteral |
---|---|---|
400 | BUSINESS_ERROR | MARKETPLACE_TRANSFER_EXISTS |
400 | BUSINESS_ERROR | MARKETPLACE_NO_BALANCE |
400 | BUSINESS_ERROR | MARKETPLACE_FEE_TRANSFER_LIMITS_EXCEEDED |