Payment Facilitator is a special type of merchant which processes payments and settles its own merchants.
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.
A PF is set up as PayU merchant, but it can sign its own merchants (known as "submerchants" or "sponsored merchants").
PayU provides payment services to the PF and does not directly contract or settle with the submerchants.
Payment processing is a regulated business, therefore there are certain necessary legal and business arrangements to be made before PayU can cede some of its responsibilites to a third party.
Detailed description of these arrangements is out of scope of this documentation, what is however important is that although PayU does not directly settle or contact etc the submerchants, all of the submerchants at any time must be known to PayU and each payment transaction must be made for a single, specific submerchant indicated when the payment is facilitated by the PF.
For example, card schemes like Visa and Mastercard require PayU (which is a member of both of the schemes) to provide submerchant details during card payment authorization and report the submerchants on a cyclical basis.
Therefore it is crucial that the submerchants are registered before any payment is facilitated and the submerchant data is updated whenever any required submerchant data changes.
Initial set up must be performed by PayU before you can register submerchants.
In order to register, update or retrieve a submerchant, you need to obtain OAuth access token (note: you may use any REST API POS ID to get the access token).
Submerchant registration varies depending on payment type category to be used by the
submerchant.
Currently available types are: CARD and PBL (pay-by-link online transfers).
The types should be specified in the payTypeCategories
array. In case payTypeCategory is not provided explicitely, the default value is
CARD.
All submerchants have status
attribute. Depending on status, some or all payments may be blocked.
Status | Allowed payments |
---|---|
ACTIVE | All payment types allowed. |
NOT_ACTIVE | CARD payments not allowed, PBL payments allowed. |
BLOCKED | No payments allowed. |
Submerchant may receive BLOCKED status only in rare cases when suspicious activity has been detected.
Other statuses are assigned automatically depending on submitted submerchant data,
as shown in table below which specifies possible types of registration depending on
values in payTypeCategory
array
(see Data fields for detailed description of submerchant data fields and validations).
payTypeCategories | Required Data Fields | Initial Status |
---|---|---|
CARD,PBL | All fields are required. | NOT_ACTIVE |
CARD | All fields are required. | NOT_ACTIVE |
PBL | Some fields are excluded. | ACTIVE |
Notifications about status change are sent to the URL address specified in notifyUrl
field (see below for details).
Submerchant activation is performed as soon as possible, after necessary checks and registration in card schemes have been performed.
To register a submerchant you need to send a HTTP POST request with Content-Type application/json header
to https://secure.payu.com/api/v2_1/firms/{firmId}/submerchants
where firmId is the public firm id in alphanumeric format.
This id can obtained from the merchant panel.
Below is a sample request body with all possible data fields. The fields are explained in Data fields.
{ "externalId": "your_submerchant_id", "notifyUrl": "https://notification-when-status-changes.will-be-sent.here", "legalName": "Submerchant Ltd", "dbaName": "superstore.com", "address": { "street": "1 Flower St", "city": "Flowerton", "postalCode": "00-000", "countryCode": "PL" }, "phone": "+48 123 123 123", "websiteUrl": "https://www.superstore.com", "mcc": 5999, "debtRepayment": false, "riskClass": "LOW", "taxId": "123123123", "representatives": [ { "name": "Store Owner", "phone": "+48 123 123 123" } ], "legalForm": "SO", "agreementDate": "2021-03-01", "payTypeCategories": ["CARD","PBL"] }
Response code for a successful request is HTTP 200 (OK).
In case of validation errors, HTTP 400 (Bad Request) is returned with validation errors specified in the response body in JSON format.
Below is a sample response body. Data fields are explained in Data fields.
{ "id": "2578ed95-5b69-411d-9a52-743f80504ebe", "externalId": "your_submerchant_id", "status": "NOT_ACTIVE", "lastUpdated": "2021-03-27T10:57:59+00:00", "notifyUrl": "https://notification-when-status-changes.will-be-sent.here", "legalName": "Submerchant Ltd", "dbaName": "superstore.com", "address": { "street": "1 Flower St", "city": "Flowerton", "postalCode": "00-000", "countryCode": "PL" }, "phone": "+48 123 123 123", "websiteUrl": "https://www.superstore.com", "mcc": 5999, "debtRepayment": false, "riskClass": "LOW", "taxId": "123123123", "representatives": [ { "name": "Store Owner", "phone": "+48 123 123 123" } ], "legalForm": "SO", "agreementDate": "2021-03-01", "payTypeCategories": ["CARD","PBL"] }
Each time a status change occurs, a notification in the form of HTTP POST is sent
to notifyUrl
specified for the given submerchant.
You need to respond with HTTP 200 (OK) status to such request and perform Retrieval to check current status.
To update a submerchant you need to send a HTTP PUT request with Content-Type application/json header
to https://secure.payu.com/api/v2_1/firms/{firmId}/submerchants/{submerchantId}
where
{firmId}
is the firm id in alphanumeric format (visible in the merchant panel) and
{submerchantId}
is the id returned by PayU upon submerchant registration.
Response body and HTTP status codes returned from this endpoint are the same as in Registration.
The request body is similar to the body sent for registration
Please note that due to compliance requirements, changing the following fields:
mcc
, riskClass
, representatives
or adding CARD to payTypeCategories
will cause the submerchant to become NOT_ACTIVE, because additional verification may be necessary before card payments are allowed.
Note that status change into NOT_ACTIVE will not block PBL payments.
Below is a sample request body. Data fields are explained in Data fields.
{ "externalId": "your_submerchant_id", "notifyUrl": "https://notification-when-status-changes.will-be-sent.here", "legalName": "Submerchant Ltd", "dbaName": "superstore.com", "address": { "street": "1 Flower St", "city": "Flowerton", "postalCode": "00-000", "countryCode": "PL" }, "phone": "+48 123 123 123", "websiteUrl": "https://www.superstore.com", "taxId": "123123123", "legalForm": "SO", "agreementDate": "2021-03-01", "payTypeCategories": ["CARD","PBL"] }
To retrieve submerchant data you need to send a HTTP GET request
to https://secure.payu.com/api/v2_1/firms/{firmId}/submerchants/{submerchantId}
where
{firmId}
is the firm id in alphanumeric format (visible in the merchant panel) and
{submerchantId}
is the id returned by PayU upon submerchant registration.
Response code returned for a successful request is HTTP 200 (OK).
The response body is the same as response for Registration request.
Other possible code is HTTP 404 (Not Found).
Fields marked as conditionally required need to be sent only if CARD is present in payTypeCategories
.
Parameter | Description | Required |
---|---|---|
id | Id assigned by PayU and required in OrderCreateRequest. | Only present in response |
status | Submerchant status. Enumerated values: NOT_ACTIVE, ACTIVE, BLOCKED. | Only present in response |
lastUpdated | Datetime of resource creation or last update (if applicable) in ISO 8601 format (YYYY-MM-DDThh:mm:ss±hh:mm, e.g. "2021-03-27T10:57:59+00:00"). | Only present in response |
notifyUrl | Notifications regarding submerchant status change will be sent to address provided in this field. | Yes |
externalId | Id assigned by the Payment Facilitator. | Yes |
legalName | Full legal (registration) name. | Yes |
dbaName | "Doing business as" name, usually simplified website address which can be recognized by customer (e.g. when displayed on card statement). | Yes |
address | Legal address object. | Yes |
address.street | Legal address street including house/apartment number (if applicable). | Yes |
address.postalCode | Legal address postal code. | Yes |
address.city | Legal address city. | Yes |
address.countryCode | Legal address country code. Must be a valid ISO 3166-1 two-letter code. | Yes |
phone | Contact phone number. | Conditionally |
websiteUrl | A valid URL address of merchant's website. | Yes |
mcc | Accurate Merchant Category Code established during KYC process by the PF. | Yes |
debtRepayment | Boolean indicating whether submerchant accepts payments on existing debt (i.e. is a loan or debt collection company). Should be true only in conjunction with MCC of 6012 or 6051. | No, defaults to false |
payTypeCategories | Array of enumerated values: CARD, PBL. Minimum one is required. | No (defaults to CARD) |
riskClass | Risk class assigned by Payment Facilitator (basing on requirements provided by PayU). Enumerated values: LOW, NORMAL, HIGH. | Conditionally |
taxId | Tax identification (e.g. NIP in Poland) or business identification (e.g. IČ in Czechia). | Yes |
representatives | Array of either principals or enterprise owners (depends on legal form). Minimum one is required. | Conditionally |
representatives.name | Representative name. | Yes |
representatives.phone | Representative contact phone. | Yes |
legalForm | Dictionary value - legal entity type. Dictionaries for specific origin are available here. | Conditionally |
agreementDate | Date (yyyy-mm-dd, e.g. "2021-05-25") when PF signed agreement with the submerchant (required by Visa for reporting purposes). | Conditionally |
To facilitate payments as a Payment Facilitator you have to integrate with PayU via
the REST API
protocol and extend the OrderCreateRequest with PF specific
submerchant
object and always specify a payment method with
either card
or payMethod.value
.
In case of non-card payments, like pay-by-link online transfers (PBL), please refer
to Transparent integration section
to see example of payMethods
object.
Please note the difference between PBL aspayMethods.payMethod.type
and PBL aspayTypeCategories
.
The former means a payment method available via a link (including redirection to PayU hosted card payment page), the latter denotes alternative payment methods known as pay-by-link transfers. This latter include the following methods: Czech PBLs, Polish PBLs, Slovak PBLs.
In case the payMethod
used for a given submerchant does not fit into payTypeCategories
of this submerchant,
response with HTTP 400 status and body containing status.codeLiteral
set to SUBMERCHANT_PAYTYPE_NOT_ALLOWED will be returned.
Sample request for card payment is shown below. Apart from submerchant
, please note other data specific to card payments:
buyer
with name, email and delivery addressthreeDsAuthentication
with browser and billing addresspayMethods
with full card data (you may also use tokenization)Please check card tokenization and card authentication sections to learn more about data in example below.
{ "continueUrl": "https://after.payment.com/thankyoupage", "notifyUrl": "https://your.eshop.com/notify", "customerIp": "216.72.35.5", "merchantPosId": "1111111", "submerchant": { "id": "2578ed95-5b69-411d-9a52-743f80504ebe" }, "description": "Order with submerchant ID", "currencyCode": "PLN", "totalAmount": 300, "products": [ { "name": "a product", "unitPrice": 300, "quantity": 1 } ], "buyer": { "firstName": "John", "lastName": " ", "phone": "+48 555555555", "email": "john@doe.pl", "delivery": { "street": "Delivery St. 1", "postalCode": "55033", "city": "Delivery Town", "state": "30", "countryCode": "PL" } }, "threeDsAuthentication": { "browser": { "acceptHeaders": "*/*", "screenWidth": "1536", "javaEnabled": false, "timezoneOffset": "-120", "screenHeight": "864", "requestIP": "216.72.35.5", "language": "en", "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:81.0) Gecko/20100101 Firefox/81.0", "colorDepth": "24" }, "cardholder": { "billingAddress": { "street": "Billing St. 1", "postalCode": "33055", "city": "Billington", "state": "30", "countryCode": "PL" } } }, "payMethods": { "payMethod": { "card": { "number": "4444333322221111", "expirationMonth": "02", "expirationYear": "2025", "cvv": "536" } } } }