Referral Program

1 Referral Program

Referral Program allows you to earn money by referring merchants to PayU.
The Referral Program is aimed at all businesses who want to partner with PayU. This applies especially to all kinds of e-commerce platforms and web-developers integrating payment services for their customers.

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.

2 Registration via link

Registration link is the easiest way to register the referred merchants in the PayU system.

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.

Parameter Description
nsf Optional. If this value is present and set to true, the merchant will be registered without accepting online agreement in the process. This option can be used if your merchants are not subject to the standard PayU merchant agreement.
partnerId Your Partner ID provided by PayU.
lang Optional. If not present, the default value will be used. Possible values: 'en' (English, default), pl (Polish).

3 Terms and Conditions

Terms and Conditions of the Referral Program valid from 1st Apr 2017 are available for download here.

Previous version is here.

4 Program branding

Graphic materials for download:

Standard

Alternate

5 Registration via API

Use Merchant Registration API to register merchants in the PayU system directly from your website.

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.

5.1 Preface

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.

5.2 Overview

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.

5.3 Firm creation

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.

curl -X POST https://secure.snd.payu.com/api/v2_1/firms \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer d9a4536e-62ba-4f60-8017-6053211d3f47" \
    -d '{
            "name": "Testowa sp. z o.o.",
            "type": "SO",
            "taxId": "3771910486",
            "taxIdType": "NIP",
            "cin": "138237420",
            "bankAccount": "PL92906300080597567560803897",
            "partnerId": "egmcvdo5",
            "businessArea": {
                "origin": "PL"
            },
            "users": [
                {
                    "name": "Jan",
                    "surname": "Nowak",
                    "email": "jan.nowak@testowa.pl",
                    "phone": "123123123",
                    "role": "manager"
                }
            ],
            "representatives": [
                {
                    "name": "Jan",
                    "surname": "Nowak",
                    "nin": "80010104578",
                    "countryCode": "PL"
                }
            ],
            "contactData": {
                "phone": "123123123",
                "email": "biuro@@testowa.pl"
            },
            "address": {
                "street": "Grunwaldzka",
                "houseNo": "186",
                "apartmentNo": "1",
                "postalCode": "61-166",
                "city": "Poznań",
                "countryCode": "PL"
            }
       }'
curl -X POST https://secure.snd.payu.com/api/v2_1/firms \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer a9a4536e-62ba-4f60-8017-6053211d3f47" \
    -d '{
            "name": "e-shop a.s.",
            "type": "AS",
            "cin": "138237420",
            "taxIdType": "VAT_EU",
            "bankAccount": "2000145399/0800",
            "partnerId": "egmcvdo5",
            "businessArea": {
                "origin": "CZ"
            },
            "users": [
                {
                    "name": "Jana",
                    "surname": "Nováková",
                    "email": "jana@e-shop.cz",
                    "role": "MANAGER"
                }
            ],
            "representatives": [
                {
                    "name": "Jana",
                    "surname": "Nováková",
                    "countryCode": "CZ",
                    "birthDate": "1990-01-01"
                }
            ],
            "contactData": {
                "phone": "123123123",
                "email": "office@@e-shop.cz"
            },
            "address": {
                "street": "Antala Staška",
                "houseNo": "2027",
                "apartmentNo": "77",
                "postalCode": "140 00",
                "city": "Praha",
                "countryCode": "CZ"
            }
        }'

In response, you will receive firmId which needs to be stored in your system and will be used to create further entities for that firm.

{
    "firmId": "KzXy4ZzD"
}

5.4 Firm OAuth

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

5.5 URL creation

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

Parameter Description Required
value URL address Yes
services Array of service types. Yes
service.type Dictionary value. Possible values:
  • TRANSFERS - online transfers ("pay-by-links" and standard bank transfers, incl. Blik),
  • CARDS - cards (Visa, Mastercard) and digital wallets (Apple Pay, Google Pay, Masterpass, Visa Checkout),
  • INSTALLMENTS - online installments,
  • DELAYED_PAYMENTS - "pay later" methods.
Yes

5.6 Shop creation

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

Parameter Description Required
name Shop name - will be visible in the merchant panel. Yes
description Shop description - more detailed info, visible in the merchant panel. No
currencyCode Must be a three-letter ISO 4217 currency code. Please contact your key account manager to get more information about available currencies. Yes
urlId Reference to previously created URL. Yes

5.7 POS creation

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"
              }
          }
      }
  
Parameter Description
posId Public POS ID.
type POS type (determines API that can be used).
encoding Determines encoding used by PayU system to read API requests. Always UTF-8 for REST type.
authorization.standard.merchantPosId POS identifier used for API calls.
authorization.standard.key First API key (client_id) used to obtain OAuth access tokens for REST API calls.
authorization.standard.secondKey Second API key (client_id) used to sign REST API forms and to validate notifications.
authorization.standard.authKey Not required for REST API.

5.8 Firm parameters

Parameter Description Required
partnerId Your partner id. Yes
businessArea.origin Denotes firm origin and applies validation and requirements for this origin. Currently only two values are available: CZ and PL. Note: it is still possible to register a firm which is incorporated outside of Czechia or Poland. Yes
name Full legal name. Yes
type Dictionary value - legal entity type. Dictionaries for specific origin are available here. For a firm which address.countryCode is not equal to businessArea.origin please use FZ type. Note: providing accurate type speeds up merchant verification. Yes
taxId Tax identification. Yes for PL origin. No for CZ.
taxIdType Type of tax identification. Possible values:
  • NIP - firm registered in Poland for VAT purposes,
  • VAT_EU - firm registered for VAT purposes in the EU, outside of Poland,
  • TAX_ID - tax id from outside of the EU.
Yes
cin Business identification. E.g. IČ (CZ) or REGON (PL). Yes
bankAccount Primary bank account to receive payouts for payments. Will be inherited by all shops created for this firm. Must be a valid IBAN number in case of firms with PL origin. Note: different bank account maybe defined at shop level manually, via PayU merchant panel. Yes
users Array of PayU panel users. At least 1 must be provided. Yes
user.name User's first name. Yes
user.surname User's last name. Yes
user.email User's email. Yes
user.phone User's phone number. No
user.role User's role. Possible values:
  • MANAGER - user with full access,
  • USER - user with limited accesss (scope maybe defined in PayU panel by a manager).
At least 1 manager must be provided.
Yes
representatives Array of firm legal representatives. At least 1 must be provided. Yes
representative.name Representative's first name. Yes
representative.surname Representative's last name. Yes
representative.countryCode Representative's citizenship. Must be a valid ISO 3166-1 two-letter code. Yes
representative.nin Representative's national identity number (PESEL). Yes (only for Polish citizens)
representative.birthDate Representative's date of birth. Yes (only for non-Polish citizens)
contactData Object containing firm's contact details. Yes
contactData.email Firm's contact email address. Yes
contactData.phone Firm's contact phone number. Yes
technicalContactData Object containing firm's technical contact details (e.g. to the developer responsible for integration with PayU). No
address Firm's registration address. Yes
address.street Firm's registration address street. Yes
address.houseNo Firm's registration address house number. Yes
address.apartmentNo Firm's registration address apartment number. Yes
address.postalCode Firm's registration address postal code. Yes
address.city Firm's registration address city. Yes
address.countryCode Firm's registration address country code. Must be a valid ISO 3166-1 two-letter code. Yes
correspondenceAddress Firm's correspondence address (if other than registration address). This object the same fields as address. No

5.9 Firm type values

Type pl en cs
PP jednoosobowa działalność gospodarcza sole trader podnikající fyzická osoba tuzemská
SO spółka z ograniczoną odpowiedzialnością limited liability company společnost s ručením omezeným
SC spółka cywilna civil law partnership občanské sdružení
SJ spółka jawna general partnership komora (hospodářská, agrární)
SA spółka akcyjna joint-stock company akciová společnost
FU fundacja foundation nadace
SK spółka komandytowa limited liability partnership společnost komanditní
ST stowarzyszenie association spolek
SP spółka partnerska professional partnership samosprávná stavovská organizace (profesní komora)
SD spółka komandytowo-akcyjna limited joint-stock partnership společnost komanditní na akcie
PO placówka oświaty educational institution školská právnická osoba
SPOL spółdzielnia cooperative družstvo
KOP kościelna osoba prawna lub jej jednostka organizacyjna church legal person evidované církevní právnické osoby
JST jednostka samorządu terytorialnego local government unit obec, kraj, městská část, městský obvod
IB instytut badawczy research institute veřejná výzkumná instituce
PPZ przedstawicielstwo przedsiębiorstwa zagranicznego agency of foreign company odštěpný závod zahraniční právnické osoby
PRPA przedsiębiorstwo państwowe state company státní podnik
SIK publiczna instytucja kultury public culture institution veřejná kulturní instituce
FZ zagraniczna osoba prawna foreign legal body zahraniční spolek

5.10 Further actions

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: