Mandarin

# Tokenization

Tokenization is used for the purpose of writing off/crediting a card without user participation, as well as to verify that the user has access to this card (writing off a checksum, checking through 3-D Secure).

To tokenize the card you need to sendPOSTrequest to separate address:https://secure.mandarinpay.com/api/card-bindings.

TESTING

Data for testing is located in the Payment services section.

# Authentication

All requests to the tokenization API are authenticated by a header x-auth. Formation of the value is in the Request Authentication.

# Tokenization of full card data

The essence of this operation is authorization (preauth) amount on a bank card in the amount of 1 ruble with subsequent unlocking. The operation is carried out using 3-D Secure technology.

After receiving a successfulcallback-notifications, the token can be used for payments to a saved card and recurring payments.

The transaction is carried out asynchronously. As a result of the request, you will synchronously receive token in the fieldid, and then a callback-notification with the token status will arrive asynchronously.

Received in synchronous responseuserWebLinkuse to work with payment page, andjsOperationIdto work through Mandarin Custom Pay.

Parameter Required Parameter Required
customerInfo Yes metadata No
customerInfo.email Yes urls No
customerInfo.phone Yes urls.return No
urls.callback No

Synchronous response and asynchronous callback-notification can contain a wider set of parameters compared to the example.

Request

curl --request POST \
  --url https://secure.mandarinpay.com/api/card-bindings \
--header 'Content-Type: application/json' \
--header 'x-auth: {{x_auth}}' \
--data-raw '{
	"customerInfo": {
		"email": "user@example.com",
		"phone": "+79001234567"
	},
	"metadata": {
		"first_parameter_to_callback_and_not_to_show": "p1",
		"second_parameter_to_callback_and_not_to_show": "p2"
	},
	"urls": {
		"callback": "http://...",
		"return": "http://..."
	}
}'

Response in case of successful tokenization (200 OK)

{
	"id": "43913ddc000c4d3990fddbd3980c1725",
	"userWebLink": "https://secure.mandarinpay.com/CardBindings/New?id=4c9932c6-5e57-4807-9103-8c4083a06d23",
	"jsOperationId": "binding_4c9932c6-5e57-4807-9103-8c4083a06d23"
}
}

Answer if tokenization is not created (400 Bad request)

{
	"error": "Invalid request"  
}

# "payout-only" status

A situation is possible in which the full card data token is forcibly transferred to the statuspayout-only. This happens in cases when a response is received from the payment system with a code that makes further automatic debits impossible. Such a token can subsequently be used only for payments to the card or for payment using a saved card in interactive mode.

Let's consider this situation in more detail. In accordance with the requirements of international payment systems, a restriction has been introduced on making recurrent payments in case of receiving the following refusals multiple times (more than 4 times in 16 calendar days - for Visa cards, more than 3 times in 30 calendar days - for MasterCard cards, more than 2 times in 14 calendar days - for MIR cards):

  • with code "05" (refuse without specifying a reason).
  • with code "51" (refuse, there are not enough funds in the account).
  • with code "61" (refuse, exceeding the maximum transaction amount for a given card).
  • with code "65" (refuse, exceeding the maximum number of transactions for a given card).

If the limits are exceeded, the operation is completed with code "66" (refuse, contact the security service). Repeated execution of a recurring payment becomes possible after a certain period has passed (16 calendar days - for Visa cards, 30 calendar days - for MasterCard cards, 14 calendar days - for MIR cards) from the moment of the last unsuccessful attempt to request a recurring payment.

If the number of refusals does not exceed the permissible number of times, then one successful operation on the card immediately leads to the reset of the refusal counter with codes “05”, “51”, “61”, “65”.

In addition, if you receive refusals from the list below, you must stop attempts at recurring payments:

  • with code "14" (incorrect card number).
  • with code "54" (card has expired).
  • with code "57" (invalid type of operation for this card).
  • with codes “04”, “07”, “33”, “35”, “36”, “37”, “38”, “41”, “43”, “67” (withdraw the card, various reasons).

# Zero Balance Tokenization

There are two ways to tokenize a card with a zero balance:

  • new: using parametercheckCard(for payments and disbursements);

  • former: with the status assigned payout-only (for payments).

# Zero balance tokenization using "checkCard"

When using the terminalecom none3ds, support can enable the use of the parametercheckCard.

In this scenario, the 3-D Secure procedure is not performed, but a full card data token is returned. Thus, it is not necessary to have 1 ruble on the client’s card.

Parameter Required Parameter Required
customerInfo Yes metadata No
customerInfo.email Yes urls No
customerInfo.phone No urls.return No
checkCard No urls.callback No

SUPPORT SERVICE

Using the parametercheckCardpossible only after settings from the support service!
Additionally, support can configure all bindings to be scripted without "3-D Secure" even if the optioncheckCardnot transmitted (except only in those cases where the request explicitly specifiescheckCard: false).

Synchronous response and asynchronous callback-notification can contain a wider set of parameters compared to the example.

Request

curl --request POST \
  --url https://secure.mandarinpay.com/api/card-bindings \
--header 'Content-Type: application/json' \
--header 'x-auth: {{x_auth}}' \
--data-raw '{
	"customerInfo": {
		"email": "user@example.com",
		"phone": "+79001234567"
	},
	"checkCard": true,
	"metadata": {
		"first_parameter_to_callback_and_not_to_show": "p1",
		"second_parameter_to_callback_and_not_to_show": "p2"
	},
	"urls": {
		"callback": "http://...",
		"return": "http://..."
	}
}'

Response in case of successful tokenization (200 OK)

{
	"id": "43913ddc000c4d3990fddbd3980c1725",
	"userWebLink": "https://secure.mandarinpay.com/CardBindings/New?id=4c9932c6-5e57-4807-9103-8c4083a06d23",
	"jsOperationId": "binding_4c9932c6-5e57-4807-9103-8c4083a06d23"
}

Answer if tokenization is not created (400 Bad request)

{
	"error": "Invalid request"  
}

# Tokenization with zero balance with "payout-only" status

A setting is possible in which, if the user does not have funds on the card (for example, after passing 3-D Secure an error with code 51 is received), the card is tokenized and goes into the status payout-only (status=payout-onlyVcallback-notification). Token of complete card data in statuspayout-onlycan be used in the same way as a card number token. That is, for payments to a card, as well as for payments with the participation of the payer (you will need to enter CVV/CVC and go through the 3-D Secure procedure).

# Card number tokenization

This call is essentially a tokenization of the card number and is used to avoid storing the card number in your system. This operation is carried out in synchronous mode - in response you will receive a token (in the fieldid).

Unlike tokenization of full card data, tokenization of a card number can be used exclusively for crediting (action=payout) funds to the card.

Parameter Required Parameter Required
customerInfo Yes target Yes
customerInfo.email Yes target.knownCardNumber Yes
customerInfo.phone No metadata No

Synchronous response and asynchronous callback-notification can contain a wider set of parameters compared to the example.

Request

curl --request POST \
  --url https://secure.mandarinpay.com/api/card-bindings \
--header 'Content-Type: application/json' \
--header 'x-auth: {{x_auth}}' \
--data-raw '{
	"customerInfo": {
		"email": "user@example.com",
		"phone": "+79001234567"
	},
  	"target": {
		"knownCardNumber": "4012888888881881"
    },
	"metadata": {
		"first_parameter_to_callback_and_not_to_show": "p1",
		"second_parameter_to_callback_and_not_to_show": "p2"
	}
}'

Response in case of successful tokenization (200 OK)

{
	"id": "43913ddc000c4d3990fddbd3980c1725"
}

Answer if tokenization is not created (400 Bad request)

{
	"error": "Invalid request"  
}

# Tokenization via SBP

The method is intended to perform zero linking of the client’s SBP account to the merchant. This link is used for further repeated debits (subscriptions, regular payments) without the need to go through the full payment script through the SBP each time.

# Creating card-binding

To create a binding, use the card-binding creation method specifying a flagisSbpBinding = true.

Parameter Required
customerInfo yes
customerInfo.email yes
customerInfo.phone yes
isSbpBinding yes

Request

curl --request POST \
  --url https://secure.mandarinpay.com/api/card-bindings \
--header 'Content-Type: application/json' \
--header 'x-auth: {{x_auth}}' \
--data-raw '{
    "customerInfo": {
        "email": "a@mandarin.io",
        "phone": "+7901763****"
    },
    "isSbpBinding": true
}'

The request contains the client's contact information. FlagisSbpBindingindicates that it is the SBP link that is being created, and not the bank card link.

Response in case of successful creation of tokenization (200 OK)

{
    "id": "94bdf1c2-714e-4250-a835-fcfa75cac2cc",
    "jsOperationId": "binding_94bdf1c2-714e-4250-a835-fcfa75cac2cc",
    "userWebLink": "https://secure.mandarinpay.com/CardBindings/New?id=94bdf1c2-714e-4250-a835-fcfa75cac2cc",
    "qrImage": "base64...",
    "qrUrl": "https://sub.nspk.ru/..."
}

The response returns the object of the created binding.

Parameter Description
id ID of the created SBP binding
jsOperationId Operation ID used in frontline scenarios
userWebLink Link to a web page where the client can complete the binding
qrImage QR code in Base64 format for display to the client
qrurl Link to SBP QR code (can be used to generate your own QR)

# Completing card-binding

After creating the binding, the client needs to:

  • or go touserWebLink,
  • or scan the QR code of the SBP (viaqrImageorqrUrl) in the bank's mobile application.

After successful confirmation, the SBP link is considered active and can be used for subsequent debits as part of subscriptions or regular payments.

# Purpose and limitations

  • Linking is performed without debiting funds (zero operation).
  • The link is created for a specific merchant.
  • Used only for scenarios of repeated write-offs through SBP.
  • Repeated write-offs are carried out using separate methods and do not require re-confirmation by the client.

# Using tokens

[Full card data token](./api_tokenization.md#tokenization-full-card data) can be used in the future for:

  1. Recurring payments (auto-debits) using a card token.
  2. Payments using a saved card in interactive mode. In this case, the user only needs to fill in the fieldCVV.
  3. Payments using a saved card without entering a CVV/CVC code and without going through 3-D Secure. In this case, auto-debit will occur. If it is not possible, then the user will only need to fill in the fieldCVV.
  4. Authorization using a card token (activated upon client request).
  5. Automatic payments to card.

# Getting tokenization status

The API method makes it possible to obtain its status, as well as information about the card, using the transaction identifier.

Request: operationId — id payment.

curl --request GET \
  --url https://secure.mandarinpay.com/api/operations/{operationId} \
--header 'x-auth: {{x_auth}}'

Sample answer:```json { "operationType": "Transaction", "state": "Success", "card": { "cardNumber": "519261XXXXXX3242", "cardHolder": "CARD HOLDER", "expireDate": "25/01", "cardId": "a3a5c49e1385e5096d05075d636f7baf", "country": "TUR", "productName": "Standard Mastercard Card", "productCode": "MCS", "brand": "mastercard", "bank": "ODEA BANK A.S.", "cardType": "Credit" } }


| Parameter | Description |
|----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| operationType | operation type, transaction/binding |
| state | Operation status: success, failed, payout-only, pendingExecution/none/unknown - the operation has not been completed and is being processed (reconciliation with the acquiring bank may be required). Only the success status clearly indicates the success of the operation! |
| cardNumber | masked card number |
| cardHolder | card holder |
| expireDate | card expiration date |
| cardId | unique hash of the full card number |
| country | country of issue |
| productName | card product/card category |
| productCode | card product/card category code |
| brand | card payment system |
| bank | bank that issued the card |
| cardType | card type (debit/credit) |

← Payments →