Skip to content

Payments through QIWI Terminals

This alternative payment method lets merchants accept payments through QIWI Terminals, and at those electronics sales points, mobile service stores, and banking service offices, which partner with QIWI.

When customers pays for goods and services through QIWI Terminals, bePaid notifies merchants of accepted payments. Besides, merchants can review details of such payments in the bePaid back office and in transaction processing reports.

Info

To accept payments with this payment method, the merchant should be registered with both bePaid and QIWI.

Payment processing flow

QIWI Terminal payment processing flow

Stage Description
1 The customer selects the merchant's goods or services to pay for through the QIWI Terminal.
2 QIWI sends a payment acceptance request to bePaid.
3 bePaid records a transaction and sends a payment confirmation request to the merchant.
4 The merchant processes the received request according to the Integration requirements and confirms the payment acceptance to bePaid.
5 bePaid confirms the payment acceptance to QIWI.
6 The QIWI Terminal shows that the payment can be accepted.
7 The customer completes the payment.
8 QIWI notifies bePaid of the payment and its status.
9 bePaid updates transaction details and sends out a webhook notification to the merchant.

Integration requirements

  1. Data sharing between the merchant's application and bePaid is based on the RESTful API interaction workflow. It is bePaid who acts as a client making requests while a merchant responds back to them.

  2. The merchant's application should accept HTTPS-requests from the IP addresses of bePaid.

    Info

    To get an up-to-date list of the IP addresses, contact your manager.

  3. The merchant's application should have the following endpoints:

    • Account Verification URL is an endpoint that validates customer account IDs and confirms the acceptance of payments from customers. bePaid will send payment confirmation requests to this endpoint;

    • Notification URL is an endpoint that receives webhook notifications. bePaid will send webhook notifications with details and status of QIWI Terminal payments to this endpoint.

  4. The endpoints should support the Basic authorization with Shop ID and Secret Key as a username and a password respectively. Authorization parameters are submitted in the Authorization request header. See how to find Shop ID and Secret key here.

  5. Besides the Authorization request header, the request to Notification URL contains the Content-Signature header with the RSA digital signature to verify the webhook request.

  6. The merchant's application should process POST requests with parameters sent in the JSON-serialized request body. The parameter scheme is described below.

  7. The Account Verification URL endpoint should provide data in the UTF-8 encoded JSON-serialized response body. The time to respond should not exceed 14 seconds. Otherwise, bePaid times out a connection.

    Info

    To test and run the integration with this payment method, inform your bePaid manager of the following parameters:

    • the URLs of the Account Verification URL and Notification URL endpoints;

    • a regular expression to validate the format of customer account IDs (account numbers, phone numbers, email addresses or others);

    • a test customer account ID matching your regular expression to test the integration.

Payment confirmation

Request

To get the payment confirmed, bePaid sends POST- request to the Account Verification URL endpoint with the following parameters:

  • Accept: application/json and Content-type: application/json headers;
  • Basic Authorization with Shop ID and Secret key;
  • a JSON-serialized body with the following parameters:
Parameter Type Description
request object A section of request parameters.
amount * required
 integer An amount in minimal currency units.
currency * required
 string (3) A currency in the ISO-4217 format.
method_type * required
 string qiwi_terminal
account * required
 string A unique customer account ID in the merchant's system (an account number, a phone number, an email address or others).
Example of the request 
{
  "request":{     
    "amount":100,
    "currency":"RUB",
    "method_type":"qiwi_terminal",
    "account":"customer@example.com"
  }
}
Response

The response to the request should meet the Integration requirements and have the following parameters:

Parameter Type Description
response object A section of response parameters.
result * required
 integer A processing result code.

See possible values in the Processing result codes table.
Example of the response 
{
  "response":{
    "result":"0"
  }
}
Processing result codes

Depending on the processing result of the payment confirmation request, set the value of the result response parameter to one of the following codes:

Code Description
0 OK
1 Temporary error. Try again later.
4 Wrong format of the customer account ID.
5 Customer account ID not found. Account number error.
7 Payment is forbidden by the merchant.
8 Payment is forbidden for a technical reason.
243 Unable to check the customer account.
300 Unknown error.

Warning

"result":"0" in the response refers to the merchant's agreement to accept the payment from the customer. After the payment method provider processes the payment, the transaction can get either the successful status, or the failed one.

Webhook notification

After the payment made with this payment method is processed, bePaid sends out a webhook notification on a payment status to the Notification URL endpoint.

Besides transaction details, the webhook notification contains the following additional parameters of the payment method:

Parameter Type Description
qiwi_terminal object A section of the payment method parameters.
type * required
 string qiwi_terminal
account_number * required
 string A unique customer account ID in the merchant's system (an account number, a phone number, an email address or others).
Example of the webhook notification 
{
    "transaction": {
        "uid": "603a8710-c804-4600-a737-0266a907ab6c",
        "type": "payment",
        "status": "successful",
        "amount": 100,
        "currency": "RUB",
        "description": "Qiwi terminal payment for user account useremail@example.com",
        "created_at": "2023-04-12T10:48:15Z",
        "updated_at": "2023-04-12T10:56:52Z",
        "method_type": "qiwi_terminal",
        "receipt_url": "https://merchant.bepaid.by/customer/transactions/603a8710-c804-4600-a737-0266a907ab6c/803a200ece51d07c8710af14b409e7b270fdb2db4ec84e8d3f7614ddc25c569e",
        "payment": {
          "status": "successful",
          "gateway_id": 2000,
          "ref_id": "1234567890123",
          "message": "Transaction was successful"
        },
        "qiwi_terminal": {
          "type": "qiwi_terminal",
          "account_number": "useremail@example.com"
        },
        "customer": {
          "email": null,
          "ip": null
        },
        "message": "Transaction was successful",
        "test": false,
        "paid_at": "2023-04-12T10:56:52+00:00",
        "additional_data": {
          "payment_method": {
            "type": "alternative"
          }
        },
        "gateway": {
          "iframe": false
        }
    }
}

Test the integration

To get a test payment confirmation request and a webhook notification on a test transaction status, the merchant should emulate a customer's request to pay for an order, and then process the incoming requests from the bePaid system according to the Interaction requirements.

Request

Send POST- request to https://api.bepaid.by/beyag/testing/payment with the following parameters:

  • Accept: application/json and Content-type: application/json headers;
  • Basic Authorization with Shop ID and Secret Key;
  • a JSON-serialized body with the following parameters:
Parameter Type Description
request object A section of request parameters.
amount * required
 integer An amount in minimal currency units.
currency * required
 string (3) A currency in the ISO-4217 format.
method object A section of the payment method parameters.
type * required
 string qiwi_terminal
account * required
 string A unique customer account ID in the merchant's system (an account number, a phone number, an email address or others).

See possible values and expected statuses of test payments in the table below.
test * required
 boolean Set to true to initiate a test transaction.
Parameter value Expected transaction status
A valid customer account ID successful if the response to the payment confirmation request contains "result":"0". Emulation of a payment that is successfully processed by the payment method provider.
A test customer account ID failed if the response to the payment confirmation request contains "result":"0". Emulation of a payment that the payment method provider failed to process successfully.
Response

After bePaid gets the test request, it responds with the 200 HTTP code or an error message.

Example of the response to the test request with a customer account ID in a wrong format 
{
  "message": "4 Wrong account format"
}