Online Banking, E-Wallet, Virtual Account and QR Payments
Acquiring Interaction Diagram
Acquiring Interaction Diagram
Acquiring Interaction Diagram Description
- The user initiates a payment using a payment method available through the Partner's service.
- The Partner's service sends a payment request to the System using a specific System URL.
- The System verifies the request by checking the required parameters and the validity of the request signature.
- The System responds with either a confirmation that the request is correct and accepted or an error message if the request doesn't meet the System's requirements.
- The System processes the request further and forwards the data to the payment method.
- The payment method's service continues processing the payment request.
- The System provides a redirect link, QR code, or operation identifier, which the User must use to confirm the payment.
- The Partner redirects the User to the provided link or displays the QR code or operation identifier for completing the payment.
- The User completes the necessary actions to finalize the payment according to the selected payment method.
- The payment method's service continues processing the payment after the User's confirmation.
- The payment method informs the System of the payment result.
- The System sends a callback message with the payment result to the Partner’s service.
- The Partner communicates the payment result to the User.
Payment Request
To initiate a payment, send the following request:
POST request to: {{url_system}}/alt
Where {{url_system}} is:
- Testing environment:
https://secure-test.8b.world - Production environment:
https://secure.8b.world
Request Parameters:
| Parameter | Required | Type | Description |
|---|---|---|---|
| data | YES | String | MIME base64-encoded JSON document string |
| sign | YES | String | Request signature, formed using the hash_hmac function to confirm data validity |
The data parameter is formed using the basic (required) parameters for each request to the System.
Additional parameters may be used if the selected payment method requires further payment details. Requirements for using additional parameters are detailed in the List of Available Payment Methods.
Basic Data Parameters Description
| Parameter | Required | Type | Description | Example |
|---|---|---|---|---|
| api_key | YES | String | Unique Partner’s identifier within the System | 1d038f70-3eff-013a-cebf-02420a00092b |
| amount | YES | Decimal | Order payment amount. Format: positive floating point number with "." as a delimiter; max 2 symbols after delimiter | 10000 100.12 |
| currency | YES | String | Payment currency. Possible values: IDR, PHP, EUR, CNY, UZS | IDR |
| reference | YES | String | Unique order ID within Partner’s system | 123456789 |
| params | NO | Object | Section containing additional payment parameters | - |
> payer_firstname | NO | String | User’s first name | Name |
> payer_lastname | NO | String | User’s last name | Surname |
> user_phone | NO | String | User’s phone number | +622851280 |
> user_email | NO | String | User’s e-mail address | [email protected] |
> ip | NO | String | User’s IP address, IPv4/IPv6 format | 8.8.8.8 / 2001:4860:4860::8888 |
> country_iso_code | NO | String | User’s country of residence in ISO 3166-1 alpha-2 format | PH |
> billing_city | NO | String | User’s city of residence | City |
> billing_address | NO | String | User’s billing address | Example street, 1, 23 |
> billing_postcode | NO | String | User’s postal/ZIP code | 1000 |
Note: > denotes depth for nested parameters.
Signature Formation Procedure (sign parameter)
The signature is created based on the data parameter (a base64-encoded parameter string) using the hash_hmac function. The "md5" algorithm is used to generate the signature:
hash_hmac('md5', $data, $secret_key)
Where:
$data– MIME base64-encoded JSON document$secret_key– Partner’s Secret key
API Reference
You can view a Reference API implementation for this method at this link
Payment Callback Message
Whenever a payment is confirmed or there is a change in the status of a payment transaction, the System sends a callback message to the Partner’s system (Webhook). This message is transmitted via an HTTP POST request to the Partner’s system (Callback URL) and includes the following parameters:
| Parameter | Description |
|---|---|
| data | MIME base64-encoded JSON document string |
| sign | Request signature, based on the data string and generated using the hash_hmac function to confirm data validity |
It is recommended to verify the callback request signature to ensure data integrity and validity using the following algorithm:
hash_hmac('md5', $_POST['data'], $secret_key) === $_POST['sign']
Where $secret_key is the Partner’s Secret key.
Callback Request Data Parameter Description
| Parameter | Description |
|---|---|
transaction_id | Unique transaction identifier within the System |
reference | Unique order ID within the Partner’s system |
api_key | Unique Partner’s identifier within the System |
amount | Transaction amount |
currency | Transaction currency |
status | Transaction processing status: 0 – created transaction (redirecting User to complete payment) 1 – successful authorization (hold) for two-stage payments 2 – successful unhold for two-stage payments 3 – successful payment (credit from User’s account) 4 – successful refund 8 – transaction processing incomplete 98 – expired transaction (User did not complete payment) 99 – processing error (failed payment) |
status_name | Transaction status name: created – created transaction (status=0) authorize – successful authorization (status=1) void – successful unhold (status=2) success – successful payment (status=3) refund – successful refund (status=4) processing_incomplete – transaction processing incomplete (status=8) expired – expired transaction (status=98) error – processing error (failed payment, status=99) |
system_amount | Final transaction amount with payment system commission deducted |
system_currency | Payment system currency |
operation_amount | Operational transaction amount |
commission | Payment system commission amount in system_currency. Always contains "0" |
payment_system_type | Payment system type: alt – local payment methods. |
card_number | Payment card mask (parameter presence depends on payment system type and Payment method) |
card_pan6 | First 6 digits of payment card number (parameter presence depends on payment system type and Payment method) |
card_pan4 | Last 4 digits of payment card number (parameter presence depends on payment system type and Payment method) |
cardholder_name | Cardholder name (parameter presence depends on payment system type and Payment method) |
processing_error_msg | Error description (when status=99) |
authorization_code | Payment system authorization code (optional parameter) |
pay_token | Payment token for recurrent payments (optional parameter, depends on Gateway settings) |
params | List of additional parameters passed in the initial request |
refund_init_type | Denotes the initiator for refunds: :api => 0 – refund via API :front => 1 – refund via Backoffice :admin => 2 – refund via Technical support |
In response to a callback message, the Partner’s system is required to return a string containing the value OK.
If the Partner’s system does not return OK in response, the Gateway will send repeat callback requests.
API Reference
You can view a Reference API implementation for this method at this link
Refund Request
To initiate a refund, make the following request:
POST request to {{url_system}}/alt/refund
Where {{url_system}}:
- For testing environment -
https://secure-test.8b.world - For production environment -
https://secure.8b.world
Request Parameters
| Parameter | Description |
|---|---|
| data | MIME base64-encoded JSON-document string |
| sign | Request signature, which is based on the data string and formed using hash_hmac function to confirm data validity |
The following parameters are used to form the data parameter:
| Parameter | Type | Description | Example |
|---|---|---|---|
| api_key | String | Unique Partner’s identifier within the System | 1d038f70-3eff-013a-cebf-02420a00092b |
| transaction_id | String | Unique transaction identifier within the System | 12345 |
| amount* | Float | Amount to be refunded Format: positive floating point number with "." as a delimiter; max 2 symbols after delimiter | 1.01 |
* - optional parameter. If amount is not present, the full original transaction amount will be refunded.
API Reference
You can view a Reference API implementation for this method at this link
Transaction Information Request
To receive detailed transaction information, make the following request:
POST request to {{url_system}}/alt/get_orders_data
Where {{url_system}}:
- For testing environment -
https://secure.8b.world - For production environment -
https://secure-test.8b.world
Request Parameters
| Parameter | Description |
|---|---|
| data | MIME base64-encoded JSON-document string |
| sign | Request signature, which is based on the data string and formed using hash_hmac function to confirm data validity |
The following parameters are used to form the data parameter:
| Parameter | Type | Description | Example |
|---|---|---|---|
| api_key | String | Unique Partner’s identifier within the System | 1d038f70-3eff-013a-cebf-02420a00092b |
| transaction_id | String | Unique transaction identifier within the System | 12345 |
| OR | |||
| reference | String | Unique order ID within Partner’s system | 123456789 |
API Reference
You can view a Reference API implementation for this method at this link
Updated 3 days ago