Общее описание
Вы можете использовать наш API продавца, чтобы создать нужный вам сценарий оплаты. Например, вы можете создать собственную полностью настроенную платежную страницу и подключить ее к нашему платежному шлюзу.
Вы можете скачать коллекцию API-запросов для Postman, чтобы протестировать основные возможности API. Обязательно отправляйте запросы как POST с атрибутами в теле запроса.
Вы также можете использовать наш Server Side SDK для выполнения запросов API.
Обязательность параметров
Обязательность присутствия параметра в запросе/ответе может принимать следующие значения:
- Обязательно - параметр должен присутствовать всегда. В случае отсутствия значения требуется передавать пустое значение в зависимости от формата;
- Необязательно - параметр может как присутствовать, так и отсутствовать, при этом его избыточное присутствие не приведет к ошибке системы;
- Условие - параметр может как присутствовать (быть обязательным), так и отсутствовать в зависимости от одного или нескольких условий.
Обязательность передачи параметра в описании запроса/ответа указывается в одноименном столбце "Обязательность".
Аутентификация
Для аутентификации мерчанта в платежном шлюзе можно использовать два метода.
- Используя логин и пароль API-пользователя мерчанта (аккаунт с суффиксом
-api
), полученный при регистрации. Эти значения передаются в параметрахuserName
иpassword
соответственно (см. таблицу ниже).
Обязательность | Название | Тип | Описание |
---|---|---|---|
Условие | userName |
String [1..100] | Логин учетной записи API продавца. Если для аутентификации при регистрации вместо логина и пароля используется открытый токен (параметр token ), пароль передавать не нужно. |
Условие | password |
String [1..200] | Пароль учетной записи API продавца. Если для аутентификации при регистрации вместо логина и пароля используется открытый токен (параметр token ), пароль передавать не нужно. |
- С помощью специального токена - его значение вы можете запросить в службе технической поддержки. В запросах его значение передается в параметре
token
(см. таблицу ниже).
Обязательность | Название | Тип | Описание |
---|---|---|---|
Условие | token |
String [1..256] | Значение, используемое для аутентификации продавца при отправке запросов платежному шлюзу. Если вы передаете этот параметр, то не передавайте userName и password . |
URL для API-вызовов
TEST: https://3dsec.berekebank.kz/payment/rest/
PROD: https://securepayments.berekebank.kz/payment/rest/
Ошибки
Коды состояния HTTP:
200
- в случае вызовов API платежного шлюза необходимо проанализировать JSON из ответа, чтобы определить, была ли обработка транзакции успешной или нет. Успех обозначается либо:
- значением параметраsuccess
равнымtrue
- значеним параметраerrorCode
равным0
Если присутствуют оба параметра,success
имеет приоритет надerrorCode
.400
- в системе произошла внутренняя ошибка.404
- ошибка при вызове API - неверный URL (не существует).429
- этот код означает, что система перегружена. Чаще всего основная причина в том, что достигнут лимит запросов в секунду или лимит одновременных запросов. Но также может быть связано с тем, что система в целом перегружена (независимо от ваших запросов).500 или 502
- этот код означает, что что-то пошло не так на нашей стороне.
Если запрос, связанный с оплатой заказа, обработан успешно, это еще не означает, что сам платеж прошел успешно.
Чтобы определить, был ли платеж успешным или нет, вы можете обратиться к описанию использованного запроса. Также для выяснения статуса платежа всегда можно использовать алгоритм, описанный ниже
- Сделать вызов getOrderStatusExtended.do;
- Проверить поле
orderStatus
в ответе: заказ считается оплаченным, только если значениеorderStatus
равно1
или2
.
Подпись запроса API
В некоторых случаях для обеспечения безопасного обмена данными может потребоваться реализовать асимметричную подпись запроса. Обычно это требование применяется, только если вы выполняете запросы P2P/AFT/OCT.
Чтобы иметь возможность подписывать запросы, вам необходимо выполнить следующие шаги:
- Создайте и загрузите сертификат.
- Рассчитайте хеш и подпись, используя свой закрытый ключ, и передайте сгенерированный хеш (X-Hash) и значение подписи (X-Signature) в заголовке запроса.
Эти шаги подробно описаны ниже.
Создание и загрузка сертификата
-
Создайте 2048-битный закрытый ключ RSA. Способ генерации зависит от политики конфиденциальности в вашей компании. Например, вы можете сделать это с помощью OpenSSL:
openssl genrsa -des3 -out private.key 2048
-
Создайте общедоступный CSR (запрос на подпись сертификата), используя сгенерированный закрытый ключ:
openssl req -key private.key -new -out public.csr
-
Создайте сертификат, используя сгенерированный закрытый ключ и CSR. Пример формирования сертификата на 5 лет:
openssl x509 -signkey private.key -in public.csr -req -days 1825 -out public.cer
Загрузите сгенерированный сертификат в Личный кабинет. Для этого перейдите в Сертификаты кошельков > Merchant API, нажмите Добавить сертификат и загрузите сгенерированный общедоступный сертификат.
Вычисление хеша и подписи
-
Рассчитайте хеш SHA256 тела запроса следующим образом:
- Используйте тело запроса в виде строки (в нашем примере это
amount=10000&password=gcjgcW1&returnUrl=http&userName=signature-api
). - Вычислите хэш SHA256 из этой строки в необработанных байтах.
- Преобразуйте необработанные байты в кодировку base64.
- Используйте тело запроса в виде строки (в нашем примере это
Сгенерируйте подпись для вычисленного хеша SHA256 с помощью алгоритма RSA, используя закрытый ключ.
В нашем примере мы используем следующий закрытый ключ с паролем 12345:
-----BEGIN RSA PRIVATE KEY-----
Proc-Type: 4,ENCRYPTED
DEK-Info: DES-EDE3-CBC,C502560EDE8F82B7
O4+bY1Q1ZcXFLDGVE8s9G2iVISHR/c/IMZKZEjkBED/TbuOCUGVjcav2ZaZO2dO0
lm771N6JNB01uhJbTHScVQ6R0UnGezHFTcsJlAlBa9RQyOwujs4Pk6riOGnLliIs
urnTXD0oskBR1wLRA2kp8+V0UPOAMXQaoLxFGE/o8taDGSrkyIcYTBoh9o7ZBxvO
SqUWAt2vPbGVyc6XspyuVtgHgEctaJO+E26QTweqdpN5JITF+fDFPNwUrFHoho4N
pxpKRWbiCJSpbvbsvhdizkmfgvRw+qYJvTirF3JTfGr14DttudFwjm7sNrr0JILR
XPKDUhRyWjkthZM+oDjF2HwISAGkbxcpn4PU7Tywq0uax+5KCQQn2uz4jLM2P6+9
000cvVLwhMnoUdOxuISRXeOcOWVyTO1mPfKiWnHaoO4yS3Y36OCIOe9RHGP8TTmq
acb3LUIF30eQyk3KxH/tUB0ScPDKEKMiww13/Kcfr0JkdIe/BWCvV+hSQm38TLQe
bTFy+wnD9kHACCwTSVVSOO+rHgJGVIyLgnpClZKWQyyJ4clH7/cORA7mTmp85Ckx
IjV5Egu0bPPUMudOB5BnQ4u85RnqXavasgrLRA3JZM4+Jzl8MNy/fsFXnVBQLJJC
Wlz/B7S7W8sabRogFuiqkkPmXE/QcpdKQoY3yh748QqMSl8vkA6WgndyYv1EnDDl
jA5j7vSf0wKI8BHgdHBEWuEjn3X/s0S/BiPPI6puboYY90tYVJTWSQCR83QrMF3N
BIcMu4+RIYu6GWnPx9npZpt0858c670ZII56np24iMse3qgHCOZxsGOenK2x7ta6
163gvaD8bu8xoeQcGVfd6IMbXWVb0+z1hvWR5HWHSalof4lMzZrDsQDKc2UA0ygh
hA1+VAl1MAEHVLNCCmyG1SwRwg1PI7FfftW7YARngCZRWkJ1haj1fgy7rtYolrdv
lEz/vjFD6diABx67omGgfiJhWdiKIlzsYlX1SW7yaik/Uxf1j8gTFwY34y8ekVd9
6pQTzV2V/4a48ELZl4LvelLWyt1AB3AR+/fM7YG6LYIqlo+qnLtro7Bqu8RNTNRP
wcWCd04r/20ulFWMIH8pVa60C98pSdOXriWEI1KDLc0E/fCdhjW2kL+FTPLC7ORe
cuzmfI27+06P/BvLZq/FAVBrDAmkioKwe6XYzTjpK1p5jZ3IrNwjAiasY1MNxCRy
5ufhQwkW//d+VUdU5m8Sm30/kXe9UkxMaetXgzPxbB7+5QFFr0bi7D1MjIrJNtTx
5g5E+UfOhqrp8ztBht9csQeFYSYabyyGX4Lh7ymVWrKCVdHlJib3M36nvOjpV/lA
zf35sxFz9kaQqNK7xJdQ9Bx6TBUzLjpYhNry37vKk+SIB6Weo+LJ99mALMeX79CB
osRqZqX5yrZhaQ8bbpo981nvLy5xFnpRqCuSWVZrVMBq3LQLaOvaCeyGC0V+ZN0C
CU6lHlR6XQqd/IjoEN8+8aiVp6Ubw8FuD28TDaEvCltrX3ARL0xFpABsa42LgV1F
09Vi+ju7SSNDvbezN8q0EILq9xp/zNCVhMpyRCIXBq9fzHkyCZ5qMw==
-----END RSA PRIVATE KEY-----
Получаем подпись:
pJ/gM4PR1/mKGuIxMvTl5pYDDjJslb0BcXFnIxijFn5qKdPd7W+2ueoctziU7omnkYp01/BlracukH1GOPWMSO+9zKuTDdFueFm1utsS0zaPFU+dmc1niGDRWE0CbCXcti/rGSTDPsnR58mwqgVkbCWxKyCDtuo5LxiKPK9mzgWTUuJ8LX6f6u42MURi5tRG6a9dc8l/+J94g0YOk911R6Lqv2jcluEvZ9ZeMMt8hyxowb0eDaCHlussu2CAyqpE9V+EUAc81Jkwv96MMSsA6UnFwEaCV/k+kwYd0jHCx94m2yWX734p9cWsBW7Fr5F0zox9Yck4GOjqe9nJMMB9jQ==
3. Теперь вам следует передать сгенерированный хэш (X-Hash
) и значение подписи (X-Signature
) в заголовке запроса. Запрос будет выглядеть так:
curl --request POST \
--url https://3dsec.berekebank.kz/payment/rest/register.do \
--header 'content-type: application/x-www-form-urlencoded' \
--header 'X-Hash: eYkMUF+xaYJhsETTIGsctl6DBNZha1ITN8muCcWQtZk=' \
--header 'X-Signature: pJ/gM4PR1/mKGuIxMvTl5pYDDjJslb0BcXFnIxijFn5qKdPd7W+2ueoctziU7omnkYp01/BlracukH1GOPWMSO+9zKuTDdFueFm1utsS0zaPFU+dmc1niGDRWE0CbCXcti/rGSTDPsnR58mwqgVkbCWxKyCDtuo5LxiKPK9mzgWTUuJ8LX6f6u42MURi5tRG6a9dc8l/+J94g0YOk911R6Lqv2jcluEvZ9ZeMMt8hyxowb0eDaCHlussu2CAyqpE9V+EUAc81Jkwv96MMSsA6UnFwEaCV/k+kwYd0jHCx94m2yWX734p9cWsBW7Fr5F0zox9Yck4GOjqe9nJMMB9jQ==' \
--data 'amount=10000&password=gcjgcW1&returnUrl=http&userName=signature-api'
Запрос должен соответствовать следующим требованиям:
- Все параметры запроса включены в тело запроса (не в URL)
-
Если параметры запроса передаются в формате JSON, должен использоваться следующий заголовок:
--header 'content-type: application/json'
-
Если параметры запроса передаются в формате Query (например,
parameterA=valueA&parameterB=valueB
), должен использоваться следующий заголовок:--header 'content-type: application/x-www-form-urlencoded'
Запрос содержит правильный логин и пароль пользователя API.
Заголовок
X-Hash
содержит хэш SHA256 тела запроса (рассчитывается на Шаге 1).Заголовок
X-Signature
содержит подпись для хэша SHA256, рассчитанного с помощью алгоритма RSA с использованием закрытого ключа (генерируется на Шаге 2).
Пример кода Java
Ниже приведен пример кода Java, который загружает закрытый ключ, вычисляет хэш SHA256, подписывает его с помощью закрытого ключа с паролем 12345, а затем отправляет правильный запрос register.do
:
import javax.net.ssl.HttpsURLConnection;
import java.io.BufferedReader;
import java.io.DataOutputStream;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.net.URL;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.security.KeyStore;
import java.security.MessageDigest;
import java.security.PrivateKey;
import java.security.Signature;
import java.util.Base64;
import static java.net.HttpURLConnection.HTTP_OK;
public class SimpleSignatureExample {
// This example is not production ready. It just shows how to use signatures in API.
public static void main(String[] args) throws Exception {
// load private key from jks
KeyStore ks = KeyStore.getInstance("JKS");
char[] pwd = "123456".toCharArray();
ks.load(Files.newInputStream(Paths.get("/path/to/certificates.jks")), pwd);
PrivateKey privateKey = (PrivateKey) ks.getKey("111111", pwd);
// Sign
String httpBody = "amount=10000&password=gcjgcW1&returnUrl=http&userName=signature-api";
MessageDigest digest = MessageDigest.getInstance("SHA-256");
Signature signature = Signature.getInstance("SHA256withRSA");
signature.initSign(privateKey);
byte[] sha256 = digest.digest(httpBody.getBytes());
signature.update(sha256);
byte[] sign = signature.sign();
// Send
Base64.Encoder encoder = Base64.getEncoder();
HttpsURLConnection connection = (HttpsURLConnection) new URL("https://<YOUR_DOMAIN>/payment/rest/register.do").openConnection();
connection.setDoOutput(true);
connection.setDoInput(true);
connection.setRequestMethod("POST");
connection.addRequestProperty("content-type", "application/x-www-form-urlencoded");
connection.addRequestProperty("X-Hash", encoder.encodeToString(sha256));
connection.addRequestProperty("X-Signature", encoder.encodeToString(sign));
connection.addRequestProperty("Content-Length", String.valueOf(httpBody.getBytes().length));
try (final DataOutputStream outputStream = new DataOutputStream(connection.getOutputStream())) {
outputStream.write(httpBody.getBytes());
outputStream.flush();
}
connection.connect();
InputStream inputStream = connection.getResponseCode() == HTTP_OK ? connection.getInputStream() : connection.getErrorStream();
BufferedReader reader = new BufferedReader(new InputStreamReader(inputStream));
String line;
while ((line = reader.readLine()) != null) {
System.out.println(line);
}
}
}
Пример кода Python
Ниже приведен пример кода Python, который генерирует подпись:
import OpenSSL
from OpenSSL import crypto
import base64
from hashlib import sha256
key_file = open("./priv.pem", "r")
key = key_file.read()
key_file.close()
if key.startswith('-----BEGIN '):
pkey = crypto.load_privatekey(crypto.FILETYPE_PEM, key)
else:
pkey = crypto.load_pkcs12(key, password).get_privatekey()
data = “amount=2000¤cy=978&userName=test_user&password=test_user_password&returnUrl=https%3A%2F%2Fmybestmerchantreturnurl.com&description=my_first_order&language=en”
sha256_hash = sha256(data.encode()).digest()
base64_hash = base64.b64encode(sha256_hash)
print(base64_hash)
sign = OpenSSL.crypto.sign(pkey, sha256_hash, "sha256")
signed_base64 = base64.b64encode(sign)
print(signed_base64)
Файл закрытого ключа для примера Python должен иметь формат:
-----BEGIN PRIVATE KEY-----
MIIEvwIBADANBgkqhkiG9w0BAQEFAASCBKkwggSlAgEAAoIBAQDdpOwhY/p9x0WmBd3HaDfCD+KYung3M8Cxrw0ozF+h//GltRdnkJD7ejsBDB6/YeIVXZeU3AyqWvsi/IfeHwnokGxVg2IMw8OPacY6o1x7W0EQtfRoZa2Cn2PMCpZhEHlIVraXZDDeg4HY26YP0FZxRbpNnpXhGbiop+Bq0wHeE3JIk53cRmwYhxdxMmvFpgNd6C3dYhmnQqLv6WSpVNDFbQxBVU+JDNyR9FQwB1dU2MadgYwFJnEssbhUkM+sXAC4Wv3qhcZek6MWeWsbFIIlyTPa1T3yrWSXIb4qFJEro4pRMmwQ72qG02p8EPx1tlveQo22TojV9WbTPtaVwQtxAgMBAAECggEBANheTGkYOYsZwgMdzPAB7BSU/0bLGdoBuoV6dqUyRdVWjqaOTwe519625uzR0R5RRqxGzlfyLKcM5Aa2cUhEEp8mhatA87G0Va8lue66VOjTH4RZq/tR7v0J7hlc6Ipe05brl5nYo+BEjriNS+I6Jnizcfid7IBvZJW4NFr0G+mWTxl2BhUK/Mk895n8hg9QtgSRoMNO4jK2f0vJrH4hBHehTYpjHx+QhbUyIvsp60bEnNOXzl054TuWBVCYAQHcHTTZowWMY0s1Z0kGNxwsqQm4amW/v+1EqCF4fjRDrU6v/kjDKxGFx9GJUktKZAe2T8e2LySjgGpJO5g4AdxIVpUCgYEA8x9te+i2ijxoS3kIUSwXaPq5EdKGWGl5mW8KZHzmt9LB/CqTKvSOiDkMGoAx/76t5QmKOYojP+Vsc2XdfQfhT6d00MGTdiPBd+8//MmQQ07/D1/PV58Jd1O8bQFU4fZCMpQl/8Azp9ix/NEx0sHDv2KigLfFMBVGeJxwSoU2JzMCgYEA6WJC0BDTA9vx+i+p9i/41f7ozpQuYey5sxdZa2emOSYen6ptxUFLAYXMxVDaBJ89PMUa8GzWoXHhgXzbuRJk74IzUhWgPpneS4HTr5KDStJh2TqWWVLwEIgLwxvtuw0i9uSEU64D/Czzm801lrOhVgmZsWwNpFtP8ujz0v84MssCgYEA1P4YhbB3kx2e5VfwgGSXUcIttr5wMi6deF0+hpCh9DNw/QEzkzNTV2ZbAzCCHSKo5/n2nbg2b3kIDQUWCL6JlqYHAghErwBeMztoHIddmoovjAGM/Z93xJGYhwremWOL1RHTRH7XAlomfG2tL43PdvDrmsbkut44sdujyLVxnt8CgYBirK3tBMADKLJVgmOM+FlwORe7iAFYW9tj8iJXe/pWvVxDS66fsOyCl0ytvHKBc8ZTdE7gilPw7JJYyi6oQDO25EjIkuYusaXALQMQf5TNRMgkLVY2LA/eHXdDpgJMjNBUrOeZ7cA3ldXl8MyQjCBRnTuDPVlDPWw/GulEM65SIwKBgQDIEv8XK2YBkZrr+0fZSFTQAeK4R7Ve3z4hbpHhJi41YanCNaEWoeYAuQd6/b/QLwABllvfJBDYCNnF8heUxqISpyWd+FZ8nhZtxBoKj5l80czTcutIz/M+ETcvl8FqnMBsoCdp1wodqaLkOx6DIldgKLze6AqKXl5lHUsU4mvVqg==
-----END PRIVATE KEY-----
Регистрация заказа
Регистрация заказа
Для регистрации заказа используется запрос https://3dsec.berekebank.kz/payment/rest/register.do
.
При выполнении запроса необходимо использовать заголовок:
Content-Type: application/x-www-form-urlencoded
Параметры запроса
Обязательность | Название | Тип | Описание |
---|---|---|---|
Условие | userName |
String [1..100] | Логин учетной записи API продавца. Если для аутентификации при регистрации вместо логина и пароля используется открытый токен (параметр token ), пароль передавать не нужно. |
Условие | password |
String [1..200] | Пароль учетной записи API продавца. Если для аутентификации при регистрации вместо логина и пароля используется открытый токен (параметр token ), пароль передавать не нужно. |
Условие | token |
String [1..256] | Значение, используемое для аутентификации продавца при отправке запросов платежному шлюзу. Если вы передаете этот параметр, то не передавайте userName и password . |
Обязательно | orderNumber |
String [1..32] | Номер заказа (ID) в системе мерчанта; должен быть уникальным для каждого заказа. |
Обязательно | amount |
Integer [0..12] | Сумма платежа в минимальных единицах валюты (например, в копейках). |
Необязательно | currency |
Integer [3] | Код валюты платежа ISO 4217. Если не указано, то используется значение по умолчанию. |
Обязательно | returnUrl |
String [1..512] | Адрес, на который требуется перенаправить пользователя в случае успешной оплаты. Адрес должен быть указан полностью, включая используемый протокол (например, https://mybestmerchantreturnurl.com вместо mybestmerchantreturnurl.com ). В противном случае пользователь будет перенаправлен по адресу следующего вида: https://3dsec.berekebank.kz/payment/<merchant_address> . |
Необязательно | failUrl |
String [1..512] | Адрес, на который требуется перенаправить пользователя в случае неуспешной оплаты. Адрес должен быть указан полностью, включая используемый протокол (например, https://mybestmerchantreturnurl.com вместо mybestmerchantreturnurl.com ). В противном случае пользователь будет перенаправлен по адресу следующего вида: https://3dsec.berekebank.kz/payment/<merchant_address> . |
Необязательно | dynamicCallbackUrl |
String [1..512] | Параметр для передачи динамического адреса для получения "платежных" callback-уведомлений по заказу, активированных для мерчанта (успешная авторизация, успешное списание, возврат, отмена, отклонение платежа по таймауту, отклонение card present платежа). "Не платежные" callback-уведомления (включение/выключение связки, создание связки), будут отправляться на статический callback адрес. |
Необязательно | description |
String [1..598] | Описание заказа в любом формате. Чтобы включить отправку этого поля в процессинговую систему, обратитесь в службу технической поддержки. В этом поле недопустимо передавать персональные данные или платежные данные (номера карт т.п.). Данное требование связано с тем, что описание заказа нигде не маскируется. |
Необязательно | language |
String [2] | Ключ языка по ISO 639-1. Если язык не указан, используется язык по умолчанию, указанный в настройках магазина. Поддерживаемые языки: ru, en. |
Необязательно | ip |
String [1..39] | IP адрес плательщика. IPv6 поддерживается во всех запросах (до 39 символов). |
Необязательно | clientId |
String [0..255] | Номер клиента (ID) в системе мерчанта — до 255 символов. Используется для реализации функциональности связок. Может возвращаться в ответе, если мерчанту разрешено создавать связки. Указание этого параметра при обработке платежей по связке обязательно. В противном случае платеж будет невозможен. |
Необязательно | merchantLogin |
String [1..255] | Чтобы зарегистрировать заказ от имени другого мерчанта, укажите его логин (для API-аккаунта) в этом параметре. Можно использовать, только если у вас есть разрешение на просмотр транзакций других продавцов или если указанный продавец является вашим дочерним продавцом. |
Необязательно | cardholderName |
String [1..150] | Имя держателя карты латинскими буквами. При передаче данного параметра имя держателя карты будет отображено на платежной странице. |
Необязательно | jsonParams |
Object | Набор дополнительных атрибутов произвольной формы, структура:jsonParams={"param_1_name":"param_1_value",...,"param_n_name":"param_n_value"} Могут быть переданы в Процесинговый Центр, для последующей обработки (требуется дополнительная настройка - обратитесь в поддержку). Некоторые предопределенные атрибуты jsonParams:
|
Необязательно | sessionTimeoutSecs |
Integer [1..9] | Продолжительность жизни заказа в секундах. В случае если параметр не задан, будет использовано значение, указанное в настройках мерчанта или время по умолчанию (1200 секунд = 20 минут). Если в запросе присутствует параметр expirationDate , то значение параметра sessionTimeoutSecs не учитывается. |
Необязательно | expirationDate |
String | Дата и время истечения срока действия заказа. Формат: yyyy-MM-ddTHH:mm:ss .Если этот параметр не передается в запросе, то для определения времени истечения срока действия заказа используется параметр sessionTimeoutSecs . |
Необязательно | bindingId |
String [1..255] | Идентификатор уже существующей связки. (идентификатор карты, токенизированной шлюзом). Его можно использовать, только если у мерчанта есть разрешение на работу со связками. Если этот параметр передается в этом запросе, это означает, что:
|
Необязательно | features |
String | Функции заказа Ниже приведены возможные значения.
|
Необязательно | postAddress |
String [1..255] | Адрес доставки. |
Необязательно | orderBundle |
Object | Объект, содержащий корзину товаров. Описание вложенных элементов приведено ниже. |
Необязательно | feeInput |
String | Размер комиссии в минимальных единицах валюты. Функциональность должна быть включена на уровне продавца в шлюзе. |
Условие | email |
String | Электронная почта для отображения на платежной странице. Если для продавца настроены уведомления клиента, электронную почту необходимо указать. Пример: client_mail@email.com . Адрес электронной почты не проверяется при регистрации, он будет проверен позже при оплате. |
Необязательно | billingPayerData |
Object | Блок с регистрационными данными клиента (адрес, почтовый индекс), необходимый для прохождения проверки адреса в рамках сервисов AVS/AVV. Обязательно, если функция включена для продавца на стороне Платежного шлюза. См вложенные параметры. |
Необязательно | shippingPayerData |
Object | Объект, содержащий данные о доставке клиенту. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. См. вложенные параметры. |
Необязательно | preOrderPayerData |
Object | Объект, содержащий данные предварительного заказа. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. См. вложенные параметры. |
Необязательно | orderPayerData |
Object | Объект, содержащий данные о плательщике заказа. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. См. вложенные параметры. |
Необязательно | billingAndShippingAddressMatchIndicator |
A1 | Индикатор соответствия платежного адреса владельца карты и адреса доставки. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. Возможные значения:
|
Ниже приведены параметры блока billingPayerData
(данные об адресе регистрации клиента).
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | billingCity |
String [0..50] | Город, зарегистрированный по конкретной карте у Банка Эмитента. |
Необязательно | billingCountry |
String [0..50] | Страна, зарегистрированная по конкретной карте банка-эмитента (ISO 3166-1, числовой). |
Необязательно | billingAddressLine1 |
String [0..50] | Адрес, зарегистрированный по конкретной карте у Банка Эмитента. Строка 1. Обязательно к передаче для AVS-проверки. |
Необязательно | billingAddressLine2 |
String [0..50] | Адрес, зарегистрированный по конкретной карте у Банка Эмитента. Строка 2. |
Необязательно | billingAddressLine3 |
String [0..50] | Адрес, зарегистрированный по конкретной карте у Банка Эмитента. Строка 3. |
Необязательно | billingPostalCode |
String [0..9] | Почтовый индекс, зарегистрированный по конкретной карте у Банка Эмитента. Обязательно к передаче для AVS-проверки. |
Необязательно | billingState |
String [0..50] | Штат, зарегистрированный по конкретной карте у Банка Эмитента. |
Описание параметров объекта shippingPayerData
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | shippingCity |
ANS...50 | Город заказчика (из адреса доставки) |
Необязательно | shippingCountry |
ANS...50 | Страна заказчика |
Необязательно | shippingAddressLine1 |
ANS...50 | Основной адрес клиента (из адреса доставки) |
Необязательно | shippingAddressLine2 |
ANS...50 | Основной адрес клиента (из адреса доставки) |
Необязательно | shippingAddressLine3 |
ANS...50 | Основной адрес клиента (из адреса доставки) |
Необязательно | shippingPostalCode |
ANS...16 | Почтовый индекс клиента для доставки |
Необязательно | shippingState |
ANS...50 | Штат/регион покупателя (из адреса доставки) |
Необязательно | shippingMethodIndicator |
N2 | Индикатор способа доставки. Возможные значения:
|
Необязательно | deliveryTimeframe |
N2 | Срок поставки товара. Возможные значения:
|
Необязательно | deliveryEmail |
ANS...254 | Целевой адрес электронной почты для доставки цифрового распространения. Предпочтительно передавать электронную почту в самостоятельном параметре запроса email (но если вы передадите его в этом блоке, к нему применятся те же правила). |
Описание параметров объекта preOrderPayerData
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | preOrderDate |
ANS8 | Ожидаемая дата доставки (для предзаказанных покупок) в формате ГГГГММДД. |
Необязательно | preOrderPurchaseInd |
N2 | Индикатор размещения клиентом заказа на доступную или будущую доставку. Возможные значения:
|
Необязательно | reorderItemsInd |
N2 | Индикатор того, что клиент перебронирует ранее оплаченную доставку в составе нового заказа. Возможные значения:
|
Описание параметров объекта orderPayerData
.
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | homePhone |
ANS...19 | Домашний телефон владельца карты. Необходимо всегда указывать код страны, но знак + или 00 в начале можно указать или опустить. Номер должен иметь длину от 7 до 15 цифр. Таким образом, возможны следующие значения:
|
Необязательно | workPhone |
ANS...19 | Рабочий телефон владельца карты. Необходимо всегда указывать код страны, но знак + или 00 в начале можно указать или опустить. Номер должен иметь длину от 7 до 15 цифр. Таким образом, возможны следующие значения:
|
Необязательно | mobilePhone |
ANS...19 | Номер мобильного телефона владельца карты. Необходимо всегда указывать код страны, но знак + или 00 в начале можно указать или опустить. Номер должен иметь длину от 7 до 15 цифр. Таким образом, возможны следующие значения:
Для платежей по VISA с 3DS авторизацией необходимо указать либо электронную почту, либо номер телефона владельца карты. Если у вас настроено отображение номера телефона на платежной странице и вы указали неверный номер телефона, клиент сможет исправить его на платежной странице. |
Описание параметров в объекте orderBundle
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | orderCreationDate |
String | Дата создания заказа в формате YYYY-MM-DDTHH:MM:SS . |
Необязательно | customerDetails |
Object | Блок, содержащий атрибуты клиента. Описание атрибутов тега приведено ниже. |
Обязательно | cartItems |
Object | Объект, содержащий атрибуты товаров в корзине. Описание вложенных элементов приведено ниже. |
Описание параметров в объекте customerDetails
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | contact |
String [0..40] | Предпочитаемый клиентом способ связи. |
Необязательно | fullName |
String [1..100] | ФИО плательщика. |
Необязательно | passport |
Integer | Серия и номер паспорта плательщика в следующем формате: 2222888888
|
Необязательно | deliveryInfo |
Object | Объект, содержащий атрибуты адреса доставки. Описание вложенных элементов приведено ниже. |
Описание параметров в объекте deliveryInfo
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | deliveryType |
String [1..20] | Способ доставки. |
Обязательно | country |
String | Двухбуквенный код страны доставки. |
Обязательно | city |
String [0..40] | Город назначения. |
Обязательно | postAddress |
String [1..255] | Адрес доставки. |
Описание параметров в объекте cartItems
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | items |
Object | Элемент массива с атрибутами товарной позиции. Описание вложенных элементов приведено ниже. |
Описание параметров в объекте items
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | positionId |
Integer [1..12] | Уникальный идентификатор товарной позиции в корзине. |
Обязательно | name |
String [1..255] | Наименование или описание товарной позиции в свободной форме. |
Необязательно | itemDetails |
Object | Объект с параметрами описания товарной позиции. Описание вложенных элементов приведено ниже. |
Обязательно | quantity |
Object | Элемент, описывающий передается общее количество товарных позиций одного positionId и его единицы измерения. Описание вложенных элементов приведено ниже. |
Необязательно | itemAmount |
Integer [1..12] | Сумма стоимости всех товарных позиций одного positionId в минимальных единицах валюты. itemAmount обязателен к передаче, только если не был передан параметр itemPrice . В противном случае передача itemAmount не требуется. Если же в запросе передаются оба параметра: itemPrice и itemAmount , то itemAmount должен равняться itemPrice * quantity , в противном случае запрос завершится с ошибкой. |
Необязательно | itemPrice |
Integer [1..18] | Сумма стоимости товарной позиции одного positionId в деньгах в минимальных единицах валюты. |
Необязательно | itemCurrency |
Integer | Код валюты ISO 4217. Если не указан, считается равным валюте заказа. |
Обязательно | itemCode |
String [1..100] | Номер (идентификатор) товарной позиции в системе магазина. |
Описание параметров в объекте quantity
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | value |
String | Количество товарных позиций данного positionId . Для указания дробных чисел используйте десятичную точку. |
Обязательно | measure |
String [1..20] | Единица измерения количества по позиции. |
Описание параметров в объекте itemDetails
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | itemDetailsParams |
Object | Параметр, описывающий дополнительную информацию по товарной позиции. Описание вложенных элементов приведено ниже. |
Описание параметров в объекте itemDetailsParams
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | value |
String | Дополнительная информация по товарной позиции. |
Обязательно | name |
String [1..255] | Наименование параметра описания детализации товарной позиции |
Параметры ответа
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | errorCode |
Integer [1..2] | Информационный параметр в случае ошибки, который может иметь разные кодовые значения:
|
Необязательно | errorMessage |
String [1..512] | Информационный параметр, являющийся описанием ошибки в случае возникновения ошибки. Значение errorMessage может варьироваться, поэтому не следует явным образом ссылаться на его значения в коде. Язык описания задается в параметре language запроса. |
Необязательно | formUrl |
String [1..512] | URL платежной формы, на которую будет перенаправлен покупатель. URL не возвращается, если регистрация заказа не прошла из-за ошибки, указанной в errorCode . |
Необязательно | orderId |
String [1..36] | Номер заказа в платежном шлюзе. Уникален в пределах платежного шлюза. |
Примеры
Пример запроса
curl --request POST \
--url https://3dsec.berekebank.kz/payment/rest/register.do \
--header 'content-type: application/x-www-form-urlencoded' \
--data amount=123456 \
--data userName=test_user \
--data password=test_user_password \
--data orderNumber=1234567890ABCDEF \
--data returnUrl=https://mybestmerchantreturnurl.com \
--data failUrl=https://mybestmerchantfailurl.com \
--data email=test@test.com \
--data clientId=259753456 \
--data language=en
--data 'jsonParams={"param_1_name":"param_1_value","param_2_name":"param_2_value"}'
Пример ответа - успех
{
"orderId": "01491d0b-c848-7dd6-a20d-e96900a7d8c0",
"formUrl": "https://3dsec.berekebank.kz/payment/payment/merchants/ecom/payment_en.html?mdOrder=01491d0b-c848-7dd6-a20d-e96900a7d8c0"
}
Пример ответа - ошибка
{
"errorCode": "1",
"errorMessage": "Заказ с таким номером уже обработан"
}
Регистрация заказа с предавторизацией
Для запроса регистрации заказа с предавторизацией используется метод https://3dsec.berekebank.kz/payment/rest/registerPreAuth.do
.
При выполнении запроса необходимо использовать заголовок:
Content-Type: application/x-www-form-urlencoded
Параметры запроса
Обязательность | Название | Тип | Описание |
---|---|---|---|
Условие | userName |
String [1..100] | Логин учетной записи API продавца. Если для аутентификации при регистрации вместо логина и пароля используется открытый токен (параметр token ), пароль передавать не нужно. |
Условие | password |
String [1..200] | Пароль учетной записи API продавца. Если для аутентификации при регистрации вместо логина и пароля используется открытый токен (параметр token ), пароль передавать не нужно. |
Условие | token |
String [1..256] | Значение, используемое для аутентификации продавца при отправке запросов платежному шлюзу. Если вы передаете этот параметр, то не передавайте userName и password . |
Обязательно | orderNumber |
String [1..32] | Номер заказа (ID) в системе мерчанта; должен быть уникальным для каждого заказа. |
Обязательно | amount |
Integer [0..12] | Сумма платежа в минимальных единицах валюты (например, в копейках). |
Необязательно | currency |
Integer [3] | Код валюты платежа ISO 4217. Если не указано, то используется значение по умолчанию. |
Обязательно | returnUrl |
String [1..512] | Адрес, на который требуется перенаправить пользователя в случае успешной оплаты. Адрес должен быть указан полностью, включая используемый протокол (например, https://mybestmerchantreturnurl.com вместо mybestmerchantreturnurl.com ). В противном случае пользователь будет перенаправлен по адресу следующего вида: https://3dsec.berekebank.kz/payment/<merchant_address> . |
Необязательно | failUrl |
String [1..512] | Адрес, на который требуется перенаправить пользователя в случае неуспешной оплаты. Адрес должен быть указан полностью, включая используемый протокол (например, https://mybestmerchantreturnurl.com вместо mybestmerchantreturnurl.com ). В противном случае пользователь будет перенаправлен по адресу следующего вида: https://3dsec.berekebank.kz/payment/<merchant_address> . |
Необязательно | dynamicCallbackUrl |
String [1..512] | Параметр для передачи динамического адреса для получения "платежных" callback-уведомлений по заказу, активированных для мерчанта (успешная авторизация, успешное списание, возврат, отмена, отклонение платежа по таймауту, отклонение card present платежа). "Не платежные" callback-уведомления (включение/выключение связки, создание связки), будут отправляться на статический callback адрес. |
Необязательно | description |
String [1..598] | Описание заказа в любом формате. Чтобы включить отправку этого поля в процессинговую систему, обратитесь в службу технической поддержки. В этом поле недопустимо передавать персональные данные или платежные данные (номера карт т.п.). Данное требование связано с тем, что описание заказа нигде не маскируется. |
Необязательно | ip |
String [1..39] | IP адрес плательщика. IPv6 поддерживается во всех запросах (до 39 символов). |
Необязательно | language |
String [2] | Ключ языка по ISO 639-1. Если язык не указан, используется язык по умолчанию, указанный в настройках магазина. Поддерживаемые языки: ru, en. |
Необязательно | clientId |
String [0..255] | Номер клиента (ID) в системе мерчанта — до 255 символов. Используется для реализации функциональности связок. Может возвращаться в ответе, если мерчанту разрешено создавать связки. Указание этого параметра при обработке платежей по связке обязательно. В противном случае платеж будет невозможен. |
Необязательно | merchantLogin |
String [1..255] | Чтобы зарегистрировать заказ от имени другого мерчанта, укажите его логин (для API-аккаунта) в этом параметре. Можно использовать, только если у вас есть разрешение на просмотр транзакций других продавцов или если указанный продавец является вашим дочерним продавцом. |
Необязательно | cardholderName |
String [1..150] | Имя держателя карты латинскими буквами. При передаче данного параметра имя держателя карты будет отображено на платежной странице. |
Необязательно | jsonParams |
Object | Набор дополнительных атрибутов произвольной формы, структура:jsonParams={"param_1_name":"param_1_value",...,"param_n_name":"param_n_value"} Могут быть переданы в Процесинговый Центр, для последующей обработки (требуется дополнительная настройка - обратитесь в поддержку). Некоторые предопределенные атрибуты jsonParams:
|
Необязательно | sessionTimeoutSecs |
Integer [1..9] | Продолжительность жизни заказа в секундах. В случае если параметр не задан, будет использовано значение, указанное в настройках мерчанта или время по умолчанию (1200 секунд = 20 минут). Если в запросе присутствует параметр expirationDate , то значение параметра sessionTimeoutSecs не учитывается. |
Необязательно | expirationDate |
String | Дата и время истечения срока действия заказа. Формат: yyyy-MM-ddTHH:mm:ss .Если этот параметр не передается в запросе, то для определения времени истечения срока действия заказа используется параметр sessionTimeoutSecs . |
Необязательно | bindingId |
String [1..255] | Идентификатор уже существующей связки. (идентификатор карты, токенизированной шлюзом). Его можно использовать, только если у мерчанта есть разрешение на работу со связками. Если этот параметр передается в этом запросе, это означает, что:
|
Необязательно | features |
String | Функции заказа Ниже приведены возможные значения.
|
Необязательно | autocompletionDate |
String | Дата и время автоматического завершения двухстадийного платежа в следующем формате: 2017-12-29T13:02:51. Используемый часовой пояс: UTC+3. Чтобы включить отправку этого поля в процессинговую систему, обратитесь в службу технической поддержки. |
Необязательно | autoReverseDate |
String | Дата и время автоматического отмены двухстадийного платежа в следующем формате: 2022-06-23T13:02:51. Используемый часовой пояс: UTC+3. Чтобы включить отправку этого поля в процессинговую систему, обратитесь в службу технической поддержки. |
Необязательно | postAddress |
String [1..255] | Адрес доставки. |
Необязательно | orderBundle |
Object | Объект, содержащий корзину товаров. Описание вложенных элементов приведено ниже. |
Необязательно | feeInput |
String | Размер комиссии в минимальных единицах валюты. Функциональность должна быть включена на уровне продавца в шлюзе. |
Условие | email |
String | Электронная почта для отображения на платежной странице. Если для продавца настроены уведомления клиента, электронную почту необходимо указать. Пример: client_mail@email.com . Адрес электронной почты не проверяется при регистрации, он будет проверен позже при оплате. |
Необязательно | billingPayerData |
Object | Блок с регистрационными данными клиента (адрес, почтовый индекс), необходимый для прохождения проверки адреса в рамках сервисов AVS/AVV. Обязательно, если функция включена для продавца на стороне Платежного шлюза. См вложенные параметры. |
Необязательно | shippingPayerData |
Object | Объект, содержащий данные о доставке клиенту. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. См. вложенные параметры. |
Необязательно | preOrderPayerData |
Object | Объект, содержащий данные предварительного заказа. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. См. вложенные параметры. |
Необязательно | orderPayerData |
Object | Объект, содержащий данные о плательщике заказа. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. См. вложенные параметры. |
Необязательно | billingAndShippingAddressMatchIndicator |
A1 | Индикатор соответствия платежного адреса владельца карты и адреса доставки. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. Возможные значения:
|
Ниже приведены параметры блока billingPayerData
(данные об адресе регистрации клиента).
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | billingCity |
String [0..50] | Город, зарегистрированный по конкретной карте у Банка Эмитента. |
Необязательно | billingCountry |
String [0..50] | Страна, зарегистрированная по конкретной карте банка-эмитента (ISO 3166-1, числовой). |
Необязательно | billingAddressLine1 |
String [0..50] | Адрес, зарегистрированный по конкретной карте у Банка Эмитента. Строка 1. Обязательно к передаче для AVS-проверки. |
Необязательно | billingAddressLine2 |
String [0..50] | Адрес, зарегистрированный по конкретной карте у Банка Эмитента. Строка 2. |
Необязательно | billingAddressLine3 |
String [0..50] | Адрес, зарегистрированный по конкретной карте у Банка Эмитента. Строка 3. |
Необязательно | billingPostalCode |
String [0..9] | Почтовый индекс, зарегистрированный по конкретной карте у Банка Эмитента. Обязательно к передаче для AVS-проверки. |
Необязательно | billingState |
String [0..50] | Штат, зарегистрированный по конкретной карте у Банка Эмитента. |
Описание параметров объекта shippingPayerData
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | shippingCity |
ANS...50 | Город заказчика (из адреса доставки) |
Необязательно | shippingCountry |
ANS...50 | Страна заказчика |
Необязательно | shippingAddressLine1 |
ANS...50 | Основной адрес клиента (из адреса доставки) |
Необязательно | shippingAddressLine2 |
ANS...50 | Основной адрес клиента (из адреса доставки) |
Необязательно | shippingAddressLine3 |
ANS...50 | Основной адрес клиента (из адреса доставки) |
Необязательно | shippingPostalCode |
ANS...16 | Почтовый индекс клиента для доставки |
Необязательно | shippingState |
ANS...50 | Штат/регион покупателя (из адреса доставки) |
Необязательно | shippingMethodIndicator |
N2 | Индикатор способа доставки. Возможные значения:
|
Необязательно | deliveryTimeframe |
N2 | Срок поставки товара. Возможные значения:
|
Необязательно | deliveryEmail |
ANS...254 | Целевой адрес электронной почты для доставки цифрового распространения. Предпочтительно передавать электронную почту в самостоятельном параметре запроса email (но если вы передадите его в этом блоке, к нему применятся те же правила). |
Описание параметров объекта preOrderPayerData
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | preOrderDate |
ANS8 | Ожидаемая дата доставки (для предзаказанных покупок) в формате ГГГГММДД. |
Необязательно | preOrderPurchaseInd |
N2 | Индикатор размещения клиентом заказа на доступную или будущую доставку. Возможные значения:
|
Необязательно | reorderItemsInd |
N2 | Индикатор того, что клиент перебронирует ранее оплаченную доставку в составе нового заказа. Возможные значения:
|
Описание параметров объекта orderPayerData
.
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | homePhone |
ANS...19 | Домашний телефон владельца карты. Необходимо всегда указывать код страны, но знак + или 00 в начале можно указать или опустить. Номер должен иметь длину от 7 до 15 цифр. Таким образом, возможны следующие значения:
|
Необязательно | workPhone |
ANS...19 | Рабочий телефон владельца карты. Необходимо всегда указывать код страны, но знак + или 00 в начале можно указать или опустить. Номер должен иметь длину от 7 до 15 цифр. Таким образом, возможны следующие значения:
|
Необязательно | mobilePhone |
ANS...19 | Номер мобильного телефона владельца карты. Необходимо всегда указывать код страны, но знак + или 00 в начале можно указать или опустить. Номер должен иметь длину от 7 до 15 цифр. Таким образом, возможны следующие значения:
Для платежей по VISA с 3DS авторизацией необходимо указать либо электронную почту, либо номер телефона владельца карты. Если у вас настроено отображение номера телефона на платежной странице и вы указали неверный номер телефона, клиент сможет исправить его на платежной странице. |
Описание параметров в объекте orderBundle
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | orderCreationDate |
String | Дата создания заказа в формате YYYY-MM-DDTHH:MM:SS . |
Необязательно | customerDetails |
Object | Блок, содержащий атрибуты клиента. Описание атрибутов тега приведено ниже. |
Обязательно | cartItems |
Object | Объект, содержащий атрибуты товаров в корзине. Описание вложенных элементов приведено ниже. |
Описание параметров в объекте customerDetails
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | contact |
String [0..40] | Предпочитаемый клиентом способ связи. |
Необязательно | fullName |
String [1..100] | ФИО плательщика. |
Необязательно | passport |
Integer | Серия и номер паспорта плательщика в следующем формате: 2222888888
|
Необязательно | deliveryInfo |
Object | Объект, содержащий атрибуты адреса доставки. Описание вложенных элементов приведено ниже. |
Описание параметров в объекте deliveryInfo
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | deliveryType |
String [1..20] | Способ доставки. |
Обязательно | country |
String | Двухбуквенный код страны доставки. |
Обязательно | city |
String [0..40] | Город назначения. |
Обязательно | postAddress |
String [1..255] | Адрес доставки. |
Описание параметров в объекте cartItems
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | items |
Object | Элемент массива с атрибутами товарной позиции. Описание вложенных элементов приведено ниже. |
Описание параметров в объекте items
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | positionId |
Integer [1..12] | Уникальный идентификатор товарной позиции в корзине. |
Обязательно | name |
String [1..255] | Наименование или описание товарной позиции в свободной форме. |
Необязательно | itemDetails |
Object | Объект с параметрами описания товарной позиции. Описание вложенных элементов приведено ниже. |
Обязательно | quantity |
Object | Элемент, описывающий передается общее количество товарных позиций одного positionId и его единицы измерения. Описание вложенных элементов приведено ниже. |
Необязательно | itemAmount |
Integer [1..12] | Сумма стоимости всех товарных позиций одного positionId в минимальных единицах валюты. itemAmount обязателен к передаче, только если не был передан параметр itemPrice . В противном случае передача itemAmount не требуется. Если же в запросе передаются оба параметра: itemPrice и itemAmount , то itemAmount должен равняться itemPrice * quantity , в противном случае запрос завершится с ошибкой. |
Необязательно | itemPrice |
Integer [1..18] | Сумма стоимости товарной позиции одного positionId в деньгах в минимальных единицах валюты. |
Необязательно | itemCurrency |
Integer | Код валюты ISO 4217. Если не указан, считается равным валюте заказа. |
Обязательно | itemCode |
String [1..100] | Номер (идентификатор) товарной позиции в системе магазина. |
Описание параметров в объекте quantity
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | value |
String | Количество товарных позиций данного positionId . Для указания дробных чисел используйте десятичную точку. |
Обязательно | measure |
String [1..20] | Единица измерения количества по позиции. |
Описание параметров в объекте itemDetails
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | itemDetailsParams |
Object | Параметр, описывающий дополнительную информацию по товарной позиции. Описание вложенных элементов приведено ниже. |
Описание параметров в объекте itemDetailsParams
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | value |
String | Дополнительная информация по товарной позиции. |
Обязательно | name |
String [1..255] | Наименование параметра описания детализации товарной позиции |
Параметры ответа
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | errorCode |
Integer [1..2] | Информационный параметр в случае ошибки, который может иметь разные кодовые значения:
|
Необязательно | errorMessage |
String [1..512] | Информационный параметр, являющийся описанием ошибки в случае возникновения ошибки. Значение errorMessage может варьироваться, поэтому не следует явным образом ссылаться на его значения в коде. Язык описания задается в параметре language запроса. |
Необязательно | orderId |
String [1..36] | Номер заказа в платежном шлюзе. Уникален в пределах платежного шлюза. |
Необязательно | formUrl |
String [1..512] | URL платежной формы, на которую будет перенаправлен покупатель. URL не возвращается, если регистрация заказа не прошла из-за ошибки, указанной в errorCode . |
Примеры
Пример запроса
curl --request POST \
--url https://3dsec.berekebank.kz/payment/rest/registerPreAuth.do \
--header 'content-type: application/x-www-form-urlencoded' \
--data amount=2000 \
--data userName=test_user \
--data password=test_user_password \
--data returnUrl=https://mybestmerchantreturnurl.com \
--data orderNumber=1255555555555 \
--data clientId=259753456 \
--data language=en
Пример ответа
{
"orderId": "01492437-d2fb-77fa-8db7-9e2900a7d8c0",
"formUrl": "https://3dsec.berekebank.kz/payment/merchants/pay/payment_en.html?mdOrder=01492437-d2fb-77fa-8db7-9e2900a7d8c0"
}
Прямые платежи
Оплата заказа
Для оплаты ранее зарегистрированного заказа используется запрос https://3dsec.berekebank.kz/payment/rest/paymentorder.do
.
Запрос используется в режиме внутренний MPI/3DS Server, для этого не требуется наличие дополнительных разрешений и/или сертификаций.
Запрос используется в режиме внешнего MPI/3DS Server если у вас есть договор с международной платежной системой или сертификат, который позволяет самостоятельно проводить аутентификацию 3DS.
Это означает, что вы можете использовать собственный MPI/3DS Server для аутентификации клиента с использованием технологии 3D Secure. Дополнительная информация об оплате с собственным MPI/3DS Server доступна здесь.
При выполнении запроса необходимо использовать заголовок:
Content-Type: application/x-www-form-urlencoded
Оплата заказа (внутренний MPI/3DS Server)
Оплата заказа происходит с передачей карточных платежных данных, а так же с использованием технологии аутентификации 3DS (применение аутентификации регулируется настройками, регулируемых службой поддержки).
Параметры запроса
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | userName |
String [1..100] | Логин учетной записи API продавца. |
Обязательно | password |
String [1..200] | Пароль учетной записи API продавца. Если для аутентификации при регистрации вместо логина и пароля используется открытый токен (параметр token ), пароль передавать не нужно. |
Обязательно | MDORDER |
String [1..36] | Номер заказа в платежном шлюзе. |
Обязательно | $PAN |
Integer [1..19] | Номер платежной карты. Обязательный, если не передан seToken . |
Обязательно | $CVC |
Integer | Код CVC/CVV2 на обратной стороне карты. Обязательный, если не передан seToken . |
Обязательно | YYYY |
Integer | Год окончания действия платежной карты. Если seToken не передан, обязательно необходимо передать либо $EXPIRY , либо YYYY и MM . |
Обязательно | MM |
Integer | Месяц окончания действия платежной карты. Если seToken не передан, обязательно необходимо передать либо $EXPIRY , либо YYYY и MM . |
Условие | $EXPIRY |
Integer | Срок действия карты в следующем формате: YYYYMM . Переопределяет параметры YYYY и MM . Если seToken не передан, обязательно необходимо передать либо $EXPIRY , либо YYYY и MM . |
Условие | seToken |
String | Зашифрованные данные карты, которые заменяют параметры $PAN , $CVC и $EXPIRY (или YYYY ,MM ). Обязательно, если используется вместо данных карты.Обязательные параметры для строки seToken: timestamp , UUID , PAN , EXPDATE , MDORDER . Подробнее о генерации seToken см. здесь. Если seToken содержит шифрованные данные о связке (bindingId), для оплаты следует использовать запрос paymentOrderBinding.do. |
Обязательно | TEXT |
String | Имя держателя карты. |
Обязательно | language |
String [2] | Ключ языка по ISO 639-1. Если язык не указан, используется язык по умолчанию, указанный в настройках магазина. Поддерживаемые языки: ru, en. |
Необязательно | ip |
String [1..39] | IP адрес плательщика. IPv6 поддерживается во всех запросах (до 39 символов). |
Необязательно | bindingNotNeeded |
Boolean | Допустимые значения:
|
Необязательно | jsonParams |
Object | Поля дополнительной информации для последующего хранения, передаются в следующем виде: jsonParams={"param_1_name":"param_1_value",...,"param_n_name":"param_n_value"} .Могут быть переданы в Процесинговый Центр, для последующей обработки (требуется дополнительная настройка - обратитесь в поддержку). Если вы используете внешний MPI/3DS Server, платежный шлюз ожидает, что каждый запрос paymentOrder будет включать ряд дополнительных параметров, таких как eci , xid , cavv и пр. Более подробная информация здесь.Чтобы инициировать 3RI аутентификацию, вам может быть необходимо передать ряд дополнительных параметров (см. 3RI аутентификация). Некоторые предопределенные атрибуты jsonParams:
|
Необязательно | threeDSSDK |
Boolean | Возможные значения: true или false Флаг, показывающий, что платеж поступает из 3DS SDK. |
Условие | email |
String | Электронная почта для отображения на платежной странице. Если для продавца настроены уведомления клиента, электронную почту необходимо указать. Пример: client_mail@email.com . Для платежей по VISA с 3DS авторизацией необходимо указать либо электронную почту, либо номер телефона владельца карты. |
Необязательно | billingPayerData |
Object | Блок с регистрационными данными клиента (адрес, почтовый индекс), необходимый для прохождения проверки адреса в рамках сервисов AVS/AVV. Обязательно, если функция включена для продавца на стороне Платежного шлюза. См вложенные параметры. |
Необязательно | shippingPayerData |
Object | Объект, содержащий данные о доставке клиенту. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. См. вложенные параметры. |
Необязательно | preOrderPayerData |
Object | Объект, содержащий данные предварительного заказа. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. См. вложенные параметры. |
Необязательно | orderPayerData |
Object | Объект, содержащий данные о плательщике заказа. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. См. вложенные параметры. |
Необязательно | tii |
String | Идентификатор инициатора транзакции. Параметр, указывающий, какой тип операции будет выполнять инициатор (Клиент или Мерчант). Возможные значения |
Необязательно | externalScaExemptionIndicator |
String | Тип исключения SCA (Strong Customer Authentication). Если указан этот параметр, транзакция будет обработана в зависимости от ваших настроек в платежном шлюзе: либо будет выполнена принудительная операция SSL, либо банк-эмитент получит информацию об исключении SCA и примет решение о проведении операции с 3DS-аутентификацией или без нее (для получения подробной информации свяжитесь с нашей службой поддержки). Допустимые значения:
Для передачи этого параметра у вас должны быть достаточные права в платежном шлюзе. |
Необязательно | clientBrowserInfo |
Object | Блок данных о браузере клиента, который отправляется на ACS во время 3DS аутентификации. Этот блок можно передавать, только если включена специальная настройка (обратитесь в команду поддержки). См. вложенные параметры. |
Необязательно | acsInIFrame |
Boolean | Флаг, показывающий, что для финишного URL будет возвращаться iFrame версия. Возможные значения true or false . Для подключения данной функциональности обратитесь в службу поддержки. |
Ниже приведены параметры блока billingPayerData
(данные об адресе регистрации клиента).
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | billingCity |
String [0..50] | Город, зарегистрированный по конкретной карте у Банка Эмитента. |
Необязательно | billingCountry |
String [0..50] | Страна, зарегистрированная по конкретной карте банка-эмитента (ISO 3166-1, числовой). |
Необязательно | billingAddressLine1 |
String [0..50] | Адрес, зарегистрированный по конкретной карте у Банка Эмитента. Строка 1. Обязательно к передаче для AVS-проверки. |
Необязательно | billingAddressLine2 |
String [0..50] | Адрес, зарегистрированный по конкретной карте у Банка Эмитента. Строка 2. |
Необязательно | billingAddressLine3 |
String [0..50] | Адрес, зарегистрированный по конкретной карте у Банка Эмитента. Строка 3. |
Необязательно | billingPostalCode |
String [0..9] | Почтовый индекс, зарегистрированный по конкретной карте у Банка Эмитента. Обязательно к передаче для AVS-проверки. |
Необязательно | billingState |
String [0..50] | Штат, зарегистрированный по конкретной карте у Банка Эмитента. |
Описание параметров объекта shippingPayerData
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | shippingCity |
ANS...50 | Город заказчика (из адреса доставки) |
Необязательно | shippingCountry |
ANS...50 | Страна заказчика |
Необязательно | shippingAddressLine1 |
ANS...50 | Основной адрес клиента (из адреса доставки) |
Необязательно | shippingAddressLine2 |
ANS...50 | Основной адрес клиента (из адреса доставки) |
Необязательно | shippingAddressLine3 |
ANS...50 | Основной адрес клиента (из адреса доставки) |
Необязательно | shippingPostalCode |
ANS...16 | Почтовый индекс клиента для доставки |
Необязательно | shippingState |
ANS...50 | Штат/регион покупателя (из адреса доставки) |
Необязательно | shippingMethodIndicator |
N2 | Индикатор способа доставки. Возможные значения:
|
Необязательно | deliveryTimeframe |
N2 | Срок поставки товара. Возможные значения:
|
Необязательно | deliveryEmail |
ANS...254 | Целевой адрес электронной почты для доставки цифрового распространения. Предпочтительно передавать электронную почту в самостоятельном параметре запроса email (но если вы передадите его в этом блоке, к нему применятся те же правила). |
Описание параметров объекта preOrderPayerData
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | preOrderDate |
ANS8 | Ожидаемая дата доставки (для предзаказанных покупок) в формате ГГГГММДД. |
Необязательно | preOrderPurchaseInd |
N2 | Индикатор размещения клиентом заказа на доступную или будущую доставку. Возможные значения:
|
Необязательно | reorderItemsInd |
N2 | Индикатор того, что клиент перебронирует ранее оплаченную доставку в составе нового заказа. Возможные значения:
|
Описание параметров объекта orderPayerData
.
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | homePhone |
ANS...19 | Домашний телефон владельца карты. Необходимо всегда указывать код страны, но знак + или 00 в начале можно указать или опустить. Номер должен иметь длину от 7 до 15 цифр. Таким образом, возможны следующие значения:
|
Необязательно | workPhone |
ANS...19 | Рабочий телефон владельца карты. Необходимо всегда указывать код страны, но знак + или 00 в начале можно указать или опустить. Номер должен иметь длину от 7 до 15 цифр. Таким образом, возможны следующие значения:
|
Необязательно | mobilePhone |
ANS...19 | Номер мобильного телефона владельца карты. Необходимо всегда указывать код страны, но знак + или 00 в начале можно указать или опустить. Номер должен иметь длину от 7 до 15 цифр. Таким образом, возможны следующие значения:
Для платежей по VISA с 3DS авторизацией необходимо указать либо электронную почту, либо номер телефона владельца карты. Если у вас настроено отображение номера телефона на платежной странице и вы указали неверный номер телефона, клиент сможет исправить его на платежной странице. |
Возможные значения tii
(Подробнее о типах связок, поддерживаемых платежным шлюзом, читайте здесь).
Значение tii
|
Описание | Тип транзакции | Инициатор транзакции | Данные карты для транзакции | Сохранение данных карты после транзакции | Примечание |
---|---|---|---|---|---|---|
Пусто | Обычный | Покупатель | Вводится покупателем | Нет | Транзакция электронной коммерции без сохранения связки. | |
CI | Инициирующий - Обычный (CIT) | Инициирующая | Покупатель | Вводится покупателем | Да | Транзакция электронной коммерции с сохранением связки. |
F | Внеплановый платеж (CIT) | Последующая | Покупатель | Клиент выбирает карту вместо ручного ввода | Нет | Транзакция электронной коммерции, использующая ранее сохраненную обычную связку. |
U | Внеплановый платеж (MIT) | Последующая | Продавец | Нет ручного ввода, продавец передает данные | Нет | Транзакция электронной коммерции, использующая ранее сохраненную обычную связку. |
RI | Инициирующий - Рекурентные (CIT) | Инициирующая | Покупатель | Вводится покупателем | Да | Транзакция электронной коммерции с сохранением связки. |
R | Рекуррентный платеж (MIT) | Последующая | Продавец | Нет ручного ввода, продавец передает данные | Нет | Рекуррентная операция, использующая сохраненную связку. |
II | Инициирующий - Рассрочка (CIT) | Инициирующая | Покупатель | Вводится покупателем | Да | Транзакция электронной коммерции с сохранением связки. |
I | Платеж по рассрочке (MIT) | Последующая | Продавец | Нет ручного ввода, продавец передает данные | Нет | Операция рассрочки, использующая сохраненную связку. |
Ниже приведены параметры блока clientBrowserInfo
(данные о браузере клиента).
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | userAgent | string | Агент браузера. |
Необязательно | OS | string | Операционная система. |
Необязательно | OSVersion | string | Версия операционной системы. |
Необязательно | browserAcceptHeader | string | Заголовок Accept, который сообщает серверу, какие форматы (или MIME-типы) поддерживает браузер. |
Необязательно | browserIpAddress | string | IP-адрес браузера. |
Необязательно | browserLanguage | string | Язык браузера. |
Необязательно | browserTimeZone | string | Часовой пояс браузера. |
Необязательно | browserTimeZoneOffset | integer | Смещение часового пояса в минутах между локальным временем пользователя и UTC. |
Необязательно | colorDepth | string | Глубина цвета экрана, в битах. |
Необязательно | fingerprint | string | Отпечаток браузера - уникальный цифровой идентификатор браузера. |
Необязательно | isMobile | Boolean | Возможные значения: true или false . Флаг, указывающий на то, что используется мобильное устройство. |
Необязательно | javaEnabled | Boolean | Возможные значения: true или false . Флаг, указывающий на то, что в браузере включена поддержка java. |
Необязательно | javascriptEnabled | Boolean | Возможные значения: true или false . Флаг, указывающий на то, что в браузере включена поддержка javascript. |
Необязательно | plugins | string | Список плагинов, используемых в браузере, через запятую. |
Необязательно | screenHeight | integer | Высота экрана в пикселях. |
Необязательно | screenWidth | integer | Ширина экрана в пикселях. |
Необязательно | screenPrint | string | Данные о параметрах печати браузера, включая разрешение, глубину цвета, плотность пикселей. |
Пример блока clientBrowserInfo
:
"clientBrowserInfo":
{
"userAgent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/111.0.0.0 Safari/537.36 Edg/111.0.1661.41",
"fingerprint":850891523,
"OS":"Windows",
"OSVersion":"10",
"isMobile":false,
"screenPrint":"Current Resolution: 1536x864, Available Resolution: 1536x824, Color Depth: 24, Device XDPI: undefined, Device YDPI: undefined",
"colorDepth":24,
"screenHeight":"864",
"screenWidth":"1536",
"plugins":"PDF Viewer, Chrome PDF Viewer, Chromium PDF Viewer, Microsoft Edge PDF Viewer, WebKit built-in PDF",
"javaEnabled":false,
"javascriptEnabled":true,
"browserLanguage":"it-IT",
"browserTimeZone":"Europe/Rome",
"browserTimeZoneOffset":-120,
"browserAcceptHeader":"gzip",
"browserIpAddress":"10.99.50.37"
}
При аутентификации по протоколу 3DS 2.0 также передаются следующие параметры:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | threeDSServerTransId |
String | Идентификатор транзакции, созданный на сервере 3DS. |
Необязательно | threeDSVer2FinishUrl |
String | URL-адрес, по которому клиент должен быть перенаправлен после аутентификации на сервере ACS. |
Необязательно | threeDSMethodNotificationUrl |
String | URL-адрес для отправки уведомления о прохождении проверки на ACS. |
Параметры ответа
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | errorCode |
Integer [1..2] | Информационный параметр в случае ошибки, который может иметь разные кодовые значения:
|
Необязательно | errorMessage |
String [1..512] | Информационный параметр, являющийся описанием ошибки в случае возникновения ошибки. Значение errorMessage может варьироваться, поэтому не следует явным образом ссылаться на его значения в коде. Язык описания задается в параметре language запроса. |
Необязательно | info |
String | В случае успешного ответа. Результат попытки оплаты. Ниже приведены возможные значения.
|
Необязательно | redirect |
String [1..512] | Этот параметр возвращается, если платеж прошел успешно и для платежа не проводилась проверка карты на вовлеченность в 3-D Secure. Продавцы могут использовать его, если хотят перенаправить пользователя на страницу платежного шлюза. Если продавец использует собственную страницу, это значение можно игнорировать. |
Необязательно | termUrl |
String [1..512] | При успешном ответе в случае оплаты 3D-Secure. Это URL-адрес, на который ACS перенаправляет владельца карты после аутентификации. Подробнее см. Редирект на ACS. |
Необязательно | acsUrl |
String [1..512] | При успешном ответе в случае оплаты 3D-Secure. URL-адрес для редиректа на ACS. Обязательный, если нужен редирект на ACS. Подробнее см. Редирект на ACS. |
Необязательно | paReq |
String [1..255] | При успешном ответе в случае оплаты 3D-Secure. PAReq (Payment Authentication Request) — сообщение, которое необходимо отправить в ACS вместе с редиректом. Это сообщение содержит данные в кодировке Base64, необходимые для аутентификации держателя карты. Подробнее см. Редирект на ACS. |
При аутентификации по протоколу 3DS 2.0 в ответ на первый запрос приходят следующие параметры:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | is3DSVer2 |
Boolean | Возможные значения: true или false Флаг, показывающий, что платеж поступает из 3DS 2.0. |
Обязательно | threeDSServerTransId |
String | Идентификатор транзакции, созданный на сервере 3DS. |
Необязательно | threeDSMethodUrl |
String | URL-адрес сервера ACS для сбора данных браузера. |
Обязательно | threeDSMethodUrlServer |
String | URL-адрес сервера 3DS для сбора данных браузера, которые будут включены в AReq (Authentication Request) с сервера 3DS на сервер ACS. |
Необязательно | threeDSMethodDataPacked |
String | Данные CReq (Challenge Response) в кодировке Base-64 для отправки на сервер ACS. |
Необязательно | threeDSMethodURLServerDirect |
String | URL-адрес 3dsmethod.do для выполнения метода 3DS на сервере 3DS через платежный шлюз (при наличии соответствующего разрешения на уровне продавца). |
Ниже приведены параметры, которые должны присутствовать в ответе, после повторного запроса платежа и необходимости перенаправления клиента в ACS при аутентификации по протоколу 3DS 2.0:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Условие | acsUrl |
String [1..512] | При успешном ответе в случае оплаты 3D-Secure. URL-адрес для редиректа на ACS. Обязательный, если нужен редирект на ACS. Подробнее см. Редирект на ACS. |
Условие | packedCReq |
String | Запакованные данные challenge request. Обязательный, если нужен редирект на ACS. Это значение следует использовать как значение параметра creq ссылки на ACS (acsUrl ), для перенаправления клиента на ACS. |
Примеры
Пример запроса
Пример первого запроса:
curl --request POST \
--url https://3dsec.berekebank.kz/payment/rest/paymentorder.do \
--header 'content-type: application/x-www-form-urlencoded' \
--data userName=test_user \
--data password=test_user_password \
--data MDORDER=64d3b8c2-5d87-7d92-bd20-d8db011b4f5b \
--data '$PAN=4000001111111118' \
--data '$CVC=123' \
--data YYYY=2030 \
--data MM=12 \
--data 'TEXT=TEST CARDHOLDER' \
--data language=en
--data 'jsonParams={"param_1_name":"param_1_value","param_2_name":"param_2_value"}'
Пример второго запроса:
curl --request POST \
--url https://3dsec.berekebank.kz/payment/rest/paymentorder.do \
--header 'content-type: application/x-www-form-urlencoded' \
--data userName=test_user \
--data password=test_user_password \
--data MDORDER=64d3b8c2-5d87-7d92-bd20-d8db011b4f5b \
--data '$PAN=4000001111111118' \
--data '$CVC=123' \
--data YYYY=2030 \
--data MM=12 \
--data 'TEXT=TEST CARDHOLDER' \
--data language=en \
--data threeDSServerTransID=5802746e-3393-40c3-929a-dc966ebf08c6
Примеры ответа
Пример ответа на первый запрос:
{
"errorCode": 0,
"is3DSVer2": true,
"threeDSServerTransId": "5802746e-3393-40c3-929a-dc966ebf08c6",
"threeDSMethodURL": "https://example.com/acs2/acs/3dsMethod",
"threeDSMethodURLServer": "example.com/3dsserver/api/v1/client/gather?threeDSServerTransID=5802746e-3393-40c3-929a-dc966ebf08c6",
"threeDSMethodDataPacked": "eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly9hY3F1aXJlci5jb20vM2Rzc2VydmVyL2FwaS92MS9hY3Mvbm90aWZpY2F0aW9uP3RocmVlRFNTZXJ2ZXJUcmFuc0lEPTNhZmMxNjhhLTk0YjQtNGViMy04ZTJlLTgwZjZjMTg2NjY5ZCIsInRocmVlRFNTZXJ2ZXJUcmFuc0lEIjoiM2FmYzE2OGEtOTRiNC00ZWIzLThlMmUtODBmNmMxODY2NjlkIn0="
}
Пример ответа на второй запрос:
{
"info": "Your order is proceeded, redirecting...",
"errorCode": 0,
"acsUrl": "https://example.com/acs2/acs/creq",
"is3DSVer2": true,
"packedCReq": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjU4MDI3NDZlLTMzOTMtNDBjMy05MjlhLWRjOTY2ZWJmMDhjNiIsIm1lc3NhZ2VUeXBlIjoiQ1JlcSIsIm1lc3NhZ2VWZXJzaW9uIjoiMi4xLjAiLCJhY3NUcmFuc0lEIjoiODFmZTU1ODUtZmZhOS00Y2NkLTljMjAtY2QzYWFiZDQwNTllIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjA1In0"
}
Оплата заказа (в режиме внешнего MPI/3DS Server)
Для использования запроса paymenOrder.do
в режиме внешний MPI/3DS Server
вам необходимо выполнить аутентификацию 3DS с использованием вашего собственного сервера MPI/3DS.
Также вам необходимо дополнительное разрешение, назначаемое службой поддержки.
Параметры запроса
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | userName |
String [1..100] | Логин учетной записи API продавца. |
Обязательно | password |
String [1..200] | Пароль учетной записи API продавца. |
Обязательно | MDORDER |
String [1..36] | Номер заказа в платежном шлюзе. |
Условие | $PAN |
Integer [1..19] | Номер платежной карты. Обязательный, если не передан seToken . |
Условие | $CVC |
Integer | Код CVC/CVV2 на обратной стороне карты. Обязательный, если не передан seToken . |
Условие | YYYY |
Integer | Год окончания действия платежной карты. Если seToken не передан, обязательно необходимо передать либо $EXPIRY , либо YYYY и MM . |
Условие | MM |
Integer | Месяц окончания действия платежной карты. Если seToken не передан, обязательно необходимо передать либо $EXPIRY , либо YYYY и MM . |
Условие | $EXPIRY |
Integer | Срок действия карты в следующем формате: YYYYMM . Переопределяет параметры YYYY и MM . Если seToken не передан, обязательно необходимо передать либо $EXPIRY , либо YYYY и MM . |
Условие | seToken |
String | Зашифрованные данные карты, которые заменяют параметры $PAN , $CVC и $EXPIRY (или YYYY ,MM ). Обязательно, если используется вместо данных карты.Обязательные параметры для строки seToken: timestamp , UUID , PAN , EXPDATE , MDORDER . Подробнее о генерации seToken см. здесь. Если seToken содержит шифрованные данные о связке (bindingId), для оплаты следует использовать запрос paymentOrderBinding.do. |
Обязательно | TEXT |
String | Имя держателя карты. |
Обязательно | language |
String [2] | Ключ языка по ISO 639-1. Если язык не указан, используется язык по умолчанию, указанный в настройках магазина. Поддерживаемые языки: ru, en. |
Необязательно | ip |
String [1..39] | IP адрес плательщика. IPv6 поддерживается во всех запросах (до 39 символов). |
Необязательно | bindingNotNeeded |
Boolean | Допустимые значения:
|
Необязательно | jsonParams |
Object | Поля дополнительной информации для последующего хранения, передаются в следующем виде: jsonParams={"param_1_name":"param_1_value",...,"param_n_name":"param_n_value"} .Могут быть переданы в Процесинговый Центр, для последующей обработки (требуется дополнительная настройка - обратитесь в поддержку). Если вы используете внешний MPI/3DS Server, платежный шлюз ожидает, что каждый запрос paymentOrder будет включать ряд дополнительных параметров, таких как eci , xid , cavv и пр. Более подробная информация здесь.Чтобы инициировать 3RI аутентификацию, вам может быть необходимо передать ряд дополнительных параметров (см. 3RI аутентификация). Некоторые предопределенные атрибуты jsonParams:
|
Необязательно | tii |
String | Идентификатор инициатора транзакции. Параметр, указывающий, какой тип операции будет выполнять инициатор (Клиент или Мерчант). Возможные значения |
Необязательно | threeDSProtocolVersion |
String | Версия протокола 3DS. Возможные значения: "2.1.0", "2.2.0" для 3DS2. Если в запросе не передается threeDSProtocolVersion , то для авторизации 3D Secure будет использоваться значение по умолчанию (2.1.0 - для 3DS 2). |
Условие | email |
String | Электронная почта для отображения на платежной странице. Если для продавца настроены уведомления клиента, электронную почту необходимо указать. Пример: client_mail@email.com . Для платежей по VISA с 3DS авторизацией необходимо указать либо электронную почту, либо номер телефона владельца карты. |
Необязательно | billingPayerData |
Object | Блок с регистрационными данными клиента (адрес, почтовый индекс), необходимый для прохождения проверки адреса в рамках сервисов AVS/AVV. Обязательно, если функция включена для продавца на стороне Платежного шлюза. См вложенные параметры. |
Необязательно | shippingPayerData |
Object | Объект, содержащий данные о доставке клиенту. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. См. вложенные параметры. |
Необязательно | preOrderPayerData |
Object | Объект, содержащий данные предварительного заказа. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. См. вложенные параметры. |
Необязательно | orderPayerData |
Object | Объект, содержащий данные о плательщике заказа. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. См. вложенные параметры. |
Необязательно | billingAndShippingAddressMatchIndicator |
A1 | Индикатор соответствия платежного адреса владельца карты и адреса доставки. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. Возможные значения:
|
Необязательно | clientBrowserInfo |
Object | Блок данных о браузере клиента, который отправляется на ACS во время 3DS аутентификации. Этот блок можно передавать, только если включена специальная настройка (обратитесь в команду поддержки). См. вложенные параметры. |
Необязательно | acsInIFrame |
Boolean | Флаг, показывающий, что для финишного URL будет возвращаться iFrame версия. Возможные значения true or false . Для подключения данной функциональности обратитесь в службу поддержки. |
Ниже приведены параметры блока billingPayerData
(данные об адресе регистрации клиента).
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | billingCity |
String [0..50] | Город, зарегистрированный по конкретной карте у Банка Эмитента. |
Необязательно | billingCountry |
String [0..50] | Страна, зарегистрированная по конкретной карте банка-эмитента (ISO 3166-1, числовой). |
Необязательно | billingAddressLine1 |
String [0..50] | Адрес, зарегистрированный по конкретной карте у Банка Эмитента. Строка 1. Обязательно к передаче для AVS-проверки. |
Необязательно | billingAddressLine2 |
String [0..50] | Адрес, зарегистрированный по конкретной карте у Банка Эмитента. Строка 2. |
Необязательно | billingAddressLine3 |
String [0..50] | Адрес, зарегистрированный по конкретной карте у Банка Эмитента. Строка 3. |
Необязательно | billingPostalCode |
String [0..9] | Почтовый индекс, зарегистрированный по конкретной карте у Банка Эмитента. Обязательно к передаче для AVS-проверки. |
Необязательно | billingState |
String [0..50] | Штат, зарегистрированный по конкретной карте у Банка Эмитента. |
Описание параметров объекта shippingPayerData
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | shippingCity |
ANS...50 | Город заказчика (из адреса доставки) |
Необязательно | shippingCountry |
ANS...50 | Страна заказчика |
Необязательно | shippingAddressLine1 |
ANS...50 | Основной адрес клиента (из адреса доставки) |
Необязательно | shippingAddressLine2 |
ANS...50 | Основной адрес клиента (из адреса доставки) |
Необязательно | shippingAddressLine3 |
ANS...50 | Основной адрес клиента (из адреса доставки) |
Необязательно | shippingPostalCode |
ANS...16 | Почтовый индекс клиента для доставки |
Необязательно | shippingState |
ANS...50 | Штат/регион покупателя (из адреса доставки) |
Необязательно | shippingMethodIndicator |
N2 | Индикатор способа доставки. Возможные значения:
|
Необязательно | deliveryTimeframe |
N2 | Срок поставки товара. Возможные значения:
|
Необязательно | deliveryEmail |
ANS...254 | Целевой адрес электронной почты для доставки цифрового распространения. Предпочтительно передавать электронную почту в самостоятельном параметре запроса email (но если вы передадите его в этом блоке, к нему применятся те же правила). |
Описание параметров объекта orderPayerData
.
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | homePhone |
ANS...19 | Домашний телефон владельца карты. Необходимо всегда указывать код страны, но знак + или 00 в начале можно указать или опустить. Номер должен иметь длину от 7 до 15 цифр. Таким образом, возможны следующие значения:
|
Необязательно | workPhone |
ANS...19 | Рабочий телефон владельца карты. Необходимо всегда указывать код страны, но знак + или 00 в начале можно указать или опустить. Номер должен иметь длину от 7 до 15 цифр. Таким образом, возможны следующие значения:
|
Необязательно | mobilePhone |
ANS...19 | Номер мобильного телефона владельца карты. Необходимо всегда указывать код страны, но знак + или 00 в начале можно указать или опустить. Номер должен иметь длину от 7 до 15 цифр. Таким образом, возможны следующие значения:
Для платежей по VISA с 3DS авторизацией необходимо указать либо электронную почту, либо номер телефона владельца карты. Если у вас настроено отображение номера телефона на платежной странице и вы указали неверный номер телефона, клиент сможет исправить его на платежной странице. |
Описание параметров объекта preOrderPayerData
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | preOrderDate |
ANS8 | Ожидаемая дата доставки (для предзаказанных покупок) в формате ГГГГММДД. |
Необязательно | preOrderPurchaseInd |
N2 | Индикатор размещения клиентом заказа на доступную или будущую доставку. Возможные значения:
|
Необязательно | reorderItemsInd |
N2 | Индикатор того, что клиент перебронирует ранее оплаченную доставку в составе нового заказа. Возможные значения:
|
Описание параметров объекта orderPayerData
.
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | homePhone |
ANS...19 | Домашний телефон владельца карты. Необходимо всегда указывать код страны, но знак + или 00 в начале можно указать или опустить. Номер должен иметь длину от 7 до 15 цифр. Таким образом, возможны следующие значения:
|
Необязательно | workPhone |
ANS...19 | Рабочий телефон владельца карты. Необходимо всегда указывать код страны, но знак + или 00 в начале можно указать или опустить. Номер должен иметь длину от 7 до 15 цифр. Таким образом, возможны следующие значения:
|
Необязательно | mobilePhone |
ANS...19 | Номер мобильного телефона владельца карты. Необходимо всегда указывать код страны, но знак + или 00 в начале можно указать или опустить. Номер должен иметь длину от 7 до 15 цифр. Таким образом, возможны следующие значения:
Для платежей по VISA с 3DS авторизацией необходимо указать либо электронную почту, либо номер телефона владельца карты. Если у вас настроено отображение номера телефона на платежной странице и вы указали неверный номер телефона, клиент сможет исправить его на платежной странице. |
Возможные значения tii
(Подробнее о типах связок, поддерживаемых платежным шлюзом, читайте здесь).
Значение tii
|
Описание | Тип транзакции | Инициатор транзакции | Данные карты для транзакции | Сохранение данных карты после транзакции | Примечание |
---|---|---|---|---|---|---|
Пусто | Обычный | Покупатель | Вводится покупателем | Нет | Транзакция электронной коммерции без сохранения связки. | |
CI | Инициирующий - Обычный (CIT) | Инициирующая | Покупатель | Вводится покупателем | Да | Транзакция электронной коммерции с сохранением связки. |
F | Внеплановый платеж (CIT) | Последующая | Покупатель | Клиент выбирает карту вместо ручного ввода | Нет | Транзакция электронной коммерции, использующая ранее сохраненную обычную связку. |
U | Внеплановый платеж (MIT) | Последующая | Продавец | Нет ручного ввода, продавец передает данные | Нет | Транзакция электронной коммерции, использующая ранее сохраненную обычную связку. |
RI | Инициирующий - Рекурентные (CIT) | Инициирующая | Покупатель | Вводится покупателем | Да | Транзакция электронной коммерции с сохранением связки. |
R | Рекуррентный платеж (MIT) | Последующая | Продавец | Нет ручного ввода, продавец передает данные | Нет | Рекуррентная операция, использующая сохраненную связку. |
II | Инициирующий - Рассрочка (CIT) | Инициирующая | Покупатель | Вводится покупателем | Да | Транзакция электронной коммерции с сохранением связки. |
I | Платеж по рассрочке (MIT) | Последующая | Продавец | Нет ручного ввода, продавец передает данные | Нет | Операция рассрочки, использующая сохраненную связку. |
Ниже приведены параметры блока clientBrowserInfo
(данные о браузере клиента).
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | userAgent | string | Агент браузера. |
Необязательно | OS | string | Операционная система. |
Необязательно | OSVersion | string | Версия операционной системы. |
Необязательно | browserAcceptHeader | string | Заголовок Accept, который сообщает серверу, какие форматы (или MIME-типы) поддерживает браузер. |
Необязательно | browserIpAddress | string | IP-адрес браузера. |
Необязательно | browserLanguage | string | Язык браузера. |
Необязательно | browserTimeZone | string | Часовой пояс браузера. |
Необязательно | browserTimeZoneOffset | integer | Смещение часового пояса в минутах между локальным временем пользователя и UTC. |
Необязательно | colorDepth | string | Глубина цвета экрана, в битах. |
Необязательно | fingerprint | string | Отпечаток браузера - уникальный цифровой идентификатор браузера. |
Необязательно | isMobile | Boolean | Возможные значения: true или false . Флаг, указывающий на то, что используется мобильное устройство. |
Необязательно | javaEnabled | Boolean | Возможные значения: true или false . Флаг, указывающий на то, что в браузере включена поддержка java. |
Необязательно | javascriptEnabled | Boolean | Возможные значения: true или false . Флаг, указывающий на то, что в браузере включена поддержка javascript. |
Необязательно | plugins | string | Список плагинов, используемых в браузере, через запятую. |
Необязательно | screenHeight | integer | Высота экрана в пикселях. |
Необязательно | screenWidth | integer | Ширина экрана в пикселях. |
Необязательно | screenPrint | string | Данные о параметрах печати браузера, включая разрешение, глубину цвета, плотность пикселей. |
Пример блока clientBrowserInfo
:
"clientBrowserInfo":
{
"userAgent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/111.0.0.0 Safari/537.36 Edg/111.0.1661.41",
"fingerprint":850891523,
"OS":"Windows",
"OSVersion":"10",
"isMobile":false,
"screenPrint":"Current Resolution: 1536x864, Available Resolution: 1536x824, Color Depth: 24, Device XDPI: undefined, Device YDPI: undefined",
"colorDepth":24,
"screenHeight":"864",
"screenWidth":"1536",
"plugins":"PDF Viewer, Chrome PDF Viewer, Chromium PDF Viewer, Microsoft Edge PDF Viewer, WebKit built-in PDF",
"javaEnabled":false,
"javascriptEnabled":true,
"browserLanguage":"it-IT",
"browserTimeZone":"Europe/Rome",
"browserTimeZoneOffset":-120,
"browserAcceptHeader":"gzip",
"browserIpAddress":"10.99.50.37"
}
Параметры ответа
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | errorCode |
Integer [1..2] | Информационный параметр в случае ошибки, который может иметь разные кодовые значения:
|
Необязательно | errorMessage |
String [1..512] | Информационный параметр, являющийся описанием ошибки в случае возникновения ошибки. Значение errorMessage может варьироваться, поэтому не следует явным образом ссылаться на его значения в коде. Язык описания задается в параметре language запроса. |
Необязательно | info |
String | В случае успешного ответа. Результат попытки оплаты. Ниже приведены возможные значения.
|
Примеры
Пример запроса
curl --request POST \\
--url https://3dsec.berekebank.kz/payment/rest/paymentorder.do \\
--header 'content-type: application/x-www-form-urlencoded' \\
--data userName=test_user \\
--data password=test_user_password \\
--data MDORDER=0140dda0-71ed-7706-a61f-36bd00a7d8c0 \\
--data '$PAN=4000001111111118' \\
--data '$CVC=123' \\
--data YYYY=2030 \\
--data MM=12 \\
--data 'TEXT=TEST CARDHOLDER' \\
--data language=en \\
--data 'jsonParams={"eci": "02", "cavv": "AkZO5XQAA0rhBxoaufa+MAABAAA=", "xid": "5010857f-8d3f-74e1-9c5a-54a000cc4110", "threeDSProtocolVersion": "2.2.0", "authenticationTypeIndicator": "5"}'
Пример ответа
{
"redirect": "https://3dsec.berekebank.kz/payment/merchants/temp/finish.html?orderId=01493844-d4d3-703f-9f7e-a73900a7d8c0",
"info": "Your order is proceeded, redirecting...",
"errorCode": 0
}
MOTO-платеж
Для осуществления MOTO-платежей используется метод https://3dsec.berekebank.kz/payment/rest/motoPayment.do
.
При выполнении запроса необходимо использовать заголовок:
Content-Type: application/x-www-form-urlencoded
Параметры запроса
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | userName |
String [1..100] | Логин учетной записи API продавца. Если для аутентификации при регистрации вместо логина и пароля используется открытый токен (параметр token ), пароль передавать не нужно. |
Необязательно | password |
String [1..200] | Пароль учетной записи API продавца. Если для аутентификации при регистрации вместо логина и пароля используется открытый токен (параметр token ), пароль передавать не нужно. |
Необязательно | token |
String [1..256] | Значение, используемое для аутентификации продавца при отправке запросов платежному шлюзу. Если вы передаете этот параметр, то не передавайте userName и password . |
Необязательно | orderNumber |
String [1..32] | Номер заказа (ID) в системе мерчанта; должен быть уникальным для каждого заказа. |
Обязательно | amount |
Integer [0..12] | Сумма платежа в минимальных единицах валюты (например, в копейках). |
Необязательно | currency |
Integer [3] | Код валюты платежа ISO 4217. Если не указано, то используется значение по умолчанию. |
Обязательно | returnUrl |
String [1..512] | Адрес, на который требуется перенаправить пользователя в случае успешной оплаты. Адрес должен быть указан полностью, включая используемый протокол (например, https://mybestmerchantreturnurl.com вместо mybestmerchantreturnurl.com ). В противном случае пользователь будет перенаправлен по адресу следующего вида: https://3dsec.berekebank.kz/payment/<merchant_address> . |
Необязательно | failUrl |
String [1..512] | Адрес, на который требуется перенаправить пользователя в случае неуспешной оплаты. Адрес должен быть указан полностью, включая используемый протокол (например, https://mybestmerchantreturnurl.com вместо mybestmerchantreturnurl.com ). В противном случае пользователь будет перенаправлен по адресу следующего вида: https://3dsec.berekebank.kz/payment/<merchant_address> . |
Необязательно | description |
String [1..598] | Описание заказа в любом формате. Чтобы включить отправку этого поля в процессинговую систему, обратитесь в службу технической поддержки. В этом поле недопустимо передавать персональные данные или платежные данные (номера карт т.п.). Данное требование связано с тем, что описание заказа нигде не маскируется. |
Необязательно | language |
String [2] | Ключ языка по ISO 639-1. Если язык не указан, используется язык по умолчанию, указанный в настройках магазина. Поддерживаемые языки: ru, en. |
Необязательно | clientId |
String [0..255] | Номер клиента (ID) в системе мерчанта — до 255 символов. Используется для реализации функциональности связок. Может возвращаться в ответе, если мерчанту разрешено создавать связки. Указание этого параметра при обработке платежей по связке обязательно. В противном случае платеж будет невозможен. |
Необязательно | merchantLogin |
String [1..255] | Для проведения МОТО-платежа от имени другого мерчанта укажите в этом параметре логин API-аккаунта продавца. Можно использовать, только если у вас есть разрешение на просмотр транзакций других продавцов или если указанный продавец является вашим дочерним продавцом. |
Необязательно | postAddress |
String [1..255] | Адрес доставки. |
Необязательно | jsonParams |
Object | Набор дополнительных атрибутов произвольной формы, структура:jsonParams={"param_1_name":"param_1_value",...,"param_n_name":"param_n_value"} Могут быть переданы в Процесинговый Центр, для последующей обработки (требуется дополнительная настройка - обратитесь в поддержку). Некоторые предопределенные атрибуты jsonParams:
|
Необязательно | features |
String | Функции заказа Ниже приведены возможные значения.
|
Необязательно | dynamicCallbackUrl |
String [1..512] | Параметр для передачи динамического адреса для получения "платежных" callback-уведомлений по заказу, активированных для мерчанта (успешная авторизация, успешное списание, возврат, отмена, отклонение платежа по таймауту, отклонение card present платежа). "Не платежные" callback-уведомления (включение/выключение связки, создание связки), будут отправляться на статический callback адрес. |
Условие | email |
String | Электронная почта для отображения на платежной странице. Если для продавца настроены уведомления клиента, электронную почту необходимо указать. Пример: client_mail@email.com . Для платежей по VISA с 3DS авторизацией необходимо указать либо электронную почту, либо номер телефона владельца карты. |
Необязательно | billingPayerData |
Object | Блок с регистрационными данными клиента (адрес, почтовый индекс), необходимый для прохождения проверки адреса в рамках сервисов AVS/AVV. Обязательно, если функция включена для продавца на стороне Платежного шлюза. См. вложенные параметры. |
Необязательно | shippingPayerData |
Object | Объект, содержащий данные о доставке клиенту. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. См. вложенные параметры. |
Необязательно | preOrderPayerData |
Object | Объект, содержащий данные предварительного заказа. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. См. вложенные параметры. |
Необязательно | orderPayerData |
Object | Объект, содержащий данные о плательщике заказа. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. См. вложенные параметры. |
Необязательно | ip |
String [1..39] | IP адрес плательщика. IPv6 поддерживается во всех запросах (до 39 символов). |
Необязательно | preAuth |
Boolean | Параметр, определяющий необходимость предварительной авторизации (блокирования средств на счете клиента до их списания). Доступны следующие значения:
|
Обязательно | pan |
String [1..19] | Маскированный номер карты, которая использовалась для оплаты. Этот параметр указывается только после оплаты заказа. При оплате через Apple Pay в качестве номера карты используется DPAN - это номер, привязанный к мобильному устройству клиента, который функционирует как номер платежной карты в системе Apple Pay. |
Обязательно | expiry |
Integer | Срок действия карты в следующем формате: YYYYMM . Обязательно, если не переданы ни seToken , ни bindingId . |
Обязательно | cardholder |
String [1..26] | Имя держателя карты латинскими буквами. Этот параметр передается только после оплаты заказа. |
Необязательно | cvc |
Integer | Этот параметр обязателен, если для мерчанта не выбрано разрешение Может проводить оплату без подтверждения CVC. |
Ниже приведены параметры блока billingPayerData
(данные об адресе регистрации клиента).
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | billingCity |
String [0..50] | Город, зарегистрированный по конкретной карте у Банка Эмитента. |
Необязательно | billingCountry |
String [0..50] | Страна, зарегистрированная по конкретной карте банка-эмитента (ISO 3166-1, числовой). |
Необязательно | billingAddressLine1 |
String [0..50] | Адрес, зарегистрированный по конкретной карте у Банка Эмитента. Строка 1. Обязательно к передаче для AVS-проверки. |
Необязательно | billingAddressLine2 |
String [0..50] | Адрес, зарегистрированный по конкретной карте у Банка Эмитента. Строка 2. |
Необязательно | billingAddressLine3 |
String [0..50] | Адрес, зарегистрированный по конкретной карте у Банка Эмитента. Строка 3. |
Необязательно | billingPostalCode |
String [0..9] | Почтовый индекс, зарегистрированный по конкретной карте у Банка Эмитента. Обязательно к передаче для AVS-проверки. |
Необязательно | billingState |
String [0..50] | Штат, зарегистрированный по конкретной карте у Банка Эмитента. |
Описание параметров объекта shippingPayerData
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | shippingCity |
ANS...50 | Город заказчика (из адреса доставки) |
Необязательно | shippingCountry |
ANS...50 | Страна заказчика |
Необязательно | shippingAddressLine1 |
ANS...50 | Основной адрес клиента (из адреса доставки) |
Необязательно | shippingAddressLine2 |
ANS...50 | Основной адрес клиента (из адреса доставки) |
Необязательно | shippingAddressLine3 |
ANS...50 | Основной адрес клиента (из адреса доставки) |
Необязательно | shippingPostalCode |
ANS...16 | Почтовый индекс клиента для доставки |
Необязательно | shippingState |
ANS...50 | Штат/регион покупателя (из адреса доставки) |
Необязательно | shippingMethodIndicator |
N2 | Индикатор способа доставки. Возможные значения:
|
Необязательно | deliveryTimeframe |
N2 | Срок поставки товара. Возможные значения:
|
Необязательно | deliveryEmail |
ANS...254 | Целевой адрес электронной почты для доставки цифрового распространения. Предпочтительно передавать электронную почту в самостоятельном параметре запроса email (но если вы передадите его в этом блоке, к нему применятся те же правила). |
Описание параметров объекта preOrderPayerData
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | preOrderDate |
ANS8 | Ожидаемая дата доставки (для предзаказанных покупок) в формате ГГГГММДД. |
Необязательно | preOrderPurchaseInd |
N2 | Индикатор размещения клиентом заказа на доступную или будущую доставку. Возможные значения:
|
Необязательно | reorderItemsInd |
N2 | Индикатор того, что клиент перебронирует ранее оплаченную доставку в составе нового заказа. Возможные значения:
|
Описание параметров объекта orderPayerData
.
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | homePhone |
ANS...19 | Домашний телефон владельца карты. Необходимо всегда указывать код страны, но знак + или 00 в начале можно указать или опустить. Номер должен иметь длину от 7 до 15 цифр. Таким образом, возможны следующие значения:
|
Необязательно | workPhone |
ANS...19 | Рабочий телефон владельца карты. Необходимо всегда указывать код страны, но знак + или 00 в начале можно указать или опустить. Номер должен иметь длину от 7 до 15 цифр. Таким образом, возможны следующие значения:
|
Необязательно | mobilePhone |
ANS...19 | Номер мобильного телефона владельца карты. Необходимо всегда указывать код страны, но знак + или 00 в начале можно указать или опустить. Номер должен иметь длину от 7 до 15 цифр. Таким образом, возможны следующие значения:
Для платежей по VISA с 3DS авторизацией необходимо указать либо электронную почту, либо номер телефона владельца карты. Если у вас настроено отображение номера телефона на платежной странице и вы указали неверный номер телефона, клиент сможет исправить его на платежной странице. |
Параметры ответа
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | success |
Boolean | Основной параметр, который указывает на то, что запрос прошел успешно. Доступны следующие значения:
Обратите внимание, что значение true означает, что запрос был обработан, а не что заказ был оплачен.Более подробная информация о том, как узнать, был ли платеж успешным или нет, доступна здесь. |
Обязательно | errorCode |
Integer [1..2] | Информационный параметр в случае ошибки, который может иметь разные кодовые значения:
|
Обязательно | errorMessage |
String [1..512] | Информационный параметр, являющийся описанием ошибки в случае возникновения ошибки. Значение errorMessage может варьироваться, поэтому не следует явным образом ссылаться на его значения в коде. Язык описания задается в параметре language запроса. |
Обязательно | mdOrder |
String [1..36] | Номер заказа в платежном шлюзе. Уникален в пределах платежного шлюза. |
Обязательно | orderNumber |
String [1..32] | Номер заказа (ID) в системе мерчанта; должен быть уникальным для каждого заказа. |
Необязательно | userMessage |
String [1..512] | Сообщению пользователю с описанием кода результата. |
Примеры
Пример запроса
curl --request POST \
--url https://3dsec.berekebank.kz/payment/rest/motoPayment.do \
--header 'content-type: application/x-www-form-urlencoded' \
--data amount=2000 \
--data currency=398 \
--data userName=test_user \
--data password=test_user_password \
--data returnUrl=https://mybestmerchantreturnurl.com \
--data description=my_first_order \
--data pan=4000001111111118 \
--data expiry=203012 \
--data cvc=123 \
--data cardholder="TEST CARDHOLDER" \
--data language=en
Пример ответа - успешный платеж
{
"errorCode":"0",
"success":true,
"mdOrder":"088433e9-e34d-769e-9366-696200a7d8c0",
"orderNumber":"62001"
}
Кошельки
Регистрация заказа Apple Pay
Для регистрации и оплаты заказа используется метод https://3dsec.berekebank.kz/payment/applepay/payment.do
.
При выполнении запроса необходимо использовать заголовок:
Content-Type: application/json
Параметры запроса
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | merchant |
String | Логин продавца в системе платежного шлюза. |
Обязательно | orderNumber |
String [1..32] | Номер заказа (ID) в системе мерчанта; должен быть уникальным для каждого заказа. |
Необязательно | description |
String [1..598] | Описание заказа в любом формате. Чтобы включить отправку этого поля в процессинговую систему, обратитесь в службу технической поддержки. В этом поле недопустимо передавать персональные данные или платежные данные (номера карт т.п.). Данное требование связано с тем, что описание заказа нигде не маскируется. |
Необязательно | language |
String [2] | Ключ языка по ISO 639-1. Если язык не указан, используется язык по умолчанию, указанный в настройках магазина. Поддерживаемые языки: ru, en. |
Необязательно | additionalParameters |
Object | Дополнительные параметры заказа, которые хранятся в личном кабинете продавца для последующего просмотра. Каждая новая пара имени параметра и его значения должна быть разделена запятой. Ниже приведен пример использования.{ "firstParamName": "firstParamValue", "secondParamName": "secondParamValue"} При создании связки в этом тэге могут быть переданы параметры, определяющие тип создаваемой связки. См. список параметров. |
Необязательно | preAuth |
Boolean | Параметр, определяющий необходимость предварительной авторизации (блокирования средств на счете клиента до их списания). Доступны следующие значения:
|
Обязательно | paymentToken |
String [1..8192] | Параметр paymentToken должен содержать расшифрованное и закодированное в Base64 значение свойства paymentData , полученного из объекта PKPaymentToken Object от системы Apple Pay (подробнее см. документацию Apple Pay). Таким образом, чтобы сделать запрос на оплату в платежный шлюз, продавец должен:
|
Необязательно | tii |
String | Идентификатор инициатора транзакции. Параметр, указывающий, какой тип операции будет выполнять инициатор (Клиент или Мерчант). Возможные значения. |
Условие | clientId |
String [0..255] | Номер клиента (ID) в системе мерчанта — до 255 символов. Используется для реализации функциональности связок. Может возвращаться в ответе, если мерчанту разрешено создавать связки. Указание этого параметра при обработке платежей по связке обязательно. В противном случае платеж будет невозможен. |
Условие | email |
String | Электронная почта для отображения на платежной странице. Если для продавца настроены уведомления клиента, электронную почту необходимо указать. Пример: client_mail@email.com . Для платежей по VISA с 3DS авторизацией необходимо указать либо электронную почту, либо номер телефона владельца карты. |
Условие | phone |
String | Номер телефона владельца карты. Необходимо всегда указывать код страны, но знак + или 00 в начале можно указать или опустить. Номер должен иметь длину от 7 до 15 цифр. Таким образом, возможны следующие значения:
Для платежей по VISA с 3DS авторизацией необходимо указать либо электронную почту, либо номер телефона владельца карты. |
Необязательно | threeDSProtocolVersion |
String | Версия протокола 3DS. Возможные значения: "2.1.0", "2.2.0" для 3DS2. Если в запросе не передается threeDSProtocolVersion , то для авторизации 3D Secure будет использоваться значение по умолчанию (2.1.0 - для 3DS 2). |
Необязательно | externalScaExemptionIndicator |
String | Тип исключения SCA (Strong Customer Authentication). Если указан этот параметр, транзакция будет обработана в зависимости от ваших настроек в платежном шлюзе: либо будет выполнена принудительная операция SSL, либо банк-эмитент получит информацию об исключении SCA и примет решение о проведении операции с 3DS-аутентификацией или без нее (для получения подробной информации свяжитесь с нашей службой поддержки). Допустимые значения:
Для передачи этого параметра у вас должны быть достаточные права в платежном шлюзе. |
Дополнительные параметры, определяющие тип создаваемой связки и передаваемые в additionalParameters
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Условие | installments |
Integer [3] | Максимальное количество разрешенных авторизаций для платежей в рассрочку. Указывается в случае создания связки для выполнения платежей в рассрочку. |
Условие | recurringFrequency |
Integer [2] | Минимальное количество дней между авторизациями. Целое положительное число от 1 до 28 включительно. Указывается в случае создания связки для выполнения рекуррентных платежей. |
Условие | recurringExpiry |
String [8] | Дата, после которой дальнейшие авторизации не должны выполняться. Формат: YYYYMMDD. Указывается в случае создания связки для выполнения рекуррентных платежей. |
Возможные значения tii
(Подробнее о типах связок, поддерживаемых платежным шлюзом, читайте здесь).
Значение tii
|
Описание | Тип транзакции | Инициатор транзакции | Данные карты для транзакции | Сохранение данных карты после транзакции | Примечание |
---|---|---|---|---|---|---|
Пусто | Обычный | Покупатель | Вводится покупателем | Нет | Транзакция электронной коммерции без сохранения связки. | |
CI | Инициирующий - Обычный (CIT) | Инициирующая | Покупатель | Вводится покупателем | Да | Транзакция электронной коммерции с сохранением связки. Это значение возможно передать только при наличии разрешения "Разрешено создание vendor pays common связок". |
RI | Инициирующий - Рекурентные (CIT) | Инициирующая | Покупатель | Вводится покупателем | Да | Транзакция электронной коммерции с сохранением связки. |
II | Инициирующий - Рассрочка (CIT) | Инициирующая | Покупатель | Вводится покупателем | Да | Транзакция электронной коммерции с сохранением связки. |
Параметры ответа
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | success |
Boolean | Основной параметр, который указывает на то, что запрос прошел успешно. Доступны следующие значения:
Обратите внимание, что значение true означает, что запрос был обработан, а не что заказ был оплачен.Более подробная информация о том, как узнать, был ли платеж успешным или нет, доступна здесь. |
Условие | data |
Object | Этот параметр возвращается только в случае успешной обработки платежа. См. описание ниже. |
Условие | error |
Object | Этот параметр возвращается только в случае ошибки платежа. См. описание ниже. |
Условие | orderStatus |
Object | Содержит параметры статуса заказа и возвращается только в том случае, если платежный шлюз распознал все параметры запроса как правильные. См. описание ниже. |
Блок data
содержит следующие элементы.
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | orderId |
String [1..36] | Номер заказа в платежном шлюзе. Уникален в пределах платежного шлюза. |
Блок error
содержит следующие элементы.
Обязательность | Название | Тип | Описание |
---|---|---|---|
code |
Integer [1..3] | Код как информационный параметр, сообщающий об ошибке. | |
description |
String [1..598] | Подробное техническое объяснение ошибки - содержимое этого параметра не предназначено для отображения пользователю. | |
message |
String [1..512] | Информационный параметр, являющийся описанием ошибки для отображения пользователю. Параметр может варьироваться, поэтому не следует явным образом ссылаться на его значения в коде. | |
Блок orderStatus
содержит следующие элементы.
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | errorCode |
Integer [1..2] | Информационный параметр в случае ошибки, который может иметь разные кодовые значения:
|
Необязательно | errorMessage |
String [1..512] | Информационный параметр, являющийся описанием ошибки в случае возникновения ошибки. Значение errorMessage может варьироваться, поэтому не следует явным образом ссылаться на его значения в коде. Язык описания задается в параметре language запроса. |
Необязательно | orderNumber |
String [1..32] | Номер заказа (ID) в системе мерчанта; должен быть уникальным для каждого заказа. |
Необязательно | orderStatus |
Integer | Значение этого параметра указывает статус заказа в платежном шлюзе. Отсутствует, если заказ не был найден. Ниже приведен список доступных значений:
|
Необязательно | actionCode |
Integer | Код ответа от процессинга банка. См. список кодов ответа здесь. |
Необязательно | actionCodeDescription |
String [1..512] | Описание actionCode , возвращаемое процессингом банка. |
Необязательно | amount |
Integer [0..12] | Сумма платежа в минимальных единицах валюты (например, в копейках). |
Необязательно | currency |
Integer [3] | Код валюты платежа ISO 4217. Если не указано, то используется значение по умолчанию. |
Необязательно | date |
String | Дата регистрации заказа (Unix) |
Необязательно | ip |
String [1..39] | IP адрес плательщика. IPv6 поддерживается во всех запросах (до 39 символов). |
Условие | merchantOrderParams |
Object | Объект с атрибутами, в которых передаются дополнительные параметры мерчанта. См. описание ниже. |
Условие | attributes |
Object | Атрибуты заказа в платежной системе (номер заказа). См. описание ниже. |
Условие | cardAuthInfo |
Object | Информация о платежной карте покупателя. См. описание ниже. |
Необязательно | authDateTime |
String | Дата и время авторизации, показанные как количество миллисекунд, прошедших с 00:00 GMT 1 января 1970 года (время Unix). |
Необязательно | terminalId |
String [1..10] | Идентификатор терминала в системе, обрабатывающей платеж. |
Необязательно | authRefNum |
String [1..24] | Номер авторизации платежа, присвоенный ему при регистрации платежа. |
Условие | paymentAmountInfo |
Object | Параметр, содержащий вложенные параметры с информацией о суммах подтверждения, списания и возврата. См. описание ниже. |
Условие | bankInfo |
Object | Содержит вложенный параметр bankCountryName . См. описание ниже. |
Блок merchantOrderParams
содержит следующие элементы.
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | name |
String [1..255] | Название дополнительного параметра мерчанта. |
Обязательно | value |
String | Значение дополнительного параметра продавца - до 1024 символов. |
Блок attributes
содержит следующие элементы.
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | name |
String [1..255] | Название дополнительного параметра. |
Обязательно | value |
Alphanumeric | Значение дополнительного параметра - до 1024 символов. |
Блок cardAuthInfo
содержит следующие элементы.
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | expiration |
Integer | Срок действия карты в следующем формате: .YYYYMM Указывается только после оплаты заказа. |
Обязательно | cardholdername |
String [1..26] | Имя держателя карты латинскими буквами. Этот параметр передается только после оплаты заказа. |
Обязательно | approvalCode |
String [6] | Код авторизации МПС. Это поле имеет фиксированную длину (шесть символов) и может содержать цифры и латинские буквы. |
Обязательно | pan |
String [1..19] | Маскированный DPAN: номер, привязанный к мобильному устройству покупателя и выполняющий функции номера платежной карты в системе Apple Pay. |
Блок paymentAmountInfo
содержит следующие элементы.
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | paymentState |
String | Состояние заказа, параметр может принимать следующие значения:
|
Обязательно | approvedAmount |
Integer [0..12] | Сумма в минимальных единицах валюты (например, в центах), которая была заблокирована на счете покупателя. Используется только в двухстадийных платежах. |
Обязательно | depositedAmount |
Integer [1..12] | Сумма списания в минимальных единицах валюты (например, в копейках). |
Обязательно | refundedAmount |
Integer [1..12] | Сумма возврата в минимальных единицах валюты. |
Блок bankInfo
содержит следующие элементы.
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | bankCountryName |
String [1..160] | Страна банка-эмитента. |
- Если
success
=true
иorderStatus.orderStatus
=1
или2
, то транзакция подтверждается. - Если
success
=true
иorderStatus.orderStatus
<>1
или2
, то транзакция отклоняется. - Если
success
=false
илиerrorCode
<>0
, то транзакция отклоняется.
Примеры
Пример запроса
curl --request POST \
--url https://3dsec.berekebank.kz/payment/applepay/payment.do \
--header 'Content-Type: application/json' \
--data-raw '{
"additionalParameters" : {
"phone" : "9521235847",
"order-pain" : "111",
"email" : "apple@pay.com"
},
"language" : "en",
"clientId" : "259753456",
"orderNumber" : "281477871",
"paymentToken" : "eyJkYXRhIjoiYPhK3M1bEtm...YjM2NWMzZWNmYjE5fIkVDX3YxIn0=",
"preAuth" : false
}'
Ответ в случае успешной оплаты
{
"success": true,
"data": {
"orderId": "b926351f-a634-49cf-9484-ccb0a3b8cfad"
},
"orderStatus": {
"errorCode": "0",
"orderNumber": "229",
"orderStatus": 1,
"actionCode": 0,
"actionCodeDescription": "",
"amount": 960000,
"currency": "398",
"date": 1478682458102,
"ip": "81.18.144.51",
"merchantOrderParams": [
{
"name": "param2",
"value": "param2"
},
{
"name": "param1",
"value": "param1"
}
],
"attributes": [
{
"name": "mdOrder",
"value": "b926351f-a634-49cf-9484-ccb0a3b8cfad"
}
],
"cardAuthInfo": {
"expiration": "203012",
"cardholderName": "TEST CARDHOLDER",
"approvalCode": "123456",
"pan": "500000**1115"
},
"authDateTime": 1478682459082,
"terminalId": "12345678",
"authRefNum": "111111111111",
"paymentAmountInfo": {
"paymentState": "APPROVED",
"approvedAmount": 960000,
"depositedAmount": 0,
"refundedAmount": 0
},
"bankInfo": {
"bankCountryName": "<UNKNOWN>"
}
}
}
Ответ в случае неудачной оплаты
{
"error": {
"code": 10,
"description": "Processing Error",
"message": "Auth is invalid"
},
"success": false
}
Apple Pay Direct
Запрос, используемый для осуществления прямого платежа через Apple Pay - https://3dsec.berekebank.kz/payment/applepay/paymentDirect.do
. Он используется для регистрации и оплаты заказа.
Этот запрос можно использовать для интеграций, предполагающих расшифровку платежных данных на стороне продавца.
При выполнении запроса необходимо использовать заголовок:
Content-Type: application/json
Параметры запроса
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | userName |
String [1..100] | Логин учетной записи API продавца. |
Обязательно | password |
String [1..200] | Пароль учетной записи API продавца. |
Обязательно | orderNumber |
String [1..32] | Номер заказа (ID) в системе мерчанта; должен быть уникальным для каждого заказа. |
Необязательно | description |
String [1..598] | Описание заказа в любом формате. Чтобы включить отправку этого поля в процессинговую систему, обратитесь в службу технической поддержки. В этом поле недопустимо передавать персональные данные или платежные данные (номера карт т.п.). Данное требование связано с тем, что описание заказа нигде не маскируется. |
Необязательно | language |
String [2] | Ключ языка по ISO 639-1. Если язык не указан, используется язык по умолчанию, указанный в настройках магазина. Поддерживаемые языки: ru, en. |
Необязательно | feeInput |
String | Размер комиссии в минимальных единицах валюты. Функциональность должна быть включена на уровне продавца в шлюзе. |
Необязательно | additionalParameters |
Object | Дополнительные параметры заказа, которые хранятся в личном кабинете продавца для последующего просмотра. Каждая новая пара имени параметра и его значения должна быть разделена запятой. Ниже приведен пример использования.{ "firstParamName": "firstParamValue", "secondParamName": "secondParamValue"} При создании связки в этом тэге могут быть переданы параметры, определяющие тип создаваемой связки. См. список параметров. |
Необязательно | preAuth |
Boolean | Параметр, определяющий необходимость предварительной авторизации (блокирования средств на счете клиента до их списания). Доступны следующие значения:
|
Обязательно | paymentToken |
String [1..8192] | Платежные данные, полученные от Apple Pay и расшифрованные продавцом. Последовательность действий:
|
Необязательно | merchant |
String | Логин продавца в системе платежного шлюза. |
Необязательно | features |
String | В этом параметре можно передать значение VERIFY . Тогда оплата производиться не будет, вместо этого будет создана связка (будет сохранена карта клиента).Если передается features , paymentToken.transactionAmount должно быть 0 . В противном случае будет возвращена ошибка. |
Условие | clientId |
String [0..255] | Номер клиента (ID) в системе мерчанта — до 255 символов. Используется для реализации функциональности связок. Может возвращаться в ответе, если мерчанту разрешено создавать связки. Указание этого параметра при обработке платежей по связке обязательно. В противном случае платеж будет невозможен. |
Необязательно | tii |
String | Идентификатор инициатора транзакции. Параметр, указывающий, какой тип операции будет выполнять инициатор (Клиент или Мерчант). Возможные значения. |
Необязательно | threeDSProtocolVersion |
String | Версия протокола 3DS. Возможные значения: "2.1.0", "2.2.0" для 3DS2. Если в запросе не передается threeDSProtocolVersion , то для авторизации 3D Secure будет использоваться значение по умолчанию (2.1.0 - для 3DS 2). |
Необязательно | externalScaExemptionIndicator |
String | Тип исключения SCA (Strong Customer Authentication). Если указан этот параметр, транзакция будет обработана в зависимости от ваших настроек в платежном шлюзе: либо будет выполнена принудительная операция SSL, либо банк-эмитент получит информацию об исключении SCA и примет решение о проведении операции с 3DS-аутентификацией или без нее (для получения подробной информации свяжитесь с нашей службой поддержки). Допустимые значения:
Для передачи этого параметра у вас должны быть достаточные права в платежном шлюзе. |
Условие | email |
String | Электронная почта для отображения на платежной странице. Если для продавца настроены уведомления клиента, электронную почту необходимо указать. Пример: client_mail@email.com . Для платежей по VISA с 3DS авторизацией необходимо указать либо электронную почту, либо номер телефона владельца карты. |
Необязательно | billingPayerData |
Object | Блок с регистрационными данными клиента (адрес, почтовый индекс), необходимый для прохождения проверки адреса в рамках сервисов AVS/AVV. Обязательно, если функция включена для продавца на стороне Платежного шлюза. См вложенные параметры. |
Необязательно | shippingPayerData |
Object | Объект, содержащий данные о доставке клиенту. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. См. вложенные параметры. |
Необязательно | preOrderPayerData |
Object | Объект, содержащий данные предварительного заказа. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. См. вложенные параметры. |
Необязательно | orderPayerData |
Object | Объект, содержащий данные о плательщике заказа. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. См. вложенные параметры. |
Необязательно | billingAndShippingAddressMatchIndicator |
A1 | Индикатор соответствия платежного адреса владельца карты и адреса доставки. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. Возможные значения:
|
Возможные значения tii
(Подробнее о типах связок, поддерживаемых платежным шлюзом, читайте здесь).
Значение tii
|
Описание | Тип транзакции | Инициатор транзакции | Данные карты для транзакции | Сохранение данных карты после транзакции | Примечание |
---|---|---|---|---|---|---|
Пусто | Обычный | Покупатель | Вводится покупателем | Нет | Транзакция электронной коммерции без сохранения связки. | |
CI | Инициирующий - Обычный (CIT) | Инициирующая | Покупатель | Вводится покупателем | Да | Транзакция электронной коммерции с сохранением связки. Это значение возможно передать только при наличии разрешения "Разрешено создание vendor pays common связок". |
RI | Инициирующий - Рекурентные (CIT) | Инициирующая | Покупатель | Вводится покупателем | Да | Транзакция электронной коммерции с сохранением связки. |
II | Инициирующий - Рассрочка (CIT) | Инициирующая | Покупатель | Вводится покупателем | Да | Транзакция электронной коммерции с сохранением связки. |
Дополнительные параметры, определяющие тип создаваемой связки и передаваемые в additionalParameters
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Условие | installments |
Integer [3] | Максимальное количество разрешенных авторизаций для платежей в рассрочку. Указывается в случае создания связки для выполнения платежей в рассрочку. |
Условие | recurringFrequency |
Integer [2] | Минимальное количество дней между авторизациями. Целое положительное число от 1 до 28 включительно. Указывается в случае создания связки для выполнения рекуррентных платежей. |
Условие | recurringExpiry |
String [8] | Дата, после которой дальнейшие авторизации не должны выполняться. Формат: YYYYMMDD. Указывается в случае создания связки для выполнения рекуррентных платежей. |
Ниже приведены параметры блока billingPayerData
(данные об адресе регистрации клиента).
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | billingCity |
String [0..50] | Город, зарегистрированный по конкретной карте у Банка Эмитента. |
Необязательно | billingCountry |
String [0..50] | Страна, зарегистрированная по конкретной карте банка-эмитента (ISO 3166-1, числовой). |
Необязательно | billingAddressLine1 |
String [0..50] | Адрес, зарегистрированный по конкретной карте у Банка Эмитента. Строка 1. Обязательно к передаче для AVS-проверки. |
Необязательно | billingAddressLine2 |
String [0..50] | Адрес, зарегистрированный по конкретной карте у Банка Эмитента. Строка 2. |
Необязательно | billingAddressLine3 |
String [0..50] | Адрес, зарегистрированный по конкретной карте у Банка Эмитента. Строка 3. |
Необязательно | billingPostalCode |
String [0..9] | Почтовый индекс, зарегистрированный по конкретной карте у Банка Эмитента. Обязательно к передаче для AVS-проверки. |
Необязательно | billingState |
String [0..50] | Штат, зарегистрированный по конкретной карте у Банка Эмитента. |
Описание параметров объекта shippingPayerData
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | shippingCity |
ANS...50 | Город заказчика (из адреса доставки) |
Необязательно | shippingCountry |
ANS...50 | Страна заказчика |
Необязательно | shippingAddressLine1 |
ANS...50 | Основной адрес клиента (из адреса доставки) |
Необязательно | shippingAddressLine2 |
ANS...50 | Основной адрес клиента (из адреса доставки) |
Необязательно | shippingAddressLine3 |
ANS...50 | Основной адрес клиента (из адреса доставки) |
Необязательно | shippingPostalCode |
ANS...16 | Почтовый индекс клиента для доставки |
Необязательно | shippingState |
ANS...50 | Штат/регион покупателя (из адреса доставки) |
Необязательно | shippingMethodIndicator |
N2 | Индикатор способа доставки. Возможные значения:
|
Необязательно | deliveryTimeframe |
N2 | Срок поставки товара. Возможные значения:
|
Необязательно | deliveryEmail |
ANS...254 | Целевой адрес электронной почты для доставки цифрового распространения. Предпочтительно передавать электронную почту в самостоятельном параметре запроса email (но если вы передадите его в этом блоке, к нему применятся те же правила). |
Описание параметров объекта preOrderPayerData
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | preOrderDate |
ANS8 | Ожидаемая дата доставки (для предзаказанных покупок) в формате ГГГГММДД. |
Необязательно | preOrderPurchaseInd |
N2 | Индикатор размещения клиентом заказа на доступную или будущую доставку. Возможные значения:
|
Необязательно | reorderItemsInd |
N2 | Индикатор того, что клиент перебронирует ранее оплаченную доставку в составе нового заказа. Возможные значения:
|
Описание параметров объекта orderPayerData
.
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | homePhone |
ANS...19 | Домашний телефон владельца карты. Необходимо всегда указывать код страны, но знак + или 00 в начале можно указать или опустить. Номер должен иметь длину от 7 до 15 цифр. Таким образом, возможны следующие значения:
|
Необязательно | workPhone |
ANS...19 | Рабочий телефон владельца карты. Необходимо всегда указывать код страны, но знак + или 00 в начале можно указать или опустить. Номер должен иметь длину от 7 до 15 цифр. Таким образом, возможны следующие значения:
|
Необязательно | mobilePhone |
ANS...19 | Номер мобильного телефона владельца карты. Необходимо всегда указывать код страны, но знак + или 00 в начале можно указать или опустить. Номер должен иметь длину от 7 до 15 цифр. Таким образом, возможны следующие значения:
Для платежей по VISA с 3DS авторизацией необходимо указать либо электронную почту, либо номер телефона владельца карты. Если у вас настроено отображение номера телефона на платежной странице и вы указали неверный номер телефона, клиент сможет исправить его на платежной странице. |
Параметры ответа
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | success |
Boolean | Основной параметр, который указывает на то, что запрос прошел успешно. Доступны следующие значения:
Обратите внимание, что значение true означает, что запрос был обработан, а не что заказ был оплачен.Более подробная информация о том, как узнать, был ли платеж успешным или нет, доступна здесь. |
Обязательно | data |
Object | Возвращается только в случае успешной оплаты. |
Обязательно | error |
Object | Этот параметр возвращается только в случае ошибки платежа. |
Необязательно | orderStatus |
Integer | Значение этого параметра указывает статус заказа в платежном шлюзе. Отсутствует, если заказ не был найден. Ниже приведен список доступных значений:
|
Параметры в блоке data
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | orderId |
String [1..36] | Номер заказа в платежном шлюзе. Уникален в пределах платежного шлюза. |
Параметры в блоке error
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | code |
Integer [1..3] | Код как информационный параметр, сообщающий об ошибке. |
Обязательно | message |
String [1..512] | Информационный параметр, являющийся описанием ошибки для отображения пользователю. Параметр может варьироваться, поэтому не следует явным образом ссылаться на его значения в коде. |
Обязательно | description |
String [1..598] | Подробное техническое объяснение ошибки - содержимое этого параметра не предназначено для отображения пользователю. |
Параметры в блоке orderStatus
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | errorCode |
Integer [1..2] | Информационный параметр в случае ошибки, который может иметь разные кодовые значения:
|
Необязательно | errorMessage |
String [1..512] | Информационный параметр, являющийся описанием ошибки в случае возникновения ошибки. Значение errorMessage может варьироваться, поэтому не следует явным образом ссылаться на его значения в коде. Язык описания задается в параметре language запроса. |
Необязательно | orderNumber |
String [1..32] | Номер заказа (ID) в системе мерчанта; должен быть уникальным для каждого заказа. |
Необязательно | orderStatus |
Integer | Значение этого параметра указывает статус заказа в платежном шлюзе. Отсутствует, если заказ не был найден. Ниже приведен список доступных значений:
|
Необязательно | actionCode |
Integer | Код ответа от процессинга банка. См. список кодов ответа здесь. |
Необязательно | actionCodeDescription |
String [1..512] | Описание actionCode , возвращаемое процессингом банка. |
Необязательно | amount |
Integer [0..12] | Сумма платежа в минимальных единицах валюты (например, в копейках). |
Необязательно | currency |
Integer [3] | Код валюты платежа ISO 4217. Если не указано, то используется значение по умолчанию. |
Необязательно | date |
String | Дата регистрации заказа (Unix) |
Необязательно | ip |
String [1..39] | IP адрес плательщика. IPv6 поддерживается во всех запросах (до 39 символов). |
Необязательно | merchantOrderParams |
Object | Раздел с атрибутами, в котором передаются дополнительные параметры мерчанта. |
Необязательно | cardAuthInfo |
Object | Блок с данными о карте плательщика см вложенные параметры. |
Необязательно | authDateTime |
String | Дата и время авторизации, показанные как количество миллисекунд, прошедших с 00:00 GMT 1 января 1970 года (время Unix). |
Необязательно | terminalId |
String [1..10] | Идентификатор терминала в системе, обрабатывающей платеж. |
Необязательно | authRefNum |
String [1..24] | Номер авторизации платежа, присвоенный ему при регистрации платежа. |
Необязательно | paymentAmountInfo |
Object | Объект с информацией о суммах подтверждения, списания, возврата. Список вложенных параметров см. ниже. |
Необязательно | bankInfo |
Object | Объект, содержащий вложенный параметр bankCountryName , в котором передается наименование страны банка-эмитента (при наличии). Используемый язык совпадает с языком, переданным в параметре запроса language . Если язык не передан, будет использоваться язык пользователя, вызывающего метод. |
Параметры в блоке cardAuthInfo
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | expiration |
Integer | Год и месяц окончания действия карты. |
Необязательно | cardholderName |
String [1..26] | Имя держателя карты (при наличии). |
Необязательно | approvalCode |
String [6] | Код авторизации МПС. Это поле имеет фиксированную длину (шесть символов) и может содержать цифры и латинские буквы. |
Необязательно | pan |
String [1..19] | Маскированный DPAN: номер, привязанный к мобильному устройству покупателя и выполняющий функции номера платежной карты в системе Apple Pay. |
Параметры в блоке paymentAmountInfo
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | paymentState |
String | Состояние заказа, параметр может принимать следующие значения:
|
Необязательно | approvedAmount |
Integer [0..12] | Сумма в минимальных единицах валюты (например, в центах), которая была заблокирована на счете покупателя. Используется только в двухстадийных платежах. |
Необязательно | depositedAmount |
Integer [1..12] | Сумма списания в минимальных единицах валюты (например, в копейках). |
Необязательно | refundedAmount |
Integer [1..12] | Сумма возврата в минимальных единицах валюты. |
Необязательно | totalAmount |
Integer [1..12] | Сумма заказа плюс комиссия, если таковая имеется. |
Примеры
Пример запроса
curl --location --request POST 'https://3dsec.berekebank.kz/payment/applepay/paymentDirect.do' \
--header 'Content-Type: application/json' \
--data-raw '{
"username": "test_user",
"password": "test_user_password",
"orderNumber": "947664b3-4a42-4cdf-9f8c-2e9679bad9e4",
"description": "description of the order",
"language": "en",
"paymentToken": "eyJhcHBsaWNhPT...0ifX0="
}'
Примеры ответа - успешный платеж
{
"success": true,
"data": {
"orderId": "b926351f-a634-49cf-9484-ccb0a3b8cfad"
},
"orderStatus": {
"errorCode": "0",
"orderNumber": "229",
"orderStatus": 1,
"actionCode": 0,
"actionCodeDescription": "",
"amount": 960000,
"currency": "398",
"date": 1478682458102,
"ip": "81.18.144.51",
"merchantOrderParams": [
{
"name": "param2",
"value": "param2"
},
{
"name": "param1",
"value": "param1"
}
],
"attributes": [
{
"name": "mdOrder",
"value": "b926351f-a634-49cf-9484-ccb0a3b8cfad"
}
],
"cardAuthInfo": {
"expiration": "203012",
"cardholderName": "TEST CARDHOLDER",
"approvalCode": "123456",
"pan": "500000**1115"
},
"authDateTime": 1478682459082,
"terminalId": "12345678",
"authRefNum": "111111111111",
"paymentAmountInfo": {
"paymentState": "APPROVED",
"approvedAmount": 960000,
"depositedAmount": 0,
"refundedAmount": 0
},
"bankInfo": {
"bankCountryName": "<UNKNOWN>"
}
}
}
Пример ответа - ошибка платежа
{
"error": {
"code": 1,
"description": "Processing Error",
"message": "Insufficient amount on card"
},
"success": false
}
Регистрация заказа Google Pay
Для регистрации и оплаты заказа используется запрос https://3dsec.berekebank.kz/payment/google/payment.do
.
При выполнении запроса необходимо использовать заголовок:
Content-Type: application/json
Параметры запроса
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | merchant |
String | Логин продавца в системе платежного шлюза. |
Обязательно | orderNumber |
String [1..32] | Номер заказа (ID) в системе мерчанта; должен быть уникальным для каждого заказа. |
Необязательно | description |
String [1..598] | Описание заказа в любом формате. Чтобы включить отправку этого поля в процессинговую систему, обратитесь в службу технической поддержки. В этом поле недопустимо передавать персональные данные или платежные данные (номера карт т.п.). Данное требование связано с тем, что описание заказа нигде не маскируется. |
Необязательно | language |
String [2] | Ключ языка по ISO 639-1. Если язык не указан, используется язык по умолчанию, указанный в настройках магазина. Поддерживаемые языки: ru, en. |
Необязательно | additionalParameters |
Object | Дополнительные параметры заказа, которые хранятся в личном кабинете продавца для последующего просмотра. Каждая новая пара имени параметра и его значения должна быть разделена запятой. Ниже приведен пример использования.{ "firstParamName": "firstParamValue", "secondParamName": "secondParamValue"} При создании связки в этом тэге могут быть переданы параметры, определяющие тип создаваемой связки. См. список параметров. |
Необязательно | preAuth |
Boolean | Параметр, определяющий необходимость предварительной авторизации (блокирования средств на счете клиента до их списания). Доступны следующие значения:
|
Обязательно | clientId |
String [0..255] | Номер клиента (ID) в системе мерчанта — до 255 символов. Используется для реализации функциональности связок. Может возвращаться в ответе, если мерчанту разрешено создавать связки. Указание этого параметра при обработке платежей по связке обязательно. В противном случае платеж будет невозможен. |
Необязательно | tii |
String | Идентификатор инициатора транзакции. Параметр, указывающий, какой тип операции будет выполнять инициатор (Клиент или Мерчант). Возможные значения. |
Обязательно | paymentToken |
String [1..8192] | Токен, полученный от Google Pay и закодированный в Base64. |
Обязательно | ip |
String [1..39] | IP адрес плательщика. IPv6 поддерживается во всех запросах (до 39 символов). |
Обязательно | amount |
Integer [0..12] | Сумма платежа в минимальных единицах валюты (например, в копейках). |
Необязательно | currencyCode |
String [3] | Цифровой код валюты платежа ISO 4217. Если не указан, считается равным 643 (российский рубль). |
Обязательно | returnUrl |
String [1..512] | Адрес, на который требуется перенаправить пользователя в случае успешной оплаты. Адрес должен быть указан полностью, включая используемый протокол (например, https://mybestmerchantreturnurl.com вместо mybestmerchantreturnurl.com ). В противном случае пользователь будет перенаправлен по адресу следующего вида: https://3dsec.berekebank.kz/payment/<merchant_address> . |
Необязательно | failUrl |
String [1..512] | Адрес, на который требуется перенаправить пользователя в случае неуспешной оплаты. Адрес должен быть указан полностью, включая используемый протокол (например, https://mybestmerchantreturnurl.com вместо mybestmerchantreturnurl.com ). В противном случае пользователь будет перенаправлен по адресу следующего вида: https://3dsec.berekebank.kz/payment/<merchant_address> . |
Необязательно | dynamicCallbackUrl |
String [1..512] | Параметр для передачи динамического адреса для получения "платежных" callback-уведомлений по заказу, активированных для мерчанта (успешная авторизация, успешное списание, возврат, отмена, отклонение платежа по таймауту, отклонение card present платежа). "Не платежные" callback-уведомления (включение/выключение связки, создание связки), будут отправляться на статический callback адрес. |
Условие | email |
String | Электронная почта для отображения на платежной странице. Если для продавца настроены уведомления клиента, электронную почту необходимо указать. Пример: client_mail@email.com . Для платежей по VISA с 3DS авторизацией необходимо указать либо электронную почту, либо номер телефона владельца карты. |
Необязательно | billingPayerData |
Object | Блок с регистрационными данными клиента (адрес, почтовый индекс), необходимый для прохождения проверки адреса в рамках сервисов AVS/AVV. Обязательно, если функция включена для продавца на стороне Платежного шлюза. См. вложенные параметры. |
Необязательно | shippingPayerData |
Object | Объект, содержащий данные о доставке клиенту. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. См. вложенные параметры. |
Необязательно | preOrderPayerData |
Object | Объект, содержащий данные предварительного заказа. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. См. вложенные параметры. |
Необязательно | orderPayerData |
Object | Объект, содержащий данные о плательщике заказа. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. См. вложенные параметры. |
Необязательно | billingAndShippingAddressMatchIndicator |
A1 | Индикатор соответствия платежного адреса владельца карты и адреса доставки. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. Возможные значения:
|
Необязательно | clientBrowserInfo |
Object | Блок данных о браузере клиента, который отправляется на ACS во время 3DS аутентификации. Этот блок можно передавать, только если включена специальная настройка (обратитесь в команду поддержки). См. вложенные параметры. |
При аутентификации по протоколу 3DS 2.0 также передаются следующие параметры:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Условие | threeDSServerTransId |
String | Идентификатор транзакции, созданный на сервере 3DS. |
Необязательно | threeDSVer2FinishUrl |
String | URL-адрес, по которому клиент должен быть перенаправлен после аутентификации на сервере ACS. |
Необязательно | threeDSMethodNotificationUrl |
String | URL-адрес для отправки уведомления о прохождении проверки на ACS. |
Возможные значения tii
(Подробнее о типах связок, поддерживаемых платежным шлюзом, читайте здесь).
Значение tii
|
Описание | Тип транзакции | Инициатор транзакции | Данные карты для транзакции | Сохранение данных карты после транзакции | Примечание |
---|---|---|---|---|---|---|
Пусто | Обычный | Покупатель | Вводится покупателем | Нет | Транзакция электронной коммерции без сохранения связки. | |
CI | Инициирующий - Обычный (CIT) | Инициирующая | Покупатель | Вводится покупателем | Да | Транзакция электронной коммерции с сохранением связки. Это значение возможно передать только при наличии разрешения "Разрешено создание vendor pays common связок". |
RI | Инициирующий - Рекурентные (CIT) | Инициирующая | Покупатель | Вводится покупателем | Да | Транзакция электронной коммерции с сохранением связки. |
II | Инициирующий - Рассрочка (CIT) | Инициирующая | Покупатель | Вводится покупателем | Да | Транзакция электронной коммерции с сохранением связки. |
Дополнительные параметры, определяющие тип создаваемой связки и передаваемые в additionalParameters
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Условие | installments |
Integer [3] | Максимальное количество разрешенных авторизаций для платежей в рассрочку. Указывается в случае создания связки для выполнения платежей в рассрочку. |
Условие | recurringFrequency |
Integer [2] | Минимальное количество дней между авторизациями. Целое положительное число от 1 до 28 включительно. Указывается в случае создания связки для выполнения рекуррентных платежей. |
Условие | recurringExpiry |
String [8] | Дата, после которой дальнейшие авторизации не должны выполняться. Формат: YYYYMMDD. Указывается в случае создания связки для выполнения рекуррентных платежей. |
Ниже приведены параметры блока billingPayerData
(данные об адресе регистрации клиента).
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | billingCity |
String [0..50] | Город, зарегистрированный по конкретной карте у Банка Эмитента. |
Необязательно | billingCountry |
String [0..50] | Страна, зарегистрированная по конкретной карте банка-эмитента (ISO 3166-1, числовой). |
Необязательно | billingAddressLine1 |
String [0..50] | Адрес, зарегистрированный по конкретной карте у Банка Эмитента. Строка 1. Обязательно к передаче для AVS-проверки. |
Необязательно | billingAddressLine2 |
String [0..50] | Адрес, зарегистрированный по конкретной карте у Банка Эмитента. Строка 2. |
Необязательно | billingAddressLine3 |
String [0..50] | Адрес, зарегистрированный по конкретной карте у Банка Эмитента. Строка 3. |
Необязательно | billingPostalCode |
String [0..9] | Почтовый индекс, зарегистрированный по конкретной карте у Банка Эмитента. Обязательно к передаче для AVS-проверки. |
Необязательно | billingState |
String [0..50] | Штат, зарегистрированный по конкретной карте у Банка Эмитента. |
Описание параметров объекта shippingPayerData
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | shippingCity |
ANS...50 | Город заказчика (из адреса доставки) |
Необязательно | shippingCountry |
ANS...50 | Страна заказчика |
Необязательно | shippingAddressLine1 |
ANS...50 | Основной адрес клиента (из адреса доставки) |
Необязательно | shippingAddressLine2 |
ANS...50 | Основной адрес клиента (из адреса доставки) |
Необязательно | shippingAddressLine3 |
ANS...50 | Основной адрес клиента (из адреса доставки) |
Необязательно | shippingPostalCode |
ANS...16 | Почтовый индекс клиента для доставки |
Необязательно | shippingState |
ANS...50 | Штат/регион покупателя (из адреса доставки) |
Необязательно | shippingMethodIndicator |
N2 | Индикатор способа доставки. Возможные значения:
|
Необязательно | deliveryTimeframe |
N2 | Срок поставки товара. Возможные значения:
|
Необязательно | deliveryEmail |
ANS...254 | Целевой адрес электронной почты для доставки цифрового распространения. Предпочтительно передавать электронную почту в самостоятельном параметре запроса email (но если вы передадите его в этом блоке, к нему применятся те же правила). |
Описание параметров объекта preOrderPayerData
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | preOrderDate |
ANS8 | Ожидаемая дата доставки (для предзаказанных покупок) в формате ГГГГММДД. |
Необязательно | preOrderPurchaseInd |
N2 | Индикатор размещения клиентом заказа на доступную или будущую доставку. Возможные значения:
|
Необязательно | reorderItemsInd |
N2 | Индикатор того, что клиент перебронирует ранее оплаченную доставку в составе нового заказа. Возможные значения:
|
Описание параметров объекта orderPayerData
.
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | homePhone |
ANS...19 | Домашний телефон владельца карты. Необходимо всегда указывать код страны, но знак + или 00 в начале можно указать или опустить. Номер должен иметь длину от 7 до 15 цифр. Таким образом, возможны следующие значения:
|
Необязательно | workPhone |
ANS...19 | Рабочий телефон владельца карты. Необходимо всегда указывать код страны, но знак + или 00 в начале можно указать или опустить. Номер должен иметь длину от 7 до 15 цифр. Таким образом, возможны следующие значения:
|
Необязательно | mobilePhone |
ANS...19 | Номер мобильного телефона владельца карты. Необходимо всегда указывать код страны, но знак + или 00 в начале можно указать или опустить. Номер должен иметь длину от 7 до 15 цифр. Таким образом, возможны следующие значения:
Для платежей по VISA с 3DS авторизацией необходимо указать либо электронную почту, либо номер телефона владельца карты. Если у вас настроено отображение номера телефона на платежной странице и вы указали неверный номер телефона, клиент сможет исправить его на платежной странице. |
Ниже приведены параметры блока clientBrowserInfo
(данные о браузере клиента).
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | userAgent | string | Агент браузера. |
Необязательно | OS | string | Операционная система. |
Необязательно | OSVersion | string | Версия операционной системы. |
Необязательно | browserAcceptHeader | string | Заголовок Accept, который сообщает серверу, какие форматы (или MIME-типы) поддерживает браузер. |
Необязательно | browserIpAddress | string | IP-адрес браузера. |
Необязательно | browserLanguage | string | Язык браузера. |
Необязательно | browserTimeZone | string | Часовой пояс браузера. |
Необязательно | browserTimeZoneOffset | integer | Смещение часового пояса в минутах между локальным временем пользователя и UTC. |
Необязательно | colorDepth | string | Глубина цвета экрана, в битах. |
Необязательно | fingerprint | string | Отпечаток браузера - уникальный цифровой идентификатор браузера. |
Необязательно | isMobile | Boolean | Возможные значения: true или false . Флаг, указывающий на то, что используется мобильное устройство. |
Необязательно | javaEnabled | Boolean | Возможные значения: true или false . Флаг, указывающий на то, что в браузере включена поддержка java. |
Необязательно | javascriptEnabled | Boolean | Возможные значения: true или false . Флаг, указывающий на то, что в браузере включена поддержка javascript. |
Необязательно | plugins | string | Список плагинов, используемых в браузере, через запятую. |
Необязательно | screenHeight | integer | Высота экрана в пикселях. |
Необязательно | screenWidth | integer | Ширина экрана в пикселях. |
Необязательно | screenPrint | string | Данные о параметрах печати браузера, включая разрешение, глубину цвета, плотность пикселей. |
Пример блока clientBrowserInfo
:
"clientBrowserInfo":
{
"userAgent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/111.0.0.0 Safari/537.36 Edg/111.0.1661.41",
"fingerprint":850891523,
"OS":"Windows",
"OSVersion":"10",
"isMobile":false,
"screenPrint":"Current Resolution: 1536x864, Available Resolution: 1536x824, Color Depth: 24, Device XDPI: undefined, Device YDPI: undefined",
"colorDepth":24,
"screenHeight":"864",
"screenWidth":"1536",
"plugins":"PDF Viewer, Chrome PDF Viewer, Chromium PDF Viewer, Microsoft Edge PDF Viewer, WebKit built-in PDF",
"javaEnabled":false,
"javascriptEnabled":true,
"browserLanguage":"it-IT",
"browserTimeZone":"Europe/Rome",
"browserTimeZoneOffset":-120,
"browserAcceptHeader":"gzip",
"browserIpAddress":"10.99.50.37"
}
Параметры ответа
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | success |
Boolean | Основной параметр, который указывает на то, что запрос прошел успешно. Доступны следующие значения:
Обратите внимание, что значение true означает, что запрос был обработан, а не что заказ был оплачен.Более подробная информация о том, как узнать, был ли платеж успешным или нет, доступна здесь. |
Условие | data |
Object | Этот параметр возвращается только в случае успешной обработки платежа. См. описание ниже. |
Условие | error |
Object | Этот параметр возвращается только в случае ошибки платежа. См. описание ниже. |
Блок data
содержит следующие элементы.
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | orderId |
String [1..36] | Номер заказа в платежном шлюзе. Уникален в пределах платежного шлюза. |
Условие* | termUrl |
String [1..512] | При успешном ответе в случае оплаты 3D-Secure. Это URL-адрес, на который ACS перенаправляет владельца карты после аутентификации. Подробнее см. Редирект на ACS. |
Условие* | acsUrl |
String [1..512] | При успешном ответе в случае оплаты 3D-Secure. URL-адрес для редиректа на ACS. Обязательный, если нужен редирект на ACS. Подробнее см. Редирект на ACS. |
Условие* | paReq |
String [1..255] | При успешном ответе в случае оплаты 3D-Secure. PAReq (Payment Authentication Request) — сообщение, которое необходимо отправить в ACS вместе с редиректом. Это сообщение содержит данные в кодировке Base64, необходимые для аутентификации держателя карты. Подробнее см. Редирект на ACS. |
Условие** | bindingId |
String [1..255] | Идентификатор уже существующей связки. (идентификатор карты, токенизированной шлюзом). Его можно использовать, только если у мерчанта есть разрешение на работу со связками. Если этот параметр передается в этом запросе, это означает, что:
|
* Только если используется дополнительная аутентификация на ACS банка-эмитента
** Параметр возвращается, если используются связки
Если используется протокол 3DS 2.0, ответ на запрос также включает следующие параметры в блоке data
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | is3DSVer2 |
Boolean | Возможные значения: true или false Флаг, показывающий, что платеж поступает из 3DS 2.0. |
Обязательно | threeDSServerTransId |
String | Идентификатор транзакции, созданный на сервере 3DS. |
Необязательно | threeDSMethodUrl |
String | URL-адрес сервера ACS для сбора данных браузера. |
Обязательно | threeDSMethodUrlServer |
String | URL-адрес сервера 3DS для сбора данных браузера, которые будут включены в AReq (Authentication Request) с сервера 3DS на сервер ACS. |
Необязательно | threeDSMethodDataPacked |
String | Данные CReq (Challenge Response) в кодировке Base-64 для отправки на сервер ACS. |
Необязательно | threeDSMethodURLServerDirect |
String | URL-адрес 3dsmethod.do для выполнения метода 3DS на сервере 3DS через платежный шлюз (при наличии соответствующего разрешения на уровне продавца). |
Блок error
содержит следующие элементы.
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | code |
Integer [1..3] | Код как информационный параметр, сообщающий об ошибке. |
Обязательно | message |
String [1..512] | Информационный параметр, являющийся описанием ошибки для отображения пользователю. Параметр может варьироваться, поэтому не следует явным образом ссылаться на его значения в коде. |
Обязательно | description |
String [1..598] | Подробное техническое объяснение ошибки - содержимое этого параметра не предназначено для отображения пользователю. |
Используйте запрос getOrderStatusExtended.do, чтобы проверить статус транзакции.
Примеры
Пример запроса
curl --request POST \
--url https://3dsec.berekebank.kz/payment/google/payment.do \
--header 'Content-Type: application/json' \
--data-raw '{
"merchant": "OurBestMerchantLogin",
"orderNumber": "UAF-203974-DE",
"language": "RU",
"preAuth": true,
"description" : "Test description",
"additionalParameters":
{
"firstParamName": "firstParamValue",
"secondParamName": "secondParamValue"
},
"paymentToken": "eyJtZXJjaGFudCI6ICJrdXBpdmlwIiwib3JkZXJOdW1iZXIiOiAyMDUxOTIzMzkxLCJwYXltZW50VG9rZW4iOiAie1wiZXBoZW1lcmFsUHVibGljS2V5XCI6XCJrZXlcIixcImVuY3J5cHRlZE1lc3NhZ2VcIjpcIm1lc3NhZ2VcIixcInRhZ1wiOlwidGFnXCJ9In0=",
"ip" : "127.0.0.1",
"amount" : "230000",
"currencyCode" : 643,
"failUrl" : "https://mybestmerchantfailurl.ru"
"returnUrl" : "https://mybestmerchantreturnurl.ry"
}'
Пример ответа
{
"success":true,
"data": {
"orderId": "12312312123"
"is3DSVer2": true,
"threeDSServerTransId": "f44d6d21-1874-45a5-aeb0-1c710dd6e134",
"threeDSMethodURLServer": "https://test.com/3dsserver/gatherClientInfo?threeDSServerTransID=f44d6d21-1874-45a5-aeb0-1c710dd6e134"
}
}
Google Pay Direct
Запрос, используемый для прямого платежа через Google Pay -https://3dsec.berekebank.kz/payment/google/paymentDirect.do
. Он используется для регистрации и оплаты заказа.
Этот запрос можно использовать для интеграций, предполагающих расшифровку платежных данных на стороне продавца.
При выполнении запроса необходимо использовать заголовок:
Content-Type: application/json
Параметры запроса
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | username |
String [1..100] | Логин учетной записи API продавца. |
Обязательно | password |
String [1..200] | Пароль учетной записи API продавца. |
Обязательно | orderNumber |
String [1..32] | Номер заказа (ID) в системе мерчанта; должен быть уникальным для каждого заказа. |
Необязательно | description |
String [1..598] | Описание заказа в любом формате. Чтобы включить отправку этого поля в процессинговую систему, обратитесь в службу технической поддержки. В этом поле недопустимо передавать персональные данные или платежные данные (номера карт т.п.). Данное требование связано с тем, что описание заказа нигде не маскируется. |
Необязательно | language |
String [2] | Ключ языка по ISO 639-1. Если язык не указан, используется язык по умолчанию, указанный в настройках магазина. Поддерживаемые языки: ru, en. |
Необязательно | additionalParameters |
Object | Дополнительные параметры заказа, которые хранятся в личном кабинете продавца для последующего просмотра. Каждая новая пара имени параметра и его значения должна быть разделена запятой. Ниже приведен пример использования.{ "firstParamName": "firstParamValue", "secondParamName": "secondParamValue"} При создании связки в этом тэге могут быть переданы параметры, определяющие тип создаваемой связки. См. список параметров. |
Необязательно | preAuth |
Boolean | Параметр, определяющий необходимость предварительной авторизации (блокирования средств на счете клиента до их списания). Доступны следующие значения:
|
Необязательно | clientId |
String [0..255] | Номер клиента (ID) в системе мерчанта — до 255 символов. Используется для реализации функциональности связок. Может возвращаться в ответе, если мерчанту разрешено создавать связки. Указание этого параметра при обработке платежей по связке обязательно. В противном случае платеж будет невозможен. |
Необязательно | protocolVersion |
String | Версия протокола, определенная Google для платежного токена: ECv1 (по умолчанию) или ECv2
|
Обязательно | paymentToken |
String [1..8192] | Платежные данные, полученные от Google Pay и расшифрованные продавцом. Последовательность действий:
|
Необязательно | ip |
String [1..39] | IP адрес плательщика. IPv6 поддерживается во всех запросах (до 39 символов). |
Обязательно | amount |
Integer [0..12] | Сумма платежа в минимальных единицах валюты (например, в копейках). |
Необязательно | currencyCode |
String [3] | Цифровой код валюты платежа ISO 4217. Если не указан, считается равным 643 (российский рубль). |
Обязательно | returnUrl |
String [1..512] | Адрес, на который требуется перенаправить пользователя в случае успешной оплаты. Адрес должен быть указан полностью, включая используемый протокол (например, https://mybestmerchantreturnurl.com вместо mybestmerchantreturnurl.com ). В противном случае пользователь будет перенаправлен по адресу следующего вида: https://3dsec.berekebank.kz/payment/<merchant_address> . |
Необязательно | failUrl |
String [1..512] | Адрес, на который требуется перенаправить пользователя в случае неуспешной оплаты. Адрес должен быть указан полностью, включая используемый протокол (например, https://mybestmerchantreturnurl.com вместо mybestmerchantreturnurl.com ). В противном случае пользователь будет перенаправлен по адресу следующего вида: https://3dsec.berekebank.kz/payment/<merchant_address> . |
Необязательно | merchant |
String | Логин продавца в системе платежного шлюза. |
Необязательно | features |
String | Функции заказа Ниже приведены возможные значения.
|
Необязательно | tii |
String | Идентификатор инициатора транзакции. Параметр, указывающий, какой тип операции будет выполнять инициатор (Клиент или Мерчант). Возможные значения. |
Необязательно | threeDSProtocolVersion |
String | Версия протокола 3DS. Возможные значения: "2.1.0", "2.2.0" для 3DS2. Если в запросе не передается threeDSProtocolVersion , то для авторизации 3D Secure будет использоваться значение по умолчанию (2.1.0 - для 3DS 2). |
Необязательно | externalScaExemptionIndicator |
String | Тип исключения SCA (Strong Customer Authentication). Если указан этот параметр, транзакция будет обработана в зависимости от ваших настроек в платежном шлюзе: либо будет выполнена принудительная операция SSL, либо банк-эмитент получит информацию об исключении SCA и примет решение о проведении операции с 3DS-аутентификацией или без нее (для получения подробной информации свяжитесь с нашей службой поддержки). Допустимые значения:
Для передачи этого параметра у вас должны быть достаточные права в платежном шлюзе. |
Условие | email |
String | Электронная почта для отображения на платежной странице. Если для продавца настроены уведомления клиента, электронную почту необходимо указать. Пример: client_mail@email.com . Для платежей по VISA с 3DS авторизацией необходимо указать либо электронную почту, либо номер телефона владельца карты. |
Необязательно | billingPayerData |
Object | Блок с регистрационными данными клиента (адрес, почтовый индекс), необходимый для прохождения проверки адреса в рамках сервисов AVS/AVV. Обязательно, если функция включена для продавца на стороне Платежного шлюза. См. вложенные параметры. |
Необязательно | shippingPayerData |
Object | Объект, содержащий данные о доставке клиенту. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. См. вложенные параметры. |
Необязательно | preOrderPayerData |
Object | Объект, содержащий данные предварительного заказа. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. См. вложенные параметры. |
Необязательно | orderPayerData |
Object | Объект, содержащий данные о плательщике заказа. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. См. вложенные параметры. |
Необязательно | billingAndShippingAddressMatchIndicator |
A1 | Индикатор соответствия платежного адреса владельца карты и адреса доставки. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. Возможные значения:
|
Необязательно | clientBrowserInfo |
Object | Блок данных о браузере клиента, который отправляется на ACS во время 3DS аутентификации. Этот блок можно передавать, только если включена специальная настройка (обратитесь в команду поддержки). См. вложенные параметры. |
Ниже приведены параметры блока billingPayerData
(данные об адресе регистрации клиента).
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | billingCity |
String [0..50] | Город, зарегистрированный по конкретной карте у Банка Эмитента. |
Необязательно | billingCountry |
String [0..50] | Страна, зарегистрированная по конкретной карте банка-эмитента (ISO 3166-1, числовой). |
Необязательно | billingAddressLine1 |
String [0..50] | Адрес, зарегистрированный по конкретной карте у Банка Эмитента. Строка 1. Обязательно к передаче для AVS-проверки. |
Необязательно | billingAddressLine2 |
String [0..50] | Адрес, зарегистрированный по конкретной карте у Банка Эмитента. Строка 2. |
Необязательно | billingAddressLine3 |
String [0..50] | Адрес, зарегистрированный по конкретной карте у Банка Эмитента. Строка 3. |
Необязательно | billingPostalCode |
String [0..9] | Почтовый индекс, зарегистрированный по конкретной карте у Банка Эмитента. Обязательно к передаче для AVS-проверки. |
Необязательно | billingState |
String [0..50] | Штат, зарегистрированный по конкретной карте у Банка Эмитента. |
Описание параметров объекта shippingPayerData
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | shippingCity |
ANS...50 | Город заказчика (из адреса доставки) |
Необязательно | shippingCountry |
ANS...50 | Страна заказчика |
Необязательно | shippingAddressLine1 |
ANS...50 | Основной адрес клиента (из адреса доставки) |
Необязательно | shippingAddressLine2 |
ANS...50 | Основной адрес клиента (из адреса доставки) |
Необязательно | shippingAddressLine3 |
ANS...50 | Основной адрес клиента (из адреса доставки) |
Необязательно | shippingPostalCode |
ANS...16 | Почтовый индекс клиента для доставки |
Необязательно | shippingState |
ANS...50 | Штат/регион покупателя (из адреса доставки) |
Необязательно | shippingMethodIndicator |
N2 | Индикатор способа доставки. Возможные значения:
|
Необязательно | deliveryTimeframe |
N2 | Срок поставки товара. Возможные значения:
|
Необязательно | deliveryEmail |
ANS...254 | Целевой адрес электронной почты для доставки цифрового распространения. Предпочтительно передавать электронную почту в самостоятельном параметре запроса email (но если вы передадите его в этом блоке, к нему применятся те же правила). |
Описание параметров объекта preOrderPayerData
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | preOrderDate |
ANS8 | Ожидаемая дата доставки (для предзаказанных покупок) в формате ГГГГММДД. |
Необязательно | preOrderPurchaseInd |
N2 | Индикатор размещения клиентом заказа на доступную или будущую доставку. Возможные значения:
|
Необязательно | reorderItemsInd |
N2 | Индикатор того, что клиент перебронирует ранее оплаченную доставку в составе нового заказа. Возможные значения:
|
Описание параметров объекта orderPayerData
.
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | homePhone |
ANS...19 | Домашний телефон владельца карты. Необходимо всегда указывать код страны, но знак + или 00 в начале можно указать или опустить. Номер должен иметь длину от 7 до 15 цифр. Таким образом, возможны следующие значения:
|
Необязательно | workPhone |
ANS...19 | Рабочий телефон владельца карты. Необходимо всегда указывать код страны, но знак + или 00 в начале можно указать или опустить. Номер должен иметь длину от 7 до 15 цифр. Таким образом, возможны следующие значения:
|
Необязательно | mobilePhone |
ANS...19 | Номер мобильного телефона владельца карты. Необходимо всегда указывать код страны, но знак + или 00 в начале можно указать или опустить. Номер должен иметь длину от 7 до 15 цифр. Таким образом, возможны следующие значения:
Для платежей по VISA с 3DS авторизацией необходимо указать либо электронную почту, либо номер телефона владельца карты. Если у вас настроено отображение номера телефона на платежной странице и вы указали неверный номер телефона, клиент сможет исправить его на платежной странице. |
Возможные значения tii
(Подробнее о типах связок, поддерживаемых платежным шлюзом, читайте здесь).
Значение tii
|
Описание | Тип транзакции | Инициатор транзакции | Данные карты для транзакции | Сохранение данных карты после транзакции | Примечание |
---|---|---|---|---|---|---|
Пусто | Обычный | Покупатель | Вводится покупателем | Нет | Транзакция электронной коммерции без сохранения связки. | |
CI | Инициирующий - Обычный (CIT) | Инициирующая | Покупатель | Вводится покупателем | Да | Транзакция электронной коммерции с сохранением связки. Это значение возможно передать только при наличии разрешения "Разрешено создание vendor pays common связок". |
RI | Инициирующий - Рекурентные (CIT) | Инициирующая | Покупатель | Вводится покупателем | Да | Транзакция электронной коммерции с сохранением связки. |
II | Инициирующий - Рассрочка (CIT) | Инициирующая | Покупатель | Вводится покупателем | Да | Транзакция электронной коммерции с сохранением связки. |
Дополнительные параметры, определяющие тип создаваемой связки и передаваемые в additionalParameters
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Условие | installments |
Integer [3] | Максимальное количество разрешенных авторизаций для платежей в рассрочку. Указывается в случае создания связки для выполнения платежей в рассрочку. |
Условие | recurringFrequency |
Integer [2] | Минимальное количество дней между авторизациями. Целое положительное число от 1 до 28 включительно. Указывается в случае создания связки для выполнения рекуррентных платежей. |
Условие | recurringExpiry |
String [8] | Дата, после которой дальнейшие авторизации не должны выполняться. Формат: YYYYMMDD. Указывается в случае создания связки для выполнения рекуррентных платежей. |
Ниже приведены параметры блока clientBrowserInfo
(данные о браузере клиента).
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | userAgent | string | Агент браузера. |
Необязательно | OS | string | Операционная система. |
Необязательно | OSVersion | string | Версия операционной системы. |
Необязательно | browserAcceptHeader | string | Заголовок Accept, который сообщает серверу, какие форматы (или MIME-типы) поддерживает браузер. |
Необязательно | browserIpAddress | string | IP-адрес браузера. |
Необязательно | browserLanguage | string | Язык браузера. |
Необязательно | browserTimeZone | string | Часовой пояс браузера. |
Необязательно | browserTimeZoneOffset | integer | Смещение часового пояса в минутах между локальным временем пользователя и UTC. |
Необязательно | colorDepth | string | Глубина цвета экрана, в битах. |
Необязательно | fingerprint | string | Отпечаток браузера - уникальный цифровой идентификатор браузера. |
Необязательно | isMobile | Boolean | Возможные значения: true или false . Флаг, указывающий на то, что используется мобильное устройство. |
Необязательно | javaEnabled | Boolean | Возможные значения: true или false . Флаг, указывающий на то, что в браузере включена поддержка java. |
Необязательно | javascriptEnabled | Boolean | Возможные значения: true или false . Флаг, указывающий на то, что в браузере включена поддержка javascript. |
Необязательно | plugins | string | Список плагинов, используемых в браузере, через запятую. |
Необязательно | screenHeight | integer | Высота экрана в пикселях. |
Необязательно | screenWidth | integer | Ширина экрана в пикселях. |
Необязательно | screenPrint | string | Данные о параметрах печати браузера, включая разрешение, глубину цвета, плотность пикселей. |
Пример блока clientBrowserInfo
:
"clientBrowserInfo":
{
"userAgent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/111.0.0.0 Safari/537.36 Edg/111.0.1661.41",
"fingerprint":850891523,
"OS":"Windows",
"OSVersion":"10",
"isMobile":false,
"screenPrint":"Current Resolution: 1536x864, Available Resolution: 1536x824, Color Depth: 24, Device XDPI: undefined, Device YDPI: undefined",
"colorDepth":24,
"screenHeight":"864",
"screenWidth":"1536",
"plugins":"PDF Viewer, Chrome PDF Viewer, Chromium PDF Viewer, Microsoft Edge PDF Viewer, WebKit built-in PDF",
"javaEnabled":false,
"javascriptEnabled":true,
"browserLanguage":"it-IT",
"browserTimeZone":"Europe/Rome",
"browserTimeZoneOffset":-120,
"browserAcceptHeader":"gzip",
"browserIpAddress":"10.99.50.37"
}
Если используется 3DS 2.0, необходимо также передать следующие параметры:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Условие | threeDSServerTransId |
String | Идентификатор транзакции, созданный на сервере 3DS. |
Необязательно | threeDSVer2FinishUrl |
String | URL-адрес, по которому клиент должен быть перенаправлен после аутентификации на сервере ACS. |
Необязательно | threeDSSDK |
Boolean | Возможные значения: true или false Флаг, показывающий, что платеж поступает из 3DS SDK. |
Необязательно | threeDSMethodNotificationUrl |
String | URL-адрес для отправки уведомления о прохождении проверки на ACS. |
Параметры ответа
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | success |
Boolean | Основной параметр, который указывает на то, что запрос прошел успешно. Доступны следующие значения:
Обратите внимание, что значение true означает, что запрос был обработан, а не что заказ был оплачен.Более подробная информация о том, как узнать, был ли платеж успешным или нет, доступна здесь. |
Обязательно* | data |
Object | Возвращается только в случае успешной оплаты. |
Обязательно* | error |
Object | Этот параметр возвращается только в случае ошибки платежа. |
Блок data
содержит следующие элементы.
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | orderId |
String [1..36] | Номер заказа в платежном шлюзе. Уникален в пределах платежного шлюза. |
Только если используется дополнительная аутентификация на ACS банка-эмитента | termUrl |
String [1..512] | При успешном ответе в случае оплаты 3D-Secure. Это URL-адрес, на который ACS перенаправляет владельца карты после аутентификации. Подробнее см. Редирект на ACS. |
Только если используется дополнительная аутентификация на ACS банка-эмитента | acsUrl |
String [1..512] | При успешном ответе в случае оплаты 3D-Secure. URL-адрес для редиректа на ACS. Обязательный, если нужен редирект на ACS. Подробнее см. Редирект на ACS. |
Только если используется дополнительная аутентификация на ACS банка-эмитента | paReq |
String [1..255] | При успешном ответе в случае оплаты 3D-Secure. PAReq (Payment Authentication Request) — сообщение, которое необходимо отправить в ACS вместе с редиректом. Это сообщение содержит данные в кодировке Base64, необходимые для аутентификации держателя карты. Подробнее см. Редирект на ACS. |
Параметр возвращается, если используются связки | bindingId |
String [1..255] | Идентификатор уже существующей связки. (идентификатор карты, токенизированной шлюзом). Его можно использовать, только если у мерчанта есть разрешение на работу со связками. Если этот параметр передается в этом запросе, это означает, что:
|
Если используется протокол 3DS 2.0, ответ на запрос также включает следующие параметры в блоке data
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | is3DSVer2 |
Boolean | Возможные значения: true или false Флаг, показывающий, что платеж поступает из 3DS 2.0. |
Обязательно | threeDSServerTransId |
String | Идентификатор транзакции, созданный на сервере 3DS. |
Необязательно | threeDSMethodUrl |
String | URL-адрес сервера ACS для сбора данных браузера. |
Необязательно | threeDSMethodUrlServer |
String | URL-адрес сервера 3DS для сбора данных браузера, которые будут включены в AReq (Authentication Request) с сервера 3DS на сервер ACS. |
Необязательно | threeDSMethodDataPacked |
String | Данные CReq (Challenge Response) в кодировке Base-64 для отправки на сервер ACS. |
Необязательно | threeDSMethodURLServerDirect |
String | URL-адрес 3dsmethod.do для выполнения метода 3DS на сервере 3DS через платежный шлюз (при наличии соответствующего разрешения на уровне продавца). |
Параметры в блоке error
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | code |
Integer [1..3] | Код как информационный параметр, сообщающий об ошибке. |
Обязательно | message |
String [1..512] | Информационный параметр, являющийся описанием ошибки для отображения пользователю. Параметр может варьироваться, поэтому не следует явным образом ссылаться на его значения в коде. |
Обязательно | description |
String [1..598] | Подробное техническое объяснение ошибки - содержимое этого параметра не предназначено для отображения пользователю. |
Примеры
Пример запроса
curl --request POST \
--url https://3dsec.berekebank.kz/payment/google/paymentDirect.do \
--header 'Content-Type: application/json' \
--data-raw '{
"amount": "1000",
"orderNumber": "350467565",
"features": [""],
"language": "EN",
"password": "test_user_password",
"paymentToken": "eyJnYXRldTWVY2hRJ...b25ZZWFyyMD0fX0=",
"preAuth": true,
"returnUrl": "https://mybestmerchantreturnurl.com",
"username": "test_user"
}'
Пример ответа
{
"success": true,
"data": {
"orderId": "12312312123"
}
}
Статус платежа
Самый простой способ узнать статус платежа — использовать специальный вызов API:
- Сделать вызов getOrderStatusExtended.do;
- Проверить поле
orderStatus
в ответе: заказ считается оплаченным, только если значениеorderStatus
равно1
или2
.
Еще один способ проверить, прошел ли платеж успешно или нет, – это посмотреть уведомление обратного вызова.
Статус заказа
Для получения статуса заказа используется метод https://3dsec.berekebank.kz/payment/rest/getOrderStatusExtended.do
.
При выполнении запроса необходимо использовать заголовок:
Content-Type: application/x-www-form-urlencoded
Дополнительная информация о причинах отказа доступна здесь.
Параметры запроса
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | userName |
String [1..100] | Логин учетной записи API продавца. Если для аутентификации при регистрации вместо логина и пароля используется открытый токен (параметр token ), пароль передавать не нужно. |
Обязательно | password |
String [1..200] | Пароль учетной записи API продавца. Если для аутентификации при регистрации вместо логина и пароля используется открытый токен (параметр token ), пароль передавать не нужно. |
Необязательно | token |
String [1..256] | Значение, используемое для аутентификации продавца при отправке запросов платежному шлюзу. Если вы передаете этот параметр, то не передавайте userName и password . |
Обязательно | orderId |
String | Номер заказа в платежном шлюзе. Уникален в пределах платежного шлюза. |
Обязательно | orderNumber |
String [1..32] | Номер заказа (ID) в системе мерчанта; должен быть уникальным для каждого мерчанта. |
Необязательно | language |
String [2] | Ключ языка по ISO 639-1. Если язык не указан, используется язык по умолчанию, указанный в настройках магазина. Поддерживаемые языки: ru, en. |
Необязательно | merchantLogin |
String [1..255] | Чтобы вместо текущего пользователя получить статус заказа определенного мерчанта, укажите логин мерчанта (для API-аккаунта). Можно использовать, только если у вас есть разрешение на просмотр транзакций других продавцов или если указанный продавец является вашим дочерним продавцом. |
Параметры ответа
Существует несколько наборов параметров ответа. Какой набор параметров возвращается в ответе, зависит от версии getOrderStatusExtended
указанной в настройках мерчанта в платежном шлюзе.
Версия | Обязательность | Название | Тип | Описание |
---|---|---|---|---|
Все | Необязательно | errorCode |
String [1..2] | Информационный параметр в случае ошибки, который может иметь разные кодовые значения:
|
Все | Необязательно | errorMessage |
String [1..512] | Информационный параметр, являющийся описанием ошибки в случае возникновения ошибки. Значение errorMessage может варьироваться, поэтому не следует явным образом ссылаться на его значения в коде. Язык описания задается в параметре language запроса. |
Все | Условие | orderNumber |
String [1..32] | Номер заказа (ID) в системе мерчанта, должен быть уникальным для каждого мерчанта, зарегистрированного в платежном шлюзе. Если номер заказа генерируется на стороне платежного шлюза, этот параметр передавать необязательно. |
Все | Необязательно | orderStatus |
Integer | Значение этого параметра указывает статус заказа в платежном шлюзе. Отсутствует, если заказ не был найден. Ниже приведен список доступных значений:
|
Все | Обязательно | actionCode |
Integer | Код ответа от процессинга банка. См. список кодов ответа здесь. |
Все | Обязательно | actionCodeDescription |
String [1..512] | Описание actionCode , возвращаемое процессингом банка. |
Все | Обязательно | amount |
Integer [0..12] | Сумма платежа в минимальных единицах валюты (например, в копейках). |
Все | Необязательно | currency |
String [3] | Код валюты платежа ISO 4217. Если не указано, то используется значение по умолчанию. |
Все | Обязательно | date |
String | Дата регистрации заказа (Unix) |
Все | Необязательно | depositeddate |
String | Дата оплаты заказа (время UNIX). |
Все | Необязательно | orderDescription |
String [1..600] | Описание заказа передаваемое платежному шлюзу при регистрации. В этом поле недопустимо передавать персональные данные или платежные данные (номера карт т.п.). Данное требование связано с тем, что описание заказа нигде не маскируется. |
Все | Обязательно | ip |
String [1..39] | IP адрес плательщика. IPv6 поддерживается во всех запросах (до 39 символов). |
09+ | Необязательно | authRefNum |
String [1..24] | Номер авторизации платежа, присвоенный ему при регистрации платежа. |
01+, обязательно с 27 | Необязательно | refundedDate |
Integer | Дата и время возврата. |
12+ | Необязательно | reverseddate |
Integer | Дата и время отмены платежа. |
12+ | Обязательно | paymentWay |
String | Способ совершения платежа (платеж с вводом карточных данных, оплата по связке и т.п.). Дополнительные возможные значения параметра приведены ниже |
19+ | Необязательно | avsCode |
String | Код ответа верификации AVS (проверка адреса и почтового индекса держателя карты). Возможные значения:
|
19+ | Необязательно | refund |
Boolean | Были ли средства принудительно возвращены покупателю банком. Возможные значения:
|
06+ | Необязательно | authDateTime |
String | Дата и время авторизации, показанные как количество миллисекунд, прошедших с 00:00 GMT 1 января 1970 года (время Unix). |
01+ | Необязательно | terminalId |
String [1..10] | Идентификатор терминала в системе, обрабатывающей платеж. |
Значения параметра paymentWay
:
-
CARD
- Оплата с вводом данных карты -
CARD_BINDING
- Проведение оплаты по связке -
P2P
- Перевод денег с карты на карту; -
P2P_BINDING
- Перевод с карты на карту по связке -
APPLE_PAY
- платеж Apple Pay -
APPLE_PAY_BINDING
- Оплата по связке Apple Pay. -
GOOGLE_PAY_CARD
- Оплата нетокенизированной картой Google Pay -
GOOGLE_PAY_CARD_BINDING
- Оплата по связке с помощью нетокенизированной карты Google Pay. -
GOOGLE_PAY_TOKENIZED
- Оплата токенизированной картой Google Pay -
GOOGLE_PAY_TOKENIZED_BINDING
- Оплата по связке с помощью токенизированной карты Google Pay. -
SAMSUNG_PAY
- Оплата Samsung Pay. -
SAMSUNG_PAY_BINDING
- Оплата по связке Samsung Pay.
Блок refunds
содержит информацию о возврате средств. 05+ Присутствует только при наличии возвратов в заказе.
Версия | Обязательность | Название | Тип | Описание |
---|---|---|---|---|
05+ | Необязательно | date |
String | Дата возврата заказа |
21+ | Необязательно | externalRefundId |
String [1..30] | Идентификатор возврата. При попытке возврата проверяется externalRefundId : если он существует, возвращается успешный ответ с данными о возврате, если нет — осуществляется возврат. |
С 05 до 25 для НЕ карточных платежей. 26+ для всех платежных методов | Необязательно | approvalCode |
String [6] | Код авторизации МПС. Это поле имеет фиксированную длину (шесть символов) и может содержать цифры и латинские буквы. |
05+ | Необязательно | actionCode |
Integer | Код ответа от процессинга банка. См. список кодов ответа здесь. |
05+ | Необязательно | referenceNumber |
String [12] | Уникальный идентификационный номер, который присваивается операции по ее завершению. |
05+ | Необязательно | Amount |
Integer [0..12] | Сумма платежа в минимальных единицах валюты (например, в копейках). |
Блок attributes
cодержит информацию о номере заказа в платежном шлюзе. Параметр name
всегда принимает значение mdOrder
, а параметр value
- номер заказа в платежной системе.
Версия | Обязательность | Название | Тип | Описание |
---|---|---|---|---|
Все | Необязательно | name |
String [1..255] | Название дополнительного параметра. |
Все | Необязательно | value |
String [1..1024] | Значение дополнительного параметра - до 1024 символов. |
Блок transactionAttributes
содержит набор дополнительных атрибутов транзакции. Используется для версии 14 и выше. Ниже приведен список включенных параметров.
Версия | Обязательность | Название | Тип | Описание |
---|---|---|---|---|
Все | Необязательно | name |
String [1..255] | Название дополнительного параметра. |
Все | Необязательно | value |
String [1..1024] | Значение дополнительного параметра - до 1024 символов. |
блок merchantOrderParams
передается в ответе, если в заказе есть дополнительные параметры мерчанта. Каждый дополнительный параметр передается в отдельном элементе merchantOrderParams
.
Версия | Обязательность | Название | Тип | Описание |
---|---|---|---|---|
Все | Необязательно | name |
String [1..255] | Название дополнительного параметра. |
Все | Необязательно | value |
String [1..1024] | Значение дополнительного параметра - до 1024 символов. |
В элементе cardAuthInfo
лежит структура, состоящая из списка элемента secureAuthInfo
и следующих параметров.
Версия | Обязательность | Название | Тип | Описание |
---|---|---|---|---|
01+ | Необязательно | maskedPan |
String [1..19] | Маскированный номер карты, использованной для платежа. Указывается только после оплаты заказа. |
01+ | Необязательно | expiration |
Integer | Срок действия карты в следующем формате: .YYYYMM Указывается только после оплаты заказа. |
01+ | Необязательно | cardholdername |
String [1..26] | Имя держателя карты латинскими буквами. Этот параметр передается только после оплаты заказа. |
01+ | Необязательно | approvalCode |
String [6] | Код авторизации МПС. Это поле имеет фиксированную длину (шесть символов) и может содержать цифры и латинские буквы. |
08+ | Обязательно | paymentSystem |
String | Наименование платежной системы. Возможны следующие значения:
|
08+ | Обязательно | product |
String [1..255] | Дополнительные сведения о корпоративных картах. Эти сведения заполняются службой технической поддержки. Если такие сведения отсутствуют, возвращается пустое значение. |
17+ | Обязательно | productCategory |
String | Дополнительные сведения о категории корпоративных карт. Эти сведения заполняются службой технической поддержки. Если такие сведения отсутствуют, возвращается пустое значение. Возможные значения: DEBIT, CREDIT, PREPAID, NON_MASTERCARD, CHARGE, DIFFERED_DEBIT. |
01+ | Необязательно | corporateCard |
A..5 | Указывает, является ли данная карта корпоративной. Возможные значения: false - не является корпоративной картой, true - является корпоративной картой. Может возвращать пустое значение, означает, что значение не найдено. |
Элемент secureAuthInfo
состоит из следующих элементов (параметры cavv
и xid
включены в элемент threeDSInfo
).
Версия | Обязательность | Название | Тип | Описание |
---|---|---|---|---|
01+ | Необязательно | eci |
Integer [1..4] | Электронный коммерческий индикатор. Указан только после оплаты заказа и в случае наличия соответствующего разрешения. Ниже приводится расшифровка ECI-кодов.
|
01+ | Необязательно | authTypeIndicator |
String | Тип аутентификации 3DS. В зависимости от значения ECI. Допустимые значения:
|
01+ | Необязательно | cavv |
String [0..200] | Значение проверки аутентификации владельца карты. Указан только после оплаты заказа и в случае наличия соответствующего разрешения. |
01+ | Необязательно | xid |
String [1..80] | Электронный коммерческий идентификатор транзакции. Указан только после оплаты заказа и в случае наличия соответствующего разрешения. |
30+ | Необязательно | threeDSProtocolVersion |
String | Версия протокола 3DS. Возможные значения: "2.1.0", "2.2.0" для 3DS2. Если в запросе не передается threeDSProtocolVersion , то для авторизации 3D Secure будет использоваться значение по умолчанию (2.1.0 - для 3DS 2). |
30+ | Необязательно | rreqTransStatus |
String [1] | Статус транзакции из запроса на передачу результатов аутентификации пользователя от ACS (RReq). Передается при использовании 3DS 2.0. |
30+ | Необязательно | aresTransStatus |
String | Состояние транзакции из ответа ACS на запрос аутентификации (ARes). Передается при использовании 3DS 2.0. |
Элемент bindingInfo
содержит следующие параметры.
Версия | Обязательно | Название | Тип | Описание |
---|---|---|---|---|
Все | Необязательно | clientId |
String [0..255] | Номер клиента (ID) в системе мерчанта — до 255 символов. Используется для реализации функциональности связок. Может возвращаться в ответе, если мерчанту разрешено создавать связки. Указание этого параметра при обработке платежей по связке обязательно. В противном случае платеж будет невозможен. |
Все | Необязательно | bindingId |
String [1..255] | Идентификатор уже существующей связки. (идентификатор карты, токенизированной шлюзом). Его можно использовать, только если у мерчанта есть разрешение на работу со связками. Если этот параметр передается в этом запросе, это означает, что:
|
02+ | Необязательно | authDateTime |
String | Дата и время авторизации, показанные как количество миллисекунд, прошедших с 00:00 GMT 1 января 1970 года (время Unix). |
02+ | Необязательно | authRefNum |
String [1..24] | Номер авторизации платежа, присвоенный ему при регистрации платежа. |
02+ | Необязательно | terminalId |
String [1..10] | Идентификатор терминала в системе, обрабатывающей платеж. |
Элемент paymentAmountInfo
содержит следующие параметры.
Версия | Обязательно | Название | Тип | Описание |
---|---|---|---|---|
03+ | Необязательно | approvedAmount |
Integer [0..12] | Сумма в минимальных единицах валюты (например, в центах), которая была заблокирована на счете покупателя. Используется только в двухстадийных платежах. |
03+ | Необязательно | depositedAmount |
Integer [1..12] | Сумма списания в минимальных единицах валюты (например, в копейках). |
03+ | Необязательно | refundedAmount |
Integer [1..12] | Сумма возврата в минимальных единицах валюты. |
03+ | Необязательно | paymentState |
String | Состояние заказа, параметр может принимать следующие значения:
|
Элемент bankInfo
содержит следующие параметры.
Версия | Обязательность | Название | Тип | Описание |
---|---|---|---|---|
03+ | Необязательно | bankName |
String [1..50] | Название банка-эмитента. |
03+ | Необязательно | bankCountryCode |
String | Код страны банка-эмитента. |
03+ | Необязательно | bankCountryName |
String [1..160] | Страна банка-эмитента. |
Элемент payerData
содержит следующие параметры.
Версия | Обязательность | Название | Тип | Описание |
---|---|---|---|---|
13+ | Необязательно | email |
String | Электронная почта плательщика. |
13+ | Необязательно | phone |
String | Номер телефона владельца карты. Необходимо всегда указывать код страны, но знак + или 00 в начале можно указать или опустить. Номер должен иметь длину от 7 до 15 цифр. Таким образом, возможны следующие значения:
Для платежей по VISA с 3DS авторизацией необходимо указать либо электронную почту, либо номер телефона владельца карты. |
13+ | Необязательно | postAddress |
String [1..255] | Адрес доставки. |
Элемент pluginInfo
(объект JSON) присутствует в ответе, если оплата была произведена через платежный плагин. Содержит следующие параметры.
Версия | Обязательность | Название | Тип | Описание |
---|---|---|---|---|
28+ | Необязательно | name |
String | Уникальное наименование платежного плагина. |
28+ | Необязательно | params |
Object | Параметры для конкретного способа оплаты должны передаваться следующим образом {"param":"value","param2":"value2"} . |
Описание параметров в объекте orderBundle
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | orderCreationDate |
String | Дата создания заказа в формате YYYY-MM-DDTHH:MM:SS . |
Необязательно | customerDetails |
Object | Блок, содержащий атрибуты клиента. Описание атрибутов тега приведено ниже. |
Обязательно | cartItems |
Object | Объект, содержащий атрибуты товаров в корзине. Описание вложенных элементов приведено ниже. |
Описание параметров в объекте customerDetails
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | contact |
String [0..40] | Предпочитаемый клиентом способ связи. |
Необязательно | fullName |
String [1..100] | ФИО плательщика. |
Необязательно | passport |
Integer | Серия и номер паспорта плательщика в следующем формате: 2222888888
|
Необязательно | deliveryInfo |
Object | Объект, содержащий атрибуты адреса доставки. Описание вложенных элементов приведено ниже. |
Описание параметров в объекте deliveryInfo
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | deliveryType |
String [1..20] | Способ доставки. |
Обязательно | country |
String | Двухбуквенный код страны доставки. |
Обязательно | city |
String [0..40] | Город назначения. |
Обязательно | postAddress |
String [1..255] | Адрес доставки. |
Описание параметров в объекте cartItems
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | items |
Object | Элемент массива с атрибутами товарной позиции. Описание вложенных элементов приведено ниже. |
Описание параметров в объекте quantity
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | value |
String | Количество товарных позиций данного positionId . Для указания дробных чисел используйте десятичную точку. |
Обязательно | measure |
String [1..20] | Единица измерения количества по позиции. |
Описание параметров в объекте itemDetails
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | itemDetailsParams |
Object | Параметр, описывающий дополнительную информацию по товарной позиции. Описание вложенных элементов приведено ниже. |
Примеры
Пример запроса
curl --request POST \
--url https://3dsec.berekebank.kz/payment/rest/getOrderStatusExtended.do \
--header 'content-type: application/x-www-form-urlencoded' \
--data userName=test_user \
--data password=test_user_password \
--data orderId=01491d0b-c848-7dd6-a20d-e96900a7d8c0 \
--data language=en
Пример ответа
{
"errorCode": "0",
"errorMessage": "Success",
"orderNumber": "7005",
"orderStatus": 2,
"actionCode": 0,
"actionCodeDescription": "",
"amount": 2000,
"currency": "398",
"date": 1617972915659,
"orderDescription": "",
"merchantOrderParams": [],
"transactionAttributes": [],
"attributes": [
{
"name": "mdOrder",
"value": "01491d0b-c848-7dd6-a20d-e96900a7d8c0"
}
],
"cardAuthInfo": {
"maskedPan": "500000**1115",
"expiration": "203012",
"cardholderName": "TEST CARDHOLDER",
"approvalCode": "12345678",
"pan": "500000**1115"
},
"bindingInfo": {
"clientId": "259753456",
"bindingId": "01491394-63a6-7d45-a88f-7bce00a7d8c0"
},
"authDateTime": 1617973059029,
"terminalId": "123456",
"authRefNum": "714105591198",
"paymentAmountInfo": {
"paymentState": "DEPOSITED",
"approvedAmount": 2000,
"depositedAmount": 2000,
"refundedAmount": 0
},
"bankInfo": {
"bankCountryCode": "UNKNOWN",
"bankCountryName": "<Unknown>"
}
}
Управление заказом
Завершение заказа
Для завершения предварительно авторизованного заказа используется запрос https://3dsec.berekebank.kz/payment/rest/deposit.do
.
При выполнении запроса необходимо использовать заголовок:
Content-Type: application/x-www-form-urlencoded
Параметры запроса
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | userName |
String [1..100] | Логин учетной записи API продавца. |
Обязательно | password |
String [1..200] | Пароль учетной записи API продавца. |
Обязательно | orderId |
String [1..36] | Номер заказа в платежном шлюзе. Уникален в пределах платежного шлюза. |
Обязательно | amount |
String [0..12] | Сумма завершения в минимальных единицах валюты (например, в копейках). Сумма завершения должна соответствовать общей сумме всех товаров по которым идет завершение. Если в запросе указать amount =0, будет сформировано завершение на всю сумму заказа. |
Необязательно | depositItems |
Object | Объект, содержащий атрибуты товаров в корзине. Ниже приведено описание включенных атрибутов. |
Необязательно | language |
String [2] | Ключ языка по ISO 639-1. Если язык не указан, используется язык по умолчанию, указанный в настройках магазина. Поддерживаемые языки: ru, en. |
Необязательно | currency |
Integer [3] | Код валюты платежа ISO 4217. Если не указано, то используется значение по умолчанию. |
Описание параметров в объекте quantity
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | value |
String | Количество товарных позиций данного positionId . Для указания дробных чисел используйте десятичную точку. |
Обязательно | measure |
String [1..20] | Единица измерения количества по позиции. |
Параметры ответа
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | errorCode |
Integer [1..2] | Информационный параметр в случае ошибки, который может иметь разные кодовые значения:
|
Необязательно | errorMessage |
String [1..512] | Информационный параметр, являющийся описанием ошибки в случае возникновения ошибки. Значение errorMessage может варьироваться, поэтому не следует явным образом ссылаться на его значения в коде. Язык описания задается в параметре language запроса. |
Примеры
Пример запроса
curl --request POST \
--url https://3dsec.berekebank.kz/payment/rest/deposit.do \
--header 'content-type: application/x-www-form-urlencoded' \
--data userName=test_user \
--data password=test_user_password \
--data currency=978\
--data amount=2000 \
--data orderId=01492437-d2fb-77fa-8db7-9e2900a7d8c0 \
--data language=en
Пример ответа
{
"errorCode": 0,
"errorMessage":"Success"
}
Отмена платежа
Для отмены платежа используется запрос https://3dsec.berekebank.kz/payment/rest/reverse.do
.
Отмена возможна только в течение определенного периода времени после оплаты. Свяжитесь с Поддержкой, чтобы узнать точный период, так как он варьируется.
При выполнении запроса необходимо использовать заголовок:
Content-Type: application/x-www-form-urlencoded
Платеж можно отменить только один раз. Если он завершится ошибкой, то последующие операции по отмене платежа работать не будут.
Наличие данной функции возможно по согласованию с банком. Отмена может выполняться только пользователями, которым были предоставлены соответствующие системные разрешения.
Параметры запроса
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | userName |
String [1..100] | Логин учетной записи API продавца. Если для аутентификации при регистрации вместо логина и пароля используется открытый токен (параметр token ), пароль передавать не нужно. |
Обязательно | password |
String [1..200] | Пароль учетной записи API продавца. |
Обязательно | orderId |
String [1..36] | Номер заказа в платежном шлюзе. Уникален в пределах платежного шлюза. |
Необязательно | language |
String [2] | Ключ языка по ISO 639-1. Если язык не указан, используется язык по умолчанию, указанный в настройках магазина. Поддерживаемые языки: ru, en. |
Необязательно | orderNumber |
String [1..32] | Номер заказа (ID) в системе мерчанта; должен быть уникальным для каждого заказа. |
Необязательно | jsonParams |
String | Поля для хранения дополнительных данных необходимо передавать следующим образом: {"param":"value","param2":"value2"} . |
Необязательно | merchantLogin |
String [1..255] | Чтобы отменить заказ от имени другого мерчанта, укажите его логин (для API-аккаунта) в этом параметре. Можно использовать, только если у вас есть разрешение на просмотр транзакций других продавцов или если указанный продавец является вашим дочерним продавцом. |
Необязательно | amount |
String [0..12] | Сумма отмены в минимальных единицах валюты (например, в копейках). Сумма отмены должна быть меньше или равна авторизованной сумме заказа (для двухстадийных заказов - общей предварительно авторизованной сумме заказа). |
Необязательно | currency |
Integer [3] | Код валюты платежа ISO 4217. Если не указано, то используется значение по умолчанию. |
Параметры ответа
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | errorCode |
Integer [1..2] | Информационный параметр в случае ошибки, который может иметь разные кодовые значения:
|
Необязательно | errorMessage |
String [1..512] | Информационный параметр, являющийся описанием ошибки в случае возникновения ошибки. Значение errorMessage может варьироваться, поэтому не следует явным образом ссылаться на его значения в коде. Язык описания задается в параметре language запроса. |
Примеры
Пример запроса
curl --request POST \
--url https://3dsec.berekebank.kz/payment/rest/reverse.do \
--header 'content-type: application/x-www-form-urlencoded' \
--data userName=test_user \
--data password=test_user_password \
--data currency=978\
--data orderId=01491d0b-c848-7dd6-a20d-e96900a7d8c0 \
--data language=en
Пример ответа
{
"errorCode": 0,
"errorMessage":"Success"
}
Возврат средств
Используйте https://3dsec.berekebank.kz/payment/rest/refund.do
` для отправки запросов на возврат средств.
При выполнении запроса необходимо использовать заголовок:
Content-Type: application/x-www-form-urlencoded
Нельзя осуществлять возврат средств по заказам, которые инициируют регулярные платежи, так как в этом случае не происходит списания средств.
По этому запросу средства по указанному заказу будут возвращены плательщику. Запрос закончится ошибкой, если средства по этому заказу не были списаны. Система позволяет возвращать средства более одного раза, но в общей сложности не более первоначальной суммы списания.
Параметры запроса
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | userName |
String [1..100] | Логин учетной записи API продавца. |
Обязательно | password |
String [1..200] | Пароль учетной записи API продавца. |
Обязательно | orderId |
String [1..36] | Номер заказа в платежном шлюзе. Уникален в пределах платежного шлюза. |
Обязательно | amount |
String [0..12] | Сумма возврата в минимальных единицах валюты (например, в копейках). Сумма возврата должна быть меньше или равна сумме заказа (для двухстадийных заказов - общей сумме завершения по заказу). Если в запросе указать amount =0, то будет возвращена вся сумма заказа. |
Необязательно | language |
String [2] | Ключ языка по ISO 639-1. Если язык не указан, используется язык по умолчанию, указанный в настройках магазина. Поддерживаемые языки: ru, en. |
Необязательно | jsonParams |
String | Поля для хранения дополнительных данных необходимо передавать следующим образом: {"param":"value","param2":"value2"} . |
Необязательно | expectedDepositedAmount |
Integer [1..12] | Параметр служит для определения того, что запрос является повторным. Если параметр передан, его значение сравнивается с текущим значением depositedAmount в заказе. Операция будет выполнена только в том случае, если значения совпадают. Если два возврата приходят с одинаковым expectedDepositedAmount , будет выполнен только один возврат. Этот возврат изменит значение depositedAmount , а затем второй возврат будет отклонен. |
Необязательно | externalRefundId |
String [1..30] | Идентификатор возврата. При попытке возврата проверяется externalRefundId : если он существует, возвращается успешный ответ с данными о возврате, если нет — осуществляется возврат. |
Необязательно | currency |
Integer [3] | Код валюты платежа ISO 4217. Если не указано, то используется значение по умолчанию. |
Необязательно | refundItems |
Object | Объект для передачи информации о возвращаемых товарах - номер позиции товара в запросе, название, детали, единица измерения, количество, валюта, код товара, скидка, прибыль агента. |
Параметр refundItems
включает в себя:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | items |
Object | Элемент массива с атрибутами товарной позиции. Описание вложенных элементов приведено ниже. |
Описание параметров в объекте items
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | positionId |
Integer [1..12] | Уникальный идентификатор товарной позиции в корзине. |
Обязательно | name |
String [1..255] | Наименование или описание товарной позиции в свободной форме. |
Необязательно | itemDetails |
Object | Объект с параметрами описания товарной позиции. Описание вложенных элементов приведено ниже. |
Обязательно | quantity |
Object | Элемент, описывающий передается общее количество товарных позиций одного positionId и его единицы измерения. Описание вложенных элементов приведено ниже. |
Необязательно | itemAmount |
Integer [1..12] | Сумма стоимости всех товарных позиций одного positionId в минимальных единицах валюты. itemAmount обязателен к передаче, только если не был передан параметр itemPrice . В противном случае передача itemAmount не требуется. Если же в запросе передаются оба параметра: itemPrice и itemAmount , то itemAmount должен равняться itemPrice * quantity , в противном случае запрос завершится с ошибкой. |
Необязательно | itemPrice |
Integer [1..18] | Сумма стоимости товарной позиции одного positionId в деньгах в минимальных единицах валюты. |
Необязательно | itemCurrency |
Integer | Код валюты ISO 4217. Если не указан, считается равным валюте заказа. |
Обязательно | itemCode |
String [1..100] | Номер (идентификатор) товарной позиции в системе магазина. |
Описание параметров в объекте itemAttributes
:
Параметр itemAttributes
должен содержать массив attributes
, а уже в этом массиве расположены атрибуты товарной позиции (см. пример и таблицу ниже).
"itemAttributes":{"attributes":[{"name":"paymentMethod","value":"1"},{"name":"paymentObject","value":"1"}]}
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | paymentMethod |
Integer | Тип платежа, доступные значения:
|
Обязательно | |||
Условие | nomenclature |
String | Код товарной номенклатуры в шестнадцатеричном представлении с пробелами. Максимальная длина – 32 байта. Обязательно, если передано markQuantity . |
Необязательно | markQuantity |
Object | Дробное количество маркируемого товара. См. вложенные параметры. |
Необязательно | userData |
String [1..64] | Значение реквизита пользователя. Можно передавать только после согласования с ФНС. |
Необязательно | agent_info |
Object | Объект с данными о платежном агенте для товарной позиции. |
Условие* | agent_info.type |
Integer | Тип агента, доступные значения:
|
Необязательно | agent_info.paying |
Object | Объект с данными о платежном агенте. |
Необязательно | agent_info.paying.operation |
String [1..24] | Название транзакции платежного агента. |
Необязательно | agent_info.paying.phones |
Array of strings | Массив телефонных номеров платежного агента в формате +N. |
Необязательно | agent_info.paymentsOperator |
Object | Объект с информацией об операторе по приему платежей. |
Необязательно | agent_info.paymentsOperator.phones |
Array of strings | Массив телефонных номеров платежного агента в формате +N. |
Необязательно | agent_info.MTOperator |
Object | Объект с данными об Операторе перевода. |
Необязательно | agent_info.MTOperator.phones |
Array of strings | Массив телефонных номеров оператора перевода в формате +N. |
Необязательно | agent_info.MTOperator.name |
String [1..256] | Наименование оператора перевода. |
Необязательно | agent_info.MTOperator.address |
String [1..256] | Адрес оператора перевода. |
Необязательно | agent_info.MTOperator.inn |
String [10..12] | ИНН оператора перевода. |
Необязательно | supplier_info |
Object | Объект с данными о поставщике для товарной позиции. |
Необязательно | supplier_info.phones |
Array of strings | Массив телефонных номеров поставщика в формате +N. |
Необязательно | supplier_info.name |
String | Наименование поставщика. |
Необязательно | supplier_info.inn |
String | ИНН поставщика |
* Обязателен, если передается agent_info
.
Описание параметров объекта markQuantity
.
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | numerator |
String | Числитель дробной части объекта платежа. |
Обязательно | denominator |
String | Знаменатель дробной части объекта платежа. |
Описание параметров в объекте quantity
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | value |
String | Количество товарных позиций данного positionId . Для указания дробных чисел используйте десятичную точку. |
Обязательно | measure |
String [1..20] | Единица измерения количества по позиции. |
Возможные значения параметра measure
.
Значение | Описание |
---|---|
0 | Применяется к позициям, которые могут быть реализованы индивидуально или отдельными единицами, а также если объект платежа является предметом, подлежащим обязательной идентификационной маркировке. |
10 | Грамм |
11 | Килограмм |
12 | Тонна |
20 | Сантиметр |
21 | Дециметр |
22 | Метр |
30 | Квадратный сантиметр |
31 | Квадратный дециметр |
32 | Квадратный метр |
40 | Миллилитр |
41 | Литр |
42 | Кубический метр |
50 | Киловатт час |
51 | Гигакалория |
70 | День |
71 | Час |
72 | Минута |
73 | Секунда |
80 | Килобайт |
81 | Мегабайт |
82 | Гигабайт |
83 | Терабайт |
255 | Применяется к другим единицам измерения |
Описание параметров в объекте itemDetails
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | itemDetailsParams |
Object | Параметр, описывающий дополнительную информацию по товарной позиции. Описание вложенных элементов приведено ниже. |
Описание параметров в объекте itemDetailsParams
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | value |
String | Дополнительная информация по товарной позиции. |
Обязательно | name |
String [1..255] | Наименование параметра описания детализации товарной позиции |
Параметры ответа
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | errorCode |
Integer [1..2] | Информационный параметр в случае ошибки, который может иметь разные кодовые значения:
|
Необязательно | errorMessage |
String [1..512] | Информационный параметр, являющийся описанием ошибки в случае возникновения ошибки. Значение errorMessage может варьироваться, поэтому не следует явным образом ссылаться на его значения в коде. Язык описания задается в параметре language запроса. |
Примеры
Пример запроса
curl --request POST \
--url https://3dsec.berekebank.kz/payment/rest/refund.do \
--header 'content-type: application/x-www-form-urlencoded' \
--data userName=test_user \
--data password=test_user_password \
--data currency=978\
--data orderId=01491d0b-c848-7dd6-a20d-e96900a7d8c0 \
--data amount=2000 \
--data language=en
Пример ответа
{
"errorCode": 0,
"errorMessage":"Success"
}
Отмена заказа
Чтобы отменить еще не оплаченный заказ, используйте запрос https://3dsec.berekebank.kz/payment/rest/decline.do
. Отклонить можно только заказ, который не был завершен.
После успешного выполнения данного запроса заказ переходит в статус DECLINED
.
При выполнении запроса необходимо использовать заголовок:
Content-Type: application/x-www-form-urlencoded
Параметры запроса
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | userName |
String [1..100] | Логин учетной записи API продавца. |
Обязательно | password |
String [1..200] | Пароль учетной записи API продавца. |
Необязательно | merchantLogin |
String [1..255] | Чтобы зарегистрировать заказ от имени другого мерчанта, укажите его логин (для API-аккаунта) в этом параметре. Можно использовать, только если у вас есть разрешение на просмотр транзакций других продавцов или если указанный продавец является вашим дочерним продавцом. |
Необязательно | language |
String [2] | Ключ языка по ISO 639-1. Если язык не указан, используется язык по умолчанию, указанный в настройках магазина. Поддерживаемые языки: ru, en. |
Обязательно | orderId |
String [1..36] | Номер заказа в платежном шлюзе. Уникален в пределах платежного шлюза. |
Обязательно | orderNumber |
String [1..32] | Номер заказа (ID) в системе мерчанта; должен быть уникальным для каждого заказа. |
Параметры ответа
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | errorCode |
Integer [1..2] | Информационный параметр в случае ошибки, который может иметь разные кодовые значения:
|
Обязательно | errorMessage |
String [1..512] | Информационный параметр, являющийся описанием ошибки в случае возникновения ошибки. Значение errorMessage может варьироваться, поэтому не следует явным образом ссылаться на его значения в коде. Язык описания задается в параметре language запроса. |
Примеры
Пример запроса
curl --request POST \
--url https://3dsec.berekebank.kz/payment/rest/decline.do \
--header 'content-type: application/x-www-form-urlencoded' \
--data userName=test_user \
--data password=test_user_password \
--data orderId=8cf0409e-857e-7f95-8ab1-b6810009d884 \
--data orderNumber=12345678 \
--data merchantLogin=merch_test418 \
--data language=en
Пример ответа
{
"errorCode": 0,
"errorMessage":"Success"
}
Связки
Приведенные ниже запросы API позволяют управлять транзакциями по связкам. Транзакция по связке используется, когда держатель карты разрешает продавцу хранить платежные данные для дальнейших платежей. Узнайте больше о связках здесь.
Оплата по связке
Для оплаты заказа по связке используется запрос https://3dsec.berekebank.kz/payment/rest/paymentOrderBinding.do
.
При выполнении запроса необходимо использовать заголовок:
Content-Type: application/x-www-form-urlencoded
Параметры запроса
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | userName |
String [1..100] | Логин учетной записи API продавца. |
Обязательно | password |
String [1..200] | Пароль учетной записи API продавца. |
Обязательно | mdOrder |
String [1..36] | Номер заказа в платежном шлюзе. Уникален в пределах платежного шлюза. |
Обязательно | bindingId |
String [1..255] | Идентификатор уже существующей связки. (идентификатор карты, токенизированной шлюзом). Его можно использовать, только если у мерчанта есть разрешение на работу со связками. Если этот параметр передается в этом запросе, это означает, что:
|
Необязательно | language |
String [2] | Ключ языка по ISO 639-1. Если язык не указан, используется язык по умолчанию, указанный в настройках магазина. Поддерживаемые языки: ru, en. |
Необязательно | ip |
String [1..39] | IP адрес плательщика. IPv6 поддерживается во всех запросах (до 39 символов). |
Необязательно | cvc |
Integer | Этот параметр обязателен, если для мерчанта не выбрано разрешение Может проводить оплату без подтверждения CVC. |
Необязательно | threeDSSDK |
Boolean | Возможные значения: true или false Флаг, показывающий, что платеж поступает из 3DS SDK. |
Обязательно | tii |
String | Идентификатор инициатора транзакции. Параметр, указывающий, какой тип операции будет выполнять инициатор (Клиент или Мерчант). Возможные значения |
Условие | email |
String | Электронная почта для отображения на платежной странице. Если для продавца настроены уведомления клиента, электронную почту необходимо указать. Пример: client_mail@email.com . Для платежей по VISA с 3DS авторизацией необходимо указать либо электронную почту, либо номер телефона владельца карты. |
Необязательно | threeDSProtocolVersion |
String | Версия протокола 3DS. Возможные значения: "2.1.0", "2.2.0" для 3DS2. Если в запросе не передается threeDSProtocolVersion , то для авторизации 3D Secure будет использоваться значение по умолчанию (2.1.0 - для 3DS 2). |
Необязательно | externalScaExemptionIndicator |
String | Тип исключения SCA (Strong Customer Authentication). Если указан этот параметр, транзакция будет обработана в зависимости от ваших настроек в платежном шлюзе: либо будет выполнена принудительная операция SSL, либо банк-эмитент получит информацию об исключении SCA и примет решение о проведении операции с 3DS-аутентификацией или без нее (для получения подробной информации свяжитесь с нашей службой поддержки). Допустимые значения:
Для передачи этого параметра у вас должны быть достаточные права в платежном шлюзе. |
Условие | seToken |
String | Зашифрованные данные карты, которые заменяют параметры $PAN , $CVC и $EXPIRY (или YYYY ,MM ). Обязательно, если используется вместо данных карты. Обязательные параметры для строки seToken: timestamp , UUID , bindingId , MDORDER . Подробнее о генерации seToken см. здесь. |
Optional | clientBrowserInfo |
Object | Блок данных о браузере клиента, который отправляется на ACS во время 3DS аутентификации. Этот блок можно передавать, только если включена специальная настройка (обратитесь в команду поддержки). См. вложенные параметры. |
Необязательно | acsInIFrame |
Boolean | Флаг, показывающий, что для финишного URL будет возвращаться iFrame версия. Возможные значения true or false . Для подключения данной функциональности обратитесь в службу поддержки. |
Возможные значения tii
(Подробнее о типах связок, поддерживаемых платежным шлюзом, читайте здесь).
Значение tii
|
Описание | Тип транзакции | Инициатор транзакции | Данные карты для транзакции | Сохранение данных карты после транзакции | Примечание |
---|---|---|---|---|---|---|
Пусто | Обычный | Покупатель | Вводится покупателем | Нет | Транзакция электронной коммерции без сохранения связки. | |
CI | Инициирующий - Обычный (CIT) | Инициирующая | Покупатель | Вводится покупателем | Да | Транзакция электронной коммерции с сохранением связки. |
F | Внеплановый платеж (CIT) | Последующая | Покупатель | Клиент выбирает карту вместо ручного ввода | Нет | Транзакция электронной коммерции, использующая ранее сохраненную обычную связку. |
U | Внеплановый платеж (MIT) | Последующая | Продавец | Нет ручного ввода, продавец передает данные | Нет | Транзакция электронной коммерции, использующая ранее сохраненную обычную связку. |
RI | Инициирующий - Рекурентные (CIT) | Инициирующая | Покупатель | Вводится покупателем | Да | Транзакция электронной коммерции с сохранением связки. |
R | Рекуррентный платеж (MIT) | Последующая | Продавец | Нет ручного ввода, продавец передает данные | Нет | Рекуррентная операция, использующая сохраненную связку. |
II | Инициирующий - Рассрочка (CIT) | Инициирующая | Покупатель | Вводится покупателем | Да | Транзакция электронной коммерции с сохранением связки. |
I | Платеж по рассрочке (MIT) | Последующая | Продавец | Нет ручного ввода, продавец передает данные | Нет | Операция рассрочки, использующая сохраненную связку. |
Ниже приведены параметры блока clientBrowserInfo
(данные о браузере клиента).
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | userAgent | string | Агент браузера. |
Необязательно | OS | string | Операционная система. |
Необязательно | OSVersion | string | Версия операционной системы. |
Необязательно | browserAcceptHeader | string | Заголовок Accept, который сообщает серверу, какие форматы (или MIME-типы) поддерживает браузер. |
Необязательно | browserIpAddress | string | IP-адрес браузера. |
Необязательно | browserLanguage | string | Язык браузера. |
Необязательно | browserTimeZone | string | Часовой пояс браузера. |
Необязательно | browserTimeZoneOffset | integer | Смещение часового пояса в минутах между локальным временем пользователя и UTC. |
Необязательно | colorDepth | string | Глубина цвета экрана, в битах. |
Необязательно | fingerprint | string | Отпечаток браузера - уникальный цифровой идентификатор браузера. |
Необязательно | isMobile | Boolean | Возможные значения: true или false . Флаг, указывающий на то, что используется мобильное устройство. |
Необязательно | javaEnabled | Boolean | Возможные значения: true или false . Флаг, указывающий на то, что в браузере включена поддержка java. |
Необязательно | javascriptEnabled | Boolean | Возможные значения: true или false . Флаг, указывающий на то, что в браузере включена поддержка javascript. |
Необязательно | plugins | string | Список плагинов, используемых в браузере, через запятую. |
Необязательно | screenHeight | integer | Высота экрана в пикселях. |
Необязательно | screenWidth | integer | Ширина экрана в пикселях. |
Необязательно | screenPrint | string | Данные о параметрах печати браузера, включая разрешение, глубину цвета, плотность пикселей. |
Пример блока clientBrowserInfo
:
"clientBrowserInfo":
{
"userAgent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/111.0.0.0 Safari/537.36 Edg/111.0.1661.41",
"fingerprint":850891523,
"OS":"Windows",
"OSVersion":"10",
"isMobile":false,
"screenPrint":"Current Resolution: 1536x864, Available Resolution: 1536x824, Color Depth: 24, Device XDPI: undefined, Device YDPI: undefined",
"colorDepth":24,
"screenHeight":"864",
"screenWidth":"1536",
"plugins":"PDF Viewer, Chrome PDF Viewer, Chromium PDF Viewer, Microsoft Edge PDF Viewer, WebKit built-in PDF",
"javaEnabled":false,
"javascriptEnabled":true,
"browserLanguage":"it-IT",
"browserTimeZone":"Europe/Rome",
"browserTimeZoneOffset":-120,
"browserAcceptHeader":"gzip",
"browserIpAddress":"10.99.50.37"
}
Параметры ответа
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | errorCode |
Integer [1..2] | Информационный параметр в случае ошибки, который может иметь разные кодовые значения:
|
Необязательно | errorMessage |
String [1..512] | Информационный параметр, являющийся описанием ошибки в случае возникновения ошибки. Значение errorMessage может варьироваться, поэтому не следует явным образом ссылаться на его значения в коде. Язык описания задается в параметре language запроса. |
Необязательно | redirect |
String [1..512] | Этот параметр возвращается, если платеж прошел успешно и для платежа не проводилась проверка карты на вовлеченность в 3-D Secure. Продавцы могут использовать его, если хотят перенаправить пользователя на страницу платежного шлюза. Если продавец использует собственную страницу, это значение можно игнорировать. |
Необязательно | info |
String | В случае успешного ответа. Результат попытки оплаты. Ниже приведены возможные значения.
|
Необязательно | error |
String | Сообщение об ошибке (если в ответе вернулась ошибка) на языке, переданном в запросе. |
Необязательно | processingErrorType |
String | Тип ошибки процессинга. Передается, если ошибка возникает на стороне процессинга, а не в платежном шлюзе, при этом число попыток оплаты не превышено и еще не было перенаправления на финальную страницу. |
Необязательно | displayErrorMessage |
String | Отображаемое сообщение об ошибке. |
Необязательно* | errorTypeName |
String | Параметр, необходимый фронтенд странице для определения типа ошибки. Обязательно для неудачных платежей. |
Необязательно | acsUrl |
String [1..512] | При успешном ответе в случае оплаты 3D-Secure. URL-адрес для редиректа на ACS. Обязательный, если нужен редирект на ACS. Подробнее см. Редирект на ACS. |
Необязательно | paReq |
String [1..255] | При успешном ответе в случае оплаты 3D-Secure. PAReq (Payment Authentication Request) — сообщение, которое необходимо отправить в ACS вместе с редиректом. Это сообщение содержит данные в кодировке Base64, необходимые для аутентификации держателя карты. Подробнее см. Редирект на ACS. |
Необязательно | termUrl |
String [1..512] | При успешном ответе в случае оплаты 3D-Secure. Это URL-адрес, на который ACS перенаправляет владельца карты после аутентификации. Подробнее см. Редирект на ACS. |
Примеры
Пример запроса
curl --request POST \
--url https://3dsec.berekebank.kz/payment/rest/paymentOrderBinding.do \
--header 'content-type: application/x-www-form-urlencoded' \
--data userName=test_user \
--data password=test_user_password \
--data mdOrder=01491d0b-c848-7dd6-a20d-e96900a7d8c0 \
--data bindingId=01491394-63a6-7d45-a88f-7bce00a7d8c0 \
--data cvc=123 \
--data tii=F \
--data language=en
Пример успешного ответа для SSL-платежа (без 3-D Secure)
{
"redirect": "https://3dsec.berekebank.kz/payment/merchants/temp/finish.html?orderId=01491d0b-c848-7dd6-a20d-e96900a7d8c0&lang=en",
"info": "Your order is proceeded, redirecting...",
"errorCode": 0
}
Пример успешного ответа на для платежа 3D-Secure
{
"info": "Your order is proceeded, redirecting...",
"errorCode": 0,
"acsUrl": "https://theacsserver.com/acs/auth/start.do",
"paReq": "eJxVUu9vgjAQ/...4BaHYvAI=",
"termUrl": "https://3dsec.berekebank.kz/payment/rest/finish3ds.do?lang=en"
}
Пример ответа с ошибкой
{
"error": "[clientId] is empty",
"errorCode": 5,
"is3DSVer2": false,
"errorMessage": "[clientId] is empty"
}
Получение связок
Для получения списка клиентских привязок используется запрос https://3dsec.berekebank.kz/payment/rest/getBindings.do
.
При выполнении запроса необходимо использовать заголовок:
Content-Type: application/x-www-form-urlencoded
Параметры запроса
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | clientId |
String [0..255] | Номер клиента (ID) в системе мерчанта — до 255 символов. Используется для реализации функциональности связок. Может возвращаться в ответе, если мерчанту разрешено создавать связки. Указание этого параметра при обработке платежей по связке обязательно. В противном случае платеж будет невозможен. |
Необязательно | language |
String [2] | Ключ языка по ISO 639-1. Если язык не указан, используется язык по умолчанию, указанный в настройках магазина. Поддерживаемые языки: ru, en. |
Обязательно | userName |
String [1..100] | Логин учетной записи API продавца. Если для аутентификации при регистрации вместо логина и пароля используется открытый токен (параметр token ), пароль передавать не нужно. |
Обязательно | password |
String [1..200] | Пароль учетной записи API продавца. Если для аутентификации при регистрации вместо логина и пароля используется открытый токен (параметр token ), пароль передавать не нужно. |
Необязательно | bindingId |
String [1..255] | Идентификатор уже существующей связки. (идентификатор карты, токенизированной шлюзом). Его можно использовать, только если у мерчанта есть разрешение на работу со связками. Если этот параметр передается в этом запросе, это означает, что:
|
Необязательно | bindingType |
String | Тип связки, который ожидается в ответе (если он не указан, возвращаются все типы). Возможные значения:
|
Необязательно | showExpired |
Boolean |
true /false параметр, определяющий, показывать ли связки с просроченными картами. Значение по умолчанию: false . |
Необязательно | merchantLogin |
String [1..255] | Чтобы получить список сохраненных клиентом учетных данных другого мерчанта, укажите в этом параметре логин мерчанта (для API-аккаунта). Можно использовать, только если у вас есть разрешение на просмотр транзакций других продавцов или если указанный продавец является вашим дочерним продавцом. И вы, и указанный продавец должны иметь разрешение на работу с сохраненными учетными данными (связками). |
Параметры ответа
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | errorCode |
Integer [1..2] | Информационный параметр в случае ошибки, который может иметь разные кодовые значения:
|
Необязательно | errorMessage |
String [1..512] | Информационный параметр, являющийся описанием ошибки в случае возникновения ошибки. Значение errorMessage может варьироваться, поэтому не следует явным образом ссылаться на его значения в коде. Язык описания задается в параметре language запроса. |
Необязательно | bindings |
Object | Элемент с блоками, содержащими параметры связок. См. описание ниже. |
Элемент bindings
содержит следующие параметры.
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | maskedPan |
String [1..19] | Маскированный номер карты, использованной для платежа. Указывается только после оплаты заказа. |
Необязательно | paymentWay |
String | Способ совершения платежа (платеж с вводом карточных данных, оплата по связке и т.п.). Дополнительные возможные значения параметра приведены ниже |
Обязательно | bindingId |
String [1..255] | Идентификатор уже существующей связки. (идентификатор карты, токенизированной шлюзом). Его можно использовать, только если у мерчанта есть разрешение на работу со связками. Если этот параметр передается в этом запросе, это означает, что:
|
Обязательно | expiryDate |
Integer | Срок действия карты в следующем формате: .YYYYMM Указывается только после оплаты заказа. |
Необязательно | bindingCategory |
String | Назначение связки, ожидаемой в ответе. Возможные значения: COMMON, INSTALLMENT, RECURRENT. |
Необязательно | clientId |
String [0..255] | Номер клиента (ID) в системе мерчанта — до 255 символов. Используется для реализации функциональности связок. Может возвращаться в ответе, если мерчанту разрешено создавать связки. Указание этого параметра при обработке платежей по связке обязательно. В противном случае платеж будет невозможен. |
Необязательно | displayLabel |
Integer [1..16] | Последние 4 цифры исходного PAN перед токенизацией. |
Необязательно | paymentSystem |
String | Наименование платежной системы. Возможны следующие значения:
|
Примеры
Пример запроса
curl --request POST \
--url https://3dsec.berekebank.kz/payment/rest/getBindings.do \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data userName=test_user \
--data password=test_user_password \
--data clientId=dos-clientos \
--data bindingType=C
Пример успешного запроса
{
"errorCode":"0",
"errorMessage":"Success",
"bindings": [
{
"bindingId":"69d6a793-afb5-79be-8ce7-63ff00a8656a",
"maskedPan":"400000**1118",
"expiryDate":"203012",
"paymentWay":"CARD",
"displayLabel":"XXXXXXXXXXXX1118"
}
]
}
Получение связок по номеру карты
Для получения списка всех связок банковской карты используется запрос https://3dsec.berekebank.kz/payment/rest/getBindingsByCardOrId.do
.
При выполнении запроса необходимо использовать заголовок:
Content-Type: application/x-www-form-urlencoded
Параметры запроса
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | userName |
String [1..100] | Логин учетной записи API продавца. |
Обязательно | password |
String [1..200] | Пароль учетной записи API продавца. |
Условие | pan |
String [1..19] | Номер платежной карты (обязательно, если если bindinId не передается). Значение pan заменяет собой значение bindingId . |
Условие | bindingId |
String [1..255] | Идентификатор уже существующей связки. (идентификатор карты, токенизированной шлюзом). Его можно использовать, только если у мерчанта есть разрешение на работу со связками. Если этот параметр передается в этом запросе, это означает, что:
|
Необязательно | showExpired |
Boolean |
true /false параметр, определяющий, показывать ли связки с просроченными картами. Значение по умолчанию: false . |
Параметры ответа
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | errorCode |
Integer [1..2] | Информационный параметр в случае ошибки, который может иметь разные кодовые значения:
|
Необязательно | errorMessage |
String [1..512] | Информационный параметр, являющийся описанием ошибки в случае возникновения ошибки. Значение errorMessage может варьироваться, поэтому не следует явным образом ссылаться на его значения в коде. Язык описания задается в параметре language запроса. |
Необязательно | bindings |
Object | Элемент с блоками, содержащими параметры связок: bindingId , maskedPan , expiryDate , clientId
|
Необязательно | bindingId |
String [1..255] | Идентификатор уже существующей связки. (идентификатор карты, токенизированной шлюзом). Его можно использовать, только если у мерчанта есть разрешение на работу со связками. Если этот параметр передается в этом запросе, это означает, что:
|
Необязательно | maskedPan |
String [1..19] | Маскированный номер карты, использованной для платежа. Указывается только после оплаты заказа. |
Необязательно | expiryDate |
Integer | Срок действия карты в следующем формате: .YYYYMM Указывается только после оплаты заказа. |
Необязательно | clientId |
String [0..255] | Номер клиента (ID) в системе мерчанта — до 255 символов. Используется для реализации функциональности связок. Может возвращаться в ответе, если мерчанту разрешено создавать связки. Указание этого параметра при обработке платежей по связке обязательно. В противном случае платеж будет невозможен. |
Примеры
Пример запроса
curl --request POST \
--url https://3dsec.berekebank.kz/payment/rest/getBindingsByCardOrId.do \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data userName=test_user \
--data password=test_user_password \
--data pan=4000001111111118
Пример успешного запроса
{
"errorCode":"0",
"errorMessage":"Success",
"bindings": [
{
"bindingId":"69d6a793-afb5-79be-8ce7-63ff00a8656a",
"maskedPan":"400000**1118",
"expiryDate":"203012",
"clientId":"12"
}
{
"bindingId":"6a8c0738-cc88-4200-acf6-afc264d66cb0",
"maskedPan":"400000**1118",
"expiryDate":"203012",
"clientId":"13"
}
]
}
Деактивация связки
Для деактивации существующей связки используется запрос https://3dsec.berekebank.kz/payment/rest/unBindCard.do
.
При выполнении запроса необходимо использовать заголовок:
Content-Type: application/x-www-form-urlencoded
Параметры запроса
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | userName |
String [1..100] | Логин учетной записи API продавца. |
Обязательно | password |
String [1..200] | Пароль учетной записи API продавца. |
Обязательно | bindingId |
String [1..255] | Идентификатор уже существующей связки. (идентификатор карты, токенизированной шлюзом). Его можно использовать, только если у мерчанта есть разрешение на работу со связками. Если этот параметр передается в этом запросе, это означает, что:
|
Параметры ответа
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | errorCode |
Integer [1..2] | Информационный параметр в случае ошибки, который может иметь разные кодовые значения:
|
Необязательно | errorMessage |
String [1..512] | Информационный параметр, являющийся описанием ошибки в случае возникновения ошибки. Значение errorMessage может варьироваться, поэтому не следует явным образом ссылаться на его значения в коде. Язык описания задается в параметре language запроса. |
Примеры
Пример запроса
curl --request POST \
--url https://3dsec.berekebank.kz/payment/rest/unBindCard.do \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data userName=test_user \
--data password=test_user_password \
--data bindingId=fd3afc57-c6d0-4e08-aaef-1b7cfeb093dc
Пример ответа (ошибка)
{
"errorCode":"2",
"errorMessage":"Связка не активна",
}
Активация связки
Запрос, используемый для активации существующей связки, которая была деактивирована, называется https://3dsec.berekebank.kz/payment/rest/bindCard.do
.
При выполнении запроса необходимо использовать заголовок:
Content-Type: application/x-www-form-urlencoded
Параметры запроса
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | userName |
String [1..100] | Логин учетной записи API продавца. |
Обязательно | password |
String [1..200] | Пароль учетной записи API продавца. |
Обязательно | bindingId |
String [1..255] | Идентификатор уже существующей связки. (идентификатор карты, токенизированной шлюзом). Его можно использовать, только если у мерчанта есть разрешение на работу со связками. Если этот параметр передается в этом запросе, это означает, что:
|
Параметры ответа
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | errorCode |
Integer [1..2] | Информационный параметр в случае ошибки, который может иметь разные кодовые значения:
|
Необязательно | errorMessage |
String [1..512] | Информационный параметр, являющийся описанием ошибки в случае возникновения ошибки. Значение errorMessage может варьироваться, поэтому не следует явным образом ссылаться на его значения в коде. Язык описания задается в параметре language запроса. |
Примеры
Пример запроса
curl --request POST \
--url https://3dsec.berekebank.kz/payment/rest/bindCard.do \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data userName=test_user \
--data password=test_user_password \
--data bindingId=fd3afc57-c6d0-4e08-aaef-1b7cfeb093dc
Пример ответа (ошибка)
{
"errorCode":"2",
"errorMessage":"Binging is active",
}
Продление срока действия связки
Запрос, используемый для продления срока действия существующей привязки, называется https://3dsec.berekebank.kz/payment/rest/extendBinding.do
.
При выполнении запроса необходимо использовать заголовок:
Content-Type: application/x-www-form-urlencoded
Параметры запроса
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | userName |
String [1..100] | Логин учетной записи API продавца. |
Обязательно | password |
String [1..200] | Пароль учетной записи API продавца. |
Обязательно | bindingId |
String [1..255] | Идентификатор уже существующей связки. (идентификатор карты, токенизированной шлюзом). Его можно использовать, только если у мерчанта есть разрешение на работу со связками. Если этот параметр передается в этом запросе, это означает, что:
|
Обязательно | newExpiry |
Integer | Новая дата (год и месяц) окончания срока действия в формате YYYYMM . |
Обязательно | language |
String [2] | Ключ языка по ISO 639-1. Если язык не указан, используется язык по умолчанию, указанный в настройках магазина. Поддерживаемые языки: ru, en. |
Параметры ответа
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | errorCode |
Integer [1..2] | Информационный параметр в случае ошибки, который может иметь разные кодовые значения:
|
Необязательно | errorMessage |
String [1..512] | Информационный параметр, являющийся описанием ошибки в случае возникновения ошибки. Значение errorMessage может варьироваться, поэтому не следует явным образом ссылаться на его значения в коде. Язык описания задается в параметре language запроса. |
Примеры
Пример запроса
curl --request POST \
--url https://3dsec.berekebank.kz/payment/rest/extendBinding.do \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data userName=test_user \
--data password=test_user_password \
--data bindingId=fd3afc57-c6d0-4e08-aaef-1b7cfeb093dc
--data newExpiry=202212
--data language=en
Пример ответа
{
"errorCode":"0",
"errorMessage":"Success",
}
Рекуррентный платеж
Для проведения рекуррентного платежа используется запрос https://3dsec.berekebank.kz/payment/recurrentPayment.do
. Запрос используется для регистрации и оплаты заказа.
При выполнении запроса необходимо использовать заголовок:
Content-Type: application/json
Параметры запроса
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | userName |
String [1..100] | Логин учетной записи API продавца. |
Обязательно | password |
String [1..200] | Пароль учетной записи API продавца. |
Обязательно | orderNumber |
String [1..32] | Номер заказа (ID) в системе мерчанта; должен быть уникальным для каждого заказа. |
Необязательно | language |
String [2] | Ключ языка по ISO 639-1. Если язык не указан, используется язык по умолчанию, указанный в настройках магазина. Поддерживаемые языки: ru, en. |
Необязательно | feeInput |
String | Размер комиссии в минимальных единицах валюты. Функциональность должна быть включена на уровне продавца в шлюзе. |
Обязательно | bindingId |
String [1..255] | Идентификатор уже существующей связки. (идентификатор карты, токенизированной шлюзом). Его можно использовать, только если у мерчанта есть разрешение на работу со связками. Если этот параметр передается в этом запросе, это означает, что:
|
Обязательно | amount |
Integer [0..12] | Сумма платежа в минимальных единицах валюты (например, в копейках). |
Необязательно | currency |
Integer [3] | Код валюты платежа ISO 4217. Если не указано, то используется значение по умолчанию. |
Необязательно | description |
String [1..598] | Описание заказа в любом формате. Чтобы включить отправку этого поля в процессинговую систему, обратитесь в службу технической поддержки. В этом поле недопустимо передавать персональные данные или платежные данные (номера карт т.п.). Данное требование связано с тем, что описание заказа нигде не маскируется. |
Необязательно | additionalParameters |
Object | Дополнительные параметры заказа, которые хранятся в личном кабинете продавца для последующего просмотра. Каждая новая пара имени параметра и его значения должна быть разделена запятой. Ниже приведен пример использования.{ "firstParamName": "firstParamValue", "secondParamName": "secondParamValue"}
|
Необязательно | billingPayerData |
Object | Блок с регистрационными данными клиента (адрес, почтовый индекс), необходимый для прохождения проверки адреса в рамках сервисов AVS/AVV. Обязательно, если функция включена для продавца на стороне Платежного шлюза. См вложенные параметры. |
Необязательно | shippingPayerData |
Object | Объект, содержащий данные о доставке клиенту. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. См. вложенные параметры. |
Необязательно | preOrderPayerData |
Object | Объект, содержащий данные предварительного заказа. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. См. вложенные параметры. |
Необязательно | orderPayerData |
Object | Объект, содержащий данные о плательщике заказа. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. См. вложенные параметры. |
Необязательно | billingAndShippingAddressMatchIndicator |
A1 | Индикатор соответствия платежного адреса владельца карты и адреса доставки. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. Возможные значения:
|
Ниже приведены параметры блока billingPayerData
(данные об адресе регистрации клиента).
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | billingCity |
String [0..50] | Город, зарегистрированный по конкретной карте у Банка Эмитента. |
Необязательно | billingCountry |
String [0..50] | Страна, зарегистрированная по конкретной карте банка-эмитента (ISO 3166-1, числовой). |
Необязательно | billingAddressLine1 |
String [0..50] | Адрес, зарегистрированный по конкретной карте у Банка Эмитента. Строка 1. Обязательно к передаче для AVS-проверки. |
Необязательно | billingAddressLine2 |
String [0..50] | Адрес, зарегистрированный по конкретной карте у Банка Эмитента. Строка 2. |
Необязательно | billingAddressLine3 |
String [0..50] | Адрес, зарегистрированный по конкретной карте у Банка Эмитента. Строка 3. |
Необязательно | billingPostalCode |
String [0..9] | Почтовый индекс, зарегистрированный по конкретной карте у Банка Эмитента. Обязательно к передаче для AVS-проверки. |
Необязательно | billingState |
String [0..50] | Штат, зарегистрированный по конкретной карте у Банка Эмитента. |
Описание параметров объекта shippingPayerData
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | shippingCity |
ANS...50 | Город заказчика (из адреса доставки) |
Необязательно | shippingCountry |
ANS...50 | Страна заказчика |
Необязательно | shippingAddressLine1 |
ANS...50 | Основной адрес клиента (из адреса доставки) |
Необязательно | shippingAddressLine2 |
ANS...50 | Основной адрес клиента (из адреса доставки) |
Необязательно | shippingAddressLine3 |
ANS...50 | Основной адрес клиента (из адреса доставки) |
Необязательно | shippingPostalCode |
ANS...16 | Почтовый индекс клиента для доставки |
Необязательно | shippingState |
ANS...50 | Штат/регион покупателя (из адреса доставки) |
Необязательно | shippingMethodIndicator |
N2 | Индикатор способа доставки. Возможные значения:
|
Необязательно | deliveryTimeframe |
N2 | Срок поставки товара. Возможные значения:
|
Необязательно | deliveryEmail |
ANS...254 | Целевой адрес электронной почты для доставки цифрового распространения. Предпочтительно передавать электронную почту в самостоятельном параметре запроса email (но если вы передадите его в этом блоке, к нему применятся те же правила). |
Описание параметров объекта preOrderPayerData
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | preOrderDate |
ANS8 | Ожидаемая дата доставки (для предзаказанных покупок) в формате ГГГГММДД. |
Необязательно | preOrderPurchaseInd |
N2 | Индикатор размещения клиентом заказа на доступную или будущую доставку. Возможные значения:
|
Необязательно | reorderItemsInd |
N2 | Индикатор того, что клиент перебронирует ранее оплаченную доставку в составе нового заказа. Возможные значения:
|
Описание параметров объекта orderPayerData
.
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | homePhone |
ANS...19 | Домашний телефон владельца карты. Необходимо всегда указывать код страны, но знак + или 00 в начале можно указать или опустить. Номер должен иметь длину от 7 до 15 цифр. Таким образом, возможны следующие значения:
|
Необязательно | workPhone |
ANS...19 | Рабочий телефон владельца карты. Необходимо всегда указывать код страны, но знак + или 00 в начале можно указать или опустить. Номер должен иметь длину от 7 до 15 цифр. Таким образом, возможны следующие значения:
|
Необязательно | mobilePhone |
ANS...19 | Номер мобильного телефона владельца карты. Необходимо всегда указывать код страны, но знак + или 00 в начале можно указать или опустить. Номер должен иметь длину от 7 до 15 цифр. Таким образом, возможны следующие значения:
Для платежей по VISA с 3DS авторизацией необходимо указать либо электронную почту, либо номер телефона владельца карты. Если у вас настроено отображение номера телефона на платежной странице и вы указали неверный номер телефона, клиент сможет исправить его на платежной странице. |
Параметры ответа
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | success |
Boolean | Основной параметр, который указывает на то, что запрос прошел успешно. Доступны следующие значения:
Обратите внимание, что значение true означает, что запрос был обработан, а не что заказ был оплачен.Более подробная информация о том, как узнать, был ли платеж успешным или нет, доступна здесь. |
Условие | data |
N/A | Этот параметр возвращается только в случае успешной обработки платежа. См. описание ниже. |
Условие | error |
N/A | Этот параметр возвращается только в случае ошибки платежа. См. описание ниже. |
Блок data
содержит следующие элементы.
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | orderId |
String [1..36] | Номер заказа в платежном шлюзе. Уникален в пределах платежного шлюза. |
Блок error
содержит следующие элементы.
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | code |
Integer [1..3] | Код как информационный параметр, сообщающий об ошибке. |
Обязательно | description |
String [1..598] | Подробное техническое объяснение ошибки - содержимое этого параметра не предназначено для отображения пользователю. |
Обязательно | message |
String [1..512] | Информационный параметр, являющийся описанием ошибки для отображения пользователю. Параметр может варьироваться, поэтому не следует явным образом ссылаться на его значения в коде. |
Примеры
Пример запроса
curl --request POST \
--url https://3dsec.berekebank.kz/payment/recurrentPayment.do \
--header 'Content-Type: application/json' \
--data-raw '{
"userName" : "test_user",
"password" : "test_user_password",
"orderNumber" : "UAF-203974-DE-12",
"language" : "EN",
"bindingId": "bindingId",
"amount" : 1200,
"currency" : "398",
"description" : "Test description",
"additionalParameters" : {
"firstParamName" : "firstParamValue",
"secondParamName" : "secondParamValue"
"email" : "email@email.com"
}
}'
Пример ответа - Успешно
{
"success": true,
"data": {
"orderId": "f7beebe4-7c9a-43cf-8e26-67ab741f9b9e"
},
"orderStatus": {
"errorCode": "0",
"orderNumber": "UAF-203974-DE-12",
"orderStatus": 2,
"actionCode": 0,
"actionCodeDescription": "",
"amount": 12300,
"currency": "398",
"date": 1491333938243,
"orderDescription": "Test description",
"merchantOrderParams": [
{
"name": "firstParamName",
"value": "firstParamValue"
},
{
"name": "secondParamName",
"value": "secondParamValue"
}
],
"attributes": [],
"cardAuthInfo": {
"expiration": "203012",
"cardholderName": "TEST CARDHOLDER",
"approvalCode": "12345678",
"paymentSystem": "VISA",
"pan": "6777770000**0006"
},
"authDateTime": 1491333939454,
"terminalId": "11111",
"authRefNum": "111111111111",
"paymentAmountInfo": {
"paymentState": "DEPOSITED",
"approvedAmount": 12300,
"depositedAmount": 12300,
"refundedAmount": 0
},
"bankInfo": {
"bankCountryName": "<unknown>"
},
"chargeback": false,
"operations": [
{
"amount": 12300,
"cardHolder": "TEST CARDHOLDER",
"authCode": "123456"
}
]
}
}
Ошибка
{
"error": {
"code": "10",
"description": "Order with this number is already registered in the system.",
"message": "Order with this number is already registered in the system."
},
"success": false
}
Платеж по рассрочке
Для проведения платежа по рассрочке используется запрос https://3dsec.berekebank.kz/payment/installmentPayment.do
.
При выполнении запроса необходимо использовать заголовок:
Content-Type: application/json
Параметры запроса
Обязательность | Название | Тип | Описание |
---|---|---|---|
Условие | userName |
String [1..100] | Логин учетной записи API продавца. Если для аутентификации при регистрации вместо логина и пароля используется открытый токен (параметр token ), пароль передавать не нужно. |
Условие | password |
String [1..200] | Пароль учетной записи API продавца. Если для аутентификации при регистрации вместо логина и пароля используется открытый токен (параметр token ), пароль передавать не нужно. |
Обязательно | orderNumber |
String [1..32] | Номер заказа (ID) в системе мерчанта; должен быть уникальным для каждого заказа. |
Необязательно | language |
String [2] | Ключ языка по ISO 639-1. Если язык не указан, используется язык по умолчанию, указанный в настройках магазина. Поддерживаемые языки: ru, en. |
Обязательно | bindingId |
String [1..255] | Идентификатор уже существующей связки. (идентификатор карты, токенизированной шлюзом). Его можно использовать, только если у мерчанта есть разрешение на работу со связками. Если этот параметр передается в этом запросе, это означает, что:
|
Обязательно | amount |
Integer [0..12] | Сумма платежа в минимальных единицах валюты (например, в копейках). |
Необязательно | currency |
Integer [3] | Код валюты платежа ISO 4217. Если не указано, то используется значение по умолчанию. |
Необязательно | description |
String [1..598] | Описание заказа в любом формате. Чтобы включить отправку этого поля в процессинговую систему, обратитесь в службу технической поддержки. В этом поле недопустимо передавать персональные данные или платежные данные (номера карт т.п.). Данное требование связано с тем, что описание заказа нигде не маскируется. |
Необязательно | additionalParameters |
Object | Дополнительные параметры заказа, которые хранятся в личном кабинете продавца для последующего просмотра. Каждая новая пара имени параметра и его значения должна быть разделена запятой. Ниже приведен пример использования.{ "firstParamName": "firstParamValue", "secondParamName": "secondParamValue"}
|
Обязательно | preAuth |
Boolean | Параметр, определяющий необходимость предварительной авторизации (блокирования средств на счете клиента до их списания). Доступны следующие значения:
|
Условие | token |
String [1..256] | Значение, используемое для аутентификации продавца при отправке запросов платежному шлюзу. Если вы передаете этот параметр, то не передавайте userName и password . |
Необязательно | billingPayerData |
Object | Блок с регистрационными данными клиента (адрес, почтовый индекс), необходимый для прохождения проверки адреса в рамках сервисов AVS/AVV. Обязательно, если функция включена для продавца на стороне Платежного шлюза. См. вложенные параметры. |
Необязательно | shippingPayerData |
Object | Объект, содержащий данные о доставке клиенту. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. См. вложенные параметры. |
Необязательно | preOrderPayerData |
Object | Объект, содержащий данные предварительного заказа. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. См. вложенные параметры. |
Необязательно | orderPayerData |
Object | Объект, содержащий данные о плательщике заказа. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. См. вложенные параметры. |
Необязательно | billingAndShippingAddressMatchIndicator |
A1 | Индикатор соответствия платежного адреса владельца карты и адреса доставки. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. Возможные значения:
|
Ниже приведены параметры блока billingPayerData
(данные об адресе регистрации клиента).
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | billingCity |
String [0..50] | Город, зарегистрированный по конкретной карте у Банка Эмитента. |
Необязательно | billingCountry |
String [0..50] | Страна, зарегистрированная по конкретной карте банка-эмитента (ISO 3166-1, числовой). |
Необязательно | billingAddressLine1 |
String [0..50] | Адрес, зарегистрированный по конкретной карте у Банка Эмитента. Строка 1. Обязательно к передаче для AVS-проверки. |
Необязательно | billingAddressLine2 |
String [0..50] | Адрес, зарегистрированный по конкретной карте у Банка Эмитента. Строка 2. |
Необязательно | billingAddressLine3 |
String [0..50] | Адрес, зарегистрированный по конкретной карте у Банка Эмитента. Строка 3. |
Необязательно | billingPostalCode |
String [0..9] | Почтовый индекс, зарегистрированный по конкретной карте у Банка Эмитента. Обязательно к передаче для AVS-проверки. |
Необязательно | billingState |
String [0..50] | Штат, зарегистрированный по конкретной карте у Банка Эмитента. |
Описание параметров объекта shippingPayerData
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | shippingCity |
ANS...50 | Город заказчика (из адреса доставки) |
Необязательно | shippingCountry |
ANS...50 | Страна заказчика |
Необязательно | shippingAddressLine1 |
ANS...50 | Основной адрес клиента (из адреса доставки) |
Необязательно | shippingAddressLine2 |
ANS...50 | Основной адрес клиента (из адреса доставки) |
Необязательно | shippingAddressLine3 |
ANS...50 | Основной адрес клиента (из адреса доставки) |
Необязательно | shippingPostalCode |
ANS...16 | Почтовый индекс клиента для доставки |
Необязательно | shippingState |
ANS...50 | Штат/регион покупателя (из адреса доставки) |
Необязательно | shippingMethodIndicator |
N2 | Индикатор способа доставки. Возможные значения:
|
Необязательно | deliveryTimeframe |
N2 | Срок поставки товара. Возможные значения:
|
Необязательно | deliveryEmail |
ANS...254 | Целевой адрес электронной почты для доставки цифрового распространения. Предпочтительно передавать электронную почту в самостоятельном параметре запроса email (но если вы передадите его в этом блоке, к нему применятся те же правила). |
Описание параметров объекта preOrderPayerData
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | preOrderDate |
ANS8 | Ожидаемая дата доставки (для предзаказанных покупок) в формате ГГГГММДД. |
Необязательно | preOrderPurchaseInd |
N2 | Индикатор размещения клиентом заказа на доступную или будущую доставку. Возможные значения:
|
Необязательно | reorderItemsInd |
N2 | Индикатор того, что клиент перебронирует ранее оплаченную доставку в составе нового заказа. Возможные значения:
|
Описание параметров объекта orderPayerData
.
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | homePhone |
ANS...19 | Домашний телефон владельца карты. Необходимо всегда указывать код страны, но знак + или 00 в начале можно указать или опустить. Номер должен иметь длину от 7 до 15 цифр. Таким образом, возможны следующие значения:
|
Необязательно | workPhone |
ANS...19 | Рабочий телефон владельца карты. Необходимо всегда указывать код страны, но знак + или 00 в начале можно указать или опустить. Номер должен иметь длину от 7 до 15 цифр. Таким образом, возможны следующие значения:
|
Необязательно | mobilePhone |
ANS...19 | Номер мобильного телефона владельца карты. Необходимо всегда указывать код страны, но знак + или 00 в начале можно указать или опустить. Номер должен иметь длину от 7 до 15 цифр. Таким образом, возможны следующие значения:
Для платежей по VISA с 3DS авторизацией необходимо указать либо электронную почту, либо номер телефона владельца карты. Если у вас настроено отображение номера телефона на платежной странице и вы указали неверный номер телефона, клиент сможет исправить его на платежной странице. |
Параметры ответа
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | orderId |
String [1..36] | Номер заказа в платежном шлюзе. Уникален в пределах платежного шлюза. |
Обязательно | errorCode |
Integer [1..2] | Информационный параметр в случае ошибки, который может иметь разные кодовые значения:
|
Обязательно | errorMessage |
String [1..512] | Информационный параметр, являющийся описанием ошибки в случае возникновения ошибки. Значение errorMessage может варьироваться, поэтому не следует явным образом ссылаться на его значения в коде. Язык описания задается в параметре language запроса. |
Условие | orderStatus |
Object | Содержит параметры статуса заказа и возвращается только в том случае, если платежный шлюз распознал все параметры запроса как правильные. См. описание ниже. |
Блок orderStatus
содержит следующие элементы.
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | errorCode |
Integer [1..2] | Информационный параметр в случае ошибки, который может иметь разные кодовые значения:
|
Необязательно | errorMessage |
String [1..512] | Информационный параметр, являющийся описанием ошибки в случае возникновения ошибки. Значение errorMessage может варьироваться, поэтому не следует явным образом ссылаться на его значения в коде. Язык описания задается в параметре language запроса. |
Необязательно | orderNumber |
String [1..32] | Номер заказа (ID) в системе мерчанта; должен быть уникальным для каждого заказа. |
Необязательно | orderStatus |
Integer | Значение этого параметра указывает статус заказа в платежном шлюзе. Отсутствует, если заказ не был найден. Ниже приведен список доступных значений:
|
Необязательно | actionCode |
Integer | Код ответа от процессинга банка. См. список кодов ответа здесь. |
Необязательно | actionCodeDescription |
String [1..512] | Описание actionCode , возвращаемое процессингом банка. |
Необязательно | amount |
Integer [0..12] | Сумма платежа в минимальных единицах валюты (например, в копейках). |
Необязательно | currency |
Integer [3] | Код валюты платежа ISO 4217. Если не указано, то используется значение по умолчанию. |
Необязательно | date |
String | Дата регистрации заказа (Unix) |
Необязательно | ip |
String [1..39] | IP адрес плательщика. IPv6 поддерживается во всех запросах (до 39 символов). |
Необязательно | chargeback |
Boolean | Были ли средства принудительно возвращены покупателю банком. Возможные значения: true , false . |
Необязательно | merchantOrderParams |
N/A | Раздел с атрибутами, в котором передаются дополнительные параметры мерчанта. См. описание ниже. |
Необязательно | attributes |
Object | Атрибуты заказа в платежной системе (номер заказа). См. описание ниже. |
Необязательно | cardAuthInfo |
Object | Информация о платежной карте покупателя. См. описание ниже. |
Необязательно | authDateTime |
String | Дата и время авторизации, показанные как количество миллисекунд, прошедших с 00:00 GMT 1 января 1970 года (время Unix). |
Необязательно | terminalId |
String [1..10] | Идентификатор терминала в системе, обрабатывающей платеж. |
Необязательно | authRefNum |
String [1..24] | Номер авторизации платежа, присвоенный ему при регистрации платежа. |
Необязательно | paymentAmountInfo |
Object | Параметр, содержащий вложенные параметры с информацией о суммах подтверждения, списания и возврата. См. описание ниже. |
Необязательно | bankInfo |
Object | Содержит вложенный параметр bankCountryName . См. описание ниже. |
Необязательно | bindingInfo |
Object | Объект, содержащий информацию о связке, по которой осуществляется платеж. См. описание ниже. |
Необязательно | operations |
Object | Объект, содержащий информацию об операциях. См. описание ниже. |
Блок merchantOrderParams
содержит следующие элементы.
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | name |
String [1..255] | Название дополнительного параметра мерчанта. |
Обязательно | value |
String | Значение дополнительного параметра продавца - до 1024 символов. |
Блок attributes
содержит следующие элементы.
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | name |
String [1..255] | Название дополнительного параметра. |
Обязательно | value |
Alphanumeric | Значение дополнительного параметра - до 1024 символов. |
Блок cardAuthInfo
содержит следующие элементы.
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | expiration |
Integer | Срок действия карты в следующем формате: .YYYYMM Указывается только после оплаты заказа. |
Обязательно | cardholdername |
String [1..26] | Имя держателя карты латинскими буквами. Этот параметр передается только после оплаты заказа. |
Обязательно | approvalCode |
String [6] | Код авторизации МПС. Это поле имеет фиксированную длину (шесть символов) и может содержать цифры и латинские буквы. |
Обязательно | pan |
String [1..19] | Маскированный DPAN: номер, привязанный к мобильному устройству покупателя и выполняющий функции номера платежной карты в системе Apple Pay. |
Обязательно | maskedPan |
String [1..19] | Маскированный номер карты, использованной для платежа. Указывается только после оплаты заказа. |
Обязательно | paymentSystem |
String | Наименование платежной системы. Возможны следующие значения:
|
Блок paymentAmountInfo
содержит следующие элементы.
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | paymentState |
String | Состояние заказа, параметр может принимать следующие значения:
|
Обязательно | approvedAmount |
Integer [0..12] | Сумма в минимальных единицах валюты (например, в центах), которая была заблокирована на счете покупателя. Используется только в двухстадийных платежах. |
Обязательно | depositedAmount |
Integer [1..12] | Сумма списания в минимальных единицах валюты (например, в копейках). |
Обязательно | refundedAmount |
Integer [1..12] | Сумма возврата в минимальных единицах валюты. |
Обязательно | totalAmount |
Integer [1..12] | Сумма заказа плюс комиссия, если таковая имеется. |
Блок bankInfo
содержит следующие элементы.
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | bankCountryName |
String [1..160] | Страна банка-эмитента. |
Элемент bindingInfo
содержит следующие параметры.
Название | Тип | Обязательно | Описание |
---|---|---|---|
Необязательно | clientId |
String [0..255] | Номер клиента (ID) в системе мерчанта — до 255 символов. Используется для реализации функциональности связок. Может возвращаться в ответе, если мерчанту разрешено создавать связки. Указание этого параметра при обработке платежей по связке обязательно. В противном случае платеж будет невозможен. |
Необязательно | bindingId |
String [1..255] | Идентификатор уже существующей связки. (идентификатор карты, токенизированной шлюзом). Его можно использовать, только если у мерчанта есть разрешение на работу со связками. Если этот параметр передается в этом запросе, это означает, что:
|
Элемент operations
содержит следующие параметры.
Название | Тип | Обязательно | Описание |
---|---|---|---|
Необязательно | amount |
Integer [0..12] | Сумма платежа в минимальных единицах валюты (например, в копейках). |
Необязательно | cardHolder |
String [1..26] | Имя держателя карты латинскими буквами. Этот параметр передается только после оплаты заказа. |
Необязательно | authCode |
Integer [6] | Устаревший параметр (не используется). Его значение всегда 2 независимо от статуса заказа и кода авторизации процессинговой системы. |
Примеры
Пример запроса
curl --request POST \
--url https://3dsec.berekebank.kz/payment/installmentPayment.do \
--header 'Content-Type: application/json' \
--data '{
"userName": "test_user",
"password": "test_user_password",
"orderNumber": "UAF-203974-DE-12",
"language": "EN",
"bindingId": "8aa4fa8b-4d8a-76ca-b314-7bcc00b4f820",
"amount": 12300,
"currency": "398",
"description" : "Test description",
"additionalParameters": {
"firstParamName": "firstParamValue",
"secondParamName": "secondParamValue"
}
}'
Примеры ответа
{
"errorCode": 0,
"errorMessage": "Success",
"orderId": "0e441115-f3bc-711c-8827-2fdc00b4f820",
"orderStatus": {
"errorCode": "0",
"orderNumber": "7033",
"orderStatus": 2,
"actionCode": 0,
"actionCodeDescription": "",
"amount": 12300,
"currency": "398",
"date": 1618340470944,
"orderDescription": "Test description",
"merchantOrderParams": [
{
"name": "firstParamName",
"value": "firstParamValue"
},
{
"name": "secondParamName",
"value": "secondParamValue"
}
],
"transactionAttributes": [],
"attributes": [
{
"name": "mdOrder",
"value": "0e441115-f3bc-711c-8827-2fdc00b4f820"
}
],
"cardAuthInfo": {
"maskedPan": "400000**1118",
"expiration": "203012",
"cardholderName": "TEST CARDHOLDER",
"approvalCode": "123456",
"paymentSystem": "VISA",
"product": "visa-product",
"secureAuthInfo": {
"eci": 7
},
"pan": "400000**1118"
},
"bindingInfo": {
"clientId": "TEST CARDHOLDER",
"bindingId": "8aa4fa8b-4d8a-76ca-b314-7bcc00b4f820"
},
"authDateTime": 1618340471076,
"authRefNum": "111111111111",
"paymentAmountInfo": {
"paymentState": "DEPOSITED",
"approvedAmount": 12300,
"depositedAmount": 12300,
"refundedAmount": 0,
"totalAmount": 12300
},
"bankInfo": {
"bankName": "ES TEST BANK",
"bankCountryCode": "ES",
"bankCountryName": "Spain"
},
"chargeback": false,
"operations": [
{
"amount": 12300,
"cardHolder": "TEST CARDHOLDER",
"authCode": "123456"
}
]
},
"error": false
}
3DS
Завершение платежа 3DS2 через API
Для завершения заказа 3DS2 через API используется метод https://3dsec.berekebank.kz/payment/rest/finish3dsVer2Payment.do
.
При выполнении запроса необходимо использовать заголовок:
Content-Type: application/x-www-form-urlencoded
Параметры запроса
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | userName |
String [1..100] | Логин учетной записи API продавца. |
Обязательно | password |
String [1..200] | Пароль учетной записи API продавца. |
Обязательно | threeDSServerTransId |
String | Идентификатор транзакции, созданный на сервере 3DS. |
Необязательно | threeDSVer2MdOrder |
String | Номер заказа, который был зарегистрирован в первой части запроса в рамках 3DS 2.0 операции. Если данный параметр присутствует в запросе, то используется mdOrder , который передается в настоящем параметре. В таком случае регистрация заказа не происходит, а происходит сразу оплата заказа.Этот параметр передается только при использовании методов мгновенной оплаты, т.е., когда заказ регистрируется и оплачивается в рамках одного запроса. |
Параметры ответа
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | errorCode |
Integer [1..2] | Информационный параметр в случае ошибки, который может иметь разные кодовые значения:
|
Обязательно | errorMessage |
String [1..512] | Информационный параметр, являющийся описанием ошибки в случае возникновения ошибки. Значение errorMessage может варьироваться, поэтому не следует явным образом ссылаться на его значения в коде. Язык описания задается в параметре language запроса. |
Необязательно | redirect |
String [1..512] | Этот параметр возвращается, если платеж прошел успешно и для платежа не проводилась проверка карты на вовлеченность в 3-D Secure. Продавцы могут использовать его, если хотят перенаправить пользователя на страницу платежного шлюза. Если продавец использует собственную страницу, это значение можно игнорировать. |
Необязательно | is3DSVer2 |
Boolean | Возможные значения: true или false Флаг, показывающий, что платеж поступает из 3DS 2.0. |
Примеры
Пример запроса
curl --request POST \
--url https://3dsec.berekebank.kz/payment/rest/finish3dsVer2Payment.do \
--header 'content-type: application/x-www-form-urlencoded' \
--data threeDSServerTransId=33b17cb5-b4a5-48ac-a3b8-bc8d6d979a46 \
--data userName=test_user \
--data password=test_user_password \
Пример ответа
{
"redirect": "http://test.com?orderId=f61e2a41-34b9-7a2d-b4d6-83ac00c305c8&lang=en",
"errorCode": 0,
"is3DSVer2": true
}
Пример запроса с параметром threeDSVer2MdOrder
curl --request POST \
--url https://3dsec.berekebank.kz/payment/rest/finish3dsVer2Payment.do \
--header 'content-type: application/x-www-form-urlencoded' \
--data threeDSServerTransId=33b17cb5-b4a5-48ac-a3b8-bc8d6d979a46 \
--data threeDSVer2MdOrder=fbcb596f-25ba-70e7-a6cf-4fb100c305c8 \
--data userName=test_user \
--data password=test_user_password \
Пример ответа
{
"redirect": "http://test.com?orderId=f61e2a41-34b9-7a2d-b4d6-83ac00c305c8&lang=en",
"errorCode": 0,
"is3DSVer2": true
}
Продолжение оплаты для 3DS2
Для продолжения оплаты с 3DS2 авторизацией используется запрос https://3dsec.berekebank.kz/payment/rest/3ds/continue.do
.
При выполнении запроса необходимо использовать заголовок:
Content-Type: application/x-www-form-urlencoded
Параметры запроса
Обязательность | Название | Тип | Описание |
---|---|---|---|
Условие | userName |
String [1..100] | Логин учетной записи API продавца. Если для аутентификации при регистрации вместо логина и пароля используется открытый токен (параметр token ), пароль передавать не нужно. |
Условие | password |
String [1..200] | Пароль учетной записи API продавца. Если для аутентификации при регистрации вместо логина и пароля используется открытый токен (параметр token ), пароль передавать не нужно. |
Условие | token |
String [1..256] | Значение, используемое для аутентификации продавца при отправке запросов платежному шлюзу. Если вы передаете этот параметр, то не передавайте userName и password . |
Обязательно | mdOrder |
String [1..36] | Номер заказа в платежном шлюзе. Уникален в пределах платежного шлюза. |
Параметры ответа
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | errorCode |
Integer [1..2] | Информационный параметр в случае ошибки, который может иметь разные кодовые значения:
|
Необязательно | errorMessage |
String [1..512] | Информационный параметр, являющийся описанием ошибки в случае возникновения ошибки. Значение errorMessage может варьироваться, поэтому не следует явным образом ссылаться на его значения в коде. Язык описания задается в параметре language запроса. |
Необязательно | info |
String | В случае успешного ответа. Результат попытки оплаты. Ниже приведены возможные значения.
|
Необязательно | redirect |
String [1..512] | Этот параметр возвращается, если платеж прошел успешно и для платежа не проводилась проверка карты на вовлеченность в 3-D Secure. Продавцы могут использовать его, если хотят перенаправить пользователя на страницу платежного шлюза. Если продавец использует собственную страницу, это значение можно игнорировать. |
Условие* | acsUrl |
String [1..512] | При успешном ответе в случае оплаты 3D-Secure. URL-адрес для редиректа на ACS. Обязательный, если нужен редирект на ACS. Подробнее см. Редирект на ACS. |
Условие* | packedCReq |
String | Запакованные данные challenge request. Обязательный, если нужен редирект на ACS. Это значение следует использовать как значение параметра creq ссылки на ACS (acsUrl ), для перенаправления клиента на ACS. |
* Обязательно, если требуется перенаправление на ACS (используется полный 3DS2).
Примеры
Пример запроса
curl --request POST \
--url https://3dsec.berekebank.kz/payment/rest/3ds/continue.do \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data mdOrder=eb708f0a-2683-7437-b458-f80400b40dc0 \
--data userName=test-user \
--data password=test-password
Пример ответа (полный 3DS2, успешный запрос)
{
"info": "Your order is proceeded, redirecting...",
"errorCode": 0,
"acsUrl": "https://bestbank.com/acs2/acs/creq",
"is3DSVer2": true,
"packedCReq": "eyJ0aHJlZURTU...6IjA1In0"
}
Пример ответа (frictionless 3DS2, успешный запрос)
{
"redirect": "https://merchant.com/returnUrl?orderId=9666296c-e4f1-7285-a57c-20eb00b40dc1&lang=en",
"info": "Your order is proceeded, redirecting...",
"errorCode": 0,
"is3DSVer2": true
}
Пример ответа (ошибка - неизвестный статус в ARes)
{
"redirect": "https://merchant.com/failUrl?orderId=b69ac21f-6cd3-7e06-931d-d90100b40dc1&lang=en",
"error": "Error 3-D Secure authorization.",
"errorCode": 0,
"is3DSVer2": true,
"errorTypeName": "TDS_UNKNOWN_ARES_STATUS",
"processingErrorType": "MANDATORY_3DSECURE",
"errorMessage": "Error 3-D Secure authorization."
}
Пример ответа (ошибка авторизации)
{
"redirect": "https://merchant.com/failUrl?orderId=de056d10-f91d-7c91-a3de-559800b40dc1&lang=en",
"error": "Operation declined. Please check the data and available balance of the account.",
"errorCode": 0,
"is3DSVer2": true,
"errorTypeName": "DATA_INPUT_ERROR",
"processingErrorType": "CLIENT_ERROR",
"errorMessage": "Operation declined. Please check the data and available balance of the account."
}
Разное
Верификация карты
Метод https://3dsec.berekebank.kz/payment/rest/verifyCard.do
используется для проверки карты. Оплата не производится, и заказ сразу переходит в статус REVERSED
.
При выполнении запроса необходимо использовать заголовок:
Content-Type: application/x-www-form-urlencoded
Параметры запроса
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | userName |
String [1..100] | Логин учетной записи API продавца. Если для аутентификации при регистрации вместо логина и пароля используется открытый токен (параметр token ), пароль передавать не нужно. |
Необязательно | password |
String [1..200] | Пароль учетной записи API продавца. Если для аутентификации при регистрации вместо логина и пароля используется открытый токен (параметр token ), пароль передавать не нужно. |
Необязательно | token |
String [1..256] | Значение, используемое для аутентификации продавца при отправке запросов платежному шлюзу. Если вы передаете этот параметр, то не передавайте userName и password . |
Обязательно | amount |
Integer [0..12] | Сумма платежа в минимальных единицах валюты (например, в копейках). |
Необязательно | currency |
Integer [3] | Код валюты платежа ISO 4217. Если не указано, то используется значение по умолчанию. |
Необязательно | pan |
String [1..19] | Маскированный номер карты, которая использовалась для оплаты. Этот параметр указывается только после оплаты заказа. При оплате через Apple Pay в качестве номера карты используется DPAN - это номер, привязанный к мобильному устройству клиента, который функционирует как номер платежной карты в системе Apple Pay. |
Необязательно | cvc |
Integer | Этот параметр обязателен, если для мерчанта не выбрано разрешение Может проводить оплату без подтверждения CVC. |
Необязательно | expiry |
Integer | Срок действия карты в следующем формате: YYYYMM . Обязательно, если не переданы ни seToken , ни bindingId . |
Необязательно | cardholdername |
String [1..26] | Имя держателя карты латинскими буквами. Этот параметр передается только после оплаты заказа. |
Необязательно | backUrl |
String [1..512] | URL-адрес, на который будет перенаправлен пользователь в случае успешной оплаты. Используйте полный путь с указанием протокола, например https://test.com (а не test.com ).В противном случае пользователь будет перенаправлен на URL-адрес следующего вида: http://paymentGatewayURL/merchantURL |
Необязательно | failUrl |
String [1..512] | Адрес, на который требуется перенаправить пользователя в случае неуспешной оплаты. Адрес должен быть указан полностью, включая используемый протокол (например, https://mybestmerchantreturnurl.com вместо mybestmerchantreturnurl.com ). В противном случае пользователь будет перенаправлен по адресу следующего вида: https://3dsec.berekebank.kz/payment/<merchant_address> . |
Необязательно | description |
String [1..598] | Описание заказа в любом формате. Чтобы включить отправку этого поля в процессинговую систему, обратитесь в службу технической поддержки. В этом поле недопустимо передавать персональные данные или платежные данные (номера карт т.п.). Данное требование связано с тем, что описание заказа нигде не маскируется. |
Необязательно | language |
String [2] | Ключ языка по ISO 639-1. Если язык не указан, используется язык по умолчанию, указанный в настройках магазина. Поддерживаемые языки: ru, en. |
Необязательно | returnUrl |
String [1..512] | Адрес, на который требуется перенаправить пользователя в случае успешной оплаты. Адрес должен быть указан полностью, включая используемый протокол (например, https://mybestmerchantreturnurl.com вместо mybestmerchantreturnurl.com ). В противном случае пользователь будет перенаправлен по адресу следующего вида: https://3dsec.berekebank.kz/payment/<merchant_address> . |
Необязательно | threeDSServerTransId |
String | Идентификатор транзакции, созданный на сервере 3DS. |
Необязательно | threeDSVer2FinishUrl |
String | URL-адрес, по которому клиент должен быть перенаправлен после аутентификации на сервере ACS. |
Условие | threeDSVer2MdOrder |
String | Номер заказа, который был зарегистрирован в первой части запроса в рамках 3DS 2.0 операции. Если данный параметр присутствует в запросе, то используется mdOrder , который передается в настоящем параметре. В таком случае регистрация заказа не происходит, а происходит сразу оплата заказа.Этот параметр передается только при использовании методов мгновенной оплаты, т.е., когда заказ регистрируется и оплачивается в рамках одного запроса. |
Необязательно | threeDSSDK |
Boolean | Возможные значения: true или false Флаг, показывающий, что платеж поступает из 3DS SDK. |
Необязательно | billingPayerData |
Object | Блок с регистрационными данными клиента (адрес, почтовый индекс), необходимый для прохождения проверки адреса в рамках сервисов AVS/AVV. Обязательно, если функция включена для продавца на стороне Платежного шлюза. См вложенные параметры. |
Необязательно | shippingPayerData |
Object | Объект, содержащий данные о доставке клиенту. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. См. вложенные параметры. |
Необязательно | preOrderPayerData |
Object | Объект, содержащий данные предварительного заказа. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. См. вложенные параметры. |
Необязательно | orderPayerData |
Object | Объект, содержащий данные о плательщике заказа. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. См. вложенные параметры. |
Необязательно | billingAndShippingAddressMatchIndicator |
A1 | Индикатор соответствия платежного адреса владельца карты и адреса доставки. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. Возможные значения:
|
Ниже приведены параметры блока billingPayerData
(данные об адресе регистрации клиента).
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | billingCity |
String [0..50] | Город, зарегистрированный по конкретной карте у Банка Эмитента. |
Необязательно | billingCountry |
String [0..50] | Страна, зарегистрированная по конкретной карте банка-эмитента (ISO 3166-1, числовой). |
Необязательно | billingAddressLine1 |
String [0..50] | Адрес, зарегистрированный по конкретной карте у Банка Эмитента. Строка 1. Обязательно к передаче для AVS-проверки. |
Необязательно | billingAddressLine2 |
String [0..50] | Адрес, зарегистрированный по конкретной карте у Банка Эмитента. Строка 2. |
Необязательно | billingAddressLine3 |
String [0..50] | Адрес, зарегистрированный по конкретной карте у Банка Эмитента. Строка 3. |
Необязательно | billingPostalCode |
String [0..9] | Почтовый индекс, зарегистрированный по конкретной карте у Банка Эмитента. Обязательно к передаче для AVS-проверки. |
Необязательно | billingState |
String [0..50] | Штат, зарегистрированный по конкретной карте у Банка Эмитента. |
Описание параметров объекта shippingPayerData
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | shippingCity |
ANS...50 | Город заказчика (из адреса доставки) |
Необязательно | shippingCountry |
ANS...50 | Страна заказчика |
Необязательно | shippingAddressLine1 |
ANS...50 | Основной адрес клиента (из адреса доставки) |
Необязательно | shippingAddressLine2 |
ANS...50 | Основной адрес клиента (из адреса доставки) |
Необязательно | shippingAddressLine3 |
ANS...50 | Основной адрес клиента (из адреса доставки) |
Необязательно | shippingPostalCode |
ANS...16 | Почтовый индекс клиента для доставки |
Необязательно | shippingState |
ANS...50 | Штат/регион покупателя (из адреса доставки) |
Необязательно | shippingMethodIndicator |
N2 | Индикатор способа доставки. Возможные значения:
|
Необязательно | deliveryTimeframe |
N2 | Срок поставки товара. Возможные значения:
|
Необязательно | deliveryEmail |
ANS...254 | Целевой адрес электронной почты для доставки цифрового распространения. Предпочтительно передавать электронную почту в самостоятельном параметре запроса email (но если вы передадите его в этом блоке, к нему применятся те же правила). |
Описание параметров объекта preOrderPayerData
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | preOrderDate |
ANS8 | Ожидаемая дата доставки (для предзаказанных покупок) в формате ГГГГММДД. |
Необязательно | preOrderPurchaseInd |
N2 | Индикатор размещения клиентом заказа на доступную или будущую доставку. Возможные значения:
|
Необязательно | reorderItemsInd |
N2 | Индикатор того, что клиент перебронирует ранее оплаченную доставку в составе нового заказа. Возможные значения:
|
Описание параметров объекта orderPayerData
.
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | homePhone |
ANS...19 | Домашний телефон владельца карты. Необходимо всегда указывать код страны, но знак + или 00 в начале можно указать или опустить. Номер должен иметь длину от 7 до 15 цифр. Таким образом, возможны следующие значения:
|
Необязательно | workPhone |
ANS...19 | Рабочий телефон владельца карты. Необходимо всегда указывать код страны, но знак + или 00 в начале можно указать или опустить. Номер должен иметь длину от 7 до 15 цифр. Таким образом, возможны следующие значения:
|
Необязательно | mobilePhone |
ANS...19 | Номер мобильного телефона владельца карты. Необходимо всегда указывать код страны, но знак + или 00 в начале можно указать или опустить. Номер должен иметь длину от 7 до 15 цифр. Таким образом, возможны следующие значения:
Для платежей по VISA с 3DS авторизацией необходимо указать либо электронную почту, либо номер телефона владельца карты. Если у вас настроено отображение номера телефона на платежной странице и вы указали неверный номер телефона, клиент сможет исправить его на платежной странице. |
Параметры ответа
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | errorCode |
Integer [1..2] | Информационный параметр в случае ошибки, который может иметь разные кодовые значения:
|
Необязательно | errorMessage |
String [1..512] | Информационный параметр, являющийся описанием ошибки в случае возникновения ошибки. Значение errorMessage может варьироваться, поэтому не следует явным образом ссылаться на его значения в коде. Язык описания задается в параметре language запроса. |
Необязательно | orderId |
String [1..36] | Номер заказа в платежном шлюзе. Уникален в пределах платежного шлюза. |
Необязательно | orderNumber |
String [1..32] | Номер заказа (ID) в системе мерчанта; должен быть уникальным для каждого заказа. |
Необязательно | authCode |
Integer [6] | Устаревший параметр (не используется). Его значение всегда 2 независимо от статуса заказа и кода авторизации процессинговой системы. |
Необязательно | actionCode |
Integer | Код ответа от процессинга банка. См. список кодов ответа здесь. |
Необязательно | actionCodeDescription |
String [1..512] | Описание actionCode , возвращаемое процессингом банка. |
Необязательно | time |
String | Время совершения транзакции. |
Необязательно | eci |
Integer [1..4] | Электронный коммерческий индикатор. Указан только после оплаты заказа и в случае наличия соответствующего разрешения. Ниже приводится расшифровка ECI-кодов.
|
Необязательно | amount |
Integer [0..12] | Сумма платежа в минимальных единицах валюты (например, в копейках). |
Необязательно | currency |
Integer [3] | Код валюты платежа ISO 4217. Если не указано, то используется значение по умолчанию. |
Необязательно | rrn |
Integer [1..12] | Reference Retrieval Number - идентификатор транзакции, присвоенный банком-эквайером. |
Необязательно | acsUrl |
String [1..512] | При успешном ответе в случае оплаты 3D-Secure. URL-адрес для редиректа на ACS. Обязательный, если нужен редирект на ACS. Подробнее см. Редирект на ACS. |
Необязательно | termUrl |
String [1..512] | При успешном ответе в случае оплаты 3D-Secure. Это URL-адрес, на который ACS перенаправляет владельца карты после аутентификации. Подробнее см. Редирект на ACS. |
Необязательно | paReq |
String [1..255] | При успешном ответе в случае оплаты 3D-Secure. PAReq (Payment Authentication Request) — сообщение, которое необходимо отправить в ACS вместе с редиректом. Это сообщение содержит данные в кодировке Base64, необходимые для аутентификации держателя карты. Подробнее см. Редирект на ACS. |
Примеры
Пример запроса
curl --request POST \
--url https://3dsec.berekebank.kz/payment/rest/verifyCard.do \
--header 'content-type: application/x-www-form-urlencoded' \
--data userName=test_user \
--data password=test_user_password \
--data pan=4000001111111118 \
--data cvc=123 \
--data expiry=203012
Пример ответа
{
"errorCode": "0",
"errorMessage": "Success",
"orderId": "cfc238ca-68f9-745c-ba7e-eb9100af79e0",
"orderNumber": "12017",
"rrn": "111111111115",
"authCode": "123456",
"actionCode": 0,
"actionCodeDescription": "",
"time": 1595284781180,
"eci": "07",
"amount": 0,
"currency": "398"
}
API платежных ссылок
Эти методы API позволяют управлять шаблонами платежных ссылок, которые перенаправляют клиента на страницу оплаты.
Создание шаблона
Для создания шаблона платежной ссылки используется запрос https://3dsec.berekebank.kz/payment/rest/templates/create.do
.
При выполнении запроса необходимо использовать заголовок:
Content-Type: application/x-www-form-urlencoded
Параметры запроса
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | userName |
String [1..100] | Логин учетной записи API продавца. |
Обязательно | password |
String [1..200] | Пароль учетной записи API продавца. |
Обязательно | template |
Object | Объект, содержащий набор параметров создаваемого шаблона. См. вложенные параметры. |
Параметры блока template
(набор параметров создаваемого шаблона).
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | type |
String | Тип шаблона. Возможные значения параметра: ECOM . |
Обязательно | name |
String [1..140] | Название шаблона. |
Необязательно | preAuth |
Boolean | Признак шаблона, указывающий, что заказ должен быть зарегистрирован по шаблону как двухстадийный. Возможные значения:
|
Необязательно | amount |
Integer [0..10] | Сумма в минорных единицах. Если сумма не указана, то шаблон создаётся с опцией "Любая сумма". |
Необязательно | currency |
Integer [3] | Код валюты платежа ISO 4217. Если не указано, то используется значение по умолчанию. |
Необязательно | description |
String [0..255] | Описание шаблона для мерчанта. |
Необязательно | startDate |
String [1..19] | Дата начала действия шаблона, начиная с которой по данному шаблону возможно создание заказа и проведение оплаты. Формат: "YYYY-MM-DDThh:mm:ss". |
Необязательно | endDate |
String [1..19] | Дата окончания действия шаблона. Формат: "YYYY-MM-DDThh:mm:ss". Если этот параметр не задан, шаблон является бессрочным. |
Обязательно | nameForClient |
String [0..255] | Название шаблона, которое клиент видит на предплатежной странице. |
Необязательно | descriptionForClient |
String [0..255] | Описание шаблона, которое клиент видит на предплатежной странице. |
Необязательно | singlePayment |
Boolean | Признак шаблона, указывающий, что после проведения одной единственной оплаты шаблон перейдет в статус "INACTIVE". |
Необязательно | additionalParams |
Array of objects | Массив объектов, описывающих дополнительные параметры шаблона. См. вложенные параметры. |
Необязательно | commission |
Object | Объект, содержащий параметры, описывающие комиссию, выставленную на уровне шаблона. См. вложенные параметры. |
Необязательно | qrTemplate |
Object | Объект, содержащий параметры шаблона для QR-кода. Укажите этот параметр, если хотите получить визуализированный QR-код в формате PNG. См. вложенные параметры. |
Параметры объекта массива additionalParams
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | additionalParams.label |
String [1..255] | Название дополнительного параметра, которое клиент видит на предплатежной странице. |
Обязательно | additionalParams.name |
String [1..255] | Наименование параметра в Платежном Шлюзе. Допустимо использование только латинских строчных символов и символа подчеркивания. Например: size , items_count и т.п. |
Необязательно | additionalParams.placeholder |
String [1..255] | Подсказка клиенту при заполнении поля {lable} на предплатёжной странице. |
Необязательно | additionalParams.regexp |
String [1..200] | Регулярное выражение для проверки поля дополнительного параметра {lable} на предплатёжной странице. Если параметр не указан, проверка параметра не выполняется. |
Обязательно | additionalParams.required |
Boolean | Признак, указывающий на обязательность заполнения поля {lable} на предплатёжной странице. |
Необязательно | additionalParams.value |
String [1..255] | Предзаполненное значение поля {lable} на предплатёжной странице. |
Необязательно | additionalParams.visible |
Boolean | Признак, указывающий, отображать или нет поле {lable} на предплатёжной странице. По умолчанию false . |
Параметры блока commission
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Условие | commission.feeMin |
Integer [1..10] | Минимальный размер комиссии в минорных единицах валюты. |
Условие | commission.feeMax |
Integer [1..10] | Максимальный размер комиссии в минорных единицах валюты. |
Условие | commission.feePercentage |
String [1..10] | Размер комиссии в процентах от суммы заказа. Процент в виде дробного значения с разделителем-точкой. |
Условие | commission.fixedAmount |
String [1..10] | Размер фиксированной части комиссии в минорных единицах валюты. |
*Объект commission
должен содержать один или оба набора параметров:
-
feeMin
+feeMax
+feePercentage
-
fixedAmount
Ниже приведены параметры блока qrTemplate
(данные о размере QR-кода).
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | qrHeight |
String | Высота QR-кода в пикселях. Укажите этот параметр, если хотите получить визуализированный QR-код в формате PNG. Минимальное значение - 10. Максимальное значение - 1000. |
Обязательно | qrWidth |
String | Ширина QR-кода в пикселях. Укажите этот параметр, если хотите получить визуализированный QR-код в формате PNG. Минимальное значение - 10. Максимальное значение - 1000. |
Параметры ответа
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | status |
String | Статус ответа. Допустимые значения:
|
Условие | error |
Object | Объект, содержащий информацию об ошибке. Обязательный, если status имеет значение FAIL . См. вложенные параметры. |
Условие | template |
Object | Объект, содержащий информацию о созданном шаблоне. Обязательный, если status имеет значение SUCCESS . См. вложенные параметры. |
Параметры блока error
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | code |
String | Код ошибки. Возможные значения:
|
Обязательно | description |
String | Описание ошибки. |
Обязательно | message |
String | Подробное сообщение об ошибке. |
Параметры блока template
(набор параметров шаблона):
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | templateId |
String [1..32] | Идентификатор созданного шаблона. |
Обязательно | status |
String [1..8] | Статус шаблона. Возможные значения:
|
Обязательно | qrTemplate |
Object | Блок с параметрами шаблона для QR-кода. См. вложенные параметры. |
Ниже приведены параметры блока qrTemplate
(данные о размере QR-кода).
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | payload |
String [1..999] | Содержимое QR-кода платежной ссылки. |
Условие | renderedQr |
String [1..255] | QR-код в формате PNG, закодированный в Base64. Этот параметр возвращается, если запрос содержит qrHeight и qrWidth и если status = ACTIVE . |
Примеры
Пример запроса
curl --location 'https://3dsec.berekebank.kz/payment/rest/templates/create.do' \
--header 'Content-Type: application/json' \
--data '{
"username": "test_user",
"password": "test_user_password",
"language": "en",
"template": {
"type": "ECOM",
"name": "template_test",
"currency": "EUR",
"nameForClient": "Name For Client",
"descriptionForClient": "Description For Client",
"qrTemplate": {
"qrWidth": 150,
"qrHeight": 150
},
"commission": {
"feeMin": 14,
"feeMax": 14,
"fixedAmount": 34,
"feePercentage": 3.3
},
"additionalParams": [
{
"label": "Test",
"name": "phone",
"placeholder": "test",
"regexp": "\\w+",
"required": true,
"value": "123",
"visible": true
}
]
}
}'
Пример ответа
{
"status": "SUCCESS",
"template": {
"templateId": "umoPoMUCbGrsKRKT",
"status": "ACTIVE",
"qrTemplate": {
"renderedQr": "IBFEARgEQRBABZBEARgEQQBWARBEErj/8eaPTWORnTBAAAAAElFTkSuQmCC",
"payload": "https://someurl.com/sc/umoPoMUCbGrsKRKT"
}
}
}
Получение информации о шаблоне
Для получения информации о шаблоне платежной ссылки используется запрос https://3dsec.berekebank.kz/payment/rest/templates/get.do
.
При выполнении запроса необходимо использовать заголовок:
Content-Type: application/x-www-form-urlencoded
Параметры запроса
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | userName |
String [1..100] | Логин учетной записи API продавца. |
Обязательно | password |
String [1..200] | Пароль учетной записи API продавца. |
Обязательно | template |
Object | Объект, содержащий информацию о шаблоне, по которому выполняется запрос. См. вложенные параметры. |
Параметры блока template
(набор параметров шаблона, по которому нужно получить информацию).
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | templateId |
String [1..32] | Идентификатор шаблона. |
Необязательно | qrTemplate |
Object | Объект, указывающий размер QR-кода шаблона. Укажите этот параметр, если хотите получить визуализированный QR-код в формате PNG. См. вложенные параметры. |
Ниже приведены параметры блока qrTemplate
(данные о размере QR-кода).
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | qrHeight |
String | Высота QR-кода в пикселях. Укажите этот параметр, если хотите получить визуализированный QR-код в формате PNG. Минимальное значение - 10. Максимальное значение - 1000. |
Обязательно | qrWidth |
String | Ширина QR-кода в пикселях. Укажите этот параметр, если хотите получить визуализированный QR-код в формате PNG. Минимальное значение - 10. Максимальное значение - 1000. |
Параметры ответа
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | status |
String | Статус ответа. Допустимые значения:
|
Условие | error |
Object | Объект, содержащий информацию об ошибке. Обязательный, если status имеет значение FAIL . См. вложенные параметры. |
Условие | template |
Object | Объект, содержащий информацию о шаблоне. Обязательный, если status имеет значение SUCCESS . См. вложенные параметры. |
Параметры блока error
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | code |
String | Код ошибки. Возможные значения:
|
Обязательно | description |
String | Описание ошибки. |
Обязательно | message |
String | Подробное сообщение об ошибке. |
Параметры блока template
(набор параметров шаблона):
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | templateId |
String [1..32] | Идентификатор шаблона. |
Обязательно | status |
String [1..8] | Статус шаблона. Возможные значения:
|
Обязательно | type |
String | Тип шаблона. Возможные значения параметра: ECOM . |
Обязательно | name |
String [1..140] | Название шаблона. |
Необязательно | preAuth |
Boolean | Признак шаблона, указывающий, что заказ должен быть зарегистрирован по шаблону как двухстадийный. Возможные значения:
|
Необязательно | amount |
Integer [0..10] | Сумма в минорных единицах. Если сумма не указана, то в шаблоне выставлена опция "Любая сумма". |
Необязательно | currency |
Integer [3] | Код валюты платежа ISO 4217. Если не указано, то используется значение по умолчанию. |
Необязательно | description |
String [0..255] | Описание шаблона для мерчанта. |
Необязательно | startDate |
String [1..19] | Дата начала действия шаблона, начиная с которой по данному шаблону возможно создание заказа и проведение оплаты. Формат: "YYYY-MM-DDThh:mm:ss". |
Необязательно | endDate |
String [1..19] | Дата окончания действия шаблона. Формат: "YYYY-MM-DDThh:mm:ss". Если этот параметр не задан, шаблон является бессрочным. |
Обязательно | nameForClient |
String [0..255] | Название шаблона, которое клиент видит на предплатежной странице. |
Необязательно | descriptionForClient |
String [0..255] | Описание шаблона, которое клиент видит на предплатежной странице. |
Обязательно | singlePayment |
Boolean | Признак шаблона, указывающий, что после проведения одной единственной оплаты шаблон перейдет в статус "INACTIVE". |
Необязательно | additionalParams |
Array of objects | Массив объектов, описывающих дополнительные параметры шаблона. См. вложенные параметры. |
Необязательно | commission |
Object | Объект, содержащий параметры, описывающие комиссию, выставленную на уровне шаблона. См. вложенные параметры. |
Обязательно | qrTemplate |
Object | Объект, содержащий параметры шаблона для QR-кода. См. вложенные параметры. |
Параметры объекта массива additionalParams
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | additionalParams.label |
String [1..255] | Название дополнительного параметра, которое клиент видит на предплатежной странице. |
Обязательно | additionalParams.name |
String [1..255] | Наименование параметра в Платежном Шлюзе. Допустимо использование только латинских строчных символов и символа подчеркивания. Например: size , items_count и т.п. |
Необязательно | additionalParams.placeholder |
String [1..255] | Подсказка клиенту при заполнении поля {lable} на предплатёжной странице. |
Необязательно | additionalParams.regexp |
String [1..200] | Регулярное выражение для проверки поля дополнительного параметра {lable} на предплатёжной странице. Если параметр не указан, проверка параметра не выполняется. |
Обязательно | additionalParams.required |
Boolean | Признак, указывающий на обязательность заполнения поля {lable} на предплатёжной странице. |
Необязательно | additionalParams.value |
String [1..255] | Предзаполненное значение поля {lable} на предплатёжной странице. |
Необязательно | additionalParams.visible |
Boolean | Признак, указывающий, отображать или нет поле {lable} на предплатёжной странице. По умолчанию false . |
Параметры блока commission
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Условие | commission.feeMin |
Integer [1..10] | Минимальный размер комиссии в минорных единицах валюты. |
Условие | commission.feeMax |
Integer [1..10] | Максимальный размер комиссии в минорных единицах валюты. |
Условие | commission.feePercentage |
String [1..10] | Размер комиссии в процентах от суммы заказа. Процент в виде дробного значения с разделителем-точкой. |
Условие | commission.fixedAmount |
String [1..10] | Размер фиксированной части комиссии в минорных единицах валюты. |
*Объект commission
должен содержать один или оба набора параметров:
-
feeMin
+feeMax
+feePercentage
-
fixedAmount
Ниже приведены параметры блока qrTemplate
(данные о размере QR-кода).
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | payload |
String [1..999] | Содержимое QR-кода платежной ссылки. |
Условие | renderedQr |
String [1..255] | QR-код в формате PNG, закодированный в Base64. Этот параметр возвращается, если запрос содержит qrHeight и qrWidth и если status = ACTIVE . |
Примеры
Пример запроса
curl --location 'https://3dsec.berekebank.kz/payment/rest/templates/get.do' \
--header 'Content-Type: application/json' \
--data '{
"username": "test_user",
"password": "test_user_password",
"template": {
"templateId": "umoPoMUCbGrsKRKT"
}
}
Пример ответа
{
"status": "SUCCESS",
"template": {
"templateId": "umoPoMUCbGrsKRKT",
"status": "ACTIVE",
"type": "ECOM",
"name": "merchapitest",
"preAuth": false,
"currency": "RUB",
"nameForClient": "Name for client",
"descriptionForClient": "Description for client",
"singlePayment": false,
"additionalParams": [
{
"label": "Test",
"name": "+35799988877",
"regexp": "\\w+",
"value": "123",
"placeholder": "test",
"required": true,
"visible": true
}
],
"qrTemplate": {
"payload": "https://someurl.com/sc/umoPoMUCbGrsKRKT"
}
}
}
Изменение шаблона
Для изменения шаблона платежной ссылки используется запрос https://3dsec.berekebank.kz/payment/rest/templates/update.do
.
При выполнении запроса необходимо использовать заголовок:
Content-Type: application/x-www-form-urlencoded
Параметры запроса
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | userName |
String [1..100] | Логин учетной записи API продавца. |
Обязательно | password |
String [1..200] | Пароль учетной записи API продавца. |
Обязательно | template |
Object | Объект, содержащий информацию о шаблоне, по которому выполняется запрос. См. вложенные параметры. |
Параметры блока template
(набор параметров шаблона).
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | templateId |
String [1..32] | Идентификатор шаблона. |
Необязательно | name |
String [1..140] | Название шаблона. |
Необязательно | preAuth |
Boolean | Признак шаблона, указывающий, что заказ должен быть зарегистрирован по шаблону как двухстадийный. Возможные значения:
|
Необязательно | status |
String [1..8] | Статус шаблона. Возможные значения:
|
Необязательно | amount |
Integer [0..10] | Сумма в минорных единицах. Если сумма не указана, то в шаблоне выставлена опция "Любая сумма". |
Необязательно | isFreeAmount |
Boolean | Признак, указывающий на свободную сумму шаблона. Если признак присутствует в запросе, то значение параметра amount игнорируется. |
Необязательно | currency |
Integer [3] | Код валюты платежа ISO 4217. Если не указано, то используется значение по умолчанию. |
Необязательно | description |
String [0..255] | Описание шаблона для мерчанта. |
Необязательно | startDate |
String [1..19] | Дата начала действия шаблона, начиная с которой по данному шаблону возможно создание заказа и проведение оплаты. Формат: "YYYY-MM-DDThh:mm:ss". |
Необязательно | endDate |
String [1..19] | Дата окончания действия шаблона. Формат: "YYYY-MM-DDThh:mm:ss". Если этот параметр не задан, шаблон является бессрочным. |
Необязательно | isIndefinite |
Boolean | Признак, указывающий на бессрочность шаблона. Если признак присутствует, то значения параметров startDate и endDate игнорируются. |
Необязательно | nameForClient |
String [0..255] | Название шаблона, которое клиент видит на предплатежной странице. |
Необязательно | descriptionForClient |
String [0..255] | Описание шаблона, которое клиент видит на предплатежной странице. |
Необязательно | singlePayment |
Boolean | Признак шаблона, указывающий, что после проведения одной единственной оплаты шаблон перейдет в статус "INACTIVE". |
Необязательно | additionalParams |
Array of objects | Массив объектов, описывающих дополнительные параметры шаблона. См. вложенные параметры. |
Необязательно | commission |
Object | Объект, содержащий параметры, описывающие комиссию, выставленную на уровне шаблона. См. вложенные параметры. |
Необязательно | qrTemplate |
Object | Объект, содержащий параметры шаблона для QR-кода. Укажите этот параметр, если хотите получить визуализированный QR-код в формате PNG. См. вложенные параметры. |
Параметры объекта массива additionalParams
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | additionalParams.mode |
String | Указатель на действие, которое требуется совершить с дополнительным параметром. Возможные значения:
ADD . |
Условие | additionalParams.label |
String [1..255] | Название дополнительного параметра, которое клиент видит на предплатежной странице. Обязательный параметр, если требуется добавить новый дополнительный параметр. |
Обязательно | additionalParams.name |
String [1..255] | Наименование параметра в Платежном Шлюзе. Допустимо использование только латинских строчных символов и символа подчеркивания. Например: size , items_count и т.п. Обязательный параметр, если требуется добавить новый дополнительный параметр. |
Optional | additionalParams.placeholder |
String [1..255] | Подсказка клиенту при заполнении поля {lable} на предплатёжной странице. |
Optional | additionalParams.regexp |
String [1..200] | Регулярное выражение для проверки поля дополнительного параметра {lable} на предплатёжной странице. Если параметр не указан, проверка параметра не выполняется. |
Conditional | additionalParams.required |
Boolean | Признак, указывающий на обязательность заполнения поля {lable} на предплатёжной странице. Обязательный параметр, если требуется добавить новый дополнительный параметр. |
Optional | additionalParams.value |
String [1..255] | Предзаполненное значение поля {lable} на предплатёжной странице. |
Optional | additionalParams.visible |
Boolean | Признак, указывающий, отображать или нет поле {lable} на предплатёжной странице. По умолчанию false . |
Параметры блока commission
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Условие | commission.feeMin |
Integer [1..10] | Минимальный размер комиссии в минорных единицах валюты. |
Условие | commission.feeMax |
Integer [1..10] | Максимальный размер комиссии в минорных единицах валюты. |
Условие | commission.feePercentage |
String [1..10] | Размер комиссии в процентах от суммы заказа. Процент в виде дробного значения с разделителем-точкой. |
Условие | commission.fixedAmount |
String [1..10] | Размер фиксированной части комиссии в минорных единицах валюты. |
*Объект commission
должен содержать один или оба набора параметров:
-
feeMin
+feeMax
+feePercentage
-
fixedAmount
Ниже приведены параметры блока qrTemplate
(данные о размере QR-кода).
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | qrHeight |
String | Высота QR-кода в пикселях. Укажите этот параметр, если хотите получить визуализированный QR-код в формате PNG. Минимальное значение - 10. Максимальное значение - 1000. |
Обязательно | qrWidth |
String | Ширина QR-кода в пикселях. Укажите этот параметр, если хотите получить визуализированный QR-код в формате PNG. Минимальное значение - 10. Максимальное значение - 1000. |
Параметры ответа
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | status |
String | Статус ответа. Допустимые значения:
|
Условие | error |
Object | Объект, содержащий информацию об ошибке. Обязательный, если status имеет значение FAIL . См. вложенные параметры. |
Параметры блока error
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | code |
String | Код ошибки. Возможные значения:
|
Обязательно | description |
String | Описание ошибки. |
Обязательно | message |
String | Подробное сообщение об ошибке. |
Примеры
Пример запроса
curl --location 'https://3dsec.berekebank.kz/payment/rest/templates/create.do' \
--header 'Content-Type: application/json' \
--data '{
"username": "test_user",
"password": "test_user_password",
"language": "en",
"template": {
"templateId" : "umoPoMUCbGrsKRKT",
"name": "merchapitest",
"amount": 300444,
"nameForClient": "Name for client",
"descriptionForClient": "Description for client",
"description": "description555",
"commission": {
"feeMin": 141,
"feeMax": 141,
"fixedAmount": 341,
"feePercentage": 31.3
},
"additionalParams": [
{
"label": "Phone number",
"name": "phone",
"placeholder": "test",
"regexp": "\\w+",
"required": true,
"value": "+35799988877",
"visible": true,
"mode": "REMOVE"
}
]
}
}'
Пример ответа
{
"status": "SUCCESS"
}
Получение списка шаблонов
Для получения информации обо всех шаблонах мерчанта используется запрос https://3dsec.berekebank.kz/payment/rest/templates/getList.do
.
При выполнении запроса необходимо использовать заголовок:
Content-Type: application/x-www-form-urlencoded
Параметры запроса
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | userName |
String [1..100] | Логин учетной записи API продавца. |
Обязательно | password |
String [1..200] | Пароль учетной записи API продавца. |
Необязательно | merchant_login |
Object | Логин мерчанта, по которому выполняется поиск шаблонов. Этот параметр обязателен для работы "родительской" схемы, если вы хотите получить информацию о шаблонах вашего дочернего мерчанта. |
Необязательно | status |
String [1..8] | Статус шаблона, ограничивающий вывод списка шаблонов. Допустимые значения:
ACTIVE . |
Необязательно | qrTemplate |
Object | Объект, указывающий размер QR-кода, возвращаемого для всех шаблонов. Укажите этот параметр, чтобы получить rendered QR-код в формате PNG format. См. вложенные параметры. |
Ниже приведены параметры блока qrTemplate
(данные о размере QR-кода).
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | qrHeight |
String | Высота QR-кода в пикселях. Укажите этот параметр, если хотите получить визуализированный QR-код в формате PNG. Минимальное значение - 10. Максимальное значение - 1000. |
Обязательно | qrWidth |
String | Ширина QR-кода в пикселях. Укажите этот параметр, если хотите получить визуализированный QR-код в формате PNG. Минимальное значение - 10. Максимальное значение - 1000. |
Параметры ответа
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | status |
String | Статус ответа. Допустимые значения:
|
Условие | error |
Object | Объект, содержащий информацию об ошибке. Обязательный, если status имеет значение FAIL . См. вложенные параметры. |
Условие | templates |
Array of objects | Массив объектов, содержащий список всех шаблонов мерчанта. Обязательный, если status имеет значение SUCCESS . Если у мерчанта нет шаблонов, то возвращается пустой массив. См. вложенные параметры. |
Параметры блока error
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | code |
String | Код ошибки. Возможные значения:
|
Обязательно | description |
String | Описание ошибки. |
Обязательно | message |
String | Подробное сообщение об ошибке. |
Параметры блока template
(набор параметров шаблона):
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | templateId |
String [1..32] | Идентификатор шаблона. |
Обязательно | status |
String [1..8] | Статус шаблона. Возможные значения:
|
Обязательно | type |
String | Тип шаблона. Возможные значения параметра: ECOM . |
Обязательно | name |
String [1..140] | Название шаблона. |
Необязательно | amount |
Integer [0..10] | Сумма в минорных единицах. Если сумма не указана, то в шаблоне выставлена опция "Любая сумма". |
Обязательно | currency |
Integer [3] | Код валюты платежа ISO 4217. Если не указано, то используется значение по умолчанию. |
Обязательно | qrTemplate |
Object | Объект, содержащий параметры шаблона для QR-кода. См. вложенные параметры. |
Ниже приведены параметры блока qrTemplate
(данные о размере QR-кода).
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | payload |
String [1..999] | Содержимое QR-кода платежной ссылки. |
Условие | renderedQr |
String [1..255] | QR-код в формате PNG, закодированный в Base64. Этот параметр возвращается, если запрос содержит qrHeight и qrWidth и если status = ACTIVE . |
Примеры
Пример запроса
curl --location 'https://3dsec.berekebank.kz/payment/rest/templates/getList.do' \
--header 'Content-Type: application/json' \
--data '{
"username": "test_user",
"password": "test_user_password",
"merchantLogin": "testMerchant"
}'
Пример ответа
{
"status": "SUCCESS",
"templates": [
{
"templateId": "umoPoMUCbGrsKRKT",
"status": "ACTIVE",
"type": "ECOM",
"name": "merchapitest",
"amount": 300444,
"currency": "EUR",
"qrTemplate": {
"payload": "https://someurl/sc/umoPoMUCbGrsKRKT"
}
},
{
"templateId": "CkSCddIgVfjuVpeG",
"status": "ACTIVE",
"type": "ECOM",
"name": "template_test_2",
"currency": "EUR",
"qrTemplate": {
"payload": "https://someurl/sc/CkSCddIgVfjuVpeG"
}
},
{
"templateId": "ngycAOzNQhCVyeSy",
"status": "ACTIVE",
"type": "ECOM",
"name": "Test link",
"amount": 10000,
"currency": "EUR",
"qrTemplate": {
"payload": "https://someurl/sc/ngycAOzNQhCVyeSy"
}
}
]
}
Уведомления обратного вызова
API платежного шлюза позволяет получать уведомления обратного вызова (callback-уведомления) об изменении статусов платежей.
Общая информация
События, о которых могут приходить уведомления
Вы можете получать уведомления об изменении статуса оплаты заказа и о других событиях в платежном шлюзе.
Наиболее распространенные уведомления описывают изменения статуса заказа, например:
списание средств
удержание (холдирование) средств
отмена платежа
возврат средств
Более сложные интеграции могут подразумевать дополнительные триггеры обратного вызова, такие как:
- сохранение карты (т.е. создание связки)
- включение/выключение существующей связки
- отклонение платежей и т.д.
Тип триггера передается в параметре operation
уведомления обратного вызова (см. подробности ниже). Для удобства уведомления для дополнительных триггеров могут быть направлены на другой URL-адрес с помощью параметра dynamicCallbackUrl
в запросах на регистрацию заказа.
Интеграция через уведомления обратного вызова (callback)
Вместо последнего шага интеграции через редирект вы можете выбрать один из следующих подходов.
Использовать returnUrl
Когда код вашего сайта, расположенный по адресу returnUrl
(например, https://mybestmerchantreturnurl.com/?back&orderId=61c33664-85a0-7d6b-af26-09ee009c4000&lang=en
), идентифицирует перенаправляемого из шлюза держателя карты посде попытки оплаты, вы можете проверить статус заказа с помощью API-запроса getOrderStatusExtended
.
Этот вариант является самым простым, но он не совсем надежен, поскольку перенаправление держателя карты может завершиться ошибкой (например, в результате обрыва соединения или закрытия браузера держателем карты), а returnUrl
может не получить триггер для вызова getOrderStatusExtended
.
curl --request POST \
--url https://3dsec.berekebank.kz/payment/rest/getOrderStatusExtended.do \
--header 'content-type: application/x-www-form-urlencoded' \
--data userName=test_user \
--data password=test_user_password \
--data orderId=016b6f47-4628-7ea2-80f5-6c6e00a7d8c0 \
--data language=en
{
"errorCode": "0",
"errorMessage": "Success",
"orderNumber": "11008",
"orderStatus": 2,
"actionCode": 0,
"actionCodeDescription": "",
"amount": 2000,
"currency": "398",
"date": 1618577250840,
"orderDescription": "my_first_order",
"merchantOrderParams": [
{
"name": "browser_language_param",
"value": "en"
},
{
"name": "browser_os_param",
"value": "UNKNOWN"
},
{
"name": "user_agent",
"value": "curl/7.75.0"
},
{
"name": "browser_name_param",
"value": "DOWNLOAD"
}
],
"transactionAttributes": [],
"attributes": [
{
"name": "mdOrder",
"value": "016b7747-c4ed-70b3-bc36-fdd400a7d8c0"
}
],
"cardAuthInfo": {
"maskedPan": "555555**5599",
"expiration": "202412",
"cardholderName": "TEST CARDHOLDER",
"approvalCode": "123456",
"pan": "555555**5599"
},
"authDateTime": 1618577288377,
"terminalId": "123456",
"authRefNum": "931793605827",
"paymentAmountInfo": {
"paymentState": "DEPOSITED",
"approvedAmount": 2000,
"depositedAmount": 2000,
"refundedAmount": 0
},
"bankInfo": {
"bankCountryCode": "UNKNOWN",
"bankCountryName": "<Unknown>"
}
}
Использовать подписанный callback шлюза
Если вы знаете, как обращаться с цифровыми сертификатами и подписями, вы можете использовать callback с цифровой подписью и контрольной суммой (шлюз позволяет настроить отправку таких уведомлений). Контрольная сумма используется для проверки и безопасности. После того, как подпись уведомления была проверена, уже нет необходимости отправлять getOrderStatusExtended
, потому что уведомление содержит в себе информацию о статусе заказа.
https://mybestmerchantreturnurl.com/callback/?mdOrder=1234567890-098776-234-522&orderNumber=0987&checksum=DBBE9E54D42072D8CAF32C7F660DEB82086A25C14FD813888E231A99E1220AB3&operation=deposited&status=1
Типы уведомлений
Уведомления без контрольной суммы
Эти уведомления содержат только информацию о заказе, поэтому потенциально продавец рискует принять уведомление, отправленное злоумышленником, за подлинное.
Уведомления с контрольной суммой
Такие уведомления помимо сведений о заказе содержат аутентификационный код. Аутентификационный код представляет собой контрольную сумму сведений о заказе. Эта контрольная сумма позволяет убедиться, что callback-уведомление действительно было отправлено платежным шлюзом.
Существует два способа реализации callback-уведомлений с контрольной суммой:
- с помощью симметричной криптографии - для формирования контрольной суммы на стороне шлюза и для ее проверки на стороне продавца используется один и тот же (симметричный) криптографический ключ;
- С помощью асимметричной криптографии - для формирования контрольной суммы на стороне платежного шлюза используется закрытый ключ, известный только шлюзу, а для подтверждения контрольной суммы используется связанный с закрытым ключом открытый ключ, который известен продавцам и может распространяться свободно.
Открытый ключ можно выгрузить из личного кабинета платежного шлюза при наличии соответствующих полномочий. Для большей безопасности рекомендуется использовать асимметричную криптографию.
Чтобы включить уведомления с контрольными суммами, а также получить соответствующий криптографический ключ, обратитесь в нашу службу технической поддержки.
Требования к SSL-сертификатам на сайте продавца
Если уведомление о состоянии заказа приходит через HTTPS-соединение, необходимо удостоверить подлинность сайта с помощью SSL-сертификата, выпущенного и подписанного доверенным центром сертификации (см. таблицу ниже). Использование самозаверенных сертификатов не допускается.
Требование | Описание |
---|---|
Алгоритм подписи. | Не ниже SHA-256. |
Поддерживаемые центры сертификации. | Ниже приведены примеры организаций, которые регистрируют цифровые сертификаты: |
Формат URL-адресов уведомлений
Поддерживаются запросы POST и GET.
Ниже приведен пример GET-запроса. Параметры получены в запросе.
Уведомление без контрольной суммы (GET)
https://mybestmerchantreturnurl.com/callback/?mdOrder=
1234567890-098776-234-522&orderNumber=0987&operation=deposited&
callbackCreationDate=Mon Jan 31 21:46:52 UTC 2022&status=0
Уведомление с контрольной суммы (GET)
https://mybestmerchantreturnurl.com/callback/?mdOrder=1234567890-098776-234-522&
orderNumber=0987&checksum=DBBE9E54D42072D8CAF32C7F660DEB82086A25C14FD813888E231A99E1220AB3&
operation=deposited&callbackCreationDate=Mon Jan 31 21:46:52 UTC 2022&status=0
Для POST-коллбэков вы получите те же параметры в теле HTTP (вместо параметров запроса).
Уведомление без контрольной суммы (POST)
https://mybestmerchantreturnurl.com/callback/
mdOrder=
1234567890-098776-234-522&orderNumber=0987&operation=deposited&
callbackCreationDate=Mon Jan 31 21:46:52 UTC 2022&status=0
Уведомление с контрольной суммой (POST)
https://mybestmerchantreturnurl.com/callback/
mdOrder=1234567890-098776-234-522&
orderNumber=0987&checksum=DBBE9E54D42072D8CAF32C7F660DEB82086A25C14FD813888E231A99E1220AB3&operation=deposited&callbackCreationDate=Mon Jan 31 21:46:52 UTC 2022&status=0
Передаваемые параметры представлены в таблице ниже.
В таблице указаны только основные параметры. Вы также можете использовать дополнительные параметры, если они настроены в платежном шлюзе.
Параметр | Описание |
---|---|
mdOrder |
Уникальный номер заказа, хранящийся в платежном шлюзе. |
orderNumber |
Уникальный номер заказа (идентификатор) в системе мерчанта. |
checksum |
Аутентификационный код или контрольная сумма, полученная из набора параметров. |
operation |
Тип события, вызвавшего уведомление:
|
status |
Индикатор успешности операции, указанной в параметре operation :
|
Пользовательские заголовки callback уведомлений
Пользовательские заголовки callback уведомлений можно задать, обратившись в службу технической поддержки. Например:
'http://mybestmerchantreturnurl.com/callback.php', headers={Authorization=token, Content-type=plain
/text}, params={orderNumber=349002, mdOrder=5ffb1899-cd1e-7c1e-8750-e98500093c43, operation=deposited, status=1}
где {Authorization=token, Content-type=plain/text}
– это настраиваемый заголовок.
Примеры
Пример URL-адреса уведомления без контрольной суммы
https://mybestmerchantreturnurl.com/callback/?mdOrder=1234567890-098776-234-522&orderNumber=0987&operation=deposited&status=0
Пример URL-адреса уведомления с контрольной суммой
https://mybestmerchantreturnurl.com/callback/?mdOrder=1234567890-098776-234-522&orderNumber=0987&checksum=DBBE9E54D42072D8CAF32C7F660DEB82086A25C14FD813888E231A99E1220AB3&operation=deposited&status=0
Алгоритм обработки уведомлений о состоянии заказов
В разделах ниже представлен алгоритм обработки уведомлений о состоянии заказов в зависимости от типа таких уведомлений.
Уведомление без контрольной суммы
- Платежный шлюз отправляет на сервер продавца следующий запрос.
https://mybestmerchantreturnurl.com/callback/?mdOrder=1234567890-098776-234-522&orderNumber=0987&operation=deposited&status=0
- Сервер продавца возвращает HTTP-сообщение
200 OK
платежному шлюзу.
Уведомление с контрольной суммой
-
Платежный шлюз отправляет HTTPS-запрос следующего вида на сервер мерчанта, при этом:
- при использовании симметричной криптографии контрольная сумма формируется с помощью ключа, общего для платежного шлюза и продавца;
- при использовании асимметричной криптографии контрольная сумма формируется с помощью закрытого ключа, известного только платежному шлюзу.
https://mybestmerchantreturnurl.com/path?amount=123456&orderNumber=10747&checksum=DBBE9E54D42072D8CAF32C7F660DEB82086A25C14FD813888E231A99E1220AB3&mdOrder=3ff6962a-7dcc-4283-ab50-a6d7dd3386fe&operation=deposited&status=1
Порядок параметров в уведомлении может быть произвольным.
На стороне продавца из строки параметров уведомления удаляются параметры
checksum
иsign_alias
, а значение параметраchecksum
(контрольная сумма) сохраняется для проверки подлинности уведомления;Оставшиеся параметры и их значения используются для создания следующей строки.
имя_параметра1;значение_параметра1;имя_параметра2;значение_параметра2;…;имя_параметраN;значение_параметраN;
В этом случае парыимя_параметра;значение_параметра
должны быть отсортированы в прямом алфавитном порядке (по возрастанию) по именам параметров.
Пример сгенерированной строки параметров:amount;123456;mdOrder;3ff6962a-7dcc-4283-ab50-a6d7dd3386fe;operation;deposited;orderNumber;10747;status;1;
-
Контрольная сумма рассчитывается на стороне мерчанта, способ расчета зависит от способа ее формирования:
- при использовании симметричной криптографии - с помощью алгоритма HMAC-SHA256 и общего с платежным шлюзом закрытого ключа;
- при использовании асимметричной криптографии - с помощью алгоритма хеширования, который зависит от способа создания ключевой пары, и открытого ключа, который связан с закрытым ключом, находящимся на стороне платежного шлюза.
В получившейся строке контрольной суммы все буквы нижнего регистра заменяются на буквы верхнего регистра.
Происходит сравнение полученного значения с контрольной суммой, извлеченной ранее из параметра
checksum
.Если контрольные суммы совпадают, сервер отправляет в платежный шлюз HTTP-код
200 OK
.
Если контрольные суммы совпадают, это уведомление подлинно и было отправлено платежным шлюзом. В противном случае вероятно, что злоумышленник пытается выдать свое уведомление за уведомление платежного шлюза.
Уведомление о статусе платежа
Для того, чтобы определить, прошел ли платеж успешно или нет, вам необходимо:
- Проверить подпись (параметр
checksum
в уведомлении); - Проверять два параметра уведомления обратного вызова:
operation
иstatus
.
Если значение параметра operation
отличается от approved
или deposited
, то уведомление обратного вызова относится к статусу оплаты.
- Approved Successfully → operation = approved & status = 1 (Successful Operation)
- Approval was Declined → operation = approved & status = 0 (Failed Operation)
- Deposited Successfully → operation = deposited & status = 1 (Successful Operation)
- Deposit was Declined → operation = deposited & status = 0 (Failed Operation)
Неуспешные уведомления
Если в платежный шлюз возвращается ответ, отличный от HTTP-кода 200 OK
, отправка уведомления считается неуспешной. В этом случае платежный шлюз повторяет уведомление с интервалом в 30 секунд до тех пор, пока не будет выполнено одно из следующих условий:
- платежный шлюз получает
200 OK
или - происходит три неуспешных попытки информирования подряд.
При достижении одного из указанных выше условий попытки отправки callback-уведомлений об операции прекращаются.
Дополнительные параметры уведомлений обратного вызова
В уведомлениях обратного вызова вы можете использовать следующие дополнительные параметры, если они настроены в платежном шлюзе. Если вы хотите их использовать, свяжитесь с нашей службой поддержки.
Параметр | Описание | Тип события |
---|---|---|
bindingId |
UUIID созданных/обновленных сохраненных учетных данных (связки). | BINDING_CREATED, BINDING_ACTIVITY_CHANGED |
email |
Электронная почта клиента. | BINDING_CREATED |
phone |
Телефон клиента. | BINDING_CREATED |
panMasked |
Маскированный PAN карты клиента. | BINDING_CREATED |
panCountryCode |
Код страны клиента. | BINDING_CREATED |
enabled |
Активна ли связка (true /false ). |
BINDING_ACTIVITY_CHANGED |
currentReverseAmountFormatted |
Форматированная сумма операции отмены. | REVERSED |
currentRefundAmountFormatted |
Отформатированная сумма операции возврата. | REFUNDED |
operationRefundedAmountFormatted |
Отформатированная сумма операции возврата. | REFUNDED |
operationRefundedAmount |
Сумма возврата в минимальных денежных единицах (например, в центах). | REFUNDED |
externalRefundId |
Внешний идентификатор операции возврата. | REFUNDED |
callbackCreationDate |
Дата создания уведомления обратного вызова. Требуется специальная настройка продавца. | DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT, BINDING_CREATED, BINDING_ACTIVITY_CHANGED |
status |
Статус операции: 1 - успех, 0 - неудача | DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT |
operation |
Тип callback-а Possible values: deposited , approved , reversed , refunded , bindingCreated , bindingActivityChanged , declinedByTimeout , declinedCardpresent
|
DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT, BINDING_CREATED, BINDING_ACTIVITY_CHANGED |
finishCheckUrl |
URL для генерации чека | DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT |
sign_alias |
Имя ключа, используемого для подписи. | DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT, BINDING_CREATED, BINDING_ACTIVITY_CHANGED |
checksum |
Контрольная сумма уведомления обратного вызова (используется для уведомлений обратного вызова с контрольной суммой). | DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT, BINDING_CREATED, BINDING_ACTIVITY_CHANGED |
cardholderName |
Имя держателя карты. | DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT |
amount |
Сумма зарегистрированного заказа в минимальных денежных единицах. | DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT |
paymentAmount |
Сумма зарегистрированного заказа в минимальных денежных единицах. | DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT |
amountFormatted |
Отформатированная сумма зарегистрированного заказа. | DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT |
feeAmount |
Сумма комиссии в минимальных единицах валюты. | DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT |
approvedAmount |
Предварительно авторизованная сумма в минимальных денежных единицах. | DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT |
depositedAmount |
Сумма завершения в минимальных денежных единицах. | DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT |
refundedAmount |
Сумма возмещения в минимальных единицах валюты. | DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT |
approvedAmountFormatted |
Отформатированная предварительно авторизованная сумма. | DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT |
depositedAmountFormatted |
Отформатированная сумма зачисления. | DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT |
refundedAmountFormatted |
Отформатированная сумма возврата. | DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT |
totalAmountFormatted |
Отформатированная общая сумма заказа (зарегистрированная сумма + комиссия). | DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT |
depositedTotalAmountFormatted |
Отформатированная общая сумма завершения (все суммы завершения + все суммы возврата + комиссия). | DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT |
approvalCode |
Код авторизации платежа, полученный от процессинга. | DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT |
authCode |
Код авторизации | DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT |
bankName |
Наименование банка, выпустившего карту клиента. | DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT |
currency |
Валюта заказа. | DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT |
depositFlag |
Флаг, указывающий тип операции.
|
DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT |
eci |
Электронный коммерческий индикатор. | DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT |
ip |
IP адрес плательщика. | DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT |
ipCountryCode |
Код страны банка-эмитента. | DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT |
maskedPan |
Маскированный номер карты клиента. | DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT |
mdOrder |
Номер заказа в платежном шлюзе. Уникален в пределах платежного шлюза. | DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT |
mdorder |
Номер заказа в платежном шлюзе. Уникален в пределах платежного шлюза. | DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT |
merchantFullName |
ФИО продавца. | DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT |
merchantLogin |
Логин продавца. | DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT |
orderDescription |
Описание заказа. | DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT |
orderNumber |
Номер заказа (ID) в системе мерчанта. | DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT |
threeDSType |
Вид транзакции (3DS). Возможные значения: SSL , THREE_DS1_FULL , THREE_DS1_ATTEMPT , THREE_DS2_FULL , THREE_DS2_FRICTIONLESS , THREE_DS2_ATTEMPT , THREE_DS2_EXEMPTION_GRANTED , THREE_DS2_3RI , THREE_DS2_3RI_ATTEMPT
|
DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT |
date |
Дата создания заказа. | DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT |
clientId |
Номер клиента (ID) в системе мерчанта. | DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT,BINDING_CREATED, BINDING_ACTIVITY_CHANGED |
actionCode |
Код результата выполнения операции. | DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT |
actionCodeDescription |
Описание кода результата выполнения операции. | DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT |
paymentRefNum |
Reference Retrieval Number - идентификатор транзакции, присвоенный банком-эквайером. | DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT |
paymentState |
Статус заказа. Possible values: started , payment_approved , payment_declined , payment_void , payment_deposited , refunded , pending , partly_deposited
|
DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT |
paymentWay |
Способ оплаты заказа. Дополнительные возможные значения параметра приведены здесь. | DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT |
processingId |
Идентификатор клиента в процессинге. | DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT |
refNum |
Reference Retrieval Number - идентификатор транзакции, присвоенный банком-эквайером. | DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT |
refnum |
Reference Retrieval Number - идентификатор транзакции, присвоенный банком-эквайером. | DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT |
terminalId |
Идентификатор терминала в системе, обрабатывающей платеж. | DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT |
paymentSystem |
Наименование платежной системы. | DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT |
currencyName |
Трехбуквенный ISO-код валюты. | DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT |
transactionAttributes |
Атрибуты заказа. | DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT |
paymentDate |
Дата оплаты заказа. | DEPOSITED, APPROVED, REVERSED, REFUNDED |
depositedDate |
Дата операции завершения по заказу. | DEPOSITED, APPROVED, REVERSED, REFUNDED |
refundedDate |
Дата операции возврата по заказу. | REFUNDED |
reversedDate |
Дата операции отмены заказа. | DEPOSITED, REVERSED, REFUNDED |
declineDate |
Дата отмены заказа. | DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT |
xid |
Индикатор электронной коммерции транзакции, определяемый продавцом. | DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT |
cavv |
Значение проверки аутентификации владельца карты. | DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT |
authValue |
Значение проверки аутентификации владельца карты. | DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT |
sessionExpiredDate |
Дата и время истечения срока действия заказа. | DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT |
tokenizeCryptogram |
Токенизированная криптограмма. | DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT |
creditBankName |
Название банка, выпустившего карту для зачисления (в P2P). | DEPOSITED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT |
creditPanCountryCode |
Код страны карты получателя (в P2P). | DEPOSITED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT |
isInternationalP2P |
Является ли P2P-транзакция межстрановой. | DEPOSITED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT |
recipientData |
Информация о получателе P2P. | DEPOSITED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT |
transactionTypeIndicator |
Информация о получателе P2P. Возможные значения:
|
DEPOSITED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT |
operationType |
Тип операции P2P: AFT/OCT. | DEPOSITED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT |
debitBankName |
Название банка, выпустившего карту для списания (в P2P). | DEPOSITED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT |
debitPanCountryCode |
Код страны карты для списания (в P2P). | DEPOSITED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT |
p2pDebitRrn |
RRN (Reference Retrieval Number) операции списания P2P. | DEPOSITED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT |
avsCode |
Код ответа верификации AVS (проверка адреса и почтового индекса держателя карты). Возможные значения:
|
DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT |
Примеры кода
Симметричная криптография
Java
package net.payrdr.test;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.util.Comparator;
import java.util.Map;
import java.util.stream.Collector;
public class SymmetricCryptographyExample {
private static final String secretToken = "ooc7slpvc61k7sf7ma7p4hrefr";
private static final Map<String, String> callbackParams = Map.of(
"checksum", "EAF2FB72CAB99FD5067F4BA493DD84F4D79C1589FDE8ED29622F0F07215AA972",
"mdOrder", "06cf5599-3f17-7c86-bdbc-bd7d00a8b38b",
"operation", "approved",
"orderNumber", "2003",
"status", "1"
);
public static void main(String[] args) throws Exception {
String signedString = callbackParams.entrySet().stream()
.filter(entry -> !entry.getKey().equals("checksum"))
.sorted(Map.Entry.comparingByKey(Comparator.naturalOrder()))
.collect(Collector.of(
StringBuilder::new,
(accumulator, element) -> accumulator
.append(element.getKey()).append(";")
.append(element.getValue()).append(";"),
StringBuilder::append,
StringBuilder::toString
));
byte[] mac = generateHMacSHA256(secretToken.getBytes(), signedString.getBytes());
String signature = callbackParams.get("checksum");
boolean verified = verifyMac(signature, mac);
System.out.println("signature verification result: " + verified);
}
private static boolean verifyMac(String signature, byte[] mac) {
return signature.equals(bytesToHex(mac));
}
public static byte[] generateHMacSHA256(byte[] hmacKeyBytes, byte[] dataBytes) throws Exception {
SecretKeySpec secretKey = new SecretKeySpec(hmacKeyBytes, "HmacSHA256");
Mac hMacSHA256 = Mac.getInstance("HmacSHA256");
hMacSHA256.init(secretKey);
return hMacSHA256.doFinal(dataBytes);
}
private static String bytesToHex(byte[] bytes) {
final byte[] HEX_ARRAY = "0123456789ABCDEF".getBytes(StandardCharsets.US_ASCII);
byte[] hexChars = new byte[bytes.length * 2];
for (int j = 0; j < bytes.length; j++) {
int v = bytes[j] & 0xFF;
hexChars[j * 2] = HEX_ARRAY[v >>> 4];
hexChars[j * 2 + 1] = HEX_ARRAY[v & 0x0F];
}
return new String(hexChars, StandardCharsets.UTF_8);
}
}
Асимметричная криптография
Java
package net.payrdr.test;
import java.io.ByteArrayInputStream;
import java.io.InputStream;
import java.security.Signature;
import java.security.cert.CertificateFactory;
import java.security.cert.X509Certificate;
import java.util.Base64;
import java.util.Comparator;
import java.util.Map;
import java.util.stream.Collector;
public class AsymmetricCryptographyExample {
private static final Map<String, String> callbackParams = Map.of(
"amount", "35000099",
"sign_alias", "SHA-256 with RSA",
"checksum", "163BD9FAE437B5DCDAAC4EB5ECEE5E533DAC7BD2C8947B0719F7A8BD17C101EBDBEACDB295C10BF041E903AF3FF1E6101FF7DB9BD024C6272912D86382090D5A7614E174DC034EBBB541435C80869CEED1F1E1710B71D6EE7F52AE354505A83A1E279FBA02572DC4661C1D75ABF5A7130B70306CAFA69DABC2F6200A698198F8",
"mdOrder", "12b59da8-f68f-7c8d-12b5-9da8000826ea",
"operation", "deposited",
"status", "1");
private static final String certificate =
"MIICcTCCAdqgAwIBAgIGAWAnZt3aMA0GCSqGSIb3DQEBCwUAMHwxIDAeBgkqhkiG9w0BCQEWEWt6" +
"bnRlc3RAeWFuZGV4LnJ1MQswCQYDVQQGEwJSVTESMBAGA1UECBMJVGF0YXJzdGFuMQ4wDAYDVQQH" +
"EwVLYXphbjEMMAoGA1UEChMDUkJTMQswCQYDVQQLEwJRQTEMMAoGA1UEAxMDUkJTMB4XDTE3MTIw" +
"NTE2MDEyMFoXDTE4MTIwNTE2MDExOVowfDEgMB4GCSqGSIb3DQEJARYRa3pudGVzdEB5YW5kZXgu" +
"cnUxCzAJBgNVBAYTAlJVMRIwEAYDVQQIEwlUYXRhcnN0YW4xDjAMBgNVBAcTBUthemFuMQwwCgYD" +
"VQQKEwNSQlMxCzAJBgNVBAsTAlFBMQwwCgYDVQQDEwNSQlMwgZ8wDQYJKoZIhvcNAQEBBQADgY0A" +
"MIGJAoGBAJNgxgtWRFe8zhF6FE1C8s1t/dnnC8qzNN+uuUOQ3hBx1CHKQTEtZFTiCbNLMNkgWtJ/" +
"CRBBiFXQbyza0/Ks7FRgSD52qFYUV05zRjLLoEyzG6LAfihJwTEPddNxBNvCxqdBeVdDThG81zC0" +
"DiAhMeSwvcPCtejaDDSEYcQBLLhDAgMBAAEwDQYJKoZIhvcNAQELBQADgYEAfRP54xwuGLW/Cg08" +
"ar6YqhdFNGq5TgXMBvQGQfRvL7W6oH67PcvzgvzN8XCL56dcpB7S8ek6NGYfPQ4K2zhgxhxpFEDH" +
"PcgU4vswnhhWbGVMoVgmTA0hEkwq86CA5ZXJkJm6f3E/J6lYoPQaKatKF24706T6iH2htG4Bkjre" +
"gUA=";
public static void main(String[] args) throws Exception {
String signedString = callbackParams.entrySet().stream()
.filter(entry -> !entry.getKey().equals("checksum") && !entry.getKey().equals("sign_alias"))
.sorted(Map.Entry.comparingByKey(Comparator.naturalOrder()))
.collect(Collector.of(
StringBuilder::new,
(accumulator, element) -> accumulator
.append(element.getKey()).append(";")
.append(element.getValue()).append(";"),
StringBuilder::append,
StringBuilder::toString
));
InputStream publicCertificate = new ByteArrayInputStream(Base64.getDecoder().decode(certificate));
String signature = callbackParams.get("checksum");
boolean verified = checkSignature(signedString.getBytes(), signature.getBytes(), publicCertificate);
System.out.println("signature verification result: " + verified);
}
private static boolean checkSignature(byte[] signedString, byte[] signature, InputStream publicCertificate) throws Exception {
CertificateFactory certFactory = CertificateFactory.getInstance("X.509");
X509Certificate x509Cert = (X509Certificate) certFactory.generateCertificate(publicCertificate);
Signature signatureAlgorithm = Signature.getInstance("SHA512withRSA");
signatureAlgorithm.initVerify(x509Cert.getPublicKey());
signatureAlgorithm.update(signedString);
return signatureAlgorithm.verify(decodeHex(new String(signature)));
}
private static byte[] decodeHex(String hex) {
int l = hex.length();
byte[] data = new byte[l / 2];
for (int i = 0; i < l; i += 2) {
data[i / 2] = (byte) ((Character.digit(hex.charAt(i), 16) << 4)
+ Character.digit(hex.charAt(i + 1), 16));
}
return data;
}
}
Симметричная криптография
PHP
<?php
$data = 'amount;123456;mdOrder;3ff6962a-7dcc-4283-ab50-a6d7dd3386fe;operation;deposited;orderNumber;10747;status;1;';
$key = 'yourSecretToken';
$hmac = hash_hmac ( 'sha256' , $data , $key);
echo "[$hmac]\n";
?>
- Присвойте строковое значение переменной
data
. - Присвойте значение закрытого ключа переменной
key
. - Функция
hash_hmac
( 'sha256', $data, $key) вычисляет контрольную сумму от переданной строки, с помощью закрытого ключа по алгоритму SHA-256. - Сохраните результат работы функции в переменной
hmac
. - Выведите результат работы функции командой
echo
. - Сравните это значение с тем, что передано в уведомлении о состоянии заказа.
Асимметричная криптография
PHP
<?php
// data from response
$data = 'amount;35000099;mdOrder;12b59da8-f68f-7c8d-12b5-9da8000826ea;operation;deposited;status;1;';
$checksum = '9524FD765FB1BABFB1F42E4BC6EF5A4B07BAA3F9C809098ACBB462618A9327539F975FEDB4CF6EC1556FF88BA74774342AF4F5B51BA63903BE9647C670EBD962467282955BD1D57B16935C956864526810870CD32967845EBABE1C6565C03F94FF66907CEDB54669A1C74AC1AD6E39B67FA7EF6D305A007A474F03B80FD6C965656BEAA74E09BB1189F4B32E622C903DC52843C454B7ACF76D6F76324C27767DE2FF6E7217716C19C530CA7551DB58268CC815638C30F3BCA3270E1FD44F63C14974B108E65C20638ECE2F2D752F32742FFC5077415102706FA5235D310D4948A780B08D1B75C8983F22F211DFCBF14435F262ADDA6A97BFEB6D332C3D51010B';
// your public key (e.g. SHA-512 with RSA)
// if you have a CERT, please see openssl_get_publickey()
$publicKey = <<<EOD
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwtuGKbQ4WmfdV1gjWWys
5jyHKTWXnxX3zVa5/Cx5aKwJpOsjrXnHh6l8bOPQ6Sgj3iSeKJ9plZ3i7rPjkfmw
qUOJ1eLU5NvGkVjOgyi11aUKgEKwS5Iq5HZvXmPLzu+U22EUCTQwjBqnE/Wf0hnI
wYABDgc0fJeJJAHYHMBcJXTuxF8DmDf4DpbLrQ2bpGaCPKcX+04POS4zVLVCHF6N
6gYtM7U2QXYcTMTGsAvmIqSj1vddGwvNGeeUVoPbo6enMBbvZgjN5p6j3ItTziMb
Vba3m/u7bU1dOG2/79UpGAGR10qEFHiOqS6WpO7CuIR2tL9EznXRc7D9JZKwGfoY
/QIDAQAB
-----END PUBLIC KEY-----
EOD;
$binarySignature = hex2bin(strtolower($checksum));
$isVerify = openssl_verify($data, $binarySignature, $publicKey, OPENSSL_ALGO_SHA512);
if ($isVerify == 1) {
echo "signature ok\n";
} elseif ($isVerify == 0) {
echo "bad (there's something wrong)\n";
} else {
echo "error checking signature\n";
}
?>