S2S APM Overview

This page describes the integration procedures for the Payment Platform used by e-commerce merchants.

APM Payment flow

The S2S APM payment flow is shown below.

Integration process

The Payment Platform implements acquiring payments (purchases) using a specific API interaction.

Client Registration

Provide the following data to your account administrator in order to get an account and access the Payment Platform:

Data	Description
notification_url	URL which will be receiving the notifications of the processing results of your request to the Payment Platform
Contact e-mail	Merchant's contact email
IP List	List of your IP addresses, from which requests to the Payment Platform will be sent.

tip

The system returns an OK string for all POST requests at the callback URL when you have successfully provided the data. Otherwise, the response will have an ERROR message.

Receive the following information from your administrator to begin working with the Payment Platform:

Parameter	Description
CLIENT_KEY	Unique key to identify the account in the Payment Platform (used as request parameter). In the administration platform this parameter corresponds to the "Merchant key" field
PASSWORD	Password for Client authentication in the Payment Platform (used for calculating hash parameter). In the administration platform this parameter corresponds to the "Password" field
PAYMENT_URL	URL to request the Payment

Redirects

There are two possible approaches for implementing the redirect when:

• The required method is GET
• redirect_url contains query parameters such as redirect_url=https://example.domain.com/?parameter=1

Option 1 Redirect the customer by sending query parameters within the form inputs

Parse the query parameters from the redirect_url and pass them as input elements in an HTML form:

Example:

<form action="https://example.domain.com" method="GET">
  <input name="parameter" value="1">
  <input type="submit" value="Go">
</form>

Option 2: Redirect Using JavaScript

Use JavaScript to redirect the customer to the specified redirect_url with the query parameters:

Example:

document.location = 'https://example.domain.com/?parameter=1';

Redirect with memory storage

When enabled in Configuration > Protocol Mappings, Payment Platform stores the redirect data server-side and returns a simple GET URL instead of a full set of redirect parameters. When the customer's browser follows that URL, Payment Platform's wrapper endpoint:

1. Retrieves the stored redirect data from memory storage.
2. Builds the required POST form automatically.
3. Renders and submits the form to the destination (3DS page, alternative payment method provider, etc.).

Use this option when you want to minimize the merchant-side redirect implementation. Advantages:

• Minimal integration effort (no form-building logic on the merchant side).
• Improved security (sensitive redirect parameters are not exposed in the URL or page source).
• No URL length limits (large redirect payloads are stored server-side).
• Fewer integration errors (Payment Platform handles form encoding and submission).

Contact your account manager to enable memory storage redirects for your account.

URL blocking

Notification URLs may be temporarily blocked due to consistently receiving timeouts in response to the callback.

If five timeouts accumulate within five minutes for a merchant’s notification URL, it will be blocked for 15 minutes. During this block, all merchants associated with the URL will not receive notifications.

info

The blocking automatically lifts after 15 minutes.

Additionally, it is possible to manually unblock the URL through the admin panel by navigating to Configuration → Merchants → Edit Merchant. In this case, the block will be removed immediately.

The timeout counter resets if a callback response is successfully processed. For instance, if there are four timeouts within five minutes but a successful response on the sixth minute, the counter resets.

Protocol Mapping

Verifiy that your protocol mapping meets requirements before using the S2S integration. This is done via your Admin.

warning

You cannot make payments if the S2S APM protocol is not mapped.

Payment Platform Interaction

Send the server to server HTTPS POST request to the Payment Platform URL (PAYMENT_URL) in all transactions.

In response, the Payment Platform will return the JSON encoded string.

Transactions requests

S2s APM Transaction Requests

Sale: →

Credit 2 Virtual →

Credit 2 Crypto →

Credit 2 Void →

Void →

Debit →

Get transaction status →

Possible actions

When you make request to the Payment Platform, you need to specify action that needs to be done. Possible actions are:

Action	Description
SALE	Creates a SALE transaction
CREDITVOID	Creates a REFUND transaction
VOID	Creates a VOID transaction
CREDIT2VIRTUAL	Creates a CREDIT2VIRTUAL transaction
CREDIT2CRYPTO	Creates a CREDIT transaction
DEBIT2VIRTUAL	Creates a DEBIT transaction as a part of transfer flow
GET_TRANS_STATUS	Gets the status of a transaction in the Payment Platform

Possible transaction results and statuses

Result - value that system returns on request.

Result	Description
SUCCESS	Action was successfully completed in the Payment Platform
DECLINED	Result of unsuccessful action in the Payment Platform
REDIRECT	Additional action required from requester
ACCEPTED	Action was accepted by the Payment Platform, but will be completed later
INIT	Additional action required from customer, final status will be sent in callback
ERROR	Request has errors and was not validated by the Payment Platform

Status - actual status of transaction in the Payment Platform.

Status	Description	Final
PREPARE	Status is undetermined, final status will be sent in callback	no
REDIRECT	The transaction awaits SALE	no
PENDING	The payment has been initiated and additional actions are required from customer	no
SETTLED	Successful transaction	yes
VOID	Transaction for which void was made	yes
REFUND	Transaction for which refund was made	yes
DECLINED	Not successful transaction	yes

How to recognize the final status

SETTLED, VOID, REFUND, and DECLINED are final: processing is complete and the status will not change on its own. PREPARE, REDIRECT, and PENDING are intermediary: the transaction is still in progress, and the final status arrives in the callback. Rely on the callback as the source of truth.

Callback Events

Callbacks are sent with the following content type: application/x-www-form-urlencoded

After creating transaction, you will receive callbacks with the following statuses:

Transaction	Status
SALE, CREDITVOID, DEBIT	SUCCESS, FAIL, WAITING, UNDEFINED, PREPARE
VOID, CREDIT2VIRTUAL	SUCCESS, FAIL, UNDEFINED

Postman collection

Download the collection file below, then import it in Postman: File > Import > Upload Files and select the downloaded .json file.

Postman collection →

Errors

In case error you get synchronous response from the Payment Platform:

Parameter	Description
result	ERROR
error_message	Error message

Testing

You can make test requests using data below. Please note, that all transactions will be processed using Test engine.

Customer's email	Testing / Result
[email protected]	Email for testing successful sales. Response on successful SALE request: {action: SALE, result: SUCCESS, status: SETTLED}
[email protected]	Email for testing unsuccessful sales. Response on unsuccessful SALE request: {action: SALE, result: DECLINED, status: DECLINED}