BLIK OneClick

1 BLIK OneClick

BLIK payments can be configured in several ways, the simplest of which is redirection. Customers enter a six-digit code on the BLIK website and confirm the payment in their bank's mobile application. However, BLIK payments can be even faster and more convenient, thanks to a transparent integration with PayU.

Each of these solutions (payment with redirection to eblik.pl or with a transparent integration) require a separate POS.

Possible test scenarios:

Scenario 1.

BLIK level 0 (transparent payment with a T6 code)

The six-digit code, which customers start their payment with, doesn't have to be entered on the BLIK website. Merchant can retrieve the code on their website while accepting the order.

  1. OAuth authorize (retrieving access_token)
  2. BLIK OCR code (creating order with T6 payment)
  3. Order Retrieve (checking order status)

Scenario 2.

BLIK level 0 with token registration (transparent payment with T6 code)

Each time a customer enters the T6 code, merchant can send a request to register BLIK token. Then, when confirming the transaction in the bank's mobile application, a customer will have an additional option to save the BLIK payment (no additional buttons are needed on the merchant's website).

  1. OAuth authorize (retrieving access_token)
  2. BLIK OCR - token registered by PayU (creating order with a T6 payment + token registration)
  3. PayU automatically activates the token
  4. Order Retrieve (checking the order status)
  5. PayMethods Retrieve (retrieving payment methods – a BLIK token appears)

Scenario 3.

BLIK OneClick (transparent payment with a token)

If customers saved a token durign their last BLIK payment, they can now pay with OneClick without entering a new code.

  1. BLIK OCR - pay with a token ( a token-only payment)
  2. Order Retrieve (checking the order status)
  3. PayMethods Retrieve (retrieving payment methods – a BLIK token appears)

Scenario 4.

Handling ambiguity (transparent payment with more than a single token)

Customers can have accounts in several banks and use BLIK in each of them. If a merchant saves a BLIK token from one bank, ambiguity occurs after an attempt to make a BLIK payment from another bank. PayU allows to handle such exception and lets the customer choose from many saved OneClick options.

Handling ambiguity can be tested in two stages. Steps 1-3 show ambiguity generation. Steps 4-6 simulate OneClick payment when ambiguity occurs.

  1. OAuth authorize (retrieving access token)
  2. PayMethods Retrieve (retrieving payment methods; missing token for given customer)
  3. BLIK OCR - register a non-unique token (non-unique token registration)
  4. PayMethods Retrieve (retrieving payment methods – a token appears in response)
  5. BLIK OCR - pay with a token (payment with a non-unique token)
  6. BLIK OCR - pay with a non-unique token (payment with a non-unique token and introduced alternative)

Information related to testing this service can be found in the Sandbox section.

2 Examples of scenarios implementation

2.1 BLIK level 0

Retrieving OAuth token:

                curl -X POST https://secure.snd.payu.com/pl/standard/oauth/authorize \
                 -d 'grant_type=trusted_merchant&client_id=300746&client_secret=2ee86a66e5d97e3fadc400c9f19b065d&email=johndoe@gmail.com&ext_customer_id=JohnDoe'
                 
            

Specification of Retrieve OAuth token parameters

Parameter Description
email Buyer e-mail address.
ext_customer_id Buyer identifier used in merchant system.

Sample response:

                {
                    "access_token": "f24bbf9b-30f0-4460-864f-aaadc07d1e34",
                    "token_type": "bearer",
                    "refresh_token": "b7a4375a-d4fc-41a0-a380-a9dd8c2e9193",
                    "expires_in": 43199,
                    "grant_type": "trusted_merchant"
                }
            

Sample order with OAuth token:

BLIK level 0 order creation is consistent with standard integration method via REST API: Creating new order. Standard OrderCreateRequest should be extended by payMethod field.

                   curl -X POST https://secure.snd.payu.com/api/v2_1/orders \
                    -H "Authorization: Bearer d9a4536e-62ba-4f60-8017-6053211d3f47" \
                    -H "Content-Type: application/json" \
                    -d '{
                        "currencyCode": "PLN",
                        "totalAmount": "21000",
                        "description": "Transakcja testowa",
                        "notifyUrl": "https://your.eshop.com/notify",
                        "customerIp": "127.0.0.1",
                        "merchantPosId": "300746",
                        "products": [
                            {
                                "name": "Wireless Mouse for Laptop",
                                "unitPrice": "21000",
                                "quantity": "1"
                            }
                        ],
                        "payMethods": {
                            "payMethod": {
                                "type": "PBL",
                                "value": "blik",
                                "authorizationCode": "777123"
                            }
                        }
                   }'
                

Specification of OrderCreateRequest parameters

Parameter Description
payMethod/type Payment method type.
payMethod/value Payment type.
payMethod/authorizationCode For transparent integration of BLIK: this field allows to retrieve a T6 code on the merchant's page without redirecting to the BLIK website. See more about transparent integration.

After payment is made PayU sends notification to the address specified in notifyURL parameter. More details about notifications can be found in Notifications section.

Sample order response:

                {
                    "orderId": "LDTD3S2WWC181109GUEST000P01",
                    "status": {
                        "statusCode": "SUCCESS"
                    }
                }
            

orderId parameter is returned in response to the created order. orderId is an identifier of a given order and it is used for Order Retrieve request.

2.2 Transparent BLIK payment with token registration

Sample order:

In order to allow to save a token for later use with OneClick transactions, payMethod section should be extended by blikData field with"register": true flag.

                curl -X POST https://secure.snd.payu.com/api/v2_1/orders \
                 -H "Authorization: Bearer d9a4536e-62ba-4f60-8017-6053211d3f47" \
                 -H "Content-Type: application/json" \
                 -d '{
                     "currencyCode": "PLN",
                     "totalAmount": "21000",
                     "description": "Testowa transakcja",
                     "notifyUrl": "https://your.eshop.com/notify",
                     "customerIp": "127.0.0.1",
                     "merchantPosId": "300746",
                     "buyer": {
                         "extCustomerId": "JohnDoe",
                         "email": "johndoe@gmail.com"
                     },
                     "products": [
                         {
                             "name": "Wireless Mouse for Laptop",
                             "unitPrice": "21000",
                             "quantity": "1"
                         }
                     ],
                     "payMethods": {
                         "payMethod": {
                             "type": "BLIK_TOKEN",
                             "authorizationCode": "777123",
                             "blikData": {
                                 "register":true
                             }
                         }
                     }
                }'
            
OCR parameters specification:
Parameter Description
payMethod/blikData/register Allows to save a token for later use. Possible values:
  • true - only in this case a user will see the option to save a token,
  • false.

PayMethods Retrieve

The following request retrieves payment methods including the BLIK token.
                curl -X GET https://secure.snd.payu.com/api/v2_1/paymethods \
                 -H "Authorization: Bearer d9a4536e-62ba-4f60-8017-6053211d3f47"
            
The BLIK token is returned in the blikTokens section:
            {
                "blikTokens": [
                    {
                        "value": "TOKB_nuGYkknycEp3NDWAN2hh1c7FLnXseaLX",
                        "type": "UID",
                        "brandImageUrl": "https://static.payu.com/images/mobile/logos/pbl_blik.png"
                    }
                ],
                "cardTokens": [],
                "pexTokens": [],
                "payByLinks": [
                    {
                        "value": "blik",
                        "brandImageUrl": "https://static.payu.com/images/mobile/logos/pbl_blik.png",
                        "name": "BLIK",
                        "status": "ENABLED"
                    },
                    {
                        "value": "p",
                        "brandImageUrl": "https://static.payu.com/images/mobile/logos/pbl_p.png",
                        "name": "Płacę z iPKO",
                        "status": "ENABLED"
                    },
                    {
                        "value": "m",
                        "brandImageUrl": "https://static.payu.com/images/mobile/logos/pbl_m.png",
                        "name": "mTransfer",
                        "status": "ENABLED"
                    },
                    ... //pojawiają się pozostałe dostępne metody płatności
                    {
                        "value": "c",
                        "brandImageUrl": "https://static.payu.com/images/mobile/logos/pbl_c.png",
                        "name": "Płatność online kartą płatniczą",
                        "status": "ENABLED"
                    }
                ],
                "status": {
                    "statusCode": "SUCCESS"
                }
            }
            

PayMethods Retrieve - response parameters specification:

For blikTokens section:

Parameter Description
value Token value.
type Token type.
brandImageUrl Reference to the graphic file on the PayU server, representing the payment type.

2.3 Transparent payment with a token

Sample transparent payment with a token:

A token generated during first transaction is passed in the payMethod field. The payer doesn't have to enter the T6 code.

                curl -X POST https://secure.snd.payu.com/api/v2_1/orders \
                 -H "Authorization: Bearer d9a4536e-62ba-4f60-8017-6053211d3f47" \
                 -H "Content-Type: application/json" \
                 -d '{
                     "currencyCode": "PLN",
                     "totalAmount": "21000",
                     "description": "Transakcja testowa",
                     "notifyUrl": "https://your.eshop.com/notify",
                     "customerIp": "127.0.0.1",
                     "merchantPosId": "300746",
                     "buyer": {
                         "extCustomerId": "JohnDoe",
                         "email": "johndoe@gmail.com"
                     },
                     "products": [
                         {
                             "name": "Wireless Mouse for Laptop",
                             "unitPrice": "21000",
                             "quantity": "1"
                         }
                     ],
                     "payMethods": {
                         "payMethod": {
                             "type": "BLIK_TOKEN",
                             "value": "TOKB_nuGYkknycEp3NDWAN2hh1c7FLnXseaLX"
                         }
                     }
                }'
            

OrderCreateRequest parameters specification

Parametr Description
payMethod/value BLIK token value.

2.4 Handling ambiguity scenario

Non-unique token registration

               curl -X POST https://secure.snd.payu.com/api/v2_1/orders \
                -H "Authorization: Bearer d9a4536e-62ba-4f60-8017-6053211d3f47" \
                -H "Content-Type: application/json" \
                -d '{
                    "currencyCode": "PLN",
                    "totalAmount": "21000",
                    "description": "Transakcja testowa",
                    "notifyUrl": "https://your.eshop.com/notify",
                    "customerIp": "127.0.0.1",
                    "merchantPosId": "300746",
                    "buyer": {
                        "extCustomerId": "JohnDoe",
                        "email": "johndoe@gmail.com"
                    },
                    "products": [
                        {
                            "name": "Wireless Mouse for Laptop",
                            "unitPrice": "21000",
                            "quantity": "1"
                        }
                    ],
                    "payMethods": {
                        "payMethod": {
                            "type": "BLIK_TOKEN",
                            "value": "SIMULATE_ALIAS_NON_UNIQUE",
                            "authorizationCode": "777123",
                            "blikData": {
                                "register":true
                            }
                        }
                    }
                }'
            
Parameter Description
payMethod/blikData/register Allows to save a token for later use. Possible values:
  • true - only in this case a user will see the option to save a token,
  • false.
payMethod/value A unique identifier that allows to test ambiguity. For testing purposes its value should be set to: "SIMULATE_ALIAS_NON_UNIQUE" + a random string of digits and/or characters.
SIMULATE_ALIAS_NON_UNIQUE is a constant, thanks to which it is possible to generate ambiguity on the sandbox. On the production environment ambiguity occurs when a payment is made by a user, who had used T6 codes from mobile applications of different banks.

Payment with a non-unique token and introduced alternative

Sample BLIK OrderCreateRequest with introduced alternative.

                curl -X POST https://secure.snd.payu.com/api/v2_1/orders \
                    -H "Authorization: Bearer d9a4536e-62ba-4f60-8017-6053211d3f47" \
                    -H "Content-Type: application/json" \
                    -d '{
                        "currencyCode": "PLN",
                        "totalAmount": "21000",
                        "description": "Transakcja testowa",
                        "notifyUrl": "https://your.eshop.com/notify",
                        "customerIp": "127.0.0.1",
                        "merchantPosId": "300746",
                        "buyer": {
                            "extCustomerId": "JohnDoe",
                            "email": "johndoe@gmail.com"
                        },
                        "products": [
                            {
                                "name": "Wireless Mouse for Laptop",
                                "unitPrice": "21000",
                                "quantity": "1"
                            }
                        ],
                        "payMethods": {
                            "payMethod": {
                                "type": "BLIK_TOKEN",
                                "value": "SIMULATE_ALIAS_NON_UNIQUE",
                                "blikData": {
                                    "appKey":"930872"
                                }
                            }
                        }
                    }'
            

Parameter Description
payMethod/blikData/appKey Optional BLIK mobile application key.

3 Error status codes

If an invalid request is sent, the response will contain an error status, code and description according to the following table.

Error StatusCodes
HTTP status StatusCode/
CodeLiteral
Description
400
ERROR_TOKEN/
AUTH_TOKEN_NONUNIQUE
The used payment token is assigned to several devices/bank applications. It is required to provide an alternative to the used token. List of available alternatives is shown in OrderCreateResponse:
{
    "blikData":{
        "alternatives":[
            {
            "appKey":"alternative key",
            "appLabel":"alternative label"
            }
        ]
    }
}
400 ERROR_TOKEN/
AUTH_TOKEN_NOT_FOUND
The specified payment token does not exist.
400 ERROR_TOKEN/
AUTH_TOKEN_EXISTS
The user already has a payment token with a different value. If the user has another active token, it should be retrieved via payMethods. In case the user has another token, which has not yet been activated, its value will be displayed in the response:
{
    "blikData":{
        "tokens":[
            {
            "value":"token value",
            "type":"token type"
            }
        ]
    }
}
400 ERROR_TOKEN/
AUTH_TOKEN_NOT_ACTIVE
The used payment token was not saved by the user.
400 ERROR_AUTHORIZATION_CODE/
AUTH_CODE_EXPIRED
The authorization code has expired.
400 ERROR_AUTHORIZATION_CODE/
AUTH_CODE_EXCEEDED
The authorization code limit has been exceeded.
400 ERROR_AUTHORIZATION_CODE/
AUTH_CODE_CANCEL
The authorization code has been cancelled.
400 ERROR_AUTHORIZATION_CODE/
AUTH_CODE_USED
The authorization code has already been used.
400 ERROR_AUTHORIZATION_CODE/
AUTH_CODE_INVALID
Invalid authorization code.
201* WARNING_CONTINUE_TOKEN
201* WARNING_CONTINUE_​AUTHORIZATION_CODE
400 ERROR_VALUE_MISSING/
MISSING_AUTHORIZATION_CODE.
Validation error, authorization code required.
400 ERROR_VALUE_MISSING/
MISSING_REGISTER_FLAG
Validation error, token registration flag required.
400 ERROR_VALUE_MISSING/
MISSING_AUTHORIZATION_​CODE_OR_TOKEN
Validation error, authorization data required: authorization code or token.
400 ERROR_VALUE_MISSING/
INVALID_CURRENCY_CODE
Currency code invalid. Supported currency: PLN.
400 ERROR_VALUE_MISSING/
MISSING_BUYER
Validation error, buyer section missing.
400 ERROR_VALUE_MISSING/
MISSING_BUYER_EMAIL
Validation error, missing email field in buyer section.
400 ERROR_VALUE_MISSING/
MISSING_BUYER_EXT_​CUSTOMER_ID
Validation error, missing extCustomerId field in buyer section.

*To be implemented when the PSP delivers the change on their side. From the start merchant must be prepared to accept both response statuses. In the first integration phase, merchant supports (ERROR_AUTH_TOKEN, WARNING_CONTINUE_AUTH_TOKEN) in the same way.

4 Sandbox

Postman collection for scenario testing purposes:

It is possible to test this service on sandbox environment. For this purpose you can use the already prepared Postman collection.

Depending on the T6 code used (authorizationCode) it is possible to obtain:

  • 777123 - positive authorization,
  • 500500 - negative authorization.

Codes for simulating transactions with an incorrect T6 code

T6 Code StatusCode CodeLiteral
700701 ERROR_AUTHORIZATION_CODE AUTH_CODE_EXPIRED
700702 ERROR_AUTHORIZATION_CODE AUTH_CODE_CANCEL
700703 ERROR_AUTHORIZATION_CODE AUTH_CODE_USED