QR NBU PayIn

In Payonhost QR NBU PayIn service allows you to create a QR code for payment using a banking application. QR code is generated according to standard of NBU (National Bank of Ukraine).

Scenario of interaction

1. Client clicks on the Payment button and selects the Payment by QR code method
2. Merchant executes a request to generate a QR code by transmitting payment details
3. In response you receive a link to a form with a QR code and a button to go to the bank's application
4. Merchant displays the generated QR code
5. Client scans a QR code or presses a button to go to the banking app
6. In the banking application, the client verifies the correctness of the recipient's (merchant's) data
7. Client confirms the transfer by pressing the payment button
8. Client's bank application displays information about the successful transfer
9. Client's bank initiates the transfer to the beneficiary's bank (merchant)
10. Payonhost sends callback on successful payment

Create a transaction

To create a transaction, use the /transaction/create method.

Request parameters

Authorization parameters

Name	Type	Mandatory	Description
auth	object	Yes	Authorization data
auth.point	integer	Yes	This is your point_id from the credentials you received earlier
auth.key	integer	Yes	Session key generated on the merchant's side. You can use unixtime as a key value
auth.hash	string	Yes	md5 hash of a string obtained by concatenating point_id, api_token and key: md5(point + api_token + key) An example of a correctly calculated hash (the data in the example is random): point_id = 111 key = 1234 api_token = aiGha$et0ainah4%*eu9Vish8oo Correct hash: fda3ff2903690ed6795ea997a8cc1773

General request parameters

Name	Type	Mandatory	Max. length	Description
locale	string	Yes	2	Language of the payment page. Available languages: en, ua, ru, pt, fr, es
external_customer_id	string	Yes	99	Client ID in the merchant's system. Used for improvement of the transaction's search during incidents analysis, as well as for improvement of operation of the anti-fraud system If such a parameter is absent in the system, it is necessary to send an alternative value for payer's identification, for example: mobile phone number or email
customer_ip_address	string	Yes	45	Client's IP address. Both IPv4 and IPv6 addresses are allowed. It is important to send the client's real ip to avoid false positives of the anti-fraud system
external_transaction_id	string	Yes	48	Transaction ID in the merchant system. Must be unique for each transaction. If a transaction already exists with the same point_id and external_transaction_id, payment creation will be rejected with an error 203
external_order_id	string	No	48	Order ID in the merchant system. It is allowed to create multiple transactions with the same external_order_id
account_id	integer	Yes		Merchant account ID in the payment gateway. Provided by the Payonhost manager
wallet_id	integer	Yes		Merchant wallet ID in the payment gateway. Provided by the Payonhost manager
service_id	integer	Yes		Payment gateway service ID. Provided by the Payonhost manager
description	string	No	100	Description of payment purpose
amount	integer	Yes		Payment amount, in the minimum currency units (kopecks, cents, etc.). For example, for 3.2 USD, you need to pass the 320 value. If the amount differs from the one provided to us during transaction creation, we will overwrite it with the correct amount and send the received sum to the merchant
amount_currency	string	Yes	6	Payment currency code (3-letter ISO 4217 code for fiat currency). For example: UAH, USD, EUR
point	object	No		A set of point parameters for payment creation. The parameters, that could possibly be passed inside of the point object are presented below
point.callback_url	string	No	1000	URL for the callbacks transmission to the merchant. See the Callbacks section for details. The parameter may be absent in the request. Although, if it was passed, then its value cannot be empty. Parameter's value should also be valid, and lead not to an IP from the local network. The same condition applies to other URLs
point.return_url	string	No	1000	URL to redirect the client back to the merchant's site before the final transaction status is received. It is used only for host-2-host interaction, if a client's redirect to the acquirer's URL was necessary for authorization

Request parameters - fields for creating a transaction

Name	Type	Mandatory	Max. length	Description
fields.payment_purpose	string	Yes	140	Purpose of payment that matches description

warning

The same description and fields.payment_purpose must be forwarded in the request body

Request example

Request: /transaction/create

{
    "auth": {
        "point": 111,
        "key": 1234,
        "hash": "fda3ff2903690ed6795ea997a8cc1773"
    },
    "locale": "en",
    "external_transaction_id": "1234567890",
    "external_order_id": "100",
    "external_customer_id": "123",
    "customer_ip_address": "0.0.0.0",
    "account_id": 123,
    "wallet_id": 123,
    "service_id": 123,
    "amount": 500,
    "amount_currency": "UAH",
    "description": "Test payment",
    "fields": {
        "payment_purpose": "Test payment"
    }
}

Response parameters

The table contains a description of the parameters that are returned inside the response object (see Response structure).

Name	Type	Description
account_id	integer	Merchant account ID in the payment gateway
amount	integer	Payment amount in minimum currency units
amount_currency	string	Payment currency (3-letter ISO 4217 code)
external_customer_id	string	Client ID in the merchant system
external_order_id	string	Order ID in the merchant system
external_transaction_id	string	Transaction ID in the merchant system
id	integer	Identifier of the created transaction in the payment gateway
is_test	boolean	Flag indicating whether the transaction is a test one. Automatically affixed to all transactions created using a merchant's test account
point_id	integer	Payment acceptance point ID
result	object	The result of transaction creation. Contains pay_url link to the payment form
result.pay_url	string	Link to the payment form with QR code
service_id	integer	Payment gateway service ID
status	integer	Transaction status (see Status reference)
wallet_id	integer	Merchant wallet ID in the payment gateway

Example of a response

Response: /transaction/create

{
    "error": {
        "code": 0,
        "title": "Success"
    },
    "response": {
        "account_id": 123,
        "amount": 500,
        "amount_currency": "UAH",
        "external_customer_id": "123",
        "external_order_id": "100",
        "external_transaction_id": "1234567890",
        "id": 1234567890,
        "is_test": false,
        "point_id": 111,
        "result": {
            "pay_url": "https://payment.page.url"
        },
        "service_id": 123,
        "status": 10,
        "wallet_id": 123
    }
}

Displaying the payment page to the customer

You can consider the transaction created, after reception of pay_url, and redirect the customer to the received URL. This can be done in one of the following ways:

• Use iframe to open the page on your site;
• Redirect the customer from your site to the received pay_url;
• Send a link to the customer using any method.

NOTE

In order to fight fraud, the list of domains on which payments are allowed, may be limited for some merchants. If this restriction is active, the Referer header, containing the domain of the website which the transition was made from, is checked, when you go to the payment page
In this case, the payment page can be displayed to the customer either in iframe or by javascript (when redirecting by returning code 302, the Referer header is not sent)

Waiting for payment to complete

After the customer has navigated to the payment page, the merchant has to expect a callback from the payment gateway, which will be sent as soon as the transaction reaches its final status. You can read more about callbacks in the Callbacks section.

The back-redirect of the customer to the merchant's page is not connected with a callback sending. It is quite possible that the redirect will go first, and the callback will be delivered shortly after. This must be taken into account during integration.

Payment status request

The merchant can send the /transaction/find request to get the current status of the transaction. In addition to the transaction status, the response will also contain the payer's card number mask in fields.card_number, if the acquirer has provided information about the card that was used for the payment. Below is the example of the /transaction/find request, details - on the method description page.

Request: /transaction/find

{
    "auth": {
        "point": 111,
        "key": 1234,
        "hash": "fda3ff2903690ed6795ea997a8cc1773"
    },
    "id": 1234567890
}

Response: /transaction/find

{
    "error": {
        "code": 0,
        "title": "Success"
    },
    "response": {
        "account_id": 123,
        "account_wallet_amount": 500,
        "account_wallet_currency": "UAH",
        "amount": 500,
        "amount_currency": "UAH",
        "created_at": "2021-01-23 10:04:44",
        "description": "Description",
        "external_customer_id": "123",
        "external_order_id": "100",
        "external_transaction_id": "1234567890",
        "extra": {},
        "failure_reason_code": null,
        "failure_reason_message": "",
        "id": 1234567890,
        "is_test": false,
        "point_id": 111,
        "service_id": 123,
        "status": 10,
        "status_description": "",
        "wallet_id": 123
    }
}