Direct Carrier Billing
SMS Payments
Direct Carrier Billing Interaction Diagram
Direct Carrier Billing (SMS Payments) 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 |
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
Updated 3 days ago