ERIP

Payment flow

The merchant sends a create a payment request to the Overpay system specifying the unique account_number.
Overpay sends the response with the instruction on how to complete the payment.
The merchant displays the instruction to the customer.
The customer completes the payment in the bank application of their choice.
Overpay sends a webhook notification to the merchant when the payment status changes.

Create a payment request

Request

Send a payment request with the following parameters:

Parameter	Type	Description
request	object
amount * required	integer	A transaction amount in minimal currency units, for example, `32.45 BYN` should be submitted as `3245`.
currency * required	string	`BYN`.
description * required	string	An order description.
ip	string	The customer's IP address.
expired_at	string	An expiry time of the payment request. Set in the ISO-8601 format: `YYYY-MM-DDThh:mm:ssTZD`, where `YYYY` stands for the year (for example, 2027), `MM` stands for the month (for example, 02), `DD` stands for the day (for example, 09), `hh` stands foe the hour (for example, 18), `mm` stands for minutes (for exampl, 20), `ss` stands for seconds (for example, 45), `TZD` stands for the timezone (`+hh:mm` or `–hh:mm`), for example, `+03:00` for Helskinki. By default, timeless.
notification_url	string	An URL to get webhook notifications. If the parameter is not set, no notifications are sent out to the merchant.
tracking_id	string	The parameter to submit an order ID or an account ID related to a payment. Used to track the payment in the received webhook notification. If not submitted, the system set it to the `order_id` value.
return_url * required	string	A URL to return the customer to when a transaction is completed.
method	object	A section of the payment method information.
type * required	string	`erip`
account_number * required	string(30)	An order, bill, agreement or account ID for a payment via ERIP. The customer should indicate this value to initiate the payment via ERIP. If you send another request with the same `account_number` value, the system will set the `expired` status to a previously created payment request with this value.
customer	object	A section of the customer information.
first_name	string(60)	The customer's first name.
middle_name	string(60)	The customer's middle name.
last_name	string(60)	The customer's last name.
country	string	The customer's country in the ISO 3166-1 alpha-2 format.
city	string(120)	The customer's city.
zip	string(40)	The customer's zip.
address	string(510)	The customer's billing address.
phone	string(200)	The customer's phone number.
device_id	string	The customer's device ID.

Request example

{
    "request": {
        "amount": 100,
        "currency": "BYN",
        "description": "description",
        "test": true,
        "expired_at": "2025-05-01T15:00:00+01:00",
        "tracking_id": "your_uniq_number",
        "ip": "127.0.0.1",
        "language": "en",
        "notification_url": "https://merchant.ltd/notification",
        "return_url": "https://merchant.ltd/return",
        "customer": {
            "first_name": "Иван",
            "last_name": "Иванов",
            "middle_name": "Иванович",
            "country": "BY",
            "city": "Минск",
            "zip": "220050",
            "address": "просп. Независимости, 10",
            "phone": "17777777777",
            "device_id": "12312312321fff67"
        },
        "method": {
            "type": "erip",
            "account_number": "1234567-1234567890"
        }
    }
}

Response

If the system accepts the request, it returns a JSON -serialized response with the status. A similar response will be sent in a webhook notification to notification_url after a payment is finished.

Parameter	Type	Description
transaction	object
status * required	string	A payment status.
message * required	string	A system message.
type * required	string	`payment`
amount * required	integer	An amount in minimal currency units.
currency * required	string	`BYN`
description * required	string	An order description.
uid * required	string	A transaction UID.
tracking_id * required	string	The `tracking_id` value from the request.
expired_at	string	An expiry date of the payment request. Missing if the request is timeless. Refer to the description of the `expired_at` request parameter.
paid_at	string	A date when the payment was made at. Missing if the payment is not made yet. Refer to the description of the `expired_at` request parameter.
created_at	string	A date when the payment request was created at.
manually_corrected_at	string	Time in the ISO-8601 format when the transaction parameters were updated in the back office system by the Tech Support Team.
language	string	A value of the `language` request parameter or `en` by default.
test	boolean	`true` if the payment request is a test one. Otherwise, `false`.
payment_method_type	string	`erip`
additional_data	object	A section of additional payment information.
notifications	array	Types of notifications sent to the customer when a payment request is created.
billing_address	object	A section for additional customer information.
first_name	string	The customer's first name.
middle_name	string	The customer's middle name.
last_name	string	The customer's last name.
country	string	The customer's country.
city	string	The customer's city.
zip	string	The customer's zip.
address	string	The customer's billing address.
phone	string	The customer's phone number.
customer	object	A section of the customer information.
ip	string	The customer's IP address.
email	string	The customer's email.
payment	object	A payment section.
ref_id	string	The ERIP reference number of a transaction.
message	string	The ERIP message.
status	string	The ERIP payment status.
gateway_id	string	The gateway ID.
erip	object	A section of ERIP payment details.
request_id	integer	The ERIP request ID.
service_no	integer	The ERIP service number assigned by Overpay.
account_number	string	The order, bill, agreement or account ID for the payment via ERIP.
transaction_id	integer	The ERIP transaction ID.
instruction	array	Information to describe how to find the payment request in the ERIP service tree. Represented as an array of strings.
service_info	array	The order description shown to the customer before a payment via ERIP. Represented as an array of strings.
receipt	array	Information shown to the customer in the payment receipt. Represented as an array of strings.
agent_code	integer	The payment agent code.
agent_name	string	The payment agent name.
service_no_erip	integer	The service number assigned by ERIP.
qr_code_raw	string	base64-encrypted data to generate a QR code.
qr_code	string	The base64-encrypted .PNG picture of the QR code. To show the QR code, embed the `qr_code` value as the `img` HTML tag: `<img src="qr_code value here">`.

Response example

{
  "transaction": {
    "uid": "5046a011-cbbc-4f90-be62-be26aab13253",
    "type": "payment",
    "status": "pending",
    "amount": 100,
    "currency": "BYN",
    "description": "description",
    "created_at": "2025-04-02T07:29:07Z",
    "updated_at": "2025-04-02T07:29:11Z",
    "method_type": "erip",
    "receipt_url": "https://backoffice.overpay.io/customer/transactions/5046a011-cbbc-4f90-be62-be26aab13253/0f2bec00306efcea78f6feaf23bde471afd7ad2f748c64b1b060efb4b04767ff?language=en",
    "payment": {
      "status": "pending",
      "gateway_id": 5202,
      "ref_id": "85d1c616-39fc-4af0-951b-57181a2af70c",
      "message": "Требование на оплату счета создано."
    },
    "erip": {
      "request_id": null,
      "service_no": null,
      "account_number": "1234567-1234567890",
      "transaction_id": null,
      "instruction": [
        "Платежи -> Магазин -> Оплата"
      ],
      "service_info": [
        "Введите номер заказа"
      ],
      "receipt": [
        "Спасибо за оплату"
      ],
      "agent_code": null,
      "agent_name": null,
      "service_no_erip": "12345678",
      "qr_code_raw": "MDAwMjAxMDEwMjEyMzI1NDAwMTBieS5yYXNjaGV0MDEwODEyMzQ1Njc4MTAxODEyMzQ1NjctMTIzNDU2Nzg5MDEyMDIxMjMzMjIwMDE4YnkuZXBvcy5iZUdhdGVUZXN0NTIwNDQ1Njc1MzAzOTMzNTQwNDEuMDA1NTAyMDI1ODAyTFQ1OTA5RGVtb1Rlc3RzNjAwN1ZpbG5pdXM2MjI4MDIxMTE3Nzc3Nzc3Nzc3MDMwOURlbW9UZXN0czY0MTkwMDAyZW4wMTA5RGVtb1Rlc3RzNTYwNDEuMDA2MzA0RTg1QQ==",
      "qr_code": "data:image/png;base64, iVBORw0KGgoAAAANSUhEUgAAALEAAACxAQAAAACjUmFoAAADo0lEQVR4nO2WsW/bRhSH71SYkoe6iDuISmBRHiLPUQYrQwzUGWwNVWY7g2gBkaihKuoOpmhAPCoopUyF48GUjIjkYHauOlgeHKBeoqXOXHuQqAASOdgGnCEijerqPyDA09rCNz58+N33wLvHC9AvLhJAX1539bv6f7VOcTAfMJQSjpSyFRsTMEe2nwzW6gt2YUEVg2N4X1vuEvcvciCfHAo0NInnR41poZLafpacrC895rt/Bj8VD8kkPKcQe7H3mx2nPxbxCOYVbpBLT3Xl971MtxQAeUy9hLn9WNlOGn/s6pRAPA0MP1zPvY/EUtf8kAuCPGKOZGKqObo4L7zb+ATzvDNr+eYD9SOZyjZ0mG/fK+RVkd3MqEe6yoD9ovW0Tr7Lpt04v+ys+yCPv06KG80ofTrqH7+5KIA+VEqF7ilYc0y5gyb4XrjX4ohf3u/1oz5zWIT9rfRyzWiglmguDe0S6IM22SnVwbI9453b96NgPi322yLDP4/TwkNZcOH8/bfCq57hSWLY3t17BPNTAXFOSzOOe2rQUzgf27d31vAb/O+PO9a3v8D59ew+WVv0uEIR9ZlZuN/qErqZJheDzI48lCY4z3xK+L6r1OebV/MJJwP77yVyR6rTEH3vc4+B5xUNDbW+wa+EsL3NRQjoj0flGvvz22o3Fo4z5QrIo4aDqHB7TBm8ceLwMJ9jwwP2lVLtHGgWOwf6o0qFdy63IlypMJQqr2Eee4Unpap33ly7H43sgDzVLg9PosOZd1hFq/wVyGOVRawpicv0zUrS8GAfb0O66DaN8FcLpL/SRCB/yfKtfaWrZs5u93oB+yszv344rRN3CZnjtgXm4793tbbvFpIvgpr/7AzkaczxvUUSPrMYR3/6EPTBunahkJdZ/WSWEneC+dZxNqmioTRKNVM7XZBH+shKO2b8hoQlK92C+5Vq7oNuR7ToDI9aKTifDV9HWR+T6Mb8CIVh/54bWmeOCXvzqFO1v4Hza6xYey2hYSwfL4XWYD7/Aylv2dy1o3dDmTjYL6qParoioNrWtubFRZDHNBsmdrKP1VU89k3YB0XTWL3MD3zG8Mvw/47i6YRXP6NyVRYsB4E8knvO89ixIvmtjMCuwrxNkOGdR+K1q8Rm5WACf2qfuZynoZ8GTmmC9wNCc3skT9x/QqZqwfcLccQkL4PCLMrxRx14niMl1je19WPBlQyHToP87ftqnMO6PWa5nhiZ4P12V7+r/0/q/wK4EMbci6sW9QAAAABJRU5ErkJggg=="
    },
    "customer": {
      "first_name": "Иван",
      "last_name": "Иванов",
      "middle_name": "Иванович",
      "country": "BY",
      "city": "Минск",
      "zip": "220050",
      "address": "просп. Независимости, 10",
      "phone": "17777777777",
      "device_id": "12312312321fff67",
      "email": null,
      "ip": "127.0.0.1"
    },
    "manually_corrected_at": null,
    "version": 0,
    "message": "Требование на оплату счета создано.",
    "tracking_id": "your_uniq_number",
    "test": true,
    "language": "en",
    "expired_at": "2025-05-01T15:00:00+01:00",
    "billing_address": {
      "first_name": "Иван",
      "last_name": "Иванов",
      "middle_name": "Иванович",
      "country": "BY",
      "city": "Минск",
      "zip": "220050",
      "address": "просп. Независимости, 10",
      "phone": "17777777777",
      "device_id": "12312312321fff67"
    },
    "additional_data": {
      "payment_method": {
        "type": "erip"
      }
    },    
    "gateway": {
      "iframe": false
    }
  }
}

Notifications about ERIP payments

To keep your IT-system notified of any changes of the payment request statuses and of processed payments, Overpay uses webhook notifications that are sent to notification_url indicated in the request.

Webhook notifications are POST-requests with your authorization data that contain JSON-serialized details of an ERIP payment request.

Verify your authorization credentials to make sure you got a request from Overpay.

Notifications are sent out if a payment status is changed to pending, expired, failed or successful.

Webhook notification parameters are the same as in the synchronous response to the payment request.