EPoint API (v1.0.3)¶

Epoint.az — electronic payment platform. Solution for payment on site.

Contents¶

• Epoint payment page working principle
• Formation of API request
• Callback function processing
• Checking payment status
• Saving a card to make payments without entering card data
• Executing a payment with a saved card
• Saving the card with the first payment made
• Request for disbursement of funds
• Cancel operations
• Split payment request
• Executing a split payment with a stored card
• Saving the card with the first split payment
• Formation of API preauth request
• Apple Pay & Google Pay
• Google Pay (integration for mobile applications)
• Wallets
• Invoices
• Heartbeat API
• Bank Response Codes

Epoint system provides possibility to connect payment acceptance to your site. To add a payment button to your application you need to connect the payment service in your personal cabinet on our website.

To set up a merchant in our system you will need to provide us with the following information:

• your website address;
• url of the page of successful payment — success_url;
• url of the page for displaying information about unsuccessful payment — error_url;
• url to send the result of payment — result_url.

After checking this information, you will be given access keys: public_key — merchant ID in our system and private_key — secret API access key.

Epoint payment page working principle¶

1. It is necessary to form a request to the Epoint API according to the technical documentation.
2. As a result of executing the request, the client will be redirected to the bank's payment page.
3. The client fills in the card details and confirms the payment.
4. In case of successful payment, the customer will be redirected to success_url, or error_url otherwise.
5. The result of payment execution with payment details will be sent to the result_url specified by you.

Formation of API request¶

To call the Epoint API, you must send the data and signature parameters using the POST method to https://epoint.az/api/1/request or redirect the user using the POST method to https://epoint.az/api/1/checkout, where:

• data — json string with API parameters encoded with base64 function, base64_encode(json_string),
• signature — unique signature for each request, base64_encode(sha1(private_key + data + private_key, 1)),
• base64_encode — returns a string encoded in MIME base64 format,
• sha1 — returns a hash of a string of 20 characters (raw binary).

Formation of data and signature¶

Parameters json_string of the api call:

json_string example:

{
    "public_key": "i000000001",
    "amount": "30.75",
    "currency": "AZN",
    "description": "test payment",
    "order_id": "1",
    "language": "az"
}

To form a signature, concatenate private_key + data + private_key and apply base64_encode(sha1(sgn_string, 1)) to the resulting string:

$data = base64_encode(json_encode($json_string));
$signature = base64_encode(sha1($private_key . $data . $private_key, 1));

Sending a request¶

A form must be generated to send a request to the Epoint page:

<form method="POST" action="https://epoint.az/api/1/checkout" accept-charset="utf-8">
    <input type="hidden" name="data" value="{data}" />
    <input type="hidden" name="signature" value="{signature}" />
    <input type="submit" value="Pay" />
</form>

Or send the received data and signature to https://epoint.az/api/1/request. In this case a json string will be returned with the value of status (success|error), transaction and redirect_url to which the user should be redirected to enter card data.

After entering the card data, the user will be redirected to success_redirect_url or error_redirect_url depending on the payment status. Along with this, a POST request will be sent to result_url with payment details and transaction status.

Callback function processing¶

After the transaction is processed by Epoint service and the payment status is received from the bank, a POST request with two parameters data and signature will be sent to your server (result_url).

To authenticate a request from the Epoint server, you must:

1. Generate a signature on your server side using the data received in the response from Epoint and your private_key.
2. The received signature should be compared with the one received from Epoint. If the signatures match, then you have received a genuine response from the Epoint server unmodified by a third party.

To decode the data value you must execute:

$result = json_decode(base64_decode($data), true);

Use the Payment Status API function to get the status of a transaction, which can be done at any time.

Payment result parameters:

Checking payment status¶

To invoke Epoint payment status check, you need to pass the data and signature parameters by POST method to https://epoint.az/api/1/get-status, where:

• data — json string with API parameters encoded by function base64, base64_encode(json_string),
• signature — unique signature for each request, base64_encode(sha1(private_key + data + private_key, 1)).

json_string example:

{
    "public_key": "i000000001",
    "transaction": "te000000001"
}

Response parameters:

Payment statuses:

• new — payment is registered in the Epoint system;
• success — successful payment;
• returned — the payment has been refunded;
• error — an error occurred during payment;
• server_error — status check execution error.

Saving a card to make payments without entering card data¶

To call Epoint API you need to send data and signature parameters by POST method to https://epoint.az/api/1/card-registration.

The json_string parameters of the api call:

The request will return a json string with the status value (success|error) and redirect_url to which the user should be redirected to enter card data, and card_id — a unique card identifier that will be used to make payments.

The client fills in the card information and confirms the payment. In case of success, the client will be redirected to success_url, or error_url otherwise (success_redirect_url and error_redirect_url, if specified).

After the transaction is processed by Epoint service and the payment status is received from the bank, a POST request with two parameters data and signature will be sent to the result_url specified by you. Verify and decode it as described in Callback function processing.

Response parameters:

Executing a payment with a saved card¶

To make a payment with a stored card you need to send data and signature parameters by POST method to https://epoint.az/api/1/execute-pay.

Parameters json_string of API call:

After processing the transaction by the Epoint service and receiving the payment status from the bank, a response will be returned with the following parameters:

Saving the card with the first payment made¶

If you use this type of payment, you will be paid for the specified amount along with the card registration. To call the Epoint API, you need to pass the data and signature parameters by POST method to https://epoint.az/api/1/card-registration-with-pay.

Parameters for the json_string call of the API:

As a result of the request, a json string with the status (success|error) value, transaction and redirect_url to which the user needs to be redirected to enter card data will be returned, and card_id — the unique identifier of the card that will need to be used to make payments.

The customer fills in the card details and confirms payment. If the payment is successful, the client will be redirected to success_url, or error_url otherwise (success_redirect_url and error_redirect_url if specified).

After processing the transaction, a POST request with data and signature parameters will be sent to the result_url indicated by you. Verify and decode it as described in Callback function processing.

Response parameters:

Request for disbursement of funds¶

To request a payout of funds, you must send a POST request to https://epoint.az/api/1/refund-request with the data and signature parameters.

API call json_string parameters:

After processing the transaction by the Epoint service and receiving the payment status from the bank, a response will be returned with the following parameters:

Cancel operations¶

To cancel the operation, you must send a POST request to https://epoint.az/api/1/reverse with the data and signature parameters.

API call json_string parameters:

After processing, a response will be returned with the following parameters:

Split payment request¶

To create a split payment, you need to pass the data and signature parameters by POST method to https://epoint.az/api/1/split-request.

Parameters for the json_string call of the API:

In this case, a json string will be returned with the status (success|error) value, transaction and redirect_url to which the user must be redirected to enter card data.

After processing the transaction, a POST request with data and signature parameters will be sent to your server (result_url). Verify and decode it as described in Callback function processing.

Please note that the amount paid for the second merchant will only appear on their payment list.

Payment result parameters:

Executing a split payment with a stored card¶

To pay with a saved card, you must send the data and signature parameters by POST method to https://epoint.az/api/1/split-execute-pay.

API call json_string parameters:

After processing, a response will be returned with the following parameters:

Saving the card with the first split payment¶

If you use this type of payment, you will be paid for the specified amount along with the card registration. To call the Epoint API, you need to pass the data and signature parameters by POST method to https://epoint.az/api/1/split-card-registration-with-pay.

Parameters for the json_string call of the API:

As a result of the request, a json string with the status (success|error) value, transaction and redirect_url to which the user needs to be redirected to enter card data will be returned, and card_id — the unique identifier of the card that will need to be used to make payments.

The customer fills in the card details and confirms payment. If the payment is successful, the client will be redirected to success_url, or error_url otherwise (success_redirect_url and error_redirect_url if specified). After processing, a POST request with data and signature parameters will be sent to the result_url indicated by you.

Response parameters:

Formation of API preauth request¶

To call the Epoint API, you must send the data and signature parameters using the POST method to https://epoint.az/api/1/pre-auth-request. data and signature are formed the same way as in Formation of API request.

Parameters json_string of the api call:

Sending a preauth request¶

Send the received data and signature to https://epoint.az/api/1/pre-auth-request. In this case a json string will be returned with the value of status (success|error), transaction and redirect_url to which user should be redirected to enter card data.

After entering the card data, the user will be redirected to success_redirect_url or error_redirect_url depending on the payment status. Along with this, a POST request will be sent to result_url with payment details and transaction status.

Complete preauth request¶

After the transaction is processed by Epoint service and the payment status is received from the bank, you should complete this payment, otherwise it will not be added to your Epoint balance. Until then, it will be shown on your pending balance in the business panel.

Everything is the same when you want to complete the preauth request, only the body data differs. Use the endpoint https://epoint.az/api/1/pre-auth-complete.

Parameters json_string of the api call:

Apple Pay & Google Pay¶

• Google Pay: for web integration.
• Apple Pay: for both web and app integration.

See also: Apple Pay & Google Pay (JS SDK) — the separate EPoint document for integrating the buttons directly into your page.

Create Widget Url (POST Request)¶

You need to pass the data and signature to https://epoint.az/api/1/token/widget.

data = base64_encode(fields_in_json)

Fields in json:

{
    "public_key": "your_public_key_on_epoint",
    "amount": 2.50,
    "order_id": "order id generated by your system",
    "description": "Test payment"
}

signature_string = private_key + data + private_key
signature = base64_encode(sha1(signature_string))

Signature string:

signature_string = d3hjsl38sd8kdfhbcea0be04eafde9e8e2bad2fb092deyJwdWJsaWNfa2V5IjoiaTAwMDAwMDAwMSIsImFtb3VudCI6IjMwLjc1IiwiY3VycmVuY3kiOiJBWk4iLCJkZXNjcmlwdGlvbiI6InRlc3QgcGF5bWVudCIsIm9yZGVyX2lkIjoiMSJ9d3hjsl38sd8kdfhbcea0be04eafde9e8e2bad2fb092d

Example in PHP (Laravel):

$payload = [
    'public_key' => 'public_key',
    'amount' => 2.50,
    'order_id' => 'order id generated by your system',
    'description' => 'Test payment',
];

$data = base64_encode(json_encode($payload));
$private_key = 'your_private_key';
$signature = base64_encode(sha1($private_key . $data . $private_key, 1));

$request = Http::get("https://epoint.az/api/1/token/widget", [
    'data' => $data,
    'signature' => $signature
]);

$response = $request->json();

Response:

{
    "status": "success",
    "widget_url": "https://epointv1.test/api/1/token/widget/000001"
}

When payment is finished inside of the iframe or webview you can listen to the iframe message:

window.addEventListener('message', function(event) {
    console.log(event.data); // {status: 'success', payment: {...}}
});

Google Pay (integration for mobile applications)¶

To integrate Google Pay into your mobile application, you must implement a native integration.

1. Implement native integration following the official Google Pay documentation: https://developers.google.com/pay/api/android/overview
2. Provide us with screenshots showing:
   • the placement of the Google Pay button in your app interface;
   • the appearance of the Google Pay button.
3. After reviewing the submitted materials, we will provide you with a Merchant ID to complete the integration.

Wallets¶

The Wallet API provides the following endpoints:

1. https://epoint.az/api/1/wallet/status — to retrieve the list of wallets
2. https://epoint.az/api/1/wallet/payment — to create a payment using a wallet

Wallet status¶

To retrieve the list of wallets, the public_key parameter must be sent to https://epoint.az/api/1/wallet/status using the POST method.

Wallet payment¶

To create a payment using a wallet, the data and signature POST parameters must be sent to https://epoint.az/api/1/wallet/payment.

Invoices¶

To call the Invoice API, you need to pass the data and signature parameters using the POST method to https://epoint.az/api/1. The Invoice API has the following endpoints:

1. /invoices/create — creating an invoice
2. /invoices/update — updating invoice information
3. /invoices/view — viewing invoice information
4. /invoices/list — viewing information on all invoices
5. /invoices/send-sms — sending an SMS to the invoice recipient
6. /invoices/send-email — sending an email to the invoice recipient

Creating and updating an invoice has an additional optional parameter invoice_images[], which contains images in jpg, png, jpeg, svg, bmp formats.

/invoices/create¶

/invoices/update¶

/invoices/view¶

/invoices/list¶

/invoices/send-sms¶

/invoices/send-email¶

Heartbeat API¶

To check the service availability, send a GET request to https://epoint.az/api/heartbeat.

This endpoint is designed to verify if the service is operational. A successful response with status: "ok" indicates that the service is running properly.

Bank Response Codes¶