Online Banking, E-Wallet, Virtual Account and QR Payments

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
`success_url*`	NO	String	URL to redirect the User to after a successful payment.	http://test.com/success
`failure_url*`	NO	String	URL to redirect the User to after a failed payment.	http://test.com/failure

Note: > denotes depth for nested parameters.

* If parameters are present - User will be redirected to passed success_url/failure_url. Otherwise User will be redirected to URL specified in Shop settings.

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