Direct Carrier Billing

Direct Carrier Billing Interaction Diagram

Direct Carrier Billing (SMS Payments) payments interaction diagram description:

The user visits the Partner's website, selects the service that he wants to pay for, selects his mobile operator from the proposed payment options list and enters the desired amount and his phone number for payment.
The partner processes the request for payment from phone number account and sends a payment request to the System.
The System checks the received request for the correct structure, required parameters, etc. and generates a request to create a payment in the Payment method.
The payment method processes the received request, checks the possibility of making a payment from the specified mobile phone account.
The payment method returns a response about the possibility of making a payment.
The system processes the received response and returns the corresponding response to the Partner service.
The Partner notifies the User about successful or unsuccessful payment initiation. In case of successful initiation, it displays a field for the User to enter a one-time payment confirmation code.
The user receives a one-time code in an SMS and confirms the payment by entering this code in the form on the Partner's website.
After receiving the payment confirmation code from the User, the Partner sends a request to confirm the payment with a one-time code to the System
The system accepts a request to confirm payment with a one-time code, processes it and generates a request to confirm payment using the Payment Method.
The payment method processes the received payment confirmation request.
The payment method returns the result of the payment confirmation.
The system generates a response to the Partner with the result of payment confirmation.
The Partner processes the response received from the System and informs the User about the result of the payment confirmation.
The payment method processes the payment and generates a response to the System based on the result of its execution.
The system receives the payment result and sends a payment notification (feedback message) to the Partner's service.
The Partner processes the payment notification and notifies the User about the result (provides the service).

Direct Carrier Billing Payments Methods

The following HTTP requests facilitate interaction between the System and the Partner:

Request Direction	Form	URL (Endpoint)
Partner → System	Phone account payment request	`POST {{url_system}}/partner/Service_ID/pay`
Partner → System	Payment confirmation request	`POST {{url_system}}/partner/Service_ID/pay_otp`
Partner → System	One-time code resend request	`POST {{url_system}}/partner/Service_ID/resend_otp`
Partner → System	Payment cancellation request	`POST {{url_system}}/partner/Service_ID/pay_cancel`
System → Partner	Payment notification request	`POST` The URL for receiving notifications is provided by the Partner
Partner → System	Payment status request	`POST {{url_system}}/partner/Service_ID/check_pay`
Partner → System	Payment registry request	`GET {{url_system}}/reestr`
Partner → System	Refund request	`POST {{url_system}}/partner/Service_ID/make_refund`

Where the value of {{url_system}} is:

For Test environment - https://int.8b.world
For PROD environment - https://api.8b.world

The value of Service_ID is provided during onboarding and is unique for each mobile operator.

Note: Every request must contain a header (HTTP header) "Content-Type" with the value:
“application/x-www-form-urlencoded”.

The system checks the request from the point of view of security and correctness of the request. If the security check fails, the System returns HTTP Status 400 or 404 to the request. In case of a request validation error, HTTP Status 401 or 403.

Payment Request From a Phone Account

To initiate a payment from a phone account, make the following request:

POST request to {{url_system}}/partner/Service_ID/pay

Request Parameters

Parameter	Required	Type	Description	Example
orderid	Yes	String	Unique operation ID in the Partner's system.	123456789
goodphone	Yes	String	Partner's ID, unique for each mobile operator, assigned during onboarding.	1001
ctn	Yes	String	11-digit mobile phone number of the User making the payment.	79012345678
smstext	Yes	String	Format: `<Partner prefix> <Order Number> <Payment Amount>` where `<Partner>` is unique and assigned during onboarding.	1001 123456789 300.00
dt	Yes	Date-Time	Date and time of the request, format: `yyyyMMddHHmmss`.	2024070123301
control	Yes	String	Request control signature: MD5 hash (`orderid+goodphone+ctn+smstext+dt+secret_key`).	a2b911b4101e4a...
merchant_site	No	String	Address of the Partner's website from which the payment is made.	https://123abc.org
return_url	No	String	User's return URL if redirected to confirm payment (may be required depending on connection)	https://www.example.com/return_url

The system generates a response in XML format with UTF-8 encoding (Content-Type: application/xml).

System Response Parameters

Parameter	Required	Type	Description
id	No	String	Unique System operation ID. Required if`result` is 0
result	Yes	Integer	Request processing result code: • `0` – Successful request • in all other cases – an error occurred while processing the request
descr	No	String	Description of processing results

API Reference

You can view a Reference API implementation for this method at this link

Payment Confirmation Request

To confirm a payment with a one-time code, submit the following request:

POST request to {{url_system}}/partner/Service_ID/pay_otp

Request Parameters

Parameter	Required	Type	Description	Example
id	Yes	String	Unique transaction ID in the System received in the response to successful payment initiation.	98765
otp	Yes	Integer	One-time code numeric value received by the User via SMS.	123456
control	Yes	String	Request control signature: MD5 hash (`id+otp+secret_key`), where `+` is the concatenation sign and `secret_key` is the secret key for the Partner's account.	8ef7de429d44664cabeb766401849844

The system generates a response in XML format encoded in UTF-8 (Content-Type: application/xml).

System Response Parameters

Parameter	Required	Type	Description
id	No	String	Unique operation ID in the System. Required if`result` is 0
result	Yes	Integer	Request processing result code: • `0` – Successful request initiation. • Any other value – Request processing error.
descr	No	String	Description of the processing result

API Reference

You can view a Reference API implementation for this method at this link

One-time Code Resend

To resend a one-time code to the user, submit the following request:

POST request to {{url_system}}/partner/Service_ID/resend_otp

Request Parameters

Parameter	Required	Type	Description	Example
orderid	Yes	String	Unique operation ID in the Partner's system	123456789
control	Yes	String	Request control signature: MD5 hash (`orderid + secret_key`), where `+` is the concatenation sign and `secret_key` is the secret key for the Partner's account.	33e5551598c3793b3673248f9c0376fa

The system generates a response in XML format encoded in UTF-8 (Content-Type: application/xml).

System Response Parameters

Parameter	Required	Type	Description
id	No	String	Unique operation ID in the System. Required if`result` is 0
result	Yes	Integer	Request processing result code: • `0` – Successful request initiation. • Any other value – Request processing error.
descr	No	String	Description of the processing result

API Reference

You can view a Reference API implementation for this method at this link

Payment Cancellation Request

To cancel a payment, submit the following request:

POST request to {{url_system}}/partner/Service_ID/pay_cancel

Request Parameters

Parameter	Required	Type	Description	Example
orderid	Yes	String	Unique operation ID in the Partner's system	123456789
control	Yes	String	Request control signature: MD5 hash (`orderid + secret_key`), where `+` is the concatenation sign and `secret_key` is the secret key for the Partner's account.	33e5551598c3793b3673248f9c0376fa

The system generates a response in XML format encoded in UTF-8 (Content-Type: application/xml).

System Response Parameters

Parameter	Required	Type	Description
id	No	String	Unique operation ID in the System. Required if`result` is 0
result	Yes	Integer	Request processing result code: • `0` – Successful request initiation. • Any other value – Request processing error.
descr	No	String	Description of the processing result

API Reference

You can view a Reference API implementation for this method at this link

Payment Notification Request

The following parameters are included in the notification sent from the System to the Partner’s system:

Parameter	Required	Type	Description	Example
id	Yes	String	Unique ID of the operation in the System	123456789
phone	Yes	String	11-digit mobile phone number of the User from which the payment is made.	79012345678
result	Yes	Integer	Payment Status: • `0` – Successful payment / successful refund. • Any value other than `0` is an error code.	0
control	Yes	String	Request control signature: MD5 hash (`id + phone + result + secret_key`), where `+` is the concatenation sign and `secret_key` is the secret key for the Partner's account.	e1e23640e789ceba6ca930a97272438a
cmd	Yes	String	Command type. For notification requests, `cmd = status`.	status

The Partner must send the following parameters in response to the System notification request:

Parameter	Required	Type	Description
result	Yes	Integer	Request processing result code: • `0` – The request was successfully accepted and processed by the Partner. • `1` – "Temporary error" when processing the request (repeat the request later). • `2` – Permanent error when processing the request (e.g., invalid request parameters).
descr	No	String	Description of the processing result

If the system encounters a "temporary error" or any other unlisted response, it will continue to repeat the requests until a successful status is received from the Partner's service.

Repeat notifications are sent at regular intervals (in seconds):
10, 30, 60, 60, 60, 60, 60, 300, 300, 300, 3600, and then stop after 5 days.

API Reference

You can view a Reference API implementation for this method at this link

Payment Status Request

To receive the current payment status, make the following request:

POST request to {{url_system}}/partner/Service_ID/check_pay

Request Parameters

Parameter	Required	Type	Description	Example
orderid	Yes	String	Unique operation ID in the Partner's system	123456789
dt	Yes	Date-Time	Date and time of request in the following format: `yyyyMMddHHmmss`	2024070131502
control	Yes	String	Request control signature: MD5 hash (`orderid + dt + secret_key`), where `+` is the concatenation sign and `secret_key` is the secret key for the Partner's account.	9b0064f0daad778e2f0891116148abb9

The system generates a response in XML format encoded in UTF-8 (Content-Type: application/xml).

System Response Parameters

Parameter	Required	Type	Description	Example
result	Yes	Integer	Code of the request processing result: • `0` – Successful request initiation. • `1` – Request processing error.	0
error	Yes	Integer	Description of the request processing result: • `0` – Successful operation. • `1` – Operation is processing (not final). • `2` – Payment error. • `3` – Operation with this `orderid` was not found. • `4` – A partial or full refund was made for the transaction. • `-1` – System error.	0
sum	No	Decimal	Payment amount	300.00
descr	No	String	Processing result description (for errors)	Error detail
id	No	String	Unique operation ID in the System	987654321
refund_details	No	Array of refunds	An array of successful return operation descriptions. This parameter contains `<refund>` tags with the same set of operation parameters as the payment operation.	`<refund>` tags

Note: In the event of a successful refund, the system's response will include the status of the original successful payment and an array containing the statuses of all completed refund operations (only final successful ones).

API Reference

You can view a Reference API implementation for this method at this link

Payment Registry Request

To obtain a registry of payments for a specified period, make the following request:

GET request to {{url_system}}/reestr

Request Parameters

Parameter	Required	Type	Description	Example
type	Yes	String	The format of the registry: `xml/json/csv`	csv
service_id	Yes	Integer	The Partner’s account ID in the System	1001
dt_start	Yes	Date-Time	The start date and time for the period: Format: `dd.MM.yyyy HH:mm`	01.07.2024 00:00
dt_end	Yes	Date-Time	The end date and time for the period: Format: `dd.MM.yyyy HH:mm`	01.07.2024 23:59
hash	Yes	String	Request Control Signature: MD5 hash(`dt_start + dt_end + secret_key`), where `+` is the concatenation sign and `secret_key` is the secret key for the Partner's account.	bcf81715f87eeb13c8d880198fd4534c

The System will respond with a registry in the requested format. The records are filtered based on the date and time the operations were created in the System.

System Response Parameters

Parameter	Required	Description
id	No	Unique operation ID in the System
pid	No	ID of the operation in the Partner's system
status	No	Status of the operation
smstext	No	Parameter format: `<Partner prefix> <Account/Order ID_in_Partner’s_System> <Payment Amount>` `<Partner prefix>` is unique to each telecom operator and assigned during onboarding.
phone	No	11-digit mobile phone number of the User from which the payment was made
goodphone	No	Partner's ID, unique for each mobile operator, assigned during onboarding.
created	No	Date and time when the payment operation was created
changed	No	Date and time when the payment operation was last updated
amount	No	Payment amount
partner_notified	No	Indicates whether a notification (callback) was sent to the Partner. Possible values: `true` - yes; `false` - no
parameters	No	Additional payment parameters
partnerName	No	Name of the Partner in the System
partnerFee	No	Commission amount for the operation

Note: The System enforces a limit on the number of transactions included in the response (no more than 20,000). If this limit is exceeded, an error message will be returned with the following text:

"Too much data was requested. Reduce the date range or DT_END parameter to 12.03.2024 14:29"

where the specified date represents the point when the 20,000 transactions were created, minus 1 minute.

To retrieve additional data, the Partner should add 1 minute to the given time and use this new time as the dt_start.

API Reference

You can view a Reference API implementation for this method at this link

Refund Request

To initiate a refund for a previously completed payment, use the following request:

POST request to {{url_system}}/partner/Service_ID/make_refund

Request Parameters

Parameter	Required	Type	Description	Example
orderid	Yes	String	Unique operation ID in the Partner's system	123456789
dt	Yes	Date-Time	Date and time of the request, formatted as `yyyyMMddHHmmss`	2024070133502
amount	Yes	Decimal	Refund amount (must not exceed the original transaction amount).	300.00
control	Yes	String	Request control signature: MD5 hash(`orderid + amount + dt + secret_key`), where `+` is the concatenation sign and `secret_key` is the secret key for the Partner's account.	5cdbda8398b7974c7f458db0cca79bbb

The system generates a response in XML format encoded in UTF-8 (Content-Type: application/xml).

System Response Parameters

Parameter	Required	Type	Description
id	No	String	Unique operation ID in the System. Required if `result` is 0.
result	Yes	Integer	Code indicating the result of the refund request: • `0` – refund successful. • `2` – refund is being processed. • Any other value indicates a request processing error.
orderid	Yes	String	Unique operation ID in the Partner's system.
descr	No	String	Description of the result if an error occurs.

API Reference

You can view a Reference API implementation for this method at this link