Skip to content

Create an ERIP payment request

API request requirements

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

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:
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
required
 string
The customer's IP address. Set to 127.0.0.1 if you do not collect the customer's ID address.
order_id
 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.
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.
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"].
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.
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.
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
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.
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.
object
A section of the customer information.
ip
 string
The customer's IP address.
email
 string
The customer's email.
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.
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."
    ]
  }
}
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.