Request for payment using Samsung Pay (payment.do)

The request used for registering an order is payment.do (see below).

https://3dsec.sberbank.ru/payment/samsung/payment.do

Use the standard requests to the payment gateway for the operations of reversal, refund and payment completion.

In this document, the following data type conventions are used when describing request and response parameters:

A<n> – a sequence of Latin letters of length <n>;
A..<n> – a sequence of Latin letters with a length not exceeding <n>;
N<n> – a sequence of digits of length <n>;
N..<n> – a sequence of digits with a length not exceeding <n>;
AN<n> – a sequence of Latin letters and numbers of fixed length <n>;
AN.. <n> – a sequence of Latin letters and numbers with a length not exceeding <n>;
ANS<n> – a sequence of Latin letters, numbers and characters of fixed length <n>
ANS.. <n> – a sequence of Latin letters, numbers and characters with a length not exceeding <n>;
UTC – date and time, in this case: the date must be passed without specifying the time zone, Moscow time, for the SOAP protocol, the standard encoding xs: dateTime is used.

Request parameters

The request parameters are given in table below.

It is necessary to add to the request a header with the definition of the type of contents – «Content-Type: application/json» to ensure that the request is processed correctly.

Name	Type	Mandatory	Description
`merchant`	AN..255	Yes	Merchant login in the payment gateway.
`orderNumber`	ANS..32	Yes	Number (identifier) of the order in the store system. It is unique for every store within the Payment Gateway. If the order number is generated on the Payment Gateway side, this parameter is not mandatory.
`description`	ANS..512	No	Description of the order in free form. To enable sending this field to the processing system, contact the technical support service.
`language`	A2	No	Language in the ISO 639-1 encoding. If the language is not specified, the default language defined in the store settings is used.
`additionalParameters`	Not applicable	No	Additional parameters of the order that are stored in the merchant personal account for the subsequent viewing. Additional parameters must be specified in the following format. `parameter_name`: `parameter_value` It is forbidden to pass reserved names in the parameter (if they are passed, the order may be rejected): sbrf_spasibo:amount_bonus sbrf_sbermiles:amount_bonus loyaltyId
`preAuth`	A..5	No	Parameter that defines the necessity of a pre-authorization (putting the amount on hold on the customer's account until its debiting). The following values are available: `true` – the parameter is enabled, a two-phase payment is made; `false` – the parameter is disabled, a one-phase payment is made (funds are debited immediately).
`clientId`	ANS..255	No	Customer identifier for which a binding for recurring payments is to be created. Specify it only if the payment is dummy and is intended for subsequent recurring payments.
`paymentToken`	String	Yes	The contents of the `3ds.data` parameter from the response received from Samsung Pay.
`ip`	ANS..39	Yes	IP-address of the buyer. IPv6 is supported in all requests (up to 39 characters).
`currencyCode`	N3	No	Numeric ISO 4217 code of the payment currency. If this parameter is not specified, it is considered to be equal to the default currency code.
`billingPayerData`	See description	No	Customer's registration data (street address, postal code). Required for AVS/AVV checks. Mandatory if «AVS/AVV use allowed» permission is enabled for merchant

billingPayerData

billingPayerData block parameters

Name	Type	Mandatory	Description
`billingCity`	AN..50	No	City registered for the card at the Issuer Bank.
`billingCountry`	AN..50	No
`billingAddressLine1`	AN..50	No	Address registered for the card at the Issuer Bank. Line 1. Mandatory if «AVS/AVV use allowed» permission is enabled for merchant.
`billingAddressLine2`	AN..50	No	Address registered for the card at the Issuer Bank. Line 2.
`billingAddressLine3`	AN..50	No	Address registered for the card at the Issuer Bank. Line 3.
`billingPostalCode`	AN..50	No	Postal code registered for the card at the Issuer Bank. Mandatory if «AVS/AVV use allowed» permission is enabled for merchant.
`billingState`	AN..50	No	State registered for the card at the Issuer Bank (ISO 3166-2).

Response parameters

The response parameters are given in table below.

Name	Type	Mandatory	Description
`success`	A..5	Yes	Designates a successful request. The following values are available: true – request is processed successfully; false – request failed.
`data` block (returned only if the request was successful)
`orderId`	ANS36	Yes	Identifier of the order in the payment system. It is unique within the system. Missing if order registration failed due to an error detailed in ErrorCode.
`error` block (returned only if the request resulted in an error)
`code`	N3	Yes	Error code.
description	ANS..512	Yes	A detailed technical explanation of the error – the contents of this parameter is not to be displayed to the customer.
`message`	AN..512	Yes	Comprehensive error description – it is intended for displaying to the user.

Error codes

Error code	Error text
0	The request has been processed without system errors.
1	The funds on the card are not sufficient.
5	Access denied.
5	The user must change the password.
7	System error.
10	Invalid parameter value `[paymentToken]`.
10	Invalid parameter value `[orderNumber]`.
10	Invalid parameter value `[merchant]`.
10	Invalid parameter value `[ip]`.
10	Invalid parameter value `[paymentToken.header]`.
10	Encryption of the data passed in unsuccessful.

POST request example

{
    "merchant": "OurBestMerchantLogin",
    "orderNumber": "UAF-203974-DE",
    "language": "RU",
    "preAuth": true,
    "description" : "Test description",
    "additionalParameters":
    {
        "firstParamName": "firstParamValue",
        "secondParamName": "secondParamValue"
    },
    "paymentToken": "ew0KICB7DQoJICAidmVyc2lvbiI6ICJSU0FfdjEiLA0KCSAgInNpZ25hdHVyZSI6ICJabUZyWlNCemFXZHVZWFIxY21VPSIsDQoJICAiaGVhZGVyIjogew0KCQkiZXBoZW1lcmFsUHVibGljS2V5IjogIk1Ga3dFd1lIS29aSXpqMENBUVlJS29aSXpqMERBUWNEUWdBRW14Q2hDcGpLemY5YVh6MjZXVDZaVE4yekUzaUdYUWpjWlJZWUFkUUlURFgyUmtBTmJ0N2s5cmFoRjFoempqbWVWVHhjZ0NvZkg4MXprMkdOVFozZHRnPT0iICAgICAgIA0KCQkid3JhcHBlZEtleSI6ICJYejI2V1Q2WlROMnpFM2lHWFFqYz0iDQoJCSJwdWJsaWNLZXlIYXNoIjogIk9yV2dqUkdrcUVXamRrUmRVclhmaUxHRDBoZS96cEV1NTEyRkpXckdZRm89IiwNCgkJInRyYW5zYWN0aW9uSWQiOiAiYXBwbGUtMTIzNDU2Nzg5MEFCQ0RFRiINCgkgIH0sDQoJICAiZGF0YSI6ICIxZFhFMTNrdnpUVlA2bldFTjhEMnBoclBsZlFjR3I4VzN5ajJTSFlZai9QeWNIV1RqbnBWN3ovRXI3OGJyaT09Ig0KICB9DQp9",
    "ip" : "127.0.0.1"
}

Response example

Successful payment

{
"success":true,
"data": {
    "orderId": "12312312123"
  }
}

Failed payment

{
  "error": {
    "code": 1,
    "description": "Processing Error",
    "message": "The funds on the card are not sufficient"
  },
  "success": false
}

Инструменты страницы