Payment Facilitator

Definition

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.

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.

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.

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).

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.

Request

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

Response

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,
  "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).

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 as payMethods.payMethod.type and PBL as payTypeCategories.

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 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.

{
    "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"
            }
        }
    }
}