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. The callback URL receives the results of your requests to Payment Platform. It is mandatory if your account supports 3D-Secure, and it must not be longer than 255 characters.

You can also send 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, for all callbacks of that payment. If the URL is not valid, the request returns a validation error (400).

For every callback, return any HTTP 2xx status to confirm that you received it. The response body is not checked. If the callback fails, Payment Platform sends it again.

URL blocking

If callbacks to your notification URL time out five times within five minutes, the URL is blocked for your account for 15 minutes. The callbacks due during the block are not lost: they are sent later, as retries. The block lifts automatically after 15 minutes.

Details on delivery, retries and URL blocking: Callbacks.

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
UPDATE_SCHEDULE	Updates an existing schedule object. Only the parameters sent in the request are updated
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
WAITING	The refund was accepted and its final result is not known yet. Returned in CREDITVOID callbacks only

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 is sent as a POST with the 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, RECURRING_SALE, DEBIT, RECURRING_DEBIT, CARD2CARD, CREDIT2CARD	SUCCESS, DECLINED, REDIRECT (payer action is awaited), UNDEFINED
CAPTURE, VOID	SUCCESS, DECLINED, UNDEFINED
CREDITVOID	SUCCESS, DECLINED, WAITING, UNDEFINED
CHARGEBACK	SUCCESS. Sent only for a successful chargeback

There is no callback with action = RETRY: the result of a RETRY request arrives as a RECURRING_SALE callback.

For the full list of parameters delivered in each callback, see S2S CARD callback parameters. Delivery, retries and hash verification: Callbacks.

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 trans_status reference.
• Callbacks: how callbacks are delivered, answered and verified, and the parameters they carry.
• External 3DS: how to send the 3DS result from your own MPI.
• 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.