Referral Program

If you are interested in the Program and would like to learn more about remuneration and business terms and how to become a participant, please contact us at partnerzy@payu.pl.

Below you can find information on how to register a merchant, so we can recognize it was referred by you and remunerate you.

Please note that currently only merchants willing to do business in Poland can be registered using the link

The link can be sent to potential merchants via email or embedded into your website. It can be used multiple times and anybody clicking it will be redirected to PayU registration process. Any business who completes the registration will be flagged as referred by you.

The link looks like this:

https://secure.payu.com/boarding/#/form?lang=pl&nsf=false&partnerId=someid

The three parameters which can be used in the link are described below.

Previous version is here.

Merchant Registration API allows participants of the Referral Program ("partners") to create merchant entities in the PayU system. It is especially meant for payment service integrators and SaaS platform operators.

Merchant Registration API assumes that despite automated merchant creation facilitated by the partner, PayU performs the following processes:

1. merchant verification through KYC (Know-Your-Customer) procedure, including AML (Anti-Money-Laundering) check,
2. merchant agreement conclusion, usually online via the merchant panel,
3. merchant activation to allow payment acceptance.

For the sake of this documentation, "merchant" means a full set of entities which designate a type of customer which creates payments and receives money from payers.

In short, these entities are:

1. Firm - merchant's legal entity (name, address, tax id etc.).
2. URL - address of the online shop, charity or other paid service.
3. Shop - payment currency, balance and payout details (incl. merchant's bank account) are defined at this level.
4. POS (point of sale) - available payment methods are configured here. Payment orders are created at this level.

To use the Registration API, you need to become registered as a "partner" (i.e. sign in to the PayU referral program) and obtain your client_id and client_secret to authenticate API calls.

The registration API is available in the PayU sandbox.

To start quickly just use these test partner credentials before you get your production ones:

• client_id = egmcvdo5
• client_secret = 9e0cad643b2d4f0bc1fe1750b9b706ec

A full flow to create a new merchant in the PayU system:

1. Obtain OAuth access token to create new firm.
2. Create new firm, receive public firmId.
3. For enhanced security, obtain another, firm-specific OAuth access token to add further entities to the firm.
4. Create new URL, receive public urlId.
5. Create new shop, using the URL to denote shop's URL, receive public shopId.
6. Create new POS for the shop, receive posId.
7. Obtain POS config details and add them to your SaaS platform to create payment transactions on behalf of the merchant.
8. Obtain OAuth 2 access token to retrieve payment methods with status.
9. Retrieve payment methods with status. Initially, POS is configured with a disabled test payment method only and without payout schedule configured. Addition of other payment methods in enabled status means merchant activation in PayU.

OAuth

You authenticate with OAuth standard by obtaining a token, which is used for further communication with PayU servers.

Request example for obtaining access token in the PayU sandbox:

curl -X POST 'https://secure.snd.payu.com/pl/standard/user/oauth/authorize' \
    -d 'grant_type=client_credentials' \
    -d 'client_id=egmcvdo5' \
    -d 'client_secret=9e0cad643b2d4f0bc1fe1750b9b706ec'

Response example:

{
    "access_token":"7524f96e-2d22-45da-bc64-778a61cbfc26",
    "token_type":"bearer",
    "expires_in":43199, //expiration time in seconds
    "grant_type":"client_credentials"
}

Creating firm

Below are examples of a request with the minimum necessary data to create a Czech and Polish Firm entity. For more detailed description of the request fields, see Firm parameters.

To create further entities within a previously created firm, you need to get a firm-specific access token.

Request example for obtaining access token in the PayU sandbox:

curl -X POST 'https://secure.snd.payu.com/pl/standard/user/oauth/authorize' \
    -d 'grant_type=partner' \
    -d 'client_id=egmcvdo5' \
    -d 'client_secret=9e0cad643b2d4f0bc1fe1750b9b706ec' \
    -d 'firm_id=nZzFT4I5'

Response example:

{
    "access_token": "2f8fc432-81df-4cc6-8286-d1115214aca5",
    "token_type": "bearer",
    "refresh_token": "c4326c52-53b0-4191-850c-cb52a9f8da4c",
    "expires_in": 43199,
    "grant_type": "partner"
}

After creating a firm and obtaining firm-specific OAuth access token, next thing to do is to create a URL.

URL should be a real address where the "customer journey" starts (like e.g. online shop or charity website etc.).

Desired payment services need to be indicated when creating URL.

Endpoint address contains firmId in the path.

Request example

               curl -X POST 'https://secure.snd.payu.com/api/v2_1/firms/KzXy4ZzD/urls' \
               -H "Content-Type: application/json" \
               -H "Authorization: Bearer d9a4536e-62ba-4f60-8017-6053211d3f47" \
               -d '{
               "value":"http://www.test-url.com",
               "mcc": "0742",
               "services":[
                  {
                  "type":"TRANSFERS"
                  },
                  {
                  "type":"CARD"
                  }
                 ]
               }'
   

In response, you will receive urlId which needs to be stored in your system and will be used to create shop.

    {
       "urlId": "PItR5x0v"
    }
  

Request params

After creating a firm and URL, you need to create a shop.

Shop requires a reference to URL and is used to store payment account balance, therefore the most important parameter is the currency.

Endpoint address contains firmId in the path.

Request example

               curl -X POST 'https://secure.snd.payu.com/api/v2_1/firms/KzXy4ZzD/shops' \
               -H "Content-Type: application/json" \
               -H "Authorization: Bearer d9a4536e-62ba-4f60-8017-6053211d3f47" \
               -d '{
                     "name":"Shop name",
                     "description":"Shop description",
                     "currencyCode":"EUR",
                     "urlId":"PItR5x0v"
                 }'
   

In response, you will receive shopId which needs to be stored in your system and will be used to create POS.

       {
           "shopId": "ycmGyfCv"
       }
  

Request params

POS (point of sale) is the last entity you need to create.

POS is created at shop level and inherits its currency. Credentials to authenticate payments are stored on POS.

Endpoint address contains shopId in the path.

Request example

               curl -X POST https://secure.snd.payu.com/api/v2_1/shops/ycmGyfCv/poses \
               -H "Content-Type: application/json" \
               -H "Authorization: Bearer d9a4536e-62ba-4f60-8017-6053211d3f47" \
               -d '{
                     "name":"Test POS",
                     "type":"REST"
                 }'
   

In response, you will receive posId which needs to be stored in your system to obtain POS data.

       {
           "posId": "JyoMIVTY"
       }
  

The request params contain POS name and type. REST is the default type and allows to integrate payments via REST API.

In rare cases when a legacy CLASSIC type needs to be used, please contact PayU technical support for further guidance.

Obtaining POS credentials

     curl -X POST 'https://secure.snd.payu.com/api/v2_1/poses/JyoMIVTY' \
     -H 'Authorization: Bearer d9a4536e-62ba-4f60-8017-6053211d3f47'
    

In response, you will receive a full set of credentials which will allow you to authenticate payments and refunds and check payment status notifications.

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

After obtaining POS credentials, you may consider not only using them integrate payment services specified in REST API reference, but also non-payment API calls, like:

• Available payment methods retrieval, note: payment methods are returned only after merchant has been activated.
• Available merchant account balance retrieval.
• Payout facilitation.