S2S Card overview

Introduction

This document describes integration procedures and POST protocol usage for e-commerce merchants.

S2S CARD protocol implements acquiring payments (purchases) with specific API interaction using.

warning

To work with S2S CARD protocol, merchants are required to comply with the Payment Card Industry Data Security Standards (PCI DSS).

Integration process

Merchant registration

To start working with the S2S CARD protocol, provide your callback URL to the Payment Platform administrator, who configures it as the notification_url in the admin panel.

You can sumbit callback_url in the request payload (for example "callback_url": "https://example.com/callback").

info

The request callback_url takes priority over the admin-panel value. If the URL is not valid, the request returns a validation error (400).

The callback URL receives the notifications of the processing results of your requests to Payment Platform. It is mandatory if your account supports 3D-Secure, and its length should not be more than 255 symbols.

For every Payment Platform POST request to the notification URL, the merchant must return the string OK if the data was received successfully, or ERROR otherwise.

warning

Note that the notification URL 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. The block 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.

Get the following information from the administrator before you begin:

Data	Description
CLIENT_KEY	Unique key that identifies the account in Payment Platform, used as a request parameter. In the administration platform this corresponds to the Merchant key field.
PASSWORD	Password used to authenticate the client in Payment Platform and to calculate the request hash. In the administration platform this corresponds to the Password field.
PAYMENT_URL	The URL to send Payment Platform requests to.

Protocol Mapping

It is necessary to check the existence of the protocol mapping before using the S2S integration. Merchants can’t make payments if the S2S CARD protocol is not mapped.

Interaction with Payment Platform

For the transaction, you must send the server to server HTTPS POST request with fields listed below to Payment Platform URL (PAYMENT_URL). In response Payment Platform will return the JSON (http://json.org/) encoded string.

tip

The S2S (Server-to-Server) protocol requires requests to be sent with the following content type: Header: Content-Type: application/x-www-form-urlencoded

Redirect parameters

For 3DS-payments, the response for SALE request may contain the redirect_params with parameters for the payer's redirection. The format in which redirect_params is returned depends on the endpoint you send the request to.

If you send the request to the https://{PAYMENT_URL}/post endpoint, redirect_params is returned as a single object where each parameter is a "key: value" pair.

Response with key-value format

    "redirect_params": {
        "Param1": "Value1",
        "Param2": "Value2"
    }

If you send the request to the https://{PAYMENT_URL}/v2/post endpoint, redirect_params is returned as an array of objects, where each object contains a name and a value parameter.

Response with "name" and "value" parameters

    "redirect_params": [
        {
            "name": "Param1",
            "value": "Value1"
        },
        {
            "name": "Param2",
            "value": "Value2"
        }
    ]

List of possible actions (operations)

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

Action	Description
SALE	Creates SALE or AUTH transaction
CAPTURE	Creates CAPTURE transaction
CREDITVOID	Creates REVERSAL or REFUND transaction
VOID	Creates VOID transaction
DEBIT	Creates DEBIT transaction as a part of transfer flow
CREDIT2CARD	Creates CREDIT2CARD transaction
GET_TRANS_STATUS	Gets status of transaction in Payment Platform
GET_TRANS_DETAILS	Gets details of the order from Payment Platform
GET_TRANS_STATUS_BY_ORDER	Gets the status of the most recent transaction in the order's transaction subsequence from Payment Platform
RECURRING_SALE	Creates SALE or AUTH transaction using previously used cardholder data
RECURRING_DEBIT	Creates a secondary DEBIT transaction using the token from a primary DEBIT initialized with recurring_init = Y
RETRY	Creates RETRY transaction
CARD2CARD	Creates TRANSFER transaction – one-step transfer without split to debit and credit

Recurring schedule operations

Action	Description
CREATE_SCHEDULE	Creates a new schedule object
PAUSE_SCHEDULE	Suspends the scheduled payments associated with schedule. A schedule can only be paused if its parameter "paused" has a value "N". Paused schedule can't be used for the new recurring payments until it is released via RUN_SCHEDULE
RUN_SCHEDULE	Releases the schedule which was paused via PAUSE_SCHEDULE. It re-schedules cycle of payments and set the value "N" for "paused" parameter for schedule
DELETE_SCHEDULE	Deleting schedule means that it can’t be used in the recurring payments
SCHEDULE_INFO	Retrieves the details of an existing schedule. You only need to supply the unique schedule identifier that was returned upon schedule creation
DESCHEDULE	Stops the payments by the schedule

Following actions cannot be made by request, they are initiated by Payment Platform in certain circumstances (e.g. issuer initiated chargeback) and you receive callback as a result.

Action	Description
CHARGEBACK	CHARGEBACK transaction was created in Payment Platform

List of possible transaction results and statuses

Result - value that system returns on request. Possible results are:

Result	Description
SUCCESS	Action was successfully completed in Payment Platform
DECLINED	Result of unsuccessful action in Payment Platform
REDIRECT	Additional action required from requester (Redirect to 3ds)
ACCEPTED	Action was accepted by Payment Platform, but will be completed later
ERROR	Request has errors and was not validated by Payment Platform
UNDEFINED	The transaction has an undefined status. Status could be changed to success or fail

Status - actual status of transaction in Payment Platform. Possible statuses are:

Status	Description	Final
3DS	The transaction awaits 3D-Secure validation	no
REDIRECT	The transaction is redirected	no
PENDING	The transaction awaits CAPTURE	no
PREPARE	Status is undetermined, final status will be sent in callback	no
SETTLED	Successful transaction	yes
REVERSAL	Transaction for which reversal was made	yes
REFUND	Transaction for which refund was made	yes
VOID	Transaction for which void was made	yes
CHARGEBACK	Transaction for which chargeback was made	yes
DECLINED	Not successful transaction	yes

How to recognize the final status

The statuses SETTLED, DECLINED, REFUND, VOID, CHARGEBACK, and REVERSAL are final: the processing of the transaction is complete and the status will not change on its own. The statuses 3DS, REDIRECT, PENDING, and PREPARE are intermediary: the transaction is still in progress, and the final status will be delivered in the callback. Rely on the callback as the source of truth for the final status.

Callback Events

tip

The callback will be sent with the following content type: application/x-www-form-urlencoded

Merchants receive callbacks for the transactions listed below when the processing finishes with the following results (the result values match the result list above):

Transaction	Result in the callback
SALE, CREDITVOID, DEBIT, RECURRING_SALE, CARD2CARD	SUCCESS, DECLINED, REDIRECT (payer action is awaited), UNDEFINED
CAPTURE, VOID, CREDIT2CARD	SUCCESS, DECLINED, UNDEFINED

For the full list of parameters delivered in each callback, see What the callback carries.

What's next

Now that you have the protocol shape, action list, and callback model in hand, the next pages cover specific flows in depth:

• Payment operation types: per-action request and response shapes for SALE, CAPTURE, VOID, CREDITVOID, RECURRING_SALE, CREDIT2CARD, and the schedule lifecycle.
• Redirect / 3DS handling: when a redirect is required, how to run it, and the transStatus reference.
• Redirect / 3DS handling: the parameters delivered to your notification URL, including the 3DS authentication attributes.
• Errors and testing: sandbox test cards, error reference, and the debugging workflow.

Reference material:

• Changelog: release history and breaking changes.
• Troubleshooting: symptom-cause-fix breakdowns for the most common integration failures.