Payment Facilitator

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.

Arrangements and Obligations

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.

While an in-depth explanation of these procedures is beyond the scope of this documentation, a key point to understand is that although PayU doesn't engage in direct settlement or communication with submerchants, it's imperative for PayU to have knowledge of all submerchants. Additionally, every 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.

Submerchants

PayU needs to perform the initial setup before you can proceed with registering submerchants.

In order to register, update or retrieve a submerchant, you need to obtain OAuth access token.

Notes

You may use any REST API POS ID to get the access token.

The registration process for submerchants varies based on the payment type category they intend to use. Currently, the available types are CARD and PBL (pay-by-link online transfers). These types should be specified within the payTypeCategories array. If the payTypeCategory is not explicitly provided, the default value is set to CARD.

All submerchants have status attribute. Depending on status, some or all payments may be blocked.

Possible Submerchant Statuses

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.

Field Requirements in Relation to the status

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

For details on parameters, please refer to the Payment Facilitator section in our API Reference.

Notifications about status change are sent to the URL address specified in notifyUrl field (see below for details).

Submerchant activation is initiated as swiftly as possible, following essential verifications and completion of registration processes with card schemes.

Registering Submerchants

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.

Notes

You can locate the firmId parameter within the merchant panel.

Registrion Request Body Example
{
  "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,
  "riskClass": "LOW",
  "taxId": "123123123",
  "representatives": [
    {
      "name": "Store Owner",
      "phone": "+48 123 123 123"
    }
  ],
  "legalForm": "SO",
  "agreementDate": "2021-03-01",
  "payTypeCategories": ["CARD", "PBL"]
}

For details on parameters, plese refer to the Payment Facilitator section in our API Reference.

Response code for a successful request is HTTP 200 (OK). If validation errors occur, the server will return an HTTP 400 (Bad Request) response. The validation errors will be outlined in the response body in JSON format.

Registration Response Example
{
  "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,
  "riskClass": "LOW",
  "taxId": "123123123",
  "representatives": [
    {
      "name": "Store Owner",
      "phone": "+48 123 123 123"
    }
  ],
  "legalForm": "SO",
  "agreementDate": "2021-03-01",
  "payTypeCategories": ["CARD", "PBL"]
}

For details on parameters, please refer to the Payment Facilitator section in our API Reference.

Notifications

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 submerchants data retrieval to check current status.

Updating Submerchants Data

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 identifier in alphanumeric format (visible in the merchant panel) and submerchantId is the identifier returned by PayU upon submerchant registration.

Response body and HTTP status codes returned from this endpoint are the same as in Registering Submerchants section.

The structure of the request body is similar to the one used for the registration process.

Please note that due to compliance requirements, changing the 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.

Notes

Status change into NOT_ACTIVE will not block PBL payments.

Update Request Body Example
{
  "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"]
}

For details on parameters, please refer to the Update Submerchants Data section in our API Reference.

Retrieving Submerchants Data

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 identifier in alphanumeric format (visible in the merchant panel) and submerchantId is the identifier returned by PayU upon submerchant registration.

Response code returned for a successful request is HTTP 200 (OK). Other possible code is **HTTP 404 (Not Found).

The response body is the same as response for registration request.

For details on the request, please refer to the Retrieve Submerchant Data section in our API Reference.

Extending the Order Request

To facilitate payments as a Payment Facilitator you have to integrate with PayU via the REST API protocol and extend the standard request body 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 see the Create an Order section in our API Reference. This section contains an example of the payMethods object that you can refer to.

Notes

There is a difference between PBL as payMethods.payMethod.type and PBL as payTypeCategories.

The former refers to a payment method accessible through a link, which can involve redirection to PayU's hosted card payment page. The latter signifies alternative payment methods known as pay-by-link transfers. This category encompasses the following methods: Czech PBLs, Polish PBLs, Slovak PBLs.

If the payMethod utilized for a specific submerchant does not align with the payTypeCategories assigned to that submerchant, the response will include an HTTP 400 status. The response body will contain the status.codeLiteral parameter set to SUBMERCHANT_PAYTYPE_NOT_ALLOWED.

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 address,
threeDsAuthentication with browser and billing address,
payMethods 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.

Body Exmple of a Card Payment as a PF
{
  "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"
      }
    }
  }
}

Arrangements and Obligations​

Submerchants​

Registering Submerchants​

Notifications​

Updating Submerchants Data​

Retrieving Submerchants Data​

Extending the Order Request​

On this page

Arrangements and Obligations

Submerchants

Registering Submerchants

Notifications

Updating Submerchants Data

Retrieving Submerchants Data

Extending the Order Request