Mandarin

# Tokenization

Tokenization is used for the purposes of debiting/crediting the card without the user's participation, as well as for verifying that the user has access to this card (debiting the checksum, verification through 3-D Secure).

To tokenize the card, send a POST request to a specific address: https://secure.mandarinpay.com/api/card-bindings.

# Tokenization of full card data

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

After receiving a successful callback notification, the token can be used for payments to a saved card and recurring payments.

The transaction is done in asynchronous mode. As a result of the request you will get a token in the id field synchronously, and then asynchronously a callback-notification with the token status.

Use the userWebLink received in the synchronous response to work with payment page and the jsOperationId to work through Mandarin Custom Pay.

Parameter Mandatory Parameter Mandatory
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

POST https://secure.mandarinpay.com/api/card-bindings

{
	{ "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"
}
}

Response in case tokenization is not created (400 Bad request)

{
	"error": "Invalid request"  
}

# Status "payout-only"

It is possible that the full card data token is forced to the payout-only status. This happens in cases when the payment system receives a response with a code, in which further autosigning is impossible. Such token can be used only for payouts to card or for payment by saved card in interactive mode.

Let's consider this situation in details. According to the requirements of international payment systems, the restriction on recurring payments was introduced in case of multiple refusals (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 the reason).
  • with code "51" (to refuse, there are not enough funds on the account).
  • with code "61" (refuse, exceeding the maximum amount of transaction for this card).
  • with code "65" (to refuse, exceeds the maximum amount of operations for this card).

In case of exceeding the limits, the transaction will be completed with code "66" (refuse, contact security service). Repeated recurring payment becomes possible after a certain period of time (16 calendar days - for Visa cards, 30 calendar days - for MasterCard cards, 14 calendar days - for MIS cards) from the last unsuccessful attempt to request recurring payment.

If the number of refusals does not exceed the allowed number of times, one successful card transaction immediately resets the refusal counter with codes "05", "51", "61", "65".

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

  • with code "14" (wrong card number).
  • with code "54" (card expired).
  • with code "57" (unacceptable operation type for this card).
  • with codes "04", "07", "33", "35", "36", "37", "38", "41", "43", "67" (withdraw card, different reasons).

# Tokenization with a zero balance

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

  • new: using the checkCard parameter (for payments and payouts);

  • old: with assignment of payout-only status (for payments).

# Tokenization with zero balance using "checkCard"

When using the ecom none3ds terminal, the helpdesk can enable the use of the checkCard parameter.

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

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

SUPPORT

The use of the checkCard parameter is only possible after a support service setting!
Additionally, support can set up all bindings to be performed in a script without "3-D Secure", even if the checkCard parameter is not passed (except for those cases where checkCard: false is explicitly mentioned in the request).

Synchronous response and asynchronous callback-notification may contain a broader set of parameters than the example.

Request.

POST https://secure.mandarinpay.com/api/card-bindings

{
	"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"
}

Response if tokenization is not created (400 Bad request)

{
	"error": "Invalid request"  
}

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

It is possible to set up where if the user has no funds on the card (for example, after passing 3-D Secure an error with code 51 is received), the card is tokenized and goes to payout-only status (status=payout-only in callback notification). Full card data token in payout-only status can be used in the same way as a card number token only. That is for payments to the card, as well as for payments involving the payer (will require entering CVV/CVC and going through 3-D Secure).

# Tokenization of the card number

This call is essentially a tokenization of the card number and is used to not store the card number in your system. This operation is done in synchronous mode - you will receive a token in response (in the id field).

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

Parameter Mandatory Parameter Mandatory
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

POST https://secure.mandarinpay.com/api/card-bindings

{
	{ "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"
}

Response in case tokenization is not created (400 Bad request)

{
	"error": "Invalid request"  
}

# Using tokens

Full card data token can be further used for:

  1. Recurring payments (auto-discharges) using card token.
  2. Payments by saved card in interactive mode. In this case the user only needs to fill in the CVV field.
  3. Payments by saved card without entering CVV/CVC-code and without passing 3-D Secure. In this case an autoschedule will occur. If it is not possible, the user will only need to fill in the CVV field.
  4. Authorizations using card token (activated on client's request).
  5. Automatic Payouts to Card.
  6. card2card operation.

# Getting tokenization status

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

Authorization - XAuth (opens new window).

Request: operationId - payment id (opens new window).

GET https://secure.mandarinpay.com/api/operations/{operationId}

Sample answer:

{
     "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"
     }
}

Response options:

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)

← Payouts →