Mandarin

# Routing

# Registration of a sub-merchant

A sub-merchant can be a legal entity or an individual entrepreneur.

To get started, a Sub-Merchant must set up a Mandarin Personal Account on their own through the standard registration (opens new window) procedure, going through the steps from (1) submitting the application to (4) completing the processing of the application.

In addition to the basic Private Office registration process, a mass Private Office creation is available through the registry. To use this scenario, contact your supervising manager.

After approval of the myAlpari, you can proceed to the procedure of linking the created myAlpari to your Marketplace account

# Creating a sub-merchant account

To create a sub-merchant account, use the token, which is available in myAlpari in the Routing section of the Project Settings.

Parameter Type Mandatory Description
accountType string yes account type,
for a legal entity takes the value business.
token string Yes legal entity account token.

The synchronous response contains the id (identifier) of the account.

Request

POST https://secure.mandarinpay.com/api/v1/accounts/business

{

	"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJtZXJjaGFudF9pZCI6MiwiaXNzIjoiMzAg0LzQsNGPIDIwMjIg0LMuIn0.unGctyIBkp4EHXw-7bFqWbkmfhs2yCJ-jAKJGqRP_1"

}

Response in case of successful account creation (200 OK)

{
	"id": "01dab7d8-be9b-4f87-ba91-801731787725",
	"type": "Business".
}

Response in case the request was not created (400 Bad request)

{
	"error": "Invalid request"  
}

# Payment acceptance (Routing)

Standard API-requests for accepting payments are used, according to documentation. Possible are single-stage payment, recurring payment (autoschedule) and two-stage payment (in this case authorization remains standard and payment distribution occurs when settlements are completed).

This adds an object routing.destination to the pay request that contains the payment distribution scheme. To accept payments: the sum of amount values from the routing object must be equal to the top-level amount!

IMPORTANT! When using two-step payment, the routing object is added to the second query with action:"pay"`.

The payer can enter card data on payment page or Mandarin Custom Pay embedded form.

Parameter Type Mandatory Description
routing Yes Object containing routing parameters.
routing.destination string yes array containing payment recipients.
routing.destination. accountId string yes destination account ID.
routing.destination. amount.value string yes amount to be transferred to the recipient's account. For accepting payments: the commission of the platform will be deducted from this amount. The separator is a dot.
routing.destination. amount.currency string yes the currency of the amount transferred to the recipient's account. Now it is always RUB.
routing.destination. platformFeeAmount. value string Yes platformFeeAmount commission, of the amount transferred to the recipient's account. The separator is a dot.
routing.destination. platformFeeAmount. currency string yes platform commission currency. It is always RUB.
routing.destination. description string no description.

In the example below 5000 rubles are debited from the payer's card and will be credited to the next recipient:

  • 3950 rubles to the account 16f90c5e-6bc3-11eb-9439-0242ac130002, owned by a legal entity.
  • 50 rubles per platform account.
  • 950 rubles to the account 8ba85f01-8cc8-4161-b45d-ce6442e678ae, which belongs to another legal entity.
  • another 50 rubles per platform account. Total 100 rubles per platform account.

Single Stage Payment Request

POST https://api.mandarin.io/secure/transactions

{
	{ "payment": {
		{ "action": { "pay",
		"orderId": "your_unique_order_id",
		{ "amount": {
			{ "value": "5000.00",
			"currency": "RUB"
		},
		"orderActualTill": "2020-02-20 12:34:56+00:00"
	},
	{ "routing": {
		{ "destination": [{
				"accountId": "16f90c5e-6bc3-11eb-9439-0242ac130002",
				{ "amount": {
					{ "value": "4000.00",
					"currency": "RUB"
				},
				{ "platformFeeAmount": {
					{ "value": "50.00",
					"currency": "RUB"
				},
				{ "description": ""
			},
			{
				"accountId": "8ba85f01-8cc8-4161-b45d-ce6442e678ae",
				{ "amount": {
					{ "value": "1000.00",
					"currency": "RUB"
				},
				{ "platformFeeAmount": {
					{ "value": "50.00",
					"currency": "RUB"
				},
				{ "description": ""
			}
		]
	},
	{ "customerInfo": {
		{ "email": "user@example.com",
		"phone": "+79001234567"
	}
}

The response to the request corresponds to the standard response for creating transactions.

Response in case of successful transaction creation (200 OK)

{
	"id": "43913ddc000c4d3990fddbd3980c1725",
	"userWebLink": "https://secure.mandarinpay.com/Pay?transaction=0eb51e74-e704-4c36-b5cb-8f0227621518",
	"jsOperationId": "9874694yr87y73e7ey39ed80"
}

Response in case the transaction was not created (400 Bad request)

{
	"error": "Invalid request"  
}

# Tokenization (Routing)

Tokenization uses standard tokenization requests. Subsequently, the card token can be used to create recurring debits, stored-card payments in interactive mode or payments with saved card without entering cvv-code and without going through 3d-secure

# Cancel payment (Routing)

Standard API requests are used for refunds on previously completed payments, according to documentation.

To cancel a successful debit card transaction (action: pay), use action: "reversal" and id of the earlier transaction as target.transaction

This adds an object routing.source to the pay request, which contains a scheme for distributing returns between Sabmerchant accounts. To accept payments: the sum of amount values from the routing object must be equal to the top-level amount!

Cancellation is possible both for the whole amount of the transaction and for a part of the amount (partial cancellation). Unlimited number of partial cancellations of one payment transaction within the payment amount is allowed. Active participation of the payer is not required.

Parameter Mandatory Parameter Mandatory
routing Yes Object containing routing parameters.
routing.source string yes array containing payers.
routing.source.accountId string yes payer account ID.
routing.source.amount.value string yes amount transferred to the payer's account. The separator is a dot.
routing.source.amount.currency string yes the currency of the amount debited from the payer's account. Now it is always RUB.
routing.source.platformFeeAmount. value string Yes Used when returning withheld commission, can be equal to 0. The separator is a dot.
routing.source.platformFeeAmount. currency string yes platform commission currency. It is always RUB.
routing.source.description string no description.

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

Request

POST https://secure.mandarinpay.com/api/transactions

{
	{ "payment": {
		{ "action": "reversal",
		"orderId": "your_unique_order_id",
	    "price": "5000.00".
	},
	{ "target": {
		{ "transaction": "43913ddc000c4d3990fddbd3980c1725"
	},
	{ "customValues": [
		{ "name": "first parameter to save and show", "value": "p1"},
		{ "name": "second parameter to save and show", "value": "p2"}
	],
	{ "metadata": {
		"first_parameter_to_callback_and_not_to_show": "p1",
		"second_parameter_to_callback_and_not_to_show": "p2"
	},
	{ "routing": {
		{ "source": [{
				"accountId": "16f90c5e-6bc3-11eb-9439-0242ac130002",
				{ "amount": {
					{ "value": "4000.00",
					"currency": "RUB"
				},
				{ "platformFeeAmount": {
					{ "value": "50.00",
					"currency": "RUB"
				},
				{ "description": ""
			},
			{
				"accountId": "8ba85f01-8cc8-4161-b45d-ce6442e678ae",
				{ "amount": {
					{ "value": "1000.00",
					"currency": "RUB"
				},
				{ "platformFeeAmount": {
					{ "value": "50.00",
					"currency": "RUB"
				},
				{ "description": ""
			}
		]
	},
	{ "urls": {
		{ "callback": "http://...",
		"return": "http://..."
	}
}

Response in case of successful transaction creation (200 OK)

{
	"id": "43913ddc000c4d3990fddbd3980c1725"
}

Response in case the transaction was not created (400 Bad request)

{
	"error": "Invalid request"
}

# Transferring funds (Routing)

The transfer of funds to Sub-Merchants is automatic on the next business day after the date of payment.

← Card2Card (p2p) →