Create an ERIP payment request

API request requirements

All requests to the bePaid API to create a payment request must:

use HTTP Basic authentication with Shop ID and secret key;
have the Content-Type: application/json and Accept: application/json headers.

A request for an ERIP payment must be a valid JSON object. If the system accepts the request, it returns a response with the pending or permanent status.

In case of an error, you will get the error status and an error description.

How ERIP payment flow works

After you get a response with the pending or permanent status, which means that the payment request is successfully created, bePaid is waiting for a payment notification from the ERIP (Raschet system).

Once the payment is made and bePaid gets a payment notification from ERIP (Raschet system), the bePaid system changes the status of the payment request to successful or failed, and it sends a webhook notification to your system. You can see the payment with the updated status in the bePaid back office.

If a payment was initiated, but not finished by any reason, the payment request gets the start status for 30 minutes and becomes invalid for another payment attempt.

In 30 minutes it gets the pending status and becomes valid again for a payment.

Statuses of ERIP payment requests

Status	Description
`pending`	The payment request is successfully created. Waiting for a payment.
`auto_created`	The system created a payment request for an advance payment or a permanent payment request. Waiting for a payment.
`expired`	The payment request was not settled and became expired, or there was created another payment request with the same bill, order or agreement number.
`permanent`	The payment request is permanent. There can be several payments.
`successful`	The payment is successful.
`failed`	The payment failed.
`deleted`	The merchant deleted the payment request.

Create a payment request

Request parameter

To create an ERIP payment request, send a POST request to https://api.bepaid.by/beyag/payments 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`. If `amount == 0` and `payment_method.type == erip`, the customer can enter and pay any amount within the limits set by ERIP for this type of service.
currency * required	string	`BYN`.
description * required	string	An order description.
email * conditionally required	string	The customer's email. Required if you want your customer get an email notification of the created payment request.
ip	string	The customer's IP address. Set to `127.0.0.1` if you do not collect the customer's ID address.
order_id * required	string	12 digits of the order number assigned as an order ID in the merchant's system. It can be used to track the paid order after a payment confirmation.
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 2015), `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 example 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 notification. If not submitted, the system set it to the `order_id` value.
customer	object	A section of the customer information.
first_name	string(30)	The customer's first name.
middle_name	string(30)	The customer's middle name.
last_name	string(30)	The customer's last name.
country	string	The customer's country in the ISO 3166-1 alpha-2 format.
city	string(60)	The customer's city.
zip	string(20)	The customer's zip.
address	string(250)	The customer's billing address.
phone * conditionally required	string(30)	The customer's phone number. Required if you want your customers get SMS notifications of created payment requests.
additional_data	object	A section of additional payment information.
notifications	array	Types of notifications sent to the customer when a payment request is created. Possible values: `sms` - SMS notifications; empty value - no notifications will be sent out. Set by default. Submit as an array of strings, for example `["sms"]`.
receipt_text	array	A text to add to a notification email sent to the customer. Submit as an array of lines. objects: `["First line", "Second line"]`.
payment_method	object	A section of the payment method.
type * required	string	`erip`
permanent	boolean	Se to `true` for a permanent ERIP payment request. Otherwise, `false`.
editable_amount	boolean	Set to `true` to enable the option of editing a payment amount. The customer can change the payment amount in ERIP (Raschet) system.
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.
service_no * conditionally required	integer(8)	The ERIP service number assigned by bePaid. Submit it if you have several ERIP services activated for your shop.
service_info	array	The order description shown to the customer before a payment via ERIP. Submit it as an array of strings, for example `["Payment under Agreement#123 for January"]`.
receipt	array	Information shown to the customer in the payment receipt. Submit it as an array of strings, for example `["Thank you for payment"]`.
instruction	array	An array of information lines to describe how to find the payment request in the ERIP service tree.
erip_devices	array	An array of counter values. Each object of the array should have the following structure:
name	string	The counter name, for example `Cold water`.
item_unit	string	The counter unit of measurement, for example `m3`.
rank	integer	The number of counter value digits, for example `4`.
value	integer	The counter current value, for example `1234`.
rate	float	The rate per counter measurement unit, for example `0.4392`

Request example

{
  "request": {
    "amount": 1000,
    "currency": "BYN",
    "description": "Payment for Order#123",
    "email": "ivanpetrov@example.com",
    "ip": "127.0.0.1",
    "order_id": 123456789012,
    "tracking_id": "AB8923",
    "notification_url": "http://merchant.example.com",
    "customer": {
      "first_name": "Ivan",
      "middle_name": "Ivanovich",
      "last_name": "Petrov",
      "country": "BY",
      "city": "Minsk",
      "zip": "220000",
      "address": "Nezavisimosti street, apt. 1",
      "phone": "+375172000000"
    },
    "payment_method": {
      "type": "erip",
      "account_number": "123",
      "service_no": "99999999",
      "service_info": [
        "Payment for Order#123"
      ],
      "receipt": [
        "Thank you for payment for order#123"
      ]
    },
    "additional_data":{
      "receipt_text": ["First line", "Second line"],
      "notifications": [
        "sms"
      ]
    }
  }
}

Request example for a payment request with a counter value

{
  "request": {
    "amount": 1000,
    "currency": "BYN",
    "description": "Payment for water supply. Counter #123",
    "email": "ivanpetrov@example.com",
    "ip": "127.0.0.1",
    "order_id": 123456789012,
    "tracking_id": "AB8923",
    "notification_url": "http://merchant.example.com",
    "customer": {
      "first_name": "Ivan",
      "middle_name": "Ivanovich",
      "last_name": "Petrov",
      "country": "BY",
      "city": "Minsk",
      "zip": "220000",
      "address": "Nezavisimosti street, apt. 1",
      "phone": "+375172000000"
    },
    "payment_method": {
      "type": "erip",
      "account_number": "123",
      "service_no": "99999999",
      "service_info": [
        "Payment for water supply. Counter #123"
      ],
      "receipt": [
        "Thank you for payment"
      ],
      "erip_devices": [
        {
          "name":"Cold water",
          "item_unit":"m3",
          "rank":"4",
          "value":"1234",
          "rate":"0.4392"
        }
      ]
    },
    "additional_data":{
      "receipt_text": ["First line", "Second line"],
      "notifications": [
        "sms"
      ]
    }
  }
}

Response parameters

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 on 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.
id * required	string	A transaction ID.
order_id * required	string	The `order_id` value from the request.
tracking_id * required	string	The `tracking_id` or `order_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.
receipt_text	array	Text added to a notification email sent to the customer. Represented as an array of strings.
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 bePaid.
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":{
    "status":"pending",
    "message":"The payment request is created.",
    "type":"payment",
    "id":"8759cf84-e56d-44b7-a8ae-62640f6402c4",
    "uid":"8759cf84-e56d-44b7-a8ae-62640f6402c4",
    "order_id":"100000003495",
    "amount":22000,
    "currency":"BYN",
    "description":"Payment for Order#123",
    "tracking_id":"AB8923",
    "created_at":"2015-12-07T14:21:24.420Z",
    "expired_at":"2016-12-07T14:21:240Z",
    "paid_at":"2016-12-07T14:40:120Z",
    "manually_corrected_at": null,
    "test":true,
    "payment_method_type":"erip",
    "billing_address":{
        "first_name":"Ivan",
        "middle_name": "Ivanovich",
        "last_name":"Petrov",
        "country":"BY",
        "city":"Minsk",
        "address":"Nezavisimosti street, apt. 1",
        "zip":"220000",
        "phone":"+375172000000"
    },
    "customer":{
        "email":"ivanpetrov@example.com",
        "ip":"127.0.0.7"
    },
    "payment":{
        "ref_id":null,
        "message":null,
        "status":"pending",
        "gateway_id":1
    },
    "erip":{
        "request_id":"00000001",
        "service_no":99999999,
        "account_number":"123",
        "transaction_id":"0000001",
        "service_info":["Payment for Order#123"],
        "instruction": ["'Raschet' ERIP-> Online shops/services-> B -> bePaid.by"],
        "receipt":["Thank you for payment for order#123"]
    }
  }
}

Error response example

If an error occurred, the system returns the following response:

{
  "message": "Unknown 'erip' payment method",
  "errors": {
    "system": [
      "System error."
    ]
  }
}

Parameter	Type	Description
message * required	string	An error message.
errors * required	object	A list of errors.
errors.{key} * required	array	An error with a message.

Get information about a payment

Using a payment UID

To get payment details by using a payment :uid, send a GET request with the authorization data to https://api.bepaid.by/beyag/payments/:uid.

Using a payment order ID

To get payment details by using a payment :order_id, send an HTTP GET request with the authorization data to https://api.bepaid.by/beyag/payments/?order_id=:order_id.

Delete a payment request by using a payment UID

If by any reason you should cancel a payment request, you can delete this request if it has the pending or permanent status.

To mark a payment request deleted, send a DELETE request with the authorization data to https://api.bepaid.by/beyag/payments/:uid.

Info

To keep the system data integrity, payment requests are never deleted from the system database. The payment request just gets the deleted status and becomes invalid for further payments.