For any question, we are one click away

Contact us

Общо описание

Можете да използвате нашето API за търговци, за да създадете необходимия ви сценарий за плащане. Например, можете да създадете собствена напълно настроена платежна страница и да я свържете с нашия платежен шлюз.

Можете да изтеглите колекция от API заявки за Postman, за да тествате основните възможности на API. Задължително изпращайте заявки като POST с атрибути в тялото на заявката.

sandbox_eCommerce.postman_collection.jsonИзтегляне на колекция Postman

Задължителност на параметрите

Задължителността за присъствие на параметъра в заявката/отговора може да приеме следните стойности:

Задължителността за предаване на параметъра в описанието на заявката/отговора се указва в едноименната колона "Задължителност".

Автентикация

За автентикация на търговеца в платежната система могат да се използват два метода.

ЗадължителностНазваниеТипОписание
УсловиеuserNameString [1..50]Потребителско име на API акаунта на продавача. Ако за удостоверяване при регистрация вместо потребителско име и парола се използва открит токен (параметър token), паролата не е необходимо да се предава.
УсловиеpasswordString [1..30]Парола на API акаунта на продавача. Ако за удостоверяване при регистрация вместо логин и парола се използва открит токен (параметър token), паролата не е необходимо да се предава.
ЗадължителностНазваниеТипОписание
УсловиеtokenString [1..256]Стойност, използвана за автентификация на продавача при изпращане на заявки към платежната шлюз. Ако предавате този параметър, то не предавайте userName и password.

URL за API-извиквания

TEST: https://uat.dskbank.bg/payment/rest/
PROD: https://epg.dskbank.bg/payment/rest/

Грешки

HTTP статус кодове:

Ако заявката, свързана с плащането на поръчка, е обработена успешно, това още не означава, че самото плащане е преминало успешно.

За да определите дали плащането е било успешно или не, можете да се обърнете към описанието на използваната заявка. Също така за изясняване статуса на плащането винаги може да се използва алгоритъмът, описан по-долу

  1. Извикайте getOrderStatusExtended.do;
  2. Проверете полето orderStatus в отговора: поръчката се счита за платена, само ако стойността на orderStatus е равна на 1 или 2.

Подпис на заявка API

В някои случаи за осигуряване на безопасен обмен на данни може да се изисква реализиране на асиметричен подпис на заявката. Обикновено това изискване се прилага само ако изпълнявате заявки P2P/AFT/OCT.

За да имате възможност да подписвате заявки, трябва да изпълните следните стъпки:

  1. Създайте и качете сертификат.
  2. Изчислете хеш и подпис, използвайки вашия частен ключ, и предайте генерирания хеш (X-Hash) и стойността на подписа (X-Signature) в заглавието на заявката.

Тези стъпки са подробно описани по-долу.

Създаване и качване на сертификат

  1. Създайте 2048-битов частен ключ RSA. Начинът на генериране зависи от политиката за поверителност във вашата компания. Например, можете да направите това с помощта на OpenSSL:

    openssl genrsa -des3 -out private.key 2048

  2. Създайте публичен CSR (заявка за подписване на сертификат), използвайки генерирания частен ключ:

    openssl req -key private.key -new -out public.csr

  3. Създайте сертификат, използвайки генерирания частен ключ и CSR. Пример за формиране на сертификат за 5 години:

    openssl x509 -signkey private.key -in public.csr -req -days 1825 -out public.cer

  4. Качете генерирания сертификат в Личен кабинет. За това отидете в Сертификати на портфейли > Merchant API, натиснете Добави сертификат и качете генерирания публичен сертификат.


JCC installments final page

Изчисляване на хеш и подпис

  1. Изчислете хеш SHA256 на тялото на заявката по следния начин:

  2. Използвайте тялото на заявката под формата на низ (в нашия пример това е amount=10000&password=gcjgcW1&returnUrl=http&userName=signature-api).

  3. Изчислете хеш SHA256 от този низ в необработени байтове.

  4. Преобразувайте необработените байтове в кодиране base64.

  5. Генерирайте подпис за изчисления хеш 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://uat.dskbank.bg/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'

Заявката трябва да отговаря на следните изисквания:

Пример код 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 {

    // Този пример не е готов за производство. Той просто показва как да използвате подписи в API.
    public static void main(String[] args) throws Exception {
        // зареди частен ключ от 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);

        // Подпиши
        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();

        // Изпрати
        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&currency=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://uat.dskbank.bg/payment/rest/register.do.


При изпълнение на заявката е необходимо да се използва заглавка: Content-Type: application/x-www-form-urlencoded

Параметри на заявката

ЗадължителностИмеТипОписание
УсловноuserNameString [1..50]Потребителско име на API акаунта на продавача. Ако за удостоверяване при регистрация вместо потребителско име и парола се използва открит токен (параметър token), паролата не е необходимо да се предава.
УсловноpasswordString [1..30]Парола на API акаунта на продавача. Ако за удостоверяване при регистрация вместо логин и парола се използва открит токен (параметър token), паролата не е необходимо да се предава.
УсловноtokenString [1..256]Стойност, използвана за автентификация на продавача при изпращане на заявки към платежната шлюз. Ако предавате този параметър, то не предавайте userName и password.
ЗадължителноorderNumberString [1..36]Номер на поръчката (ID) в системата на търговеца; трябва да бъде уникален за всяка поръчка.
ЗадължителноamountInteger [0..12]Сума на плащането в минимални единици валута (например, в стотинки).
ЗадължителноcurrencyString [3]Код на валутата на плащането ISO 4217. Ако не е посочен, се използва стойността по подразбиране. Позволени са само цифри.
ЗадължителноreturnUrlString [1..512]Адрес, към който трябва да бъде пренасочен потребителят в случай на успешно плащане. Адресът трябва да бъде указан изцяло, включително използвания протокол (например, https://mybestmerchantreturnurl.com вместо mybestmerchantreturnurl.com). В противен случай потребителят ще бъде пренасочен на адрес от следния вид: https://uat.dskbank.bg/payment/<merchant_address>.
НезадължителноfailUrlString [1..512]Адрес, на който трябва да се пренасочи потребителят в случай на неуспешно плащане. Адресът трябва да бъде посочен напълно, включително използвания протокол (например, https://mybestmerchantreturnurl.com вместо mybestmerchantreturnurl.com). В противен случай потребителят ще бъде пренасочен по адрес от следния вид: https://uat.dskbank.bg/payment/<merchant_address>.
НезадължителноdynamicCallbackUrlString [1..512]Параметър за предаване на динамичен адрес за получаване на "платежни" callback-уведомления за поръчката, активирани за търговеца (успешна авторизация, успешно списване, връщане, отказ, отхвърляне на плащане по таймаут, отхвърляне на card present плащане).
"Не платежни" callback-уведомления (включване/изключване на връзка, създаване на връзка), ще бъдат изпращани на статичен callback адрес.
НезадължителноdescriptionString [1..598]Описание на поръчката в произволен формат.
За да включите изпращането на това поле в процесинговата система, обърнете се към службата за техническа поддръжка.
В това поле е недопустимо да се предават лични данни или платежни данни (номера на карти и т.н.). Това изискване се дължи на факта, че описанието на поръчката никъде не се маскира.
НезадължителноlanguageString [2]Ключ на езика по ISO 639-1. Ако езикът не е указан, се използва езикът по подразбиране, указан в настройките на магазина.
Поддържани езици: en,ru,el,ro,bg,pt,sw,hu,it,pl,de,fr,kh,cn,es,ka,da,et,fi,lt,lv,nl,sv.
НезадължителноipString [1..39]IP адрес на платеца. IPv6 се поддържа във всички заявки (до 39 символа).
НезадължителноclientIdString [0..255]Номер на клиента (ID) в системата на търговеца — до 255 символа. Използва се за реализиране на функционалността на връзките. Може да се връща в отговора, ако на търговеца е разрешено да създава връзки.
Указването на този параметър при обработка на плащания по връзка е задължително. В противен случай плащането ще бъде невъзможно.
НезадължителноmerchantLoginString [1..255]За да регистрирате поръчка от името на друг търговец, посочете неговия логин (за API-акаунт) в този параметър.
Може да се използва само ако имате разрешение за преглед на транзакциите на други продавачи или ако посоченият продавач е ваш дъщерен продавач.
НезадължителноcardholderNameString [1..150]Име на притежателя на картата с латински букви. При предаване на този параметър името на притежателя на картата ще бъде показано на страницата за плащане.
НезадължителноjsonParamsObjectНабор от допълнителни атрибути с произволна форма, структура:
jsonParams={"param_1_name":"param_1_value",...,"param_n_name":"param_n_value"}
Могат да бъдат предадени в Процесинговия Център, за последваща обработка (изисква се допълнителна настройка - обърнете се към поддръжката).
Някои предопределени атрибути jsonParams:
  • backToShopUrl - добавя на страницата за плащане бутон, който ще върне притежателя на картата на URL-адреса предаден в този параметър
  • backToShopName - настройва текстовия етикет на бутона Върни се в магазина по подразбиране, ако се използва заедно с backToShopUrl
  • recurringFrequency - минимален брой дни между оторизациите. Изисква се за създаване на рекурентна връзка, препоръчва се за създаване на връзка за разсрочване (ако се използва 3DS2, параметърът е задължителен).
  • recurringExpiry - дата, след която оторизациите не са разрешени, във формат ГГГГММДД. Изисква се за създаване на рекурентна връзка, препоръчва се за създаване на връзка за разсрочване (ако се използва 3DS2, параметърът е задължителен).
НезадължителноsessionTimeoutSecsInteger [1..9]Продължителност на живота на поръчката в секунди. В случай че параметърът не е зададен, ще бъде използвана стойността, указана в настройките на търговеца, или времето по подразбиране (1200 секунди = 20 минути). Ако в заявката присъства параметър expirationDate, то стойността на параметър sessionTimeoutSecs не се взема предвид.
НезадължителноexpirationDateString [19]Дата и час на изтичане на срока на валидност на поръчката. Формат: yyyy-MM-ddTHH:mm:ss.
Ако този параметър не се предава в заявката, то за определяне на времето на изтичане на срока на валидност на поръчката се използва параметърът sessionTimeoutSecs.
НезадължителноbindingIdString [1..255]Идентификатор на вече съществуваща връзка (идентификатор на карта, токенизирана от gateway). Може да се използва само ако търговецът има разрешение за работа с връзки. Ако този параметър се предава в тази заявка, това означава, че:
  • Тази поръчка може да бъде платена само чрез връзка;
  • Платецът ще бъде пренасочен към страница за плащане, където се изисква само въвеждане на CVC.
НезадължителноfeaturesStringФункции на поръчката. За да посочите няколко функции, използвайте този параметър няколко пъти в една заявка. По-долу са изброени възможните стойности.
  • VERIFY - ако се предаде тази стойност в заявката за оформяне на поръчка, притежателят на картата ще бъде верифициран, но няма да се извърши списване на средства, така че в този случай параметърът amount може да има стойност 0. Верификацията позволява да се убедите, че картата се намира в ръцете на притежателя, и впоследствие да списвате от тази карта средства, без да прибягвате до проверка на автентификационните данни (CVC, 3D-Secure) при извършване на последващи плащания. Дори ако сумата на плащането бъде предадена в заявката, тя няма да бъде списана от сметката на клиента при предаване на стойността VERIFY. Тази стойност също може да се използва за създаване на връзка — в този случай параметърът clientId също трябва да бъде предаден. Подробности четете тук.
  • FORCE_TDS - Принудително извършване на плащане с използване на 3-D Secure. Ако картата не поддържа 3-D Secure, транзакцията няма да премине.
  • FORCE_SSL - Принудително извършване на плащане чрез SSL (без използване на 3-D Secure).
  • FORCE_FULL_TDS - След извършване на автентификация с помощта на 3-D Secure статусът PaRes трябва да бъде само Y, което гарантира успешна автентификация на потребителя. В противен случай транзакцията няма да премине.
  • FORCE_CREATE_BINDING - предаването на тази стойност в заявката за оформяне на поръчка принудително създава връзка. Тази функционалност трябва да бъде включена на ниво продавач в шлюза. Тази стойност не може да се предаде в заявка със съществуващ bindingId или bindingNotNeeded = true (ще предизвика грешка при проверка). Когато се предава тази функция, параметърът clientId също трябва да бъде предаден. Ако в блока features се предадат и двете стойности FORCE_CREATE_BINDING и VERIFY, тогава поръчката ще бъде създадена САМО за създаване на връзка (без плащане).
НезадължителноpostAddressString [1..255]Адрес за доставка.
НезадължителноmarketplaceObjectБлок с параметри на маркетплейса, т.е. на продавача, който предлага стоки или услуги от различни търговци на дребно (ритейлъри).
Този параметър се използва, ако е включена специална настройка (обърнете се към службата за поддръжка). Вж. вложени параметри.
НезадължителноorderBundleObjectОбект, съдържащ кошницата с продукти. Описанието на вложените елементи е дадено по-долу.
НезадължителноfeeInputInteger [0..8]Размер на комисионната в минимални единици валута. Функционалността трябва да бъде включена на ниво продавач в gateway-я.
УсловноemailString [1..40]Електронна поща за показване на платежната страница. Ако за продавача са настроени уведомления на клиента, електронната поща трябва да бъде посочена. Пример: client_mail@email.com.
Адресът на електронната поща не се проверява при регистрация, той ще бъде проверен по-късно при плащане.
НезадължителноmccInteger [4]Merchant Category Code (код на категория на търговеца).
За предаване на този параметър е необходимо специално разрешение. Могат да се използват стойности само от разрешения списък MCC. За получаване на по-подробна информация се обърнете към техническата поддръжка.
НезадължителноmvvString [1..10]Потвърждение на търговеца от Mastercard за токенизирани транзакции.
За предаване на този параметър трябва да бъде включена специална настройка (обърнете се към техническата поддръжка).
НезадължителноpaymentFacilitatorObjectБлок с информация за платежния фасилитатор, т.е. за търговеца, който позволява на няколко субтърговци да приемат плащания под неговия акаунт.
За предаване на този параметър трябва да бъде включена специална настройка (обърнете се към техническата поддръжка). Вж. вложени параметри.
НезадължителноbillingPayerDataObjectБлок с регистрационни данни на клиента (адрес, пощенски код), необходим за преминаване на проверка на адреса в рамките на услугите AVS/AVV. Задължително, ако функцията е включена за продавача от страна на Платежния шлюз. Вж вложени параметри.
НезадължителноshippingPayerDataObjectОбект, съдържащ данни за доставката до клиента. Този параметър се използва за по-нататъшна 3DS-автентификация на клиента. Вж. вложени параметри.
НезадължителноpreOrderPayerDataObjectОбект, съдържащ данни за предварителната поръчка. Този параметър се използва за по-нататъшна 3DS-автентификация на клиента. Вж. вложени параметри.
НезадължителноorderPayerDataObjectОбект, съдържащ данни за платеца на поръчката. Този параметър се използва за по-нататъшна 3DS-автентификация на клиента. Вж. вложени параметри.
НезадължителноbillingAndShippingAddressMatchIndicatorString [1]Индикатор за съответствие на платежния адрес на притежателя на картата и адреса за доставка. Този параметър се използва за по-нататъшна 3DS-автентификация на клиента.
Възможни стойности:
  • Y - съвпадение на платежния адрес на притежателя на картата и адреса за доставка;
  • N - платежният адрес на притежателя на картата и адресът за доставка не съвпадат.

По-долу са посочени параметрите на блока billingPayerData (данни за адреса за регистрация на клиента).

ЗадължителностИмеТипОписание
НезадължителноbillingCityString [0..50]Град, регистриран за конкретната карта в Банката Емитент.
НезадължителноbillingCountryString [0..50]Страна, регистрирана за конкретната карта на банката-издател. Формат: ISO 3166-1 (Alpha 2 / Alpha 3 / Number-3) или наименование на страната. Препоръчваме предаване на двубуквен/трибуквен ISO код на страната.
НезадължителноbillingAddressLine1String [0..50]Адрес, регистриран по конкретна карта в Банката Емитент (адрес на платеца). Ред 1. Задължително за предаване за AVS-проверка.
НезадължителноbillingAddressLine2String [0..50]Адрес, регистриран за конкретната карта в Банката Емитент. Ред 2.
НезадължителноbillingAddressLine3String [0..50]Адрес, регистриран за конкретната карта в Банката Емитент. Ред 3.
НезадължителноbillingPostalCodeString [0..9]Пощенски код, регистриран за конкретната карта в Банката Издател. Задължително за предаване за AVS-проверка.
НезадължителноbillingStateString [0..50]Щат, регистриран за конкретната карта в Банката Емитент. Формат: пълна стойност на кода ISO 3166-2, негова част или наименование на щата/региона. Може да съдържа букви само от латинската азбука. Препоръчваме да се предава двубуквен ISO код на щата/региона.
ЗадължителноpayerAccountString [1..32]Номер на сметката на изпращача.
НезадължителноpayerLastNameString [1..64]Фамилия на изпращача.
НезадължителноpayerFirstNameString [1..35]Име на изпращача.
НезадължителноpayerMiddleNameString [1..35]Бащино име на изпращача.
НезадължителноpayerCombinedNameString [1..99]Пълно име на подателя.
НезадължителноpayerIdTypeString [1..8]Тип на предоставения идентифициращ документ на подателя.
Възможни стойности:
  • IDTP1 - Паспорт
  • IDTP2 - Шофьорска книжка
  • IDTP3 - Социална карта
  • IDTP4 - ID карта на гражданин
  • IDTP5 - Сертификат за водене на бизнес
  • IDTP6 - Сертификат на бежанец
  • IDTP7 - Разрешително за пребиваване
  • IDTP8 - Чужд паспорт
  • IDTP9 - Служебен паспорт
  • IDTP10 - Временен паспорт
  • IDTP11 - Паспорт на моряк
НезадължителноpayerIdNumberString [1..100]Номер на предоставения идентифициращ документ (например, паспорт) на изпращача.
НезадължителноpayerBirthdayString [1..20]Дата на раждане на изпращача във формат YYYYMMDD.

Описание на параметрите на обект shippingPayerData:

ЗадължителностНаименованиеТипОписание
НезадължителноshippingCityString [1..50]Град на поръчителя (от адреса за доставка)
НезадължителноshippingCountryString [1..50]Страна на поръчителя
НезадължителноshippingAddressLine1String [1..50]Основен адрес на клиента (от адреса за доставка)
НезадължителноshippingAddressLine2String [1..50]Основен адрес на клиента (от адреса за доставка)
НезадължителноshippingAddressLine3String [1..50]Основен адрес на клиента (от адреса за доставка)
НезадължителноshippingPostalCodeString [1..16]Пощенски код на клиента за доставка
НезадължителноshippingStateString [1..50]Щат/регион на купувача (от адреса за доставка)
НезадължителноshippingMethodIndicatorInteger [2]Индикатор за начин на доставка.
Възможни стойности:
  • 01 - доставка на платежния адрес на притежателя на карта.
  • 02 - доставка на друг адрес, проверен от Търговеца.
  • 03 - доставка на адрес, различен от основния адрес на притежателя на карта.
  • 04 - изпращане в магазин/самовземане (адресът на магазина трябва да бъде указан в съответните параметри за доставка)
  • 05 - Цифрово разпространение (включва онлайн услуги и електронни подаръчни карти)
  • 06 - билети за пътувания и събития, които не могат да бъдат доставени.
  • 07 - Други (например игри, цифрови стоки, които не подлежат на доставка, цифрови абонаменти и т.н.)
НезадължителноdeliveryTimeframeInteger [2]Срок за доставка на стоката.
Възможни стойности:
  • 01 - цифрова дистрибуция
  • 02 - доставка в същия ден
  • 03 - доставка на следващия ден
  • 04 - доставка в рамките на 2 дни след плащането и по-късно.
НезадължителноdeliveryEmail String [1..254]Целеви адрес на електронна поща за доставка на цифрово разпространение. Препоръчително е да предавате електронната поща в самостоятелен параметър на заявката email (но ако я предадете в този блок, към нея ще се прилагат същите правила).

Описание на параметрите на обекта preOrderPayerData:

ЗадължителностНаименованиеТипОписание
НезадължителноpreOrderDateString [10]Очаквана дата на доставка (за предварително поръчани покупки) във формат ГГГГММДД.
НезадължителноpreOrderPurchaseIndInteger [2]Индикатор за разполагане от клиента на поръчка за налична или бъдеща доставка.
Възможни стойности:
  • 01 - възможна е доставка;
  • 02 - бъдеща доставка
НезадължителноreorderItemsIndInteger [2]Индикатор, че клиентът преподръчва преди заплатена доставка в състава на нова поръчка.
Възможни стойности:
  • 01 - поръчката се разполага за първи път;
  • 02 - повторна поръчка

Описание на параметрите на обект orderPayerData.

ЗадължителностНаименованиеТипОписание
НезадължителноhomePhoneString [7..15]Домашен телефон на притежателя на картата. Необходимо е винаги да се посочва код на страната, но знакът + или 00 в началото може да се посочи или пропусне. Номерът трябва да има дължина от 7 до 15 цифри. По този начин са възможни следните стойности:
  • +35799988877;
  • 0035799988877;
  • 35799988877.
НезадължителноworkPhoneString [7..15]Служебен телефон на притежателя на картата. Необходимо е винаги да се посочва код на страната, но знакът + или 00 в началото може да се посочи или пропусне. Номерът трябва да има дължина от 7 до 15 цифри. По този начин са възможни следните стойности:
  • +35799988877;
  • 0035799988877;
  • 35799988877.
НезадължителноmobilePhoneString [7..15]Номер на мобилния телефон на притежателя на картата. Необходимо е винаги да се посочва код на страната, но знакът + или 00 в началото може да се посочи или пропусне. Номерът трябва да има дължина от 7 до 15 цифри. По този начин са възможни следните стойности:
  • +35799988877;
  • 0035799988877;
  • 35799988877.

За плащания по VISA с 3DS авторизация е необходимо да се посочи или електронна поща, или номер на телефон на притежателя на картата. Ако имате настроено показване на номера на телефона на платежната страница и сте посочили неверен номер на телефон, клиентът ще може да го поправи на платежната страница.

Описание на параметрите на обекта marketplace:

ЗадължителностИмеТипОписание
ЗадължителноmarketplaceIdString [1..11]Идентификатор на маркетплейса в банката-акуайър.
УсловноforeignRetailerIndicatorBooleanУказва дали маркетплейсът има чуждестранни ритейлъри (дъщерни търговци). Ако в обекта marketplace се предава блок retailers, този параметър не е задължително да се предава, в противен случай – задължително.
НезадължителноretailersArray of objectsМасив от ритейлъри (дъщерни продавачи на маркетплейса). Съдържа само 1 елемент. Вложените елементи са описани по-долу.

Описание на параметрите на обекта, който е елемент от масива retailers.

ЗадължителностИмеТипОписание
ЗадължителноforeignRetailerIndicatorBooleanОпределя дали търговецът е чуждестранен.

Пример на обекта marketplace:

"marketplace": {
    "marketplaceId": "MKT12345678",
    "foreignRetailerIndicator": true,
    "retailers": [
        {
            "foreignRetailerIndicator": false
        }
    ]
}

Описание на параметрите в обекта orderBundle:

ЗадължителностИмеТипОписание
НезадължителноorderCreationDateString [19]Дата на създаване на поръчката във формат YYYY-MM-DDTHH:MM:SS.
НезадължителноcustomerDetailsObjectБлок, съдържащ атрибутите на клиента. Описанието на атрибутите на тага е дадено по-долу.
ЗадължителноcartItemsObjectОбект, съдържащ атрибутите на стоките в кошницата. Описанието на вложените елементи е дадено по-долу.

Описание на параметрите в обект customerDetails:

ЗадължителностНаименованиеТипОписание
НезадължителноcontactString [0..40]Предпочитан от клиента начин за връзка.
НезадължителноfullNameString [1..100]ФИО на платеца.
НезадължителноpassportString [1..100]Серия и номер на паспорта на платеца в следния формат: 2222888888
НезадължителноdeliveryInfoObjectОбект, съдържащ атрибутите на адреса за доставка. Описанието на вложените елементи е приведено по-долу.

Описание на параметрите в обекта deliveryInfo:

ЗадължителностНаименованиеТипОписание
НезадължителноdeliveryTypeString [1..20]Начин на доставка.
ЗадължителноcountryString [2]Двубуквен код на страната за доставка.
ЗадължителноcityString [0..40]Град на назначение.
ЗадължителноpostAddressString [1..255]Адрес за доставка.

Описание на параметрите в обекта cartItems:

ЗадължителностНаименованиеТипОписание
ЗадължителноitemsObjectЕлемент на масив с атрибути на стокова позиция. Описанието на вложените елементи е дадено по-долу.

Описание на параметрите в обект items:

ЗадължителностНаименованиеТипОписание
ЗадължителноpositionIdInteger [1..12]Уникален идентификатор на стоковата позиция в кошницата.
ЗадължителноnameString [1..255]Наименование или описание на стокова позиция в свободна форма.
НезадължителноitemDetailsObjectОбект с параметри за описанието на стоковата позиция. Описанието на вложените елементи е приведено по-долу.
ЗадължителноquantityObjectЕлемент, описващ общото количество стокови позиции на един positionId и неговите мерни единици. Описанието на вложените елементи е приведено по-долу.
НезадължителноitemAmountInteger [1..12]Сума на стойността на всички стокови позиции за един positionId в минимални единици валута. itemAmount е задължителен за предаване, само ако не е предаден параметърът itemPrice. В противен случай предаването на itemAmount не се изисква. Ако в заявката се предават и двата параметъра: itemPrice и itemAmount, то itemAmount трябва да се равнява на itemPrice * quantity, в противен случай заявката ще завърши с грешка.
НезадължителноitemPriceInteger [1..18]Сума на стойността на стоковата позиция на един positionId в пари в минимални единици валута.
НезадължителноdepositedItemAmountString [1..18]Сума на списване за един positionId в минимални валутни единици (например, в стотинки).
НезадължителноitemCurrencyInteger [3]Код на валута ISO 4217. Ако не е посочен, се счита равен на валутата на поръчката.
ЗадължителноitemCodeString [1..100]Номер (идентификатор) на стокова позиция в системата на магазина.

Описание на параметрите в обект quantity:

ЗадължителностИмеТипОписание
ЗадължителноvalueNumber [1..18]Количество на стокови позиции от дадения positionId. За указване на дробни числа използвайте десетична точка. Допуска се максимум 3 знака след точката.
ЗадължителноmeasureString [1..20]Мерна единица за количеството по позицията.

Описание на параметрите в обекта itemDetails:

ЗадължителностНазваниеТипОписание
НезадължителноitemDetailsParamsObjectПараметър, описващ допълнителна информация по стоковата позиция. Описанието на вложените елементи е приведено по-долу.

Описание на параметрите в обекта itemDetailsParams:

ЗадължителностНаименованиеТипОписание
ЗадължителноvalueString [1..2000]Допълнителна информация за товарната позиция.
ЗадължителноnameString [1..255]Наименование на параметъра за описанието на детайлизацията на стоковата позиция

Описание на параметрите на обекта paymentFacilitator:

ЗадължителностНаименованиеТипОписание
ЗадължителноpfIdString [1..11]Идентификатор на платежния фасилитатор.
ЗадължителноnameString [1..40]Наименование на платежния фасилитатор.
НезадължителноisoIdString [1..11]Идентификатор ISO.
ЗадължителноsubMerchantsArray of objectsМасив от обекти с допълнителна информация за субмерчантите. Вж. вложените параметри по-долу.

Параметри на елемента от масива subMerchants:

ЗадължителностНаименованиеТипОписание
ЗадължителноsubMerchantIdString [1..20]Идентификатор на субмерчанта.
ЗадължителноnameString [1..40]Наименование на субмерчанта.
ЗадължителноaddressObjectБлок с информация за адреса на субмерчанта. Вж. вложените параметри по-долу.

Параметри на обекта address:

ЗадължителностНаименованиеТипОписание
ЗадължителноcityString [1..50]Град на субмерчанта.
ЗадължителноpostalCodeString [1..16]Пощенски код на субмерчанта.
ЗадължителноcountryInteger [2]Код на страната на субмерчанта във формат ISO 3166-1.
НезадължителноstreetString [1..40]Улица на субмерчанта.

Пример за обекта paymentFacilitator:

"paymentFacilitator" :{
  "pfId": "PF123456",
  "name": "Payment Facilitator Name",
  "isoId": "ISO789",
  "subMerchants": [
    {
      "subMerchantId": "SM001",
      "name": "Sub Merchant 1",
      "address": {
        "city": "City 1",
        "postalCode": "101000",
        "country": "US",
        "street": "Street 1"
      }
    },
    {
      "subMerchantId": "SM002",
      "name": "Sub Merchant 2",
      "address": {
        "city": "City 2",
        "postalCode": "190000",
        "country": "US",
        "street": "Street 2"
      }
    }
  ]
}

Параметри на отговора

ЗадължителностИмеТипОписание
НезадължителноerrorCodeString [1..2]Информационен параметър в случай на грешка, който може да има различни кодови стойности:
  • стойност 0 - указва успех на обработката на заявката;
  • друга числова стойност (1-99) - указва грешка, за получаване на по-подробна информация за която е необходимо да се провери параметър errorMessage.
Може да отсъства, ако резултатът не е предизвикал грешки.
НезадължителноerrorMessageString [1..512]Информационен параметър, който представлява описание на грешката в случай на възникване на грешка. Стойността на errorMessage може да варира, затова не трябва да се препраща изрично към неговите стойности в кода.
Езикът на описанието се задава в параметъра language на заявката.
НезадължителноformUrlString [1..512]URL на платежната форма, към която ще бъде пренасочен купувачът. URL не се връща, ако регистрацията на поръчката не е преминала поради грешка, посочена в errorCode.
НезадължителноorderIdString [1..36]Номер на поръчката в платежния шлюз. Уникален в рамките на платежния шлюз.

Примери

Ример за заявка

curl --request POST \
  --url https://uat.dskbank.bg/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 features=FORCE_SSL \
  --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://uat.dskbank.bg/payment/payment/merchants/ecom/payment_en.html?mdOrder=01491d0b-c848-7dd6-a20d-e96900a7d8c0"
}

Ример за отговор - грешка

{
  "errorCode": "1",
  "errorMessage": "Order number is duplicated, order with given order number is processed already"
}

Регистрация на поръчка с предавторизация

За заявка за регистрация на поръчка с предавторизация се използва методът https://uat.dskbank.bg/payment/rest/registerPreAuth.do.


При изпълнение на заявката е необходимо да се използва заглавката: Content-Type: application/x-www-form-urlencoded

Параметри на заявката

ЗадължителностИмеТипОписание
УсловноuserNameString [1..50]Потребителско име на API акаунта на продавача. Ако за удостоверяване при регистрация вместо потребителско име и парола се използва открит токен (параметър token), паролата не е необходимо да се предава.
УсловноpasswordString [1..30]Парола на API акаунта на продавача. Ако за удостоверяване при регистрация вместо логин и парола се използва открит токен (параметър token), паролата не е необходимо да се предава.
УсловноtokenString [1..256]Стойност, използвана за автентификация на продавача при изпращане на заявки към платежната шлюз. Ако предавате този параметър, то не предавайте userName и password.
ЗадължителноorderNumberString [1..36]Номер на поръчката (ID) в системата на търговеца; трябва да бъде уникален за всяка поръчка.
ЗадължителноamountInteger [0..12]Сума на плащането в минимални единици валута (например, в стотинки).
ЗадължителноcurrencyString [3]Код на валутата на плащането ISO 4217. Ако не е посочен, се използва стойността по подразбиране. Позволени са само цифри.
ЗадължителноreturnUrlString [1..512]Адрес, към който трябва да бъде пренасочен потребителят в случай на успешно плащане. Адресът трябва да бъде указан изцяло, включително използвания протокол (например, https://mybestmerchantreturnurl.com вместо mybestmerchantreturnurl.com). В противен случай потребителят ще бъде пренасочен на адрес от следния вид: https://uat.dskbank.bg/payment/<merchant_address>.
НезадължителноfailUrlString [1..512]Адрес, на който трябва да се пренасочи потребителят в случай на неуспешно плащане. Адресът трябва да бъде посочен напълно, включително използвания протокол (например, https://mybestmerchantreturnurl.com вместо mybestmerchantreturnurl.com). В противен случай потребителят ще бъде пренасочен по адрес от следния вид: https://uat.dskbank.bg/payment/<merchant_address>.
НезадължителноdynamicCallbackUrlString [1..512]Параметър за предаване на динамичен адрес за получаване на "платежни" callback-уведомления за поръчката, активирани за търговеца (успешна авторизация, успешно списване, връщане, отказ, отхвърляне на плащане по таймаут, отхвърляне на card present плащане).
"Не платежни" callback-уведомления (включване/изключване на връзка, създаване на връзка), ще бъдат изпращани на статичен callback адрес.
НезадължителноdescriptionString [1..598]Описание на поръчката в произволен формат.
За да включите изпращането на това поле в процесинговата система, обърнете се към службата за техническа поддръжка.
В това поле е недопустимо да се предават лични данни или платежни данни (номера на карти и т.н.). Това изискване се дължи на факта, че описанието на поръчката никъде не се маскира.
НезадължителноipString [1..39]IP адрес на платеца. IPv6 се поддържа във всички заявки (до 39 символа).
НезадължителноlanguageString [2]Ключ на езика по ISO 639-1. Ако езикът не е указан, се използва езикът по подразбиране, указан в настройките на магазина.
Поддържани езици: en,ru,el,ro,bg,pt,sw,hu,it,pl,de,fr,kh,cn,es,ka,da,et,fi,lt,lv,nl,sv.
НезадължителноclientIdString [0..255]Номер на клиента (ID) в системата на търговеца — до 255 символа. Използва се за реализиране на функционалността на връзките. Може да се връща в отговора, ако на търговеца е разрешено да създава връзки.
Указването на този параметър при обработка на плащания по връзка е задължително. В противен случай плащането ще бъде невъзможно.
НезадължителноmerchantLoginString [1..255]За да регистрирате поръчка от името на друг търговец, посочете неговия логин (за API-акаунт) в този параметър.
Може да се използва само ако имате разрешение за преглед на транзакциите на други продавачи или ако посоченият продавач е ваш дъщерен продавач.
НезадължителноcardholderNameString [1..150]Име на притежателя на картата с латински букви. При предаване на този параметър името на притежателя на картата ще бъде показано на страницата за плащане.
НезадължителноjsonParamsObjectНабор от допълнителни атрибути с произволна форма, структура:
jsonParams={"param_1_name":"param_1_value",...,"param_n_name":"param_n_value"}
Могат да бъдат предадени в Процесинговия Център, за последваща обработка (изисква се допълнителна настройка - обърнете се към поддръжката).
Някои предопределени атрибути jsonParams:
  • backToShopUrl - добавя на страницата за плащане бутон, който ще върне притежателя на картата на URL-адреса предаден в този параметър
  • backToShopName - настройва текстовия етикет на бутона Върни се в магазина по подразбиране, ако се използва заедно с backToShopUrl
  • recurringFrequency - минимален брой дни между оторизациите. Изисква се за създаване на рекурентна връзка, препоръчва се за създаване на връзка за разсрочване (ако се използва 3DS2, параметърът е задължителен).
  • recurringExpiry - дата, след която оторизациите не са разрешени, във формат ГГГГММДД. Изисква се за създаване на рекурентна връзка, препоръчва се за създаване на връзка за разсрочване (ако се използва 3DS2, параметърът е задължителен).
НезадължителноsessionTimeoutSecsInteger [1..9]Продължителност на живота на поръчката в секунди. В случай че параметърът не е зададен, ще бъде използвана стойността, указана в настройките на търговеца, или времето по подразбиране (1200 секунди = 20 минути). Ако в заявката присъства параметър expirationDate, то стойността на параметър sessionTimeoutSecs не се взема предвид.
НезадължителноexpirationDateString [19]Дата и час на изтичане на срока на валидност на поръчката. Формат: yyyy-MM-ddTHH:mm:ss.
Ако този параметър не се предава в заявката, то за определяне на времето на изтичане на срока на валидност на поръчката се използва параметърът sessionTimeoutSecs.
НезадължителноbindingIdString [1..255]Идентификатор на вече съществуваща връзка (идентификатор на карта, токенизирана от gateway). Може да се използва само ако търговецът има разрешение за работа с връзки. Ако този параметър се предава в тази заявка, това означава, че:
  • Тази поръчка може да бъде платена само чрез връзка;
  • Платецът ще бъде пренасочен към страница за плащане, където се изисква само въвеждане на CVC.
НезадължителноfeaturesStringФункции на поръчката. За да посочите няколко функции, използвайте този параметър няколко пъти в една заявка. По-долу са изброени възможните стойности.
  • VERIFY - ако се предаде тази стойност в заявката за оформяне на поръчка, притежателят на картата ще бъде верифициран, но няма да се извърши списване на средства, така че в този случай параметърът amount може да има стойност 0. Верификацията позволява да се убедите, че картата се намира в ръцете на притежателя, и впоследствие да списвате от тази карта средства, без да прибягвате до проверка на автентификационните данни (CVC, 3D-Secure) при извършване на последващи плащания. Дори ако сумата на плащането бъде предадена в заявката, тя няма да бъде списана от сметката на клиента при предаване на стойността VERIFY. Тази стойност също може да се използва за създаване на връзка — в този случай параметърът clientId също трябва да бъде предаден. Подробности четете тук.
  • FORCE_TDS - Принудително извършване на плащане с използване на 3-D Secure. Ако картата не поддържа 3-D Secure, транзакцията няма да премине.
  • FORCE_SSL - Принудително извършване на плащане чрез SSL (без използване на 3-D Secure).
  • FORCE_FULL_TDS - След извършване на автентификация с помощта на 3-D Secure статусът PaRes трябва да бъде само Y, което гарантира успешна автентификация на потребителя. В противен случай транзакцията няма да премине.
  • FORCE_CREATE_BINDING - предаването на тази стойност в заявката за оформяне на поръчка принудително създава връзка. Тази функционалност трябва да бъде включена на ниво продавач в шлюза. Тази стойност не може да се предаде в заявка със съществуващ bindingId или bindingNotNeeded = true (ще предизвика грешка при проверка). Когато се предава тази функция, параметърът clientId също трябва да бъде предаден. Ако в блока features се предадат и двете стойности FORCE_CREATE_BINDING и VERIFY, тогава поръчката ще бъде създадена САМО за създаване на връзка (без плащане).
НезадължителноautocompletionDateString [19]Дата и време на автоматичното завършване на двуетапното плащане в следния формат: 2025-12-29T13:02:51. Използван часови пояс: UTC+0. За да включите изпращането на това поле в процесинговата система, обърнете се към службата за техническа поддръжка.
НезадължителноautoReverseDateString [19]Дата и час на автоматично анулиране на двуетапното плащане в следния формат: 2025-06-23T13:02:51. Използван часови пояс: UTC+0. За да включите изпращането на това поле в процесинговата система, обърнете се към службата за техническа поддръжка.
НезадължителноpostAddressString [1..255]Адрес за доставка.
НезадължителноmarketplaceObjectБлок с параметри на маркетплейса, т.е. продавача, който предлага стоки или услуги от различни дребни продавачи (ритейлъри).
Този параметър се използва, ако е включена специална настройка (обърнете се към службата за поддръжка). Вж. вложени параметри.
НезадължителноorderBundleObjectОбект, съдържащ кошницата с продукти. Описанието на вложените елементи е дадено по-долу.
НезадължителноfeeInputInteger [0..8]Размер на комисионната в минимални единици валута. Функционалността трябва да бъде включена на ниво продавач в gateway-я.
УсловноemailString [1..40]Електронна поща за показване на платежната страница. Ако за продавача са настроени уведомления на клиента, електронната поща трябва да бъде посочена. Пример: client_mail@email.com.
Адресът на електронната поща не се проверява при регистрация, той ще бъде проверен по-късно при плащане.
НезадължителноmccInteger [4]Merchant Category Code (код на категория на търговеца).
За предаване на този параметър е необходимо специално разрешение. Могат да се използват стойности само от разрешения списък MCC. За получаване на по-подробна информация се обърнете към техническата поддръжка.
НезадължителноmvvString [1..10]Потвърждение на търговеца от Mastercard за токенизирани транзакции.
За предаване на този параметър трябва да бъде включена специална настройка (обърнете се към техническата поддръжка).
НезадължителноpaymentFacilitatorObjectБлок с информация за платежния фасилитатор, т.е. за търговеца, който позволява на няколко субтърговеца да приемат плащания под неговата учетна запис.
За предаване на този параметър трябва да бъде включена специална настройка (обърнете се към техническата поддръжка). Вж. вложени параметри.
НезадължителноbillingPayerDataObjectБлок с регистрационни данни на клиента (адрес, пощенски код), необходим за преминаване на проверката на адреса в рамките на услугите AVS/AVV. Задължително, ако функцията е включена за продавача от страна на Платежния шлюз. Вж вложени параметри.
НезадължителноshippingPayerDataObjectОбект, съдържащ данни за доставката до клиента. Този параметър се използва за по-нататъшна 3DS-аутентификация на клиента. Вж. вложени параметри.
НезадължителноpreOrderPayerDataObjectОбект, съдържащ данни за предварителната поръчка. Този параметър се използва за по-нататъшна 3DS-аутентификация на клиента. Вж. вложени параметри.
НезадължителноorderPayerDataObjectОбект, съдържащ данни за платеца на поръчката. Този параметър се използва за по-нататъшна 3DS-аутентификация на клиента. Вж. вложени параметри.
НезадължителноbillingAndShippingAddressMatchIndicatorString [1]Индикатор за съответствие на платежния адрес на притежателя на картата и адреса за доставка. Този параметър се използва за по-нататъшна 3DS-автентификация на клиента.
Възможни стойности:
  • Y - съвпадение на платежния адрес на притежателя на картата и адреса за доставка;
  • N - платежният адрес на притежателя на картата и адресът за доставка не съвпадат.

По-долу са посочени параметрите на блока billingPayerData (данни за адреса за регистрация на клиента).

ЗадължителностИмеТипОписание
НезадължителноbillingCityString [0..50]Град, регистриран за конкретната карта в Банката Емитент.
НезадължителноbillingCountryString [0..50]Страна, регистрирана за конкретната карта на банката-издател. Формат: ISO 3166-1 (Alpha 2 / Alpha 3 / Number-3) или наименование на страната. Препоръчваме предаване на двубуквен/трибуквен ISO код на страната.
НезадължителноbillingAddressLine1String [0..50]Адрес, регистриран по конкретна карта в Банката Емитент (адрес на платеца). Ред 1. Задължително за предаване за AVS-проверка.
НезадължителноbillingAddressLine2String [0..50]Адрес, регистриран за конкретната карта в Банката Емитент. Ред 2.
НезадължителноbillingAddressLine3String [0..50]Адрес, регистриран за конкретната карта в Банката Емитент. Ред 3.
НезадължителноbillingPostalCodeString [0..9]Пощенски код, регистриран за конкретната карта в Банката Издател. Задължително за предаване за AVS-проверка.
НезадължителноbillingStateString [0..50]Щат, регистриран за конкретната карта в Банката Емитент. Формат: пълна стойност на кода ISO 3166-2, негова част или наименование на щата/региона. Може да съдържа букви само от латинската азбука. Препоръчваме да се предава двубуквен ISO код на щата/региона.
ЗадължителноpayerAccountString [1..32]Номер на сметката на изпращача.
НезадължителноpayerLastNameString [1..64]Фамилия на изпращача.
НезадължителноpayerFirstNameString [1..35]Име на изпращача.
НезадължителноpayerMiddleNameString [1..35]Бащино име на изпращача.
НезадължителноpayerCombinedNameString [1..99]Пълно име на подателя.
НезадължителноpayerIdTypeString [1..8]Тип на предоставения идентифициращ документ на подателя.
Възможни стойности:
  • IDTP1 - Паспорт
  • IDTP2 - Шофьорска книжка
  • IDTP3 - Социална карта
  • IDTP4 - ID карта на гражданин
  • IDTP5 - Сертификат за водене на бизнес
  • IDTP6 - Сертификат на бежанец
  • IDTP7 - Разрешително за пребиваване
  • IDTP8 - Чужд паспорт
  • IDTP9 - Служебен паспорт
  • IDTP10 - Временен паспорт
  • IDTP11 - Паспорт на моряк
НезадължителноpayerIdNumberString [1..100]Номер на предоставения идентифициращ документ (например, паспорт) на изпращача.
НезадължителноpayerBirthdayString [1..20]Дата на раждане на изпращача във формат YYYYMMDD.

Описание на параметрите на обект shippingPayerData:

ЗадължителностНаименованиеТипОписание
НезадължителноshippingCityString [1..50]Град на поръчителя (от адреса за доставка)
НезадължителноshippingCountryString [1..50]Страна на поръчителя
НезадължителноshippingAddressLine1String [1..50]Основен адрес на клиента (от адреса за доставка)
НезадължителноshippingAddressLine2String [1..50]Основен адрес на клиента (от адреса за доставка)
НезадължителноshippingAddressLine3String [1..50]Основен адрес на клиента (от адреса за доставка)
НезадължителноshippingPostalCodeString [1..16]Пощенски код на клиента за доставка
НезадължителноshippingStateString [1..50]Щат/регион на купувача (от адреса за доставка)
НезадължителноshippingMethodIndicatorInteger [2]Индикатор за начин на доставка.
Възможни стойности:
  • 01 - доставка на платежния адрес на притежателя на карта.
  • 02 - доставка на друг адрес, проверен от Търговеца.
  • 03 - доставка на адрес, различен от основния адрес на притежателя на карта.
  • 04 - изпращане в магазин/самовземане (адресът на магазина трябва да бъде указан в съответните параметри за доставка)
  • 05 - Цифрово разпространение (включва онлайн услуги и електронни подаръчни карти)
  • 06 - билети за пътувания и събития, които не могат да бъдат доставени.
  • 07 - Други (например игри, цифрови стоки, които не подлежат на доставка, цифрови абонаменти и т.н.)
НезадължителноdeliveryTimeframeInteger [2]Срок за доставка на стоката.
Възможни стойности:
  • 01 - цифрова дистрибуция
  • 02 - доставка в същия ден
  • 03 - доставка на следващия ден
  • 04 - доставка в рамките на 2 дни след плащането и по-късно.
НезадължителноdeliveryEmail String [1..254]Целеви адрес на електронна поща за доставка на цифрово разпространение. Препоръчително е да предавате електронната поща в самостоятелен параметър на заявката email (но ако я предадете в този блок, към нея ще се прилагат същите правила).

Описание на параметрите на обекта preOrderPayerData:

ЗадължителностНаименованиеТипОписание
НезадължителноpreOrderDateString [10]Очаквана дата на доставка (за предварително поръчани покупки) във формат ГГГГММДД.
НезадължителноpreOrderPurchaseIndInteger [2]Индикатор за разполагане от клиента на поръчка за налична или бъдеща доставка.
Възможни стойности:
  • 01 - възможна е доставка;
  • 02 - бъдеща доставка
НезадължителноreorderItemsIndInteger [2]Индикатор, че клиентът преподръчва преди заплатена доставка в състава на нова поръчка.
Възможни стойности:
  • 01 - поръчката се разполага за първи път;
  • 02 - повторна поръчка

Описание на параметрите на обект orderPayerData.

ЗадължителностНаименованиеТипОписание
НезадължителноhomePhoneString [7..15]Домашен телефон на притежателя на картата. Необходимо е винаги да се посочва код на страната, но знакът + или 00 в началото може да се посочи или пропусне. Номерът трябва да има дължина от 7 до 15 цифри. По този начин са възможни следните стойности:
  • +35799988877;
  • 0035799988877;
  • 35799988877.
НезадължителноworkPhoneString [7..15]Служебен телефон на притежателя на картата. Необходимо е винаги да се посочва код на страната, но знакът + или 00 в началото може да се посочи или пропусне. Номерът трябва да има дължина от 7 до 15 цифри. По този начин са възможни следните стойности:
  • +35799988877;
  • 0035799988877;
  • 35799988877.
НезадължителноmobilePhoneString [7..15]Номер на мобилния телефон на притежателя на картата. Необходимо е винаги да се посочва код на страната, но знакът + или 00 в началото може да се посочи или пропусне. Номерът трябва да има дължина от 7 до 15 цифри. По този начин са възможни следните стойности:
  • +35799988877;
  • 0035799988877;
  • 35799988877.

За плащания по VISA с 3DS авторизация е необходимо да се посочи или електронна поща, или номер на телефон на притежателя на картата. Ако имате настроено показване на номера на телефона на платежната страница и сте посочили неверен номер на телефон, клиентът ще може да го поправи на платежната страница.

Описание на параметрите на обекта marketplace:

ЗадължителностИмеТипОписание
ЗадължителноmarketplaceIdString [1..11]Идентификатор на маркетплейса в банката-акуайър.
УсловноforeignRetailerIndicatorBooleanУказва дали маркетплейсът има чуждестранни ритейлъри (дъщерни търговци). Ако в обекта marketplace се предава блок retailers, този параметър не е задължително да се предава, в противен случай – задължително.
НезадължителноretailersArray of objectsМасив от ритейлъри (дъщерни продавачи на маркетплейса). Съдържа само 1 елемент. Вложените елементи са описани по-долу.

Описание на параметрите на обекта, който е елемент от масива retailers.

ЗадължителностИмеТипОписание
ЗадължителноforeignRetailerIndicatorBooleanОпределя дали търговецът е чуждестранен.

Пример на обекта marketplace:

"marketplace": {
    "marketplaceId": "MKT12345678",
    "foreignRetailerIndicator": true,
    "retailers": [
        {
            "foreignRetailerIndicator": false
        }
    ]
}

Описание на параметрите в обекта orderBundle:

ЗадължителностИмеТипОписание
НезадължителноorderCreationDateString [19]Дата на създаване на поръчката във формат YYYY-MM-DDTHH:MM:SS.
НезадължителноcustomerDetailsObjectБлок, съдържащ атрибутите на клиента. Описанието на атрибутите на тага е дадено по-долу.
ЗадължителноcartItemsObjectОбект, съдържащ атрибутите на стоките в кошницата. Описанието на вложените елементи е дадено по-долу.

Описание на параметрите в обект customerDetails:

ЗадължителностНаименованиеТипОписание
НезадължителноcontactString [0..40]Предпочитан от клиента начин за връзка.
НезадължителноfullNameString [1..100]ФИО на платеца.
НезадължителноpassportString [1..100]Серия и номер на паспорта на платеца в следния формат: 2222888888
НезадължителноdeliveryInfoObjectОбект, съдържащ атрибутите на адреса за доставка. Описанието на вложените елементи е приведено по-долу.

Описание на параметрите в обекта deliveryInfo:

ЗадължителностНаименованиеТипОписание
НезадължителноdeliveryTypeString [1..20]Начин на доставка.
ЗадължителноcountryString [2]Двубуквен код на страната за доставка.
ЗадължителноcityString [0..40]Град на назначение.
ЗадължителноpostAddressString [1..255]Адрес за доставка.

Описание на параметрите в обекта cartItems:

ЗадължителностНаименованиеТипОписание
ЗадължителноitemsObjectЕлемент на масив с атрибути на стокова позиция. Описанието на вложените елементи е дадено по-долу.

Описание на параметрите в обект items:

ЗадължителностНаименованиеТипОписание
ЗадължителноpositionIdInteger [1..12]Уникален идентификатор на стоковата позиция в кошницата.
ЗадължителноnameString [1..255]Наименование или описание на стокова позиция в свободна форма.
НезадължителноitemDetailsObjectОбект с параметри за описанието на стоковата позиция. Описанието на вложените елементи е приведено по-долу.
ЗадължителноquantityObjectЕлемент, описващ общото количество стокови позиции на един positionId и неговите мерни единици. Описанието на вложените елементи е приведено по-долу.
НезадължителноitemAmountInteger [1..12]Сума на стойността на всички стокови позиции за един positionId в минимални единици валута. itemAmount е задължителен за предаване, само ако не е предаден параметърът itemPrice. В противен случай предаването на itemAmount не се изисква. Ако в заявката се предават и двата параметъра: itemPrice и itemAmount, то itemAmount трябва да се равнява на itemPrice * quantity, в противен случай заявката ще завърши с грешка.
НезадължителноitemPriceInteger [1..18]Сума на стойността на стоковата позиция на един positionId в пари в минимални единици валута.
НезадължителноdepositedItemAmountString [1..18]Сума на списване за един positionId в минимални валутни единици (например, в стотинки).
НезадължителноitemCurrencyInteger [3]Код на валута ISO 4217. Ако не е посочен, се счита равен на валутата на поръчката.
ЗадължителноitemCodeString [1..100]Номер (идентификатор) на стокова позиция в системата на магазина.

Описание на параметрите в обект quantity:

ЗадължителностИмеТипОписание
ЗадължителноvalueNumber [1..18]Количество на стокови позиции от дадения positionId. За указване на дробни числа използвайте десетична точка. Допуска се максимум 3 знака след точката.
ЗадължителноmeasureString [1..20]Мерна единица за количеството по позицията.

Описание на параметрите в обекта itemDetails:

ЗадължителностНазваниеТипОписание
НезадължителноitemDetailsParamsObjectПараметър, описващ допълнителна информация по стоковата позиция. Описанието на вложените елементи е приведено по-долу.

Описание на параметрите в обекта itemDetailsParams:

ЗадължителностНаименованиеТипОписание
ЗадължителноvalueString [1..2000]Допълнителна информация за товарната позиция.
ЗадължителноnameString [1..255]Наименование на параметъра за описанието на детайлизацията на стоковата позиция

Описание на параметрите на обекта paymentFacilitator:

ЗадължителностНаименованиеТипОписание
ЗадължителноpfIdString [1..11]Идентификатор на платежния фасилитатор.
ЗадължителноnameString [1..40]Наименование на платежния фасилитатор.
НезадължителноisoIdString [1..11]Идентификатор ISO.
ЗадължителноsubMerchantsArray of objectsМасив от обекти с допълнителна информация за субмерчантите. Вж. вложените параметри по-долу.

Параметри на елемента от масива subMerchants:

ЗадължителностНаименованиеТипОписание
ЗадължителноsubMerchantIdString [1..20]Идентификатор на субмерчанта.
ЗадължителноnameString [1..40]Наименование на субмерчанта.
ЗадължителноaddressObjectБлок с информация за адреса на субмерчанта. Вж. вложените параметри по-долу.

Параметри на обекта address:

ЗадължителностНаименованиеТипОписание
ЗадължителноcityString [1..50]Град на субмерчанта.
ЗадължителноpostalCodeString [1..16]Пощенски код на субмерчанта.
ЗадължителноcountryInteger [2]Код на страната на субмерчанта във формат ISO 3166-1.
НезадължителноstreetString [1..40]Улица на субмерчанта.

Пример за обекта paymentFacilitator:

"paymentFacilitator" :{
  "pfId": "PF123456",
  "name": "Payment Facilitator Name",
  "isoId": "ISO789",
  "subMerchants": [
    {
      "subMerchantId": "SM001",
      "name": "Sub Merchant 1",
      "address": {
        "city": "City 1",
        "postalCode": "101000",
        "country": "US",
        "street": "Street 1"
      }
    },
    {
      "subMerchantId": "SM002",
      "name": "Sub Merchant 2",
      "address": {
        "city": "City 2",
        "postalCode": "190000",
        "country": "US",
        "street": "Street 2"
      }
    }
  ]
}

Параметри на отговора

ЗадължителностИмеТипОписание
НезадължителноerrorCodeString [1..2]Информационен параметър в случай на грешка, който може да има различни кодови стойности:
  • стойност 0 - указва успех на обработката на заявката;
  • друга числова стойност (1-99) - указва грешка, за получаване на по-подробна информация за която е необходимо да се провери параметър errorMessage.
Може да отсъства, ако резултатът не е предизвикал грешки.
НезадължителноerrorMessageString [1..512]Информационен параметър, който представлява описание на грешката в случай на възникване на грешка. Стойността на errorMessage може да варира, затова не трябва да се препраща изрично към неговите стойности в кода.
Езикът на описанието се задава в параметъра language на заявката.
НезадължителноorderIdString [1..36]Номер на поръчката в платежния шлюз. Уникален в рамките на платежния шлюз.
НезадължителноformUrlString [1..512]URL на платежната форма, към която ще бъде пренасочен купувачът. URL не се връща, ако регистрацията на поръчката не е преминала поради грешка, посочена в errorCode.

Примери

Пример за заявка

curl --request POST \
  --url https://uat.dskbank.bg/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://uat.dskbank.bg/payment/merchants/pay/payment_en.html?mdOrder=01492437-d2fb-77fa-8db7-9e2900a7d8c0"
}

Директни плащания

Плащане на поръчка

За плащане на предварително регистрирана поръчка се използва заявка https://uat.dskbank.bg/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 (прилагането на автентификация се регулира от настройки, управлявани от службата за поддръжка).

Параметри на заявката

ЗадължителностИмеТипОписание
ЗадължителноuserNameString [1..50]Потребителско име на API акаунта на продавача.
ЗадължителноpasswordString [1..30]Парола на API акаунта на продавача. Ако за удостоверяване при регистрация вместо логин и парола се използва открит токен (параметър token), паролата не е необходимо да се предава.
ЗадължителноMDORDERString [1..36]Номер на поръчката в платежния шлюз.
Задължително$PANInteger [1..19]Номер на платежна карта. Задължителен, ако не е предаден seToken.
Задължително$CVCString [3]Код CVC/CVV2 на обратната страна на картата. Задължителен, ако не е предаден seToken.
Позволени са само цифри.
ЗадължителноYYYYInteger [4]Година на изтичане на валидността на платежната карта. Ако seToken не е предаден, задължително е необходимо да се предаде или $EXPIRY, или YYYY и MM.
ЗадължителноMMInteger [2]Месец на изтичане на действието на платежната карта. Ако seToken не е предаден, задължително е необходимо да се предаде или $EXPIRY, или YYYY и MM.
Условно$EXPIRYInteger [6]Срок на валидност на картата в следния формат: YYYYMM. Предефинира параметрите YYYY и MM. Ако seToken не е предаден, задължително е необходимо да се предаде или $EXPIRY, или YYYY и MM.
УсловноseTokenStringКриптирани данни на картата, които заменят параметрите $PAN, $CVC и $EXPIRY (или YYYY,MM). Задължително, ако се използва вместо данни на картата.
Задължителни параметри за низа seToken: timestamp, UUID, PAN, EXPDATE, MDORDER. Повече за генерирането на seToken вж. тук.
Ако seToken съдържа криптирани данни за връзката (bindingId), за плащането трябва да се използва заявката paymentOrderBinding.do.
ЗадължителноTEXTString [1..512]Име на притежателя на картата.
ЗадължителноlanguageString [2]Ключ на езика по ISO 639-1. Ако езикът не е указан, се използва езикът по подразбиране, указан в настройките на магазина.
Поддържани езици: en,ru,el,ro,bg,pt,sw,hu,it,pl,de,fr,kh,cn,es,ka,da,et,fi,lt,lv,nl,sv.
НезадължителноipString [1..39]IP адрес на платеца. IPv6 се поддържа във всички заявки (до 39 символа).
НезадължителноbindingNotNeededBooleanДопустими стойности:
  • true- създаването на връзка след извършване на плащането е изключено (връзката – това е идентификатор на клиента, предаден в заявката за регистрация на поръчката, който след заявката за плащане ще бъде изтрит от детайлите на поръчката);
  • false – в случай на успешно плащане може да бъде създадена връзка (при спазване на необходимите условия). Това е стойността по подразбиране.
НезадължителноjsonParamsObjectПолета за допълнителна информация за последващо съхранение, предават се в следния вид: jsonParams={"param_1_name":"param_1_value",...,"param_n_name":"param_n_value"}.
Могат да бъдат предадени в Процесинговия Център, за последваща обработка (изисква се допълнителна настройка - обърнете се към поддръжката).
Ако използвате външен MPI/3DS Server, платежният шлюз очаква, че всяка заявка paymentOrder ще включва редица допълнителни параметри, като eci, xid, cavv и пр. По-подробна информация тук.
За да инициирате 3RI аутентификация, може да ви е необходимо да предадете редица допълнителни параметри (вж. 3RI аутентификация).
Някои предефинирани атрибути на jsonParams:
  • backToShopUrl - добавя на страницата за плащане бутон, който ще върне притежателя на картата на URL-адреса предаден в този параметър
  • backToShopName - настройва текстовия етикет на бутона Върни се в магазина по подразбиране, ако се използва заедно с backToShopUrl
  • recurringFrequency - минимален брой дни между авторизациите. Изисква се за създаване на рекурентна връзка, препоръчва се за създаване на връзка за вноски (ако се използва 3DS2, параметърът е задължителен).
  • recurringExpiry - дата, след която авторизациите не са разрешени, във формат ГГГГММДД. Изисква се за създаване на рекурентна връзка, препоръчва се за създаване на връзка за вноски (ако се използва 3DS2, параметърът е задължителен).
НезадължителноthreeDSSDKBooleanВъзможни стойности: true или false Флаг, показващ, че плащането постъпва от 3DS SDK.
НезадължителноmccInteger [4]Merchant Category Code (код на категория на търговеца).
За предаване на този параметър е необходимо специално разрешение. Могат да се използват стойности само от разрешения списък MCC. За получаване на по-подробна информация се обърнете към техническата поддръжка.
НезадължителноmvvString [1..10]Потвърждение на търговеца от Mastercard за токенизирани транзакции.
За предаване на този параметър трябва да бъде включена специална настройка (обърнете се към техническата поддръжка).
УсловноoriginalSchemeTransactionIdString [1..22]Идентификатор на оригиналната успешна транзакция в Mastercard.
Задължителен при използване на запазени данни за карта на търговеца в преводи по запазени данни за карта.
НезадължителноpaymentFacilitatorObjectБлок с информация за платежния фасилитатор, т.е. за търговеца, който разрешава на няколко суб-търговци да приемат плащания под неговата учетна запис.
За предаване на този параметър трябва да бъде включена специална настройка (свържете се с техническата поддръжка). Вж. вложени параметри.
УсловноemailString [1..40]Електронна поща за показване на платежната страница. Ако за продавача са настроени известия на клиента, електронната поща трябва да бъде посочена. Пример: client_mail@email.com.
За плащания по VISA с 3DS авторизация е необходимо да се посочи или електронна поща, или телефонен номер на притежателя на картата.
НезадължителноbillingPayerDataObjectБлок с регистрационни данни на клиента (адрес, пощенски код), необходим за преминаване на проверка на адреса в рамките на услугите AVS/AVV. Задължително, ако функцията е включена за продавача от страна на Платежен шлюз. Вж вложени параметри.
НезадължителноshippingPayerDataObjectОбект, съдържащ данни за доставка до клиента. Този параметър се използва за по-нататъшна 3DS-автентификация на клиента. Вж. вложени параметри.
НезадължителноpreOrderPayerDataObjectОбект, съдържащ данни за предварителна поръчка. Този параметър се използва за по-нататъшна 3DS-автентификация на клиента. Вж. вложени параметри.
НезадължителноorderPayerDataObjectОбект, съдържащ данни за платеца на поръчката. Този параметър се използва за по-нататъшна 3DS-автентификация на клиента. Вж. вложени параметри.
НезадължителноtiiStringИдентификатор на инициатора на транзакцията. Параметър, указващ какъв тип операция ще изпълнява инициаторът (Клиент или Мърчант). Възможни стойности
НезадължителноexternalScaExemptionIndicatorStringТип на изключение SCA (Strong Customer Authentication). Ако е посочен този параметър, транзакцията ще бъде обработена в зависимост от вашите настройки в платежния шлюз: или ще бъде изпълнена принудителна операция SSL, или банката-издател ще получи информация за изключението SCA и ще вземе решение за провеждане на операцията с 3DS-автентификация или без нея (за получаване на подробна информация се свържете с нашата служба за поддръжка). Допустими стойности:
  • LVP – транзакция от тип Low Value Payments. Транзакцията може да бъде отнесена към транзакции с ниско ниво на риск въз основа на сумата на транзакцията, броя на транзакциите на клиента в деня или общата дневна сума на плащанията на клиента.
  • TRA – транзакция от тип Transaction Risk Analysis, т.е. транзакция, преминала успешна антифрод-проверка.

За предаване на този параметър трябва да имате достатъчни права в платежния шлюз.
НезадължителноclientBrowserInfoObjectБлок данни за браузъра на клиента, който се изпраща на ACS по време на 3DS автентификация. Този блок може да се предава само ако е включена специална настройка (обърнете се към екипа за поддръжка). Вж. вложени параметри.
УсловноoriginalPaymentNetRefNumStringИдентификатор на оригиналната или предишната успешна транзакция в платежната система по отношение на изпълняваната операция по връзката - TRN ID. Предава се, ако стойността на параметъра tii = R,U или F.
Задължителен при използване на връзките на търговеца в преводите по връзка.
УсловноoriginalPaymentDateStringДата на инициираща транзакция. Стойност във формат Unix timestamp в милисекунди. Предава се, ако стойността на параметъра tii = R,U или F.
НезадължителноmarketplaceObjectБлок с параметри на маркетплейса, т.е. продавача, който предлага стоки или услуги от различни търговци на дребно (ритейлъри).
Този параметър се използва, ако е включена специална настройка (обърнете се към службата за поддръжка). Вж. вложени параметри.
НезадължителноacsInIFrameBooleanФлаг, показващ, че за финишния URL ще се връща iFrame версия. Възможни стойности true или false. За свързване на тази функционалност се обърнете към службата за поддръжка.

По-долу са посочени параметрите на блока billingPayerData (данни за адреса за регистрация на клиента).

ЗадължителностИмеТипОписание
НезадължителноbillingCityString [0..50]Град, регистриран за конкретната карта в Банката Емитент.
НезадължителноbillingCountryString [0..50]Страна, регистрирана за конкретната карта на банката-издател. Формат: ISO 3166-1 (Alpha 2 / Alpha 3 / Number-3) или наименование на страната. Препоръчваме предаване на двубуквен/трибуквен ISO код на страната.
НезадължителноbillingAddressLine1String [0..50]Адрес, регистриран по конкретна карта в Банката Емитент (адрес на платеца). Ред 1. Задължително за предаване за AVS-проверка.
НезадължителноbillingAddressLine2String [0..50]Адрес, регистриран за конкретната карта в Банката Емитент. Ред 2.
НезадължителноbillingAddressLine3String [0..50]Адрес, регистриран за конкретната карта в Банката Емитент. Ред 3.
НезадължителноbillingPostalCodeString [0..9]Пощенски код, регистриран за конкретната карта в Банката Издател. Задължително за предаване за AVS-проверка.
НезадължителноbillingStateString [0..50]Щат, регистриран за конкретната карта в Банката Емитент. Формат: пълна стойност на кода ISO 3166-2, негова част или наименование на щата/региона. Може да съдържа букви само от латинската азбука. Препоръчваме да се предава двубуквен ISO код на щата/региона.
ЗадължителноpayerAccountString [1..32]Номер на сметката на изпращача.
НезадължителноpayerLastNameString [1..64]Фамилия на изпращача.
НезадължителноpayerFirstNameString [1..35]Име на изпращача.
НезадължителноpayerMiddleNameString [1..35]Бащино име на изпращача.
НезадължителноpayerCombinedNameString [1..99]Пълно име на подателя.
НезадължителноpayerIdTypeString [1..8]Тип на предоставения идентифициращ документ на подателя.
Възможни стойности:
  • IDTP1 - Паспорт
  • IDTP2 - Шофьорска книжка
  • IDTP3 - Социална карта
  • IDTP4 - ID карта на гражданин
  • IDTP5 - Сертификат за водене на бизнес
  • IDTP6 - Сертификат на бежанец
  • IDTP7 - Разрешително за пребиваване
  • IDTP8 - Чужд паспорт
  • IDTP9 - Служебен паспорт
  • IDTP10 - Временен паспорт
  • IDTP11 - Паспорт на моряк
НезадължителноpayerIdNumberString [1..100]Номер на предоставения идентифициращ документ (например, паспорт) на изпращача.
НезадължителноpayerBirthdayString [1..20]Дата на раждане на изпращача във формат YYYYMMDD.

Описание на параметрите на обект shippingPayerData:

ЗадължителностНаименованиеТипОписание
НезадължителноshippingCityString [1..50]Град на поръчителя (от адреса за доставка)
НезадължителноshippingCountryString [1..50]Страна на поръчителя
НезадължителноshippingAddressLine1String [1..50]Основен адрес на клиента (от адреса за доставка)
НезадължителноshippingAddressLine2String [1..50]Основен адрес на клиента (от адреса за доставка)
НезадължителноshippingAddressLine3String [1..50]Основен адрес на клиента (от адреса за доставка)
НезадължителноshippingPostalCodeString [1..16]Пощенски код на клиента за доставка
НезадължителноshippingStateString [1..50]Щат/регион на купувача (от адреса за доставка)
НезадължителноshippingMethodIndicatorInteger [2]Индикатор за начин на доставка.
Възможни стойности:
  • 01 - доставка на платежния адрес на притежателя на карта.
  • 02 - доставка на друг адрес, проверен от Търговеца.
  • 03 - доставка на адрес, различен от основния адрес на притежателя на карта.
  • 04 - изпращане в магазин/самовземане (адресът на магазина трябва да бъде указан в съответните параметри за доставка)
  • 05 - Цифрово разпространение (включва онлайн услуги и електронни подаръчни карти)
  • 06 - билети за пътувания и събития, които не могат да бъдат доставени.
  • 07 - Други (например игри, цифрови стоки, които не подлежат на доставка, цифрови абонаменти и т.н.)
НезадължителноdeliveryTimeframeInteger [2]Срок за доставка на стоката.
Възможни стойности:
  • 01 - цифрова дистрибуция
  • 02 - доставка в същия ден
  • 03 - доставка на следващия ден
  • 04 - доставка в рамките на 2 дни след плащането и по-късно.
НезадължителноdeliveryEmail String [1..254]Целеви адрес на електронна поща за доставка на цифрово разпространение. Препоръчително е да предавате електронната поща в самостоятелен параметър на заявката email (но ако я предадете в този блок, към нея ще се прилагат същите правила).

Описание на параметрите на обекта preOrderPayerData:

ЗадължителностНаименованиеТипОписание
НезадължителноpreOrderDateString [10]Очаквана дата на доставка (за предварително поръчани покупки) във формат ГГГГММДД.
НезадължителноpreOrderPurchaseIndInteger [2]Индикатор за разполагане от клиента на поръчка за налична или бъдеща доставка.
Възможни стойности:
  • 01 - възможна е доставка;
  • 02 - бъдеща доставка
НезадължителноreorderItemsIndInteger [2]Индикатор, че клиентът преподръчва преди заплатена доставка в състава на нова поръчка.
Възможни стойности:
  • 01 - поръчката се разполага за първи път;
  • 02 - повторна поръчка

Описание на параметрите на обект orderPayerData.

ЗадължителностНаименованиеТипОписание
НезадължителноhomePhoneString [7..15]Домашен телефон на притежателя на картата. Необходимо е винаги да се посочва код на страната, но знакът + или 00 в началото може да се посочи или пропусне. Номерът трябва да има дължина от 7 до 15 цифри. По този начин са възможни следните стойности:
  • +35799988877;
  • 0035799988877;
  • 35799988877.
НезадължителноworkPhoneString [7..15]Служебен телефон на притежателя на картата. Необходимо е винаги да се посочва код на страната, но знакът + или 00 в началото може да се посочи или пропусне. Номерът трябва да има дължина от 7 до 15 цифри. По този начин са възможни следните стойности:
  • +35799988877;
  • 0035799988877;
  • 35799988877.
НезадължителноmobilePhoneString [7..15]Номер на мобилния телефон на притежателя на картата. Необходимо е винаги да се посочва код на страната, но знакът + или 00 в началото може да се посочи или пропусне. Номерът трябва да има дължина от 7 до 15 цифри. По този начин са възможни следните стойности:
  • +35799988877;
  • 0035799988877;
  • 35799988877.

За плащания по VISA с 3DS авторизация е необходимо да се посочи или електронна поща, или номер на телефон на притежателя на картата. Ако имате настроено показване на номера на телефона на платежната страница и сте посочили неверен номер на телефон, клиентът ще може да го поправи на платежната страница.

Възможни стойности tii (Подробно за типовете съхранени платежни данни, поддържани от платежния шлюз, четете тук).

Стойност tiiОписаниеТип транзакцияИнициатор на транзакциятаДанни на картата за транзакциятаЗапазване на данните на картата след транзакциятаЗабележка
ПразноОбичайнаКупувачВъвежда се от купувачаНеТранзакция на електронна търговия без запазване на съхранени платежни данни.
CIИнициираща - Обичайна (CIT)ИницииращаКупувачВъвежда се от купувачаДаТранзакция на електронна търговия със запазване на съхранени платежни данни.
FИзвънпланов платеж (CIT)ПоследващаКупувачКлиентът избира карта вместо ръчно въвежданеНеТранзакция на електронна търговия, използваща предварително запазени обичайни съхранени платежни данни.
UИзвънпланов платеж (MIT)ПоследващаПродавачНяма ръчно въвеждане, продавачът предава даннитеНеТранзакция на електронна търговия, използваща предварително запазени обичайни съхранени платежни данни. Използва се само за едностадийни плащания.
RIИнициираща - Рекурентни (CIT)ИницииращаКупувачВъвежда се от купувачаДаТранзакция на електронна търговия със запазване на съхранени платежни данни.
RРекурентен платеж (MIT)ПоследващаПродавачНяма ръчно въвеждане, продавачът предава даннитеНеРекурентна операция, използваща запазени съхранени платежни данни. Използва се само за едностадийни плащания.

По-долу са дадени параметрите на блока clientBrowserInfo (данни за браузъра на клиента).

ЗадължителностНазваниеТипОписание
НезадължителноuserAgentString [1..2048]Агент на браузъра.
НезадължителноOSStringОперационна система.
НезадължителноOSVersionStringВерсия на операционната система.
НезадължителноbrowserAcceptHeaderString [1..2048]Заглавка Accept, която съобщава на сървъра какви формати (или MIME-типове) поддържа браузъра.
НезадължителноbrowserIpAddressString [1..45]IP-адрес на браузъра.
НезадължителноbrowserLanguageString [1..8]Език на браузъра.
НезадължителноbrowserTimeZoneStringЧасова зона на браузъра.
НезадължителноbrowserTimeZoneOffsetString [1..5]Отместване на часовата зона в минути между локалното време на потребителя и UTC.
НезадължителноcolorDepthString [1..2]Дълбочина на цвета на екрана, в битове.
НезадължителноfingerprintStringОтпечатък на браузъра - уникален цифров идентификатор на браузъра.
НезадължителноisMobileBooleanВъзможни стойности: true или false. Флаг, указващ че се използва мобилно устройство.
НезадължителноjavaEnabledBooleanВъзможни стойности: true или false. Флаг, указващ че в браузъра е включена поддръжка на java.
НезадължителноjavascriptEnabledBooleanВъзможни стойности: true или false. Флаг, указващ че в браузъра е включена поддръжка на javascript.
НезадължителноpluginsStringСписък на плъгините, използвани в браузъра, разделени със запетая.
НезадължителноscreenHeightInteger [1..6]Височина на екрана в пиксели.
НезадължителноscreenWidthInteger [1..6]Ширина на екрана в пиксели.
НезадължителноscreenPrintStringДанни за параметрите за печат на браузъра, включително резолюция, дълбочина на цвета, плътност на пикселите.

Пример за блок 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":"x.x.x.x"
	}

Описание на параметрите на обекта paymentFacilitator:

ЗадължителностНаименованиеТипОписание
ЗадължителноpfIdString [1..11]Идентификатор на платежния фасилитатор.
ЗадължителноnameString [1..40]Наименование на платежния фасилитатор.
НезадължителноisoIdString [1..11]Идентификатор ISO.
ЗадължителноsubMerchantsArray of objectsМасив от обекти с допълнителна информация за субмерчантите. Вж. вложените параметри по-долу.

Параметри на елемента от масива subMerchants:

ЗадължителностНаименованиеТипОписание
ЗадължителноsubMerchantIdString [1..20]Идентификатор на субмерчанта.
ЗадължителноnameString [1..40]Наименование на субмерчанта.
ЗадължителноaddressObjectБлок с информация за адреса на субмерчанта. Вж. вложените параметри по-долу.

Параметри на обекта address:

ЗадължителностНаименованиеТипОписание
ЗадължителноcityString [1..50]Град на субмерчанта.
ЗадължителноpostalCodeString [1..16]Пощенски код на субмерчанта.
ЗадължителноcountryInteger [2]Код на страната на субмерчанта във формат ISO 3166-1.
НезадължителноstreetString [1..40]Улица на субмерчанта.

Пример за обекта paymentFacilitator:

"paymentFacilitator" :{
  "pfId": "PF123456",
  "name": "Payment Facilitator Name",
  "isoId": "ISO789",
  "subMerchants": [
    {
      "subMerchantId": "SM001",
      "name": "Sub Merchant 1",
      "address": {
        "city": "City 1",
        "postalCode": "101000",
        "country": "US",
        "street": "Street 1"
      }
    },
    {
      "subMerchantId": "SM002",
      "name": "Sub Merchant 2",
      "address": {
        "city": "City 2",
        "postalCode": "190000",
        "country": "US",
        "street": "Street 2"
      }
    }
  ]
}

Описание на параметрите на обекта marketplace:

ЗадължителностИмеТипОписание
ЗадължителноmarketplaceIdString [1..11]Идентификатор на маркетплейса в банката-акуайър.
УсловноforeignRetailerIndicatorBooleanУказва дали маркетплейсът има чуждестранни ритейлъри (дъщерни търговци). Ако в обекта marketplace се предава блок retailers, този параметър не е задължително да се предава, в противен случай – задължително.
НезадължителноretailersArray of objectsМасив от ритейлъри (дъщерни продавачи на маркетплейса). Съдържа само 1 елемент. Вложените елементи са описани по-долу.

Описание на параметрите на обекта, който е елемент от масива retailers.

ЗадължителностИмеТипОписание
ЗадължителноforeignRetailerIndicatorBooleanОпределя дали търговецът е чуждестранен.

Пример на обекта marketplace:

"marketplace": {
    "marketplaceId": "MKT12345678",
    "foreignRetailerIndicator": true,
    "retailers": [
        {
            "foreignRetailerIndicator": false
        }
    ]
}

При автентификация по протокол 3DS2 също се предават следните параметри:

ЗадължителностИмеТипОписание
НезадължителноthreeDSServerTransIdString [1..36]Идентификатор на транзакцията, създаден на 3DS сървъра. Задължителен за 3DS автентикация.
НезадължителноthreeDSVer2FinishUrlString [1..512]URL-адрес, с който клиентът трябва да бъде пренасочен след автентификация на сървъра ACS.
НезадължителноthreeDSMethodNotificationUrlString [1..512]URL-адрес за изпращане на уведомление за преминаване на проверката в ACS.

Параметри на отговора

ЗадължителностИмеТипОписание
ЗадължителноerrorCodeString [1..2]Информационен параметър в случай на грешка, който може да има различни кодови стойности:
  • стойност 0 - указва успех на обработката на заявката;
  • друга числова стойност (1-99) - указва грешка, за получаване на по-подробна информация за която е необходимо да се провери параметър errorMessage.
Може да отсъства, ако резултатът не е предизвикал грешки.
НезадължителноerrorMessageString [1..512]Информационен параметър, който представлява описание на грешката в случай на възникване на грешка. Стойността на errorMessage може да варира, затова не трябва да се препраща изрично към неговите стойности в кода.
Езикът на описанието се задава в параметъра language на заявката.
НезадължителноinfoStringВ случай на успешен отговор. Резултат от опита за плащане. По-долу са приведени възможните стойности.
  • Вашето плащане е обработено, извършва се пренасочване...
  • Операцията е отхвърлена. Проверете въведените данни, достатъчността на средствата на картата и повторете операцията. Извършва се пренасочване...
  • Извинете, плащането не може да бъде извършено. Извършва се пренасочване...
  • Операцията е отхвърлена. Обърнете се към магазина. Извършва се пренасочване...
  • Операцията е отхвърлена. Обърнете се към банката, издала картата. Извършва се пренасочване...
  • Операцията е невъзможна. Удостоверяването на притежателя на картата завърши неуспешно. Извършва се пренасочване...
  • Няма връзка с банката. Повторете по-късно. Извършва се пренасочване...
  • Изтече срокът за изчакване на въвеждане на данни. Извършва се пренасочване...
  • Не е получен отговор от банката. Повторете по-късно. Извършва се пренасочване...
НезадължителноredirectString [1..512]Този параметър се връща, ако плащането е преминало успешно и за плащането не е извършвана проверка на картата за участие в 3-D Secure. Продавачите могат да го използват, ако искат да пренасочат потребителя към страницата на платежния шлюз. Ако продавачът използва собствена страница, тази стойност може да бъде игнорирана.
НезадължителноtermUrlString [1..512]При успешен отговор в случай на плащане 3D-Secure. Това е URL-адрес, към който ACS пренасочва притежателя на картата след удостоверяване. Подробно вж. Пренасочване към ACS.
НезадължителноacsUrlString [1..512]При успешен отговор в случай на плащане 3D-Secure. URL-адрес за пренасочване към ACS. Задължителен, ако е необходимо пренасочване към ACS. За повече информация вижте Пренасочване към ACS.
НезадължителноpaReqString [1..255]PAReq (Payment Authentication Request) — съобщение, което трябва да бъде изпратено в ACS заедно с пренасочването. Връща се при успешен отговор в случай на плащане 3D-Secure, ако е необходимо пренасочване към ACS. Това съобщение съдържа данни в кодировка Base64, необходими за автентификация на притежателя на картата. За повече подробности вижте Пренасочване към ACS.

Елементът payerData съдържа следните параметри.

ЗадължителностИмеТипОписание
НезадължителноpaymentAccountReferenceString [1..29]Уникален номер на сметката на клиента, свързващ всичките му платежни средства в рамките на МПС (карти и токени).

При автентификация по протокол 3DS2 в отговор на първата заявка идват следните параметри:

ЗадължителностИмеТипОписание
Задължителноis3DSVer2BooleanВъзможни стойности: true или false Флаг, показващ, че плащането постъпва от 3DS2.
ЗадължителноthreeDSServerTransIdString [1..36]Идентификатор на транзакцията, създаден на 3DS сървъра. Задължителен за 3DS автентикация.
НезадължителноthreeDSMethodUrlString [1..512]URL-адрес на ACS сървъра за събиране на данни от браузъра.
ЗадължителноthreeDSMethodUrlServerString [1..512]URL-адрес на 3DS сървъра за събиране на данни от браузъра, които ще бъдат включени в AReq (Authentication Request) от 3DS сървъра към ACS сървъра.
НезадължителноthreeDSMethodDataPackedString [1..1024]Данни CReq (Challenge Response) в кодировка Base-64 за изпращане на сървър ACS.
НезадължителноthreeDSMethodURLServerDirectString [1..512]URL адрес 3dsmethod.do за изпълнение на 3DS метода на 3DS сървъра чрез платежния шлюз (при наличие на съответното разрешение на ниво продавач).

По-долу са посочени параметрите, които трябва да присъстват в отговора, след повторната заявка за плащане и необходимостта от пренасочване на клиента в ACS при автентификация по протокол 3DS2:

ЗадължителностИмеТипОписание
УсловноacsUrlString [1..512]При успешен отговор в случай на плащане 3D-Secure. URL-адрес за пренасочване към ACS. Задължителен, ако е необходимо пренасочване към ACS. За повече информация вижте Пренасочване към ACS.
УсловноpackedCReqStringОпаковани данни challenge request. Връща се при успешен отговор в случай на плащане 3D-Secure, ако се изисква пренасочване към ACS. Тази стойност следва да се използва като стойност на параметъра creq на връзката към ACS (acsUrl), за пренасочване на клиента към ACS. За повече подробности вж. Пренасочване към ACS.

Примери

Пример на заявка

Пример на първа заявка:

curl --request POST \
  --url https://uat.dskbank.bg/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://uat.dskbank.bg/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 сървър.
Също така ви е необходимо допълнително разрешение, назначавано от службата за поддръжка.

Параметри на заявката

ЗадължителностИмеТипОписание
ЗадължителноuserNameString [1..50]Потребителско име на API акаунта на продавача.
ЗадължителноpasswordString [1..30]Парола на API акаунта на продавача.
ЗадължителноMDORDERString [1..36]Номер на поръчката в платежния шлюз.
Условно$PANInteger [1..19]Номер на платежна карта. Задължителен, ако не е предаден seToken.
Условно$CVCString [3]Код CVC/CVV2 на обратната страна на картата. Задължителен, ако не е предаден seToken.
Позволени са само цифри.
УсловноYYYYInteger [4]Година на изтичане на валидността на платежната карта. Ако seToken не е предаден, задължително е необходимо да се предаде или $EXPIRY, или YYYY и MM.
УсловноMMInteger [2]Месец на изтичане на действието на платежната карта. Ако seToken не е предаден, задължително е необходимо да се предаде или $EXPIRY, или YYYY и MM.
Условно$EXPIRYInteger [6]Срок на валидност на картата в следния формат: YYYYMM. Предефинира параметрите YYYY и MM. Ако seToken не е предаден, задължително е необходимо да се предаде или $EXPIRY, или YYYY и MM.
УсловноseTokenStringКриптирани данни на картата, които заменят параметрите $PAN, $CVC и $EXPIRY (или YYYY,MM). Задължително, ако се използва вместо данни на картата.
Задължителни параметри за низа seToken: timestamp, UUID, PAN, EXPDATE, MDORDER. Повече за генерирането на seToken вж. тук.
Ако seToken съдържа криптирани данни за връзката (bindingId), за плащането трябва да се използва заявката paymentOrderBinding.do.
ЗадължителноTEXTString [1..512]Име на притежателя на картата.
ЗадължителноlanguageString [2]Ключ на езика по ISO 639-1. Ако езикът не е указан, се използва езикът по подразбиране, указан в настройките на магазина.
Поддържани езици: en,ru,el,ro,bg,pt,sw,hu,it,pl,de,fr,kh,cn,es,ka,da,et,fi,lt,lv,nl,sv.
НезадължителноipString [1..39]IP адрес на платеца. IPv6 се поддържа във всички заявки (до 39 символа).
НезадължителноbindingNotNeededBooleanДопустими стойности:
  • true- създаването на връзка след извършване на плащането е изключено (връзката – това е идентификатор на клиента, предаден в заявката за регистрация на поръчката, който след заявката за плащане ще бъде изтрит от детайлите на поръчката);
  • false – в случай на успешно плащане може да бъде създадена връзка (при спазване на необходимите условия). Това е стойността по подразбиране.
НезадължителноjsonParamsObjectПолета за допълнителна информация за последващо съхранение, предават се в следния вид: jsonParams={"param_1_name":"param_1_value",...,"param_n_name":"param_n_value"}.
Могат да бъдат предадени в Процесинговия Център, за последваща обработка (изисква се допълнителна настройка - обърнете се към поддръжката).
Ако използвате външен MPI/3DS Server, платежният шлюз очаква, че всяка заявка paymentOrder ще включва редица допълнителни параметри, като eci, xid, cavv и пр. По-подробна информация тук.
За да инициирате 3RI аутентификация, може да ви е необходимо да предадете редица допълнителни параметри (вж. 3RI аутентификация).
Някои предефинирани атрибути на jsonParams:
  • backToShopUrl - добавя на страницата за плащане бутон, който ще върне притежателя на картата на URL-адреса предаден в този параметър
  • backToShopName - настройва текстовия етикет на бутона Върни се в магазина по подразбиране, ако се използва заедно с backToShopUrl
  • recurringFrequency - минимален брой дни между авторизациите. Изисква се за създаване на рекурентна връзка, препоръчва се за създаване на връзка за вноски (ако се използва 3DS2, параметърът е задължителен).
  • recurringExpiry - дата, след която авторизациите не са разрешени, във формат ГГГГММДД. Изисква се за създаване на рекурентна връзка, препоръчва се за създаване на връзка за вноски (ако се използва 3DS2, параметърът е задължителен).
НезадължителноtiiStringИдентификатор на инициатора на транзакцията. Параметър, указващ какъв тип операция ще изпълнява инициаторът (Клиент или Търговец). Възможни стойности
НезадължителноthreeDSProtocolVersionStringВерсия на протокола 3DS. Възможни стойности: "2.1.0", "2.2.0" за 3DS2.
Ако в заявката не се предава threeDSProtocolVersion, то за оторизация 3D Secure ще се използва стойността по подразбиране (2.1.0 - за 3DS 2).
УсловноemailString [1..40]Електронна поща за показване на платежната страница. Ако за продавача са настроени известия на клиента, електронната поща трябва да бъде посочена. Пример: client_mail@email.com.
За плащания по VISA с 3DS авторизация е необходимо да се посочи или електронна поща, или телефонен номер на притежателя на картата.
НезадължителноmccInteger [4]Merchant Category Code (код на категория на търговеца).
За предаване на този параметър е необходимо специално разрешение. Могат да се използват стойности само от разрешения списък MCC. За получаване на по-подробна информация се обърнете към техническата поддръжка.
НезадължителноmvvString [1..10]Потвърждение на търговеца от Mastercard за токенизирани транзакции.
За предаване на този параметър трябва да бъде включена специална настройка (обърнете се към техническата поддръжка).
НезадължителноpaymentFacilitatorObjectБлок с информация за платежния фасилитатор, т.е. за търговеца, който разрешава на няколко суб-търговци да приемат плащания под своята регистрация.
За предаване на този параметър трябва да бъде включена специална настройка (обърнете се към техническата поддръжка). Вж. вложени параметри.
НезадължителноbillingPayerDataObjectБлок с регистрационни данни на клиента (адрес, пощенски код), необходим за преминаване на проверка на адреса в рамките на услугите AVS/AVV. Задължително, ако функцията е включена за продавача от страна на Платежния шлюз. Вж вложени параметри.
НезадължителноshippingPayerDataObjectОбект, съдържащ данни за доставката до клиента. Този параметър се използва за по-нататъшна 3DS-автентикация на клиента. Вж. вложени параметри.
НезадължителноpreOrderPayerDataObjectОбект, съдържащ данни за предварителната поръчка. Този параметър се използва за по-нататъшна 3DS-автентикация на клиента. Вж. вложени параметри.
НезадължителноorderPayerDataObjectОбект, съдържащ данни за платеца на поръчката. Този параметър се използва за по-нататъшна 3DS-автентикация на клиента. Вж. вложени параметри.
НезадължителноbillingAndShippingAddressMatchIndicatorString [1]Индикатор за съответствие на платежния адрес на притежателя на картата и адреса за доставка. Този параметър се използва за по-нататъшна 3DS-автентификация на клиента.
Възможни стойности:
  • Y - съвпадение на платежния адрес на притежателя на картата и адреса за доставка;
  • N - платежният адрес на притежателя на картата и адресът за доставка не съвпадат.
НезадължителноclientBrowserInfoObjectБлок данни за браузъра на клиента, който се изпраща към ACS по време на 3DS удостоверяване. Този блок може да се предава, само ако е включена специална настройка (обърнете се към екипа за поддръжка). Вж. вложени параметри.
НезадължителноacsInIFrameBooleanФлаг, показващ, че за финишния URL ще се връща iFrame версия. Възможни стойности true или false. За свързване на тази функционалност се обърнете към службата за поддръжка.
НезадължителноmarketplaceObjectБлок с параметрите на маркетплейса, т.е. продавача, който предлага стоки или услуги от различни търговци на дребно (ритейлъри).
Този параметър се използва, ако е включена специална настройка (обърнете се към службата за поддръжка). Вж. вложени параметри.

По-долу са посочени параметрите на блока billingPayerData (данни за адреса за регистрация на клиента).

ЗадължителностИмеТипОписание
НезадължителноbillingCityString [0..50]Град, регистриран за конкретната карта в Банката Емитент.
НезадължителноbillingCountryString [0..50]Страна, регистрирана за конкретната карта на банката-издател. Формат: ISO 3166-1 (Alpha 2 / Alpha 3 / Number-3) или наименование на страната. Препоръчваме предаване на двубуквен/трибуквен ISO код на страната.
НезадължителноbillingAddressLine1String [0..50]Адрес, регистриран по конкретна карта в Банката Емитент (адрес на платеца). Ред 1. Задължително за предаване за AVS-проверка.
НезадължителноbillingAddressLine2String [0..50]Адрес, регистриран за конкретната карта в Банката Емитент. Ред 2.
НезадължителноbillingAddressLine3String [0..50]Адрес, регистриран за конкретната карта в Банката Емитент. Ред 3.
НезадължителноbillingPostalCodeString [0..9]Пощенски код, регистриран за конкретната карта в Банката Издател. Задължително за предаване за AVS-проверка.
НезадължителноbillingStateString [0..50]Щат, регистриран за конкретната карта в Банката Емитент. Формат: пълна стойност на кода ISO 3166-2, негова част или наименование на щата/региона. Може да съдържа букви само от латинската азбука. Препоръчваме да се предава двубуквен ISO код на щата/региона.
ЗадължителноpayerAccountString [1..32]Номер на сметката на изпращача.
НезадължителноpayerLastNameString [1..64]Фамилия на изпращача.
НезадължителноpayerFirstNameString [1..35]Име на изпращача.
НезадължителноpayerMiddleNameString [1..35]Бащино име на изпращача.
НезадължителноpayerCombinedNameString [1..99]Пълно име на подателя.
НезадължителноpayerIdTypeString [1..8]Тип на предоставения идентифициращ документ на подателя.
Възможни стойности:
  • IDTP1 - Паспорт
  • IDTP2 - Шофьорска книжка
  • IDTP3 - Социална карта
  • IDTP4 - ID карта на гражданин
  • IDTP5 - Сертификат за водене на бизнес
  • IDTP6 - Сертификат на бежанец
  • IDTP7 - Разрешително за пребиваване
  • IDTP8 - Чужд паспорт
  • IDTP9 - Служебен паспорт
  • IDTP10 - Временен паспорт
  • IDTP11 - Паспорт на моряк
НезадължителноpayerIdNumberString [1..100]Номер на предоставения идентифициращ документ (например, паспорт) на изпращача.
НезадължителноpayerBirthdayString [1..20]Дата на раждане на изпращача във формат YYYYMMDD.

Описание на параметрите на обект shippingPayerData:

ЗадължителностНаименованиеТипОписание
НезадължителноshippingCityString [1..50]Град на поръчителя (от адреса за доставка)
НезадължителноshippingCountryString [1..50]Страна на поръчителя
НезадължителноshippingAddressLine1String [1..50]Основен адрес на клиента (от адреса за доставка)
НезадължителноshippingAddressLine2String [1..50]Основен адрес на клиента (от адреса за доставка)
НезадължителноshippingAddressLine3String [1..50]Основен адрес на клиента (от адреса за доставка)
НезадължителноshippingPostalCodeString [1..16]Пощенски код на клиента за доставка
НезадължителноshippingStateString [1..50]Щат/регион на купувача (от адреса за доставка)
НезадължителноshippingMethodIndicatorInteger [2]Индикатор за начин на доставка.
Възможни стойности:
  • 01 - доставка на платежния адрес на притежателя на карта.
  • 02 - доставка на друг адрес, проверен от Търговеца.
  • 03 - доставка на адрес, различен от основния адрес на притежателя на карта.
  • 04 - изпращане в магазин/самовземане (адресът на магазина трябва да бъде указан в съответните параметри за доставка)
  • 05 - Цифрово разпространение (включва онлайн услуги и електронни подаръчни карти)
  • 06 - билети за пътувания и събития, които не могат да бъдат доставени.
  • 07 - Други (например игри, цифрови стоки, които не подлежат на доставка, цифрови абонаменти и т.н.)
НезадължителноdeliveryTimeframeInteger [2]Срок за доставка на стоката.
Възможни стойности:
  • 01 - цифрова дистрибуция
  • 02 - доставка в същия ден
  • 03 - доставка на следващия ден
  • 04 - доставка в рамките на 2 дни след плащането и по-късно.
НезадължителноdeliveryEmail String [1..254]Целеви адрес на електронна поща за доставка на цифрово разпространение. Препоръчително е да предавате електронната поща в самостоятелен параметър на заявката email (но ако я предадете в този блок, към нея ще се прилагат същите правила).

Описание на параметрите на обект orderPayerData.

ЗадължителностНаименованиеТипОписание
НезадължителноhomePhoneString [7..15]Домашен телефон на притежателя на картата. Необходимо е винаги да се посочва код на страната, но знакът + или 00 в началото може да се посочи или пропусне. Номерът трябва да има дължина от 7 до 15 цифри. По този начин са възможни следните стойности:
  • +35799988877;
  • 0035799988877;
  • 35799988877.
НезадължителноworkPhoneString [7..15]Служебен телефон на притежателя на картата. Необходимо е винаги да се посочва код на страната, но знакът + или 00 в началото може да се посочи или пропусне. Номерът трябва да има дължина от 7 до 15 цифри. По този начин са възможни следните стойности:
  • +35799988877;
  • 0035799988877;
  • 35799988877.
НезадължителноmobilePhoneString [7..15]Номер на мобилния телефон на притежателя на картата. Необходимо е винаги да се посочва код на страната, но знакът + или 00 в началото може да се посочи или пропусне. Номерът трябва да има дължина от 7 до 15 цифри. По този начин са възможни следните стойности:
  • +35799988877;
  • 0035799988877;
  • 35799988877.

За плащания по VISA с 3DS авторизация е необходимо да се посочи или електронна поща, или номер на телефон на притежателя на картата. Ако имате настроено показване на номера на телефона на платежната страница и сте посочили неверен номер на телефон, клиентът ще може да го поправи на платежната страница.

Описание на параметрите на обекта preOrderPayerData:

ЗадължителностНаименованиеТипОписание
НезадължителноpreOrderDateString [10]Очаквана дата на доставка (за предварително поръчани покупки) във формат ГГГГММДД.
НезадължителноpreOrderPurchaseIndInteger [2]Индикатор за разполагане от клиента на поръчка за налична или бъдеща доставка.
Възможни стойности:
  • 01 - възможна е доставка;
  • 02 - бъдеща доставка
НезадължителноreorderItemsIndInteger [2]Индикатор, че клиентът преподръчва преди заплатена доставка в състава на нова поръчка.
Възможни стойности:
  • 01 - поръчката се разполага за първи път;
  • 02 - повторна поръчка

Описание на параметрите на обект orderPayerData.

ЗадължителностНаименованиеТипОписание
НезадължителноhomePhoneString [7..15]Домашен телефон на притежателя на картата. Необходимо е винаги да се посочва код на страната, но знакът + или 00 в началото може да се посочи или пропусне. Номерът трябва да има дължина от 7 до 15 цифри. По този начин са възможни следните стойности:
  • +35799988877;
  • 0035799988877;
  • 35799988877.
НезадължителноworkPhoneString [7..15]Служебен телефон на притежателя на картата. Необходимо е винаги да се посочва код на страната, но знакът + или 00 в началото може да се посочи или пропусне. Номерът трябва да има дължина от 7 до 15 цифри. По този начин са възможни следните стойности:
  • +35799988877;
  • 0035799988877;
  • 35799988877.
НезадължителноmobilePhoneString [7..15]Номер на мобилния телефон на притежателя на картата. Необходимо е винаги да се посочва код на страната, но знакът + или 00 в началото може да се посочи или пропусне. Номерът трябва да има дължина от 7 до 15 цифри. По този начин са възможни следните стойности:
  • +35799988877;
  • 0035799988877;
  • 35799988877.

За плащания по VISA с 3DS авторизация е необходимо да се посочи или електронна поща, или номер на телефон на притежателя на картата. Ако имате настроено показване на номера на телефона на платежната страница и сте посочили неверен номер на телефон, клиентът ще може да го поправи на платежната страница.

Възможни стойности tii (Подробно за типовете съхранени платежни данни, поддържани от платежния шлюз, четете тук).

Стойност tiiОписаниеТип транзакцияИнициатор на транзакциятаДанни на картата за транзакциятаЗапазване на данните на картата след транзакциятаЗабележка
ПразноОбичайнаКупувачВъвежда се от купувачаНеТранзакция на електронна търговия без запазване на съхранени платежни данни.
CIИнициираща - Обичайна (CIT)ИницииращаКупувачВъвежда се от купувачаДаТранзакция на електронна търговия със запазване на съхранени платежни данни.
FИзвънпланов платеж (CIT)ПоследващаКупувачКлиентът избира карта вместо ръчно въвежданеНеТранзакция на електронна търговия, използваща предварително запазени обичайни съхранени платежни данни.
UИзвънпланов платеж (MIT)ПоследващаПродавачНяма ръчно въвеждане, продавачът предава даннитеНеТранзакция на електронна търговия, използваща предварително запазени обичайни съхранени платежни данни. Използва се само за едностадийни плащания.
RIИнициираща - Рекурентни (CIT)ИницииращаКупувачВъвежда се от купувачаДаТранзакция на електронна търговия със запазване на съхранени платежни данни.
RРекурентен платеж (MIT)ПоследващаПродавачНяма ръчно въвеждане, продавачът предава даннитеНеРекурентна операция, използваща запазени съхранени платежни данни. Използва се само за едностадийни плащания.

По-долу са дадени параметрите на блока clientBrowserInfo (данни за браузъра на клиента).

ЗадължителностНазваниеТипОписание
НезадължителноuserAgentString [1..2048]Агент на браузъра.
НезадължителноOSStringОперационна система.
НезадължителноOSVersionStringВерсия на операционната система.
НезадължителноbrowserAcceptHeaderString [1..2048]Заглавка Accept, която съобщава на сървъра какви формати (или MIME-типове) поддържа браузъра.
НезадължителноbrowserIpAddressString [1..45]IP-адрес на браузъра.
НезадължителноbrowserLanguageString [1..8]Език на браузъра.
НезадължителноbrowserTimeZoneStringЧасова зона на браузъра.
НезадължителноbrowserTimeZoneOffsetString [1..5]Отместване на часовата зона в минути между локалното време на потребителя и UTC.
НезадължителноcolorDepthString [1..2]Дълбочина на цвета на екрана, в битове.
НезадължителноfingerprintStringОтпечатък на браузъра - уникален цифров идентификатор на браузъра.
НезадължителноisMobileBooleanВъзможни стойности: true или false. Флаг, указващ че се използва мобилно устройство.
НезадължителноjavaEnabledBooleanВъзможни стойности: true или false. Флаг, указващ че в браузъра е включена поддръжка на java.
НезадължителноjavascriptEnabledBooleanВъзможни стойности: true или false. Флаг, указващ че в браузъра е включена поддръжка на javascript.
НезадължителноpluginsStringСписък на плъгините, използвани в браузъра, разделени със запетая.
НезадължителноscreenHeightInteger [1..6]Височина на екрана в пиксели.
НезадължителноscreenWidthInteger [1..6]Ширина на екрана в пиксели.
НезадължителноscreenPrintStringДанни за параметрите за печат на браузъра, включително резолюция, дълбочина на цвета, плътност на пикселите.

Пример за блок 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":"x.x.x.x"
	}

Описание на параметрите на обекта paymentFacilitator:

ЗадължителностНаименованиеТипОписание
ЗадължителноpfIdString [1..11]Идентификатор на платежния фасилитатор.
ЗадължителноnameString [1..40]Наименование на платежния фасилитатор.
НезадължителноisoIdString [1..11]Идентификатор ISO.
ЗадължителноsubMerchantsArray of objectsМасив от обекти с допълнителна информация за субмерчантите. Вж. вложените параметри по-долу.

Параметри на елемента от масива subMerchants:

ЗадължителностНаименованиеТипОписание
ЗадължителноsubMerchantIdString [1..20]Идентификатор на субмерчанта.
ЗадължителноnameString [1..40]Наименование на субмерчанта.
ЗадължителноaddressObjectБлок с информация за адреса на субмерчанта. Вж. вложените параметри по-долу.

Параметри на обекта address:

ЗадължителностНаименованиеТипОписание
ЗадължителноcityString [1..50]Град на субмерчанта.
ЗадължителноpostalCodeString [1..16]Пощенски код на субмерчанта.
ЗадължителноcountryInteger [2]Код на страната на субмерчанта във формат ISO 3166-1.
НезадължителноstreetString [1..40]Улица на субмерчанта.

Пример за обекта paymentFacilitator:

"paymentFacilitator" :{
  "pfId": "PF123456",
  "name": "Payment Facilitator Name",
  "isoId": "ISO789",
  "subMerchants": [
    {
      "subMerchantId": "SM001",
      "name": "Sub Merchant 1",
      "address": {
        "city": "City 1",
        "postalCode": "101000",
        "country": "US",
        "street": "Street 1"
      }
    },
    {
      "subMerchantId": "SM002",
      "name": "Sub Merchant 2",
      "address": {
        "city": "City 2",
        "postalCode": "190000",
        "country": "US",
        "street": "Street 2"
      }
    }
  ]
}

Описание на параметрите на обекта marketplace:

ЗадължителностИмеТипОписание
ЗадължителноmarketplaceIdString [1..11]Идентификатор на маркетплейса в банката-акуайър.
УсловноforeignRetailerIndicatorBooleanУказва дали маркетплейсът има чуждестранни ритейлъри (дъщерни търговци). Ако в обекта marketplace се предава блок retailers, този параметър не е задължително да се предава, в противен случай – задължително.
НезадължителноretailersArray of objectsМасив от ритейлъри (дъщерни продавачи на маркетплейса). Съдържа само 1 елемент. Вложените елементи са описани по-долу.

Описание на параметрите на обекта, който е елемент от масива retailers.

ЗадължителностИмеТипОписание
ЗадължителноforeignRetailerIndicatorBooleanОпределя дали търговецът е чуждестранен.

Пример на обекта marketplace:

"marketplace": {
    "marketplaceId": "MKT12345678",
    "foreignRetailerIndicator": true,
    "retailers": [
        {
            "foreignRetailerIndicator": false
        }
    ]
}

Параметри на отговора

ЗадължителностИмеТипОписание
ЗадължителноerrorCodeString [1..2]Информационен параметър в случай на грешка, който може да има различни кодови стойности:
  • стойност 0 - указва успех на обработката на заявката;
  • друга числова стойност (1-99) - указва грешка, за получаване на по-подробна информация за която е необходимо да се провери параметър errorMessage.
Може да отсъства, ако резултатът не е предизвикал грешки.
НезадължителноerrorMessageString [1..512]Информационен параметър, който представлява описание на грешката в случай на възникване на грешка. Стойността на errorMessage може да варира, затова не трябва да се препраща изрично към неговите стойности в кода.
Езикът на описанието се задава в параметъра language на заявката.
НезадължителноinfoStringВ случай на успешен отговор. Резултат от опита за плащане. По-долу са приведени възможните стойности.
  • Вашето плащане е обработено, извършва се пренасочване...
  • Операцията е отхвърлена. Проверете въведените данни, достатъчността на средствата на картата и повторете операцията. Извършва се пренасочване...
  • Извинете, плащането не може да бъде извършено. Извършва се пренасочване...
  • Операцията е отхвърлена. Обърнете се към магазина. Извършва се пренасочване...
  • Операцията е отхвърлена. Обърнете се към банката, издала картата. Извършва се пренасочване...
  • Операцията е невъзможна. Удостоверяването на притежателя на картата завърши неуспешно. Извършва се пренасочване...
  • Няма връзка с банката. Повторете по-късно. Извършва се пренасочване...
  • Изтече срокът за изчакване на въвеждане на данни. Извършва се пренасочване...
  • Не е получен отговор от банката. Повторете по-късно. Извършва се пренасочване...

Примери

Пример на заявка

curl --request POST \\
  --url https://uat.dskbank.bg/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",
  "threeDsType": "5"
}'

Пример на отговор

{
  "redirect": "https://uat.dskbank.bg/payment/merchants/temp/finish.html?orderId=01493844-d4d3-703f-9f7e-a73900a7d8c0",
  "info": "Your order is proceeded, redirecting...",
  "errorCode": 0
}

Плащане на поръчка с признаци на Industry Practice транзакция

За плащане на поръчка с признаци на Industry Practice транзакция се използва заявка https://uat.dskbank.bg/payment/industryPractice/paymentOrder.do.


При изпълнение на заявката е необходимо да се използва заглавка: Content-Type: application/x-www-form-urlencoded

Параметри на заявката

ЗадължителностИмеТипОписание
УсловиеuserNameString [1..50]Потребителско име на API акаунта на продавача. Ако за удостоверяване при регистрация вместо потребителско име и парола се използва открит токен (параметър token), паролата не е необходимо да се предава.
УсловиеpasswordString [1..30]Парола на API акаунта на продавача. Ако за удостоверяване при регистрация вместо логин и парола се използва открит токен (параметър token), паролата не е необходимо да се предава.
УсловиеtokenString [1..256]Стойност, използвана за автентификация на продавача при изпращане на заявки към платежната шлюз. Ако предавате този параметър, то не предавайте userName и password.
ЗадължителноoriginalMdOrderString [1..36]Номер на първоначалния заказ в Платежния шлюз, за който се изпълнява Industry Practice плащане.
ЗадължителноorderNumberString [1..36]Номер на поръчката (ID) в системата на търговеца; трябва да бъде уникален за всяка поръчка.
УсловиеamountInteger [0..12]Сума на плащането в минимални единици валута (например, в стотинки) на първоначалното плащане за операции Incremental, Delayed Charges, No show.
Параметърът е задължителен за предаване при операции Incremental, Delayed Charges, No show. Параметърът не трябва да се указва за Resubmission и Reauthorization.
НезадължителноjsonParamsObjectДопълнителен таг с атрибути за предаване на допълнителни параметри. Вж. по-долу.
Старият параметър params - това е псевдоним към този параметър, т.е. заявките с params също работят.
ЗадължителноtiiStringИдентификатор на инициатора (за) транзакцията. Параметър, указващ какъв тип операция ще изпълнява инициаторът (Клиент или Търговец).
НезадължителноfeaturesStringФункции на поръчката. За да посочите няколко функции, използвайте този параметър няколко пъти в една заявка. По-долу са изброени възможните стойности.
  • VERIFY - ако се предаде тази стойност в заявката за оформяне на поръчка, притежателят на картата ще бъде верифициран, но няма да се извърши списване на средства, така че в този случай параметърът amount може да има стойност 0. Верификацията позволява да се убедите, че картата се намира в ръцете на притежателя, и впоследствие да списвате от тази карта средства, без да прибягвате до проверка на автентификационните данни (CVC, 3D-Secure) при извършване на последващи плащания. Дори ако сумата на плащането бъде предадена в заявката, тя няма да бъде списана от сметката на клиента при предаване на стойността VERIFY. Тази стойност също може да се използва за създаване на връзка — в този случай параметърът clientId също трябва да бъде предаден. Подробности четете тук.
  • FORCE_TDS - Принудително извършване на плащане с използване на 3-D Secure. Ако картата не поддържа 3-D Secure, транзакцията няма да премине.
  • FORCE_SSL - Принудително извършване на плащане чрез SSL (без използване на 3-D Secure).
  • FORCE_FULL_TDS - След извършване на автентификация с помощта на 3-D Secure статусът PaRes трябва да бъде само Y, което гарантира успешна автентификация на потребителя. В противен случай транзакцията няма да премине.
  • FORCE_CREATE_BINDING - предаването на тази стойност в заявката за оформяне на поръчка принудително създава връзка. Тази функционалност трябва да бъде включена на ниво продавач в шлюза. Тази стойност не може да се предаде в заявка със съществуващ bindingId или bindingNotNeeded = true (ще предизвика грешка при проверка). Когато се предава тази функция, параметърът clientId също трябва да бъде предаден. Ако в блока features се предадат и двете стойности FORCE_CREATE_BINDING и VERIFY, тогава поръчката ще бъде създадена САМО за създаване на връзка (без плащане).

Възможни стойности tii.

Стойност tiiОписаниеТип транзакцияИнициатор на транзакциятаДанни на картата за транзакциятаЗабележка
IPIIndustry Practice Incremental (MIT)ПоследващаПродавачНе са въведени, заредени от съответния транзакционен запис или връзка на платежния шлюзТранзакция за увеличаване на сумата на плащането в рамките на вече платена поръчка.
IPSIndustry Practice Resubmission (MIT)ПоследващаПродавачНе са въведени, заредени от съответния транзакционен запис или връзка на платежния шлюзТранзакция опит за повторно плащане, когато първоначалното плащане завърши с грешка.
IPDIndustry Practice Delayed Charges (MIT)ПоследващаПродавачНе са въведени, заредени от съответния транзакционен запис или връзка на платежния шлюзФункционалност на отложени начисления.
IPAIndustry Practice Reauthorization (MIT)ПоследващаПродавачНе са въведени, заредени от съответния транзакционен запис или връзка на платежния шлюзПовторен опит за оторизация, ако завършването или изпълнението на първоначалната поръчка/услуга излиза извън рамките на срока на действие на оторизацията, установен от Visa/MC.
IPNIndustry Practice No Show (MIT)ПоследващаПродавачНе са въведени, заредени от съответния транзакционен запис или връзка на платежния шлюзИзпълнява се от търговците за начисляване на глоби на клиента за неявяване при резервация на хотели и Car Sharing автомобили.

Блокът jsonParams съдържа полета за допълнителна информация за последващо съхранение. За предаване на N параметъра, в заявката трябва да се намират N тага jsonParams, където атрибутът name съдържа името, а атрибутът value съдържа стойността (вж. таблицата по-долу).

ЗадължителностИмеТипОписание
ЗадължителноnameString [1..255]Име на допълнителния параметър.
ЗадължителноvalueString [1..1024]Стойност на допълнителния параметър - до 1024 символа.

Параметри на отговора

ЗадължителностИмеТипОписание
НезадължителноerrorCodeString [1..2]Информационен параметър в случай на грешка, който може да има различни кодови стойности:
  • стойност 0 - указва успех на обработката на заявката;
  • друга числова стойност (1-99) - указва грешка, за получаване на по-подробна информация за която е необходимо да се провери параметър errorMessage.
Може да отсъства, ако резултатът не е предизвикал грешки.
НезадължителноerrorMessageString [1..512]Информационен параметър, който представлява описание на грешката в случай на възникване на грешка. Стойността на errorMessage може да варира, затова не трябва да се препраща изрично към неговите стойности в кода.
Езикът на описанието се задава в параметъра language на заявката.
НезадължителноmdOrderString [1..36]Номер на поръчката в платежния шлюз с изпълнено Industry Practice плащане.
НезадължителноactionCodeStringКод за отговор от банковата обработка. Съдържа числова стойност. Вижте списъка с кодове за отговор тук.
НезадължителноapprovalCodeString [6]Код за оторизация на МПС. Това поле има фиксирана дължина (шест символа) и може да съдържа цифри и латински букви.
НезадължителноrrnInteger [1..12]Reference Retrieval Number - идентификатор на транзакцията, присвоен от банката-акуайър.

Примери

Пример за заявка

curl --request POST \\
  --url https://uat.dskbank.bg/payment/industryPractice/paymentOrder.do \\
  --header 'content-type: application/x-www-form-urlencoded' \\
  --data '{
    "originalMdOrder":"f252eee4-5598-728a-a023-af6e09078dd0",
    "orderNumber":"testOrderNumber1",
    "tii":"IPI",
    "amount":"10",
    "username":"test_user",
    "password":"test_user_password"
}'

Пример за отговор - Успешно плащане на поръчка с признаци на Industry Practice транзакция

{
  "errorCode": "0",
  "errorMessage": "Successful",
  "mdOrder": "d88680c4-54e9-7115-80ae-3cc709017350",
  "actionCode": "0",
  "approvalCode": "000000",
  "rrn": "111111111113"
}

Пример за отговор - Неуспешно плащане на поръчка с признаци на Industry Practice транзакция (процесингът върна грешка)

{
  "errorCode": "5",
  "errorMessage": "Unsuccessful",
  "mdOrder": "d88680c4-54e9-7115-80ae-3cc709017350",
  "actionCode": "116",
  "approvalCode": "000000",
  "rrn": "111111111113"
}

Неуспешно плащане на поръчка с признаци на Industry Practice транзакция (например, грешка при валидация)

{
  "errorCode": "5",
  "errorMessage": "Operation is not allowed for original order"
}

Моментално плащане

Заявка, използвана за регистрация на поръчка и едновременно плащане за нея – https://uat.dskbank.bg/payment/rest/instantPayment.do.


При изпълнение на заявката е необходимо да се използва заглавката: Content-Type: application/x-www-form-urlencoded

Параметри на заявката

ЗадължителностИмеТипОписание
УсловноuserNameString [1..50]Потребителско име на API акаунта на продавача. Ако за удостоверяване при регистрация вместо потребителско име и парола се използва открит токен (параметър token), паролата не е необходимо да се предава.
УсловноpasswordString [1..30]Парола на API акаунта на продавача. Ако за удостоверяване при регистрация вместо логин и парола се използва открит токен (параметър token), паролата не е необходимо да се предава.
УсловноtokenString [1..256]Стойност, използвана за автентификация на продавача при изпращане на заявки към платежната шлюз. Ако предавате този параметър, то не предавайте userName и password.
ЗадължителноamountInteger [0..12]Сума на плащането в минимални единици валута (например, в стотинки).
ЗадължителноcurrencyString [3]Код на валутата на плащането ISO 4217. Ако не е посочен, се използва стойността по подразбиране. Позволени са само цифри.
НезадължителноclientIdString [0..255]Номер на клиента (ID) в системата на търговеца — до 255 символа. Използва се за реализиране на функционалността на връзките. Може да се връща в отговора, ако на търговеца е разрешено да създава връзки.
Указването на този параметър при обработка на плащания по връзка е задължително. В противен случай плащането ще бъде невъзможно.
НезадължителноipString [1..39]IP адрес на платеца. IPv6 се поддържа във всички заявки (до 39 символа).
НезадължителноbindingNotNeededBooleanДопустими стойности:
  • true- създаването на връзка след извършване на плащането е изключено (връзката е идентификатор на клиента, предаден в заявката за регистрация на поръчката, който след заявката instantPayment.do ще бъде изтрит от детайлите на поръчката);
  • false – в случай на успешно плащане може да бъде създадена връзка (при спазване на необходимите условия). Това е стойността по подразбиране.
УсловноorderNumberString [1..36]Номер на поръчка (ID) в системата на търговеца, трябва да бъде уникален за всеки търговец, регистриран в платежния шлюз. Ако номерът на поръчката се генерира от страната на платежния шлюз, този параметър не е задължително да се предава.
НезадължителноdescriptionString [1..598]Описание на поръчката в произволен формат.
За да включите изпращането на това поле в процесинговата система, обърнете се към службата за техническа поддръжка.
В това поле е недопустимо да се предават лични данни или платежни данни (номера на карти и т.н.). Това изискване се дължи на факта, че описанието на поръчката никъде не се маскира.
НезадължителноlanguageString [2]Ключ на езика по ISO 639-1. Ако езикът не е указан, се използва езикът по подразбиране, указан в настройките на магазина.
Поддържани езици: en,ru,el,ro,bg,pt,sw,hu,it,pl,de,fr,kh,cn,es,ka,da,et,fi,lt,lv,nl,sv.
НезадължителноbindingIdString [1..255]Идентификатор на вече съществуваща връзка (идентификатор на карта, токенизирана от gateway). Може да се използва само ако търговецът има разрешение за работа с връзки. Ако този параметър се предава в тази заявка, това означава, че:
  • Тази поръчка може да бъде платена само чрез връзка;
  • Платецът ще бъде пренасочен към страница за плащане, където се изисква само въвеждане на CVC.
УсловноoriginalSchemeTransactionIdString [1..22]Идентификатор на оригиналната успешна транзакция в Mastercard.
Задължителен при използване на запазени данни за карта на търговеца в преводи по запазени данни за карта.
НезадължителноpreAuthBooleanПараметър, определящ необходимостта от предварителна оторизация (блокиране на средства по сметката на клиента преди тяхното списване). Достъпни са следните стойности:
  • true - включено е двуетапно плащане;
  • false - включено е едноетапно плащане (парите се списват веднага).
Ако параметърът липсва, извършва се едноетапно плащане.
НезадължителноpanString [1..19]Номер на платежна карта (задължително, ако bindinId не се предава). Стойността pan заменя стойността bindingId.
НезадължителноcvcString [3]Предаването на параметъра се определя от типа на плащането:
  • предаването на cvc не е предвидено за всички токенизирани плащания;
  • предаването на cvc не е предвидено за MIT плащания;
  • предаването на cvc е задължително по подразбиране за всички други типове плащания; но ако за търговеца е избрано разрешението Може да извършва плащане без потвърждение на CVC, то в такъв случай предаването на cvc става незадължително.

Допускат се само цифри.
НезадължителноcardHolderNameString [1..26]Име на притежателя на картата с латински букви. Този параметър се предава само след плащането на поръчката.
НезадължителноmerchantLoginString [1..255]За да регистрирате поръчка от името на друг търговец, посочете неговия логин (за API-акаунт) в този параметър.
Може да се използва само ако имате разрешение за преглед на транзакциите на други продавачи или ако посоченият продавач е ваш дъщерен продавач.
НезадължителноsessionTimeoutSecsInteger [1..9]Продължителност на живота на поръчката в секунди. В случай че параметърът не е зададен, ще бъде използвана стойността, указана в настройките на търговеца, или времето по подразбиране (1200 секунди = 20 минути). Ако в заявката присъства параметър expirationDate, то стойността на параметър sessionTimeoutSecs не се взема предвид.
НезадължителноautocompletionDateString [19]Дата и време на автоматичното завършване на двуетапното плащане в следния формат: 2025-12-29T13:02:51. Използван часови пояс: UTC+0. За да включите изпращането на това поле в процесинговата система, обърнете се към службата за техническа поддръжка.
НезадължителноautoReverseDateString [19]Дата и час на автоматично анулиране на двуетапното плащане в следния формат: 2025-06-23T13:02:51. Използван часови пояс: UTC+0. За да включите изпращането на това поле в процесинговата система, обърнете се към службата за техническа поддръжка.
НезадължителноexpirationDateString [19]Дата и час на изтичане на срока на валидност на поръчката. Формат: yyyy-MM-ddTHH:mm:ss.
Ако този параметър не се предава в заявката, то за определяне на времето на изтичане на срока на валидност на поръчката се използва параметърът sessionTimeoutSecs.
УсловноseTokenString [1..8192]Шифровани данни за карта, които заменят параметрите $PAN, $CVC и $EXPIRY (или YYYY,MM). Задължително, ако се използва вместо данни за карта.
Задължителни параметри за низа seToken: timestamp, UUID, bindingId(или PAN,EXPDATE). Подробности за генерирането на seToken вж. тук.
ЗадължителноreturnUrlString [1..512]Адрес, към който трябва да бъде пренасочен потребителят в случай на успешно плащане. Адресът трябва да бъде указан изцяло, включително използвания протокол (например, https://mybestmerchantreturnurl.com вместо mybestmerchantreturnurl.com). В противен случай потребителят ще бъде пренасочен на адрес от следния вид: https://uat.dskbank.bg/payment/<merchant_address>.
НезадължителноfailUrlString [1..512]Адрес, на който трябва да се пренасочи потребителят в случай на неуспешно плащане. Адресът трябва да бъде посочен напълно, включително използвания протокол (например, https://mybestmerchantreturnurl.com вместо mybestmerchantreturnurl.com). В противен случай потребителят ще бъде пренасочен по адрес от следния вид: https://uat.dskbank.bg/payment/<merchant_address>.
НезадължителноjsonParamsObjectПолета за допълнителна информация за последващо съхранение, предават се в следния вид: jsonParams={"param_1_name":"param_1_value",...,"param_n_name":"param_n_value"}.
Могат да бъдат предадени в Процесинговия Център, за последваща обработка (изисква се допълнителна настройка - обърнете се към поддръжката).
Ако използвате външен MPI/3DS Server, платежният шлюз очаква, че всяка заявка paymentOrder ще включва редица допълнителни параметри, като eci, xid, cavv и пр. По-подробна информация тук.
За да инициирате 3RI аутентификация, може да ви е необходимо да предадете редица допълнителни параметри (вж. 3RI аутентификация).
Някои предефинирани атрибути на jsonParams:
  • backToShopUrl - добавя на страницата за плащане бутон, който ще върне притежателя на картата на URL-адреса предаден в този параметър
  • backToShopName - настройва текстовия етикет на бутона Върни се в магазина по подразбиране, ако се използва заедно с backToShopUrl
  • recurringFrequency - минимален брой дни между авторизациите. Изисква се за създаване на рекурентна връзка, препоръчва се за създаване на връзка за вноски (ако се използва 3DS2, параметърът е задължителен).
  • recurringExpiry - дата, след която авторизациите не са разрешени, във формат ГГГГММДД. Изисква се за създаване на рекурентна връзка, препоръчва се за създаване на връзка за вноски (ако се използва 3DS2, параметърът е задължителен).
НезадължителноfeaturesStringФункции на поръчката. За да посочите няколко функции, използвайте този параметър няколко пъти в една заявка. По-долу са изброени възможните стойности.
  • VERIFY - ако се предаде тази стойност в заявката за оформяне на поръчка, притежателят на картата ще бъде верифициран, но няма да се извърши списване на средства, така че в този случай параметърът amount може да има стойност 0. Верификацията позволява да се убедите, че картата се намира в ръцете на притежателя, и впоследствие да списвате от тази карта средства, без да прибягвате до проверка на автентификационните данни (CVC, 3D-Secure) при извършване на последващи плащания. Дори ако сумата на плащането бъде предадена в заявката, тя няма да бъде списана от сметката на клиента при предаване на стойността VERIFY. Тази стойност също може да се използва за създаване на връзка — в този случай параметърът clientId също трябва да бъде предаден. Подробности четете тук.
  • FORCE_TDS - Принудително извършване на плащане с използване на 3-D Secure. Ако картата не поддържа 3-D Secure, транзакцията няма да премине.
  • FORCE_SSL - Принудително извършване на плащане чрез SSL (без използване на 3-D Secure).
  • FORCE_FULL_TDS - След извършване на автентификация с помощта на 3-D Secure статусът PaRes трябва да бъде само Y, което гарантира успешна автентификация на потребителя. В противен случай транзакцията няма да премине.
  • FORCE_CREATE_BINDING - предаването на тази стойност в заявката за оформяне на поръчка принудително създава връзка. Тази функционалност трябва да бъде включена на ниво продавач в шлюза. Тази стойност не може да се предаде в заявка със съществуващ bindingId или bindingNotNeeded = true (ще предизвика грешка при проверка). Когато се предава тази функция, параметърът clientId също трябва да бъде предаден. Ако в блока features се предадат и двете стойности FORCE_CREATE_BINDING и VERIFY, тогава поръчката ще бъде създадена САМО за създаване на връзка (без плащане).
НезадължителноorderBundleObjectОбект, съдържащ кошницата с продукти. Описанието на вложените елементи е дадено по-долу.
НезадължителноdynamicCallbackUrlString [1..512]Параметър за предаване на динамичен адрес за получаване на "платежни" callback-уведомления за поръчката, активирани за търговеца (успешна авторизация, успешно списване, връщане, отказ, отхвърляне на плащане по таймаут, отхвърляне на card present плащане).
"Не платежни" callback-уведомления (включване/изключване на връзка, създаване на връзка), ще бъдат изпращани на статичен callback адрес.
НезадължителноthreeDSServerTransIdString [1..36]Идентификатор на транзакцията, създаден на 3DS сървъра. Задължителен за 3DS автентикация.
НезадължителноthreeDSVer2FinishUrlString [1..512]URL-адрес, с който клиентът трябва да бъде пренасочен след автентификация на сървъра ACS.
НезадължителноthreeDSMethodNotificationUrlString [1..512]URL-адрес за изпращане на уведомление за преминаване на проверката в ACS.
УсловноthreeDSVer2MdOrderString [1..36]Номер на поръчка, който е регистриран в първата част от заявката в рамките на 3DS2 операция. Задължителен за удостоверяване 3DS.
Ако този параметър присъства в заявката, тогава се използва mdOrder, който се предава в настоящия параметър. В такъв случай регистрацията на поръчката не се извършва, а се извършва веднага плащането на поръчката.
Този параметър се предава само при използване на методи за мгновено плащане, т.е., когато поръчката се регистрира и се заплаща в рамките на една заявка.
НезадължителноthreeDSSDKBooleanВъзможни стойности: true или false Флаг, показващ, че плащането постъпва от 3DS SDK.
НезадължителноthreeDSProtocolVersionStringВерсия на протокола 3DS. Възможни стойности: "2.1.0", "2.2.0" за 3DS2.
Ако в заявката не се предава threeDSProtocolVersion, то за оторизация 3D Secure ще се използва стойността по подразбиране (2.1.0 - за 3DS 2).
НезадължителноexpiryInteger [6]Срок на валидност на картата в следния формат: YYYYMM. Задължително, ако не са предадени нито seToken, нито bindingId.
УсловноemailString [1..40]Електронна поща за показване на платежната страница. Ако за продавача са настроени известия на клиента, електронната поща трябва да бъде посочена. Пример: client_mail@email.com.
За плащания по VISA с 3DS авторизация е необходимо да се посочи или електронна поща, или телефонен номер на притежателя на картата.
НезадължителноmccInteger [4]Merchant Category Code (код на категория на търговеца).
За предаване на този параметър е необходимо специално разрешение. Могат да се използват стойности само от разрешения списък MCC. За получаване на по-подробна информация се обърнете към техническата поддръжка.
НезадължителноmvvString [1..10]Потвърждение на търговеца от Mastercard за токенизирани транзакции.
За предаване на този параметър трябва да бъде включена специална настройка (обърнете се към техническата поддръжка).
НезадължителноpaymentFacilitatorObjectБлок с информация за платежния фасилитатор, т.е. за търговеца, който позволява на няколко подтърговци да приемат плащания под неговия акаунт.
За предаване на този параметър трябва да бъде включена специална настройка (свържете се с техническата поддръжка). Вж. вложени параметри.
НезадължителноtiiStringИдентификатор на инициатора на транзакцията. Параметър, указващ какъв тип операция ще изпълнява инициаторът (Клиент или Търговец). Възможни стойности
УсловноoriginalPaymentNetRefNumStringИдентификатор на оригиналната или предишната успешна транзакция в платежната система по отношение на изпълняваната операция по връзката - TRN ID. Предава се, ако стойността на параметъра tii = R,U или F.
Задължителен при използване на връзките на търговеца в преводите по връзка.
УсловноoriginalPaymentDateStringДата на инициираща транзакция. Стойност във формат Unix timestamp в милисекунди. Предава се, ако стойността на параметъра tii = R,U или F.
НезадължителноexternalScaExemptionIndicatorStringТип на изключение SCA (Strong Customer Authentication). Ако е посочен този параметър, транзакцията ще бъде обработена в зависимост от вашите настройки в платежния шлюз: или ще бъде изпълнена принудителна операция SSL, или банката-издател ще получи информация за изключението SCA и ще вземе решение за провеждане на операцията с 3DS-автентификация или без нея (за получаване на подробна информация се свържете с нашата служба за поддръжка). Допустими стойности:
  • LVP – транзакция от тип Low Value Payments. Транзакцията може да бъде отнесена към транзакции с ниско ниво на риск въз основа на сумата на транзакцията, броя на транзакциите на клиента в деня или общата дневна сума на плащанията на клиента.
  • TRA – транзакция от тип Transaction Risk Analysis, т.е. транзакция, преминала успешна антифрод-проверка.

За предаване на този параметър трябва да имате достатъчни права в платежния шлюз.
НезадължителноbillingPayerDataObjectБлок с регистрационни данни на клиента (адрес, пощенски код), необходими за преминаване на проверка на адреса в рамките на услугите AVS/AVV. Задължително, ако функцията е включена за продавача от страна на Платежния шлюз. Вж. вложени параметри.
НезадължителноshippingPayerDataObjectОбект, съдържащ данни за доставката до клиента. Този параметър се използва за по-нататъшна 3DS-автентикация на клиента. Вж. вложени параметри.
НезадължителноmarketplaceObjectБлок с параметри на маркетплейса, т.е. продавач, който предлага стоки или услуги от различни търговци на дребно (ритейлери).
Този параметър се използва, ако е включена специална настройка (свържете се със службата за поддръжка). Вж. вложени параметри.
НезадължителноpreOrderPayerDataObjectОбект, съдържащ данни за предварителна поръчка. Този параметър се използва за по-нататъшна 3DS-автентикация на клиента. Вж. вложени параметри.
НезадължителноorderPayerDataObjectОбект, съдържащ данни за платеца на поръчката. Този параметър се използва за по-нататъшна 3DS-автентикация на клиента. Вж. вложени параметри.
НезадължителноclientBrowserInfoObjectБлок от данни за браузъра на клиента, който се изпраща на ACS по време на 3DS автентификация. Този блок може да се предава само ако е включена специална настройка (обърнете се към екипа за поддръжка). Вж. вложени параметри.
НезадължителноbillingAndShippingAddressMatchIndicatorString [1]Индикатор за съответствие на платежния адрес на притежателя на картата и адреса за доставка. Този параметър се използва за по-нататъшна 3DS-автентификация на клиента.
Възможни стойности:
  • Y - съвпадение на платежния адрес на притежателя на картата и адреса за доставка;
  • N - платежният адрес на притежателя на картата и адресът за доставка не съвпадат.

Описание на параметрите в обекта orderBundle:

ЗадължителностИмеТипОписание
НезадължителноorderCreationDateString [19]Дата на създаване на поръчката във формат YYYY-MM-DDTHH:MM:SS.
НезадължителноcustomerDetailsObjectБлок, съдържащ атрибутите на клиента. Описанието на атрибутите на тага е дадено по-долу.
ЗадължителноcartItemsObjectОбект, съдържащ атрибутите на стоките в кошницата. Описанието на вложените елементи е дадено по-долу.

Описание на параметрите в обект customerDetails:

ЗадължителностНаименованиеТипОписание
НезадължителноcontactString [0..40]Предпочитан от клиента начин за връзка.
НезадължителноfullNameString [1..100]ФИО на платеца.
НезадължителноpassportString [1..100]Серия и номер на паспорта на платеца в следния формат: 2222888888
НезадължителноdeliveryInfoObjectОбект, съдържащ атрибутите на адреса за доставка. Описанието на вложените елементи е приведено по-долу.

Описание на параметрите в обекта deliveryInfo:

ЗадължителностНаименованиеТипОписание
НезадължителноdeliveryTypeString [1..20]Начин на доставка.
ЗадължителноcountryString [2]Двубуквен код на страната за доставка.
ЗадължителноcityString [0..40]Град на назначение.
ЗадължителноpostAddressString [1..255]Адрес за доставка.

Описание на параметрите в обекта cartItems:

ЗадължителностНаименованиеТипОписание
ЗадължителноitemsObjectЕлемент на масив с атрибути на стокова позиция. Описанието на вложените елементи е дадено по-долу.

Описание на параметрите в обект items:

ЗадължителностНаименованиеТипОписание
ЗадължителноpositionIdInteger [1..12]Уникален идентификатор на стоковата позиция в кошницата.
ЗадължителноnameString [1..255]Наименование или описание на стокова позиция в свободна форма.
НезадължителноitemDetailsObjectОбект с параметри за описанието на стоковата позиция. Описанието на вложените елементи е приведено по-долу.
ЗадължителноquantityObjectЕлемент, описващ общото количество стокови позиции на един positionId и неговите мерни единици. Описанието на вложените елементи е приведено по-долу.
НезадължителноitemAmountInteger [1..12]Сума на стойността на всички стокови позиции за един positionId в минимални единици валута. itemAmount е задължителен за предаване, само ако не е предаден параметърът itemPrice. В противен случай предаването на itemAmount не се изисква. Ако в заявката се предават и двата параметъра: itemPrice и itemAmount, то itemAmount трябва да се равнява на itemPrice * quantity, в противен случай заявката ще завърши с грешка.
НезадължителноitemPriceInteger [1..18]Сума на стойността на стоковата позиция на един positionId в пари в минимални единици валута.
НезадължителноdepositedItemAmountString [1..18]Сума на списване за един positionId в минимални валутни единици (например, в стотинки).
НезадължителноitemCurrencyInteger [3]Код на валута ISO 4217. Ако не е посочен, се счита равен на валутата на поръчката.
ЗадължителноitemCodeString [1..100]Номер (идентификатор) на стокова позиция в системата на магазина.

Описание на параметрите в обекта itemDetails:

ЗадължителностНазваниеТипОписание
НезадължителноitemDetailsParamsObjectПараметър, описващ допълнителна информация по стоковата позиция. Описанието на вложените елементи е приведено по-долу.

Описание на параметрите в обекта itemDetailsParams:

ЗадължителностНаименованиеТипОписание
ЗадължителноvalueString [1..2000]Допълнителна информация за товарната позиция.
ЗадължителноnameString [1..255]Наименование на параметъра за описанието на детайлизацията на стоковата позиция

Описание на параметрите в обект quantity:

ЗадължителностИмеТипОписание
ЗадължителноvalueNumber [1..18]Количество на стокови позиции от дадения positionId. За указване на дробни числа използвайте десетична точка. Допуска се максимум 3 знака след точката.
ЗадължителноmeasureString [1..20]Мерна единица за количеството по позицията.

Възможни стойности tii (Подробно за типовете съхранени платежни данни, поддържани от платежния шлюз, четете тук).

Стойност tiiОписаниеТип транзакцияИнициатор на транзакциятаДанни на картата за транзакциятаЗапазване на данните на картата след транзакциятаЗабележка
ПразноОбичайнаКупувачВъвежда се от купувачаНеТранзакция на електронна търговия без запазване на съхранени платежни данни.
CIИнициираща - Обичайна (CIT)ИницииращаКупувачВъвежда се от купувачаДаТранзакция на електронна търговия със запазване на съхранени платежни данни.
FИзвънпланов платеж (CIT)ПоследващаКупувачКлиентът избира карта вместо ръчно въвежданеНеТранзакция на електронна търговия, използваща предварително запазени обичайни съхранени платежни данни.
UИзвънпланов платеж (MIT)ПоследващаПродавачНяма ръчно въвеждане, продавачът предава даннитеНеТранзакция на електронна търговия, използваща предварително запазени обичайни съхранени платежни данни. Използва се само за едностадийни плащания.
RIИнициираща - Рекурентни (CIT)ИницииращаКупувачВъвежда се от купувачаДаТранзакция на електронна търговия със запазване на съхранени платежни данни.
RРекурентен платеж (MIT)ПоследващаПродавачНяма ръчно въвеждане, продавачът предава даннитеНеРекурентна операция, използваща запазени съхранени платежни данни. Използва се само за едностадийни плащания.

По-долу са посочени параметрите на блока billingPayerData (данни за адреса за регистрация на клиента).

ЗадължителностИмеТипОписание
НезадължителноbillingCityString [0..50]Град, регистриран за конкретната карта в Банката Емитент.
НезадължителноbillingCountryString [0..50]Страна, регистрирана за конкретната карта на банката-издател. Формат: ISO 3166-1 (Alpha 2 / Alpha 3 / Number-3) или наименование на страната. Препоръчваме предаване на двубуквен/трибуквен ISO код на страната.
НезадължителноbillingAddressLine1String [0..50]Адрес, регистриран по конкретна карта в Банката Емитент (адрес на платеца). Ред 1. Задължително за предаване за AVS-проверка.
НезадължителноbillingAddressLine2String [0..50]Адрес, регистриран за конкретната карта в Банката Емитент. Ред 2.
НезадължителноbillingAddressLine3String [0..50]Адрес, регистриран за конкретната карта в Банката Емитент. Ред 3.
НезадължителноbillingPostalCodeString [0..9]Пощенски код, регистриран за конкретната карта в Банката Издател. Задължително за предаване за AVS-проверка.
НезадължителноbillingStateString [0..50]Щат, регистриран за конкретната карта в Банката Емитент. Формат: пълна стойност на кода ISO 3166-2, негова част или наименование на щата/региона. Може да съдържа букви само от латинската азбука. Препоръчваме да се предава двубуквен ISO код на щата/региона.
ЗадължителноpayerAccountString [1..32]Номер на сметката на изпращача.
НезадължителноpayerLastNameString [1..64]Фамилия на изпращача.
НезадължителноpayerFirstNameString [1..35]Име на изпращача.
НезадължителноpayerMiddleNameString [1..35]Бащино име на изпращача.
НезадължителноpayerCombinedNameString [1..99]Пълно име на подателя.
НезадължителноpayerIdTypeString [1..8]Тип на предоставения идентифициращ документ на подателя.
Възможни стойности:
  • IDTP1 - Паспорт
  • IDTP2 - Шофьорска книжка
  • IDTP3 - Социална карта
  • IDTP4 - ID карта на гражданин
  • IDTP5 - Сертификат за водене на бизнес
  • IDTP6 - Сертификат на бежанец
  • IDTP7 - Разрешително за пребиваване
  • IDTP8 - Чужд паспорт
  • IDTP9 - Служебен паспорт
  • IDTP10 - Временен паспорт
  • IDTP11 - Паспорт на моряк
НезадължителноpayerIdNumberString [1..100]Номер на предоставения идентифициращ документ (например, паспорт) на изпращача.
НезадължителноpayerBirthdayString [1..20]Дата на раждане на изпращача във формат YYYYMMDD.

Описание на параметрите на обект shippingPayerData:

ЗадължителностНаименованиеТипОписание
НезадължителноshippingCityString [1..50]Град на поръчителя (от адреса за доставка)
НезадължителноshippingCountryString [1..50]Страна на поръчителя
НезадължителноshippingAddressLine1String [1..50]Основен адрес на клиента (от адреса за доставка)
НезадължителноshippingAddressLine2String [1..50]Основен адрес на клиента (от адреса за доставка)
НезадължителноshippingAddressLine3String [1..50]Основен адрес на клиента (от адреса за доставка)
НезадължителноshippingPostalCodeString [1..16]Пощенски код на клиента за доставка
НезадължителноshippingStateString [1..50]Щат/регион на купувача (от адреса за доставка)
НезадължителноshippingMethodIndicatorInteger [2]Индикатор за начин на доставка.
Възможни стойности:
  • 01 - доставка на платежния адрес на притежателя на карта.
  • 02 - доставка на друг адрес, проверен от Търговеца.
  • 03 - доставка на адрес, различен от основния адрес на притежателя на карта.
  • 04 - изпращане в магазин/самовземане (адресът на магазина трябва да бъде указан в съответните параметри за доставка)
  • 05 - Цифрово разпространение (включва онлайн услуги и електронни подаръчни карти)
  • 06 - билети за пътувания и събития, които не могат да бъдат доставени.
  • 07 - Други (например игри, цифрови стоки, които не подлежат на доставка, цифрови абонаменти и т.н.)
НезадължителноdeliveryTimeframeInteger [2]Срок за доставка на стоката.
Възможни стойности:
  • 01 - цифрова дистрибуция
  • 02 - доставка в същия ден
  • 03 - доставка на следващия ден
  • 04 - доставка в рамките на 2 дни след плащането и по-късно.
НезадължителноdeliveryEmail String [1..254]Целеви адрес на електронна поща за доставка на цифрово разпространение. Препоръчително е да предавате електронната поща в самостоятелен параметър на заявката email (но ако я предадете в този блок, към нея ще се прилагат същите правила).

Описание на параметрите на обекта preOrderPayerData:

ЗадължителностНаименованиеТипОписание
НезадължителноpreOrderDateString [10]Очаквана дата на доставка (за предварително поръчани покупки) във формат ГГГГММДД.
НезадължителноpreOrderPurchaseIndInteger [2]Индикатор за разполагане от клиента на поръчка за налична или бъдеща доставка.
Възможни стойности:
  • 01 - възможна е доставка;
  • 02 - бъдеща доставка
НезадължителноreorderItemsIndInteger [2]Индикатор, че клиентът преподръчва преди заплатена доставка в състава на нова поръчка.
Възможни стойности:
  • 01 - поръчката се разполага за първи път;
  • 02 - повторна поръчка

Описание на параметрите на обект orderPayerData.

ЗадължителностНаименованиеТипОписание
НезадължителноhomePhoneString [7..15]Домашен телефон на притежателя на картата. Необходимо е винаги да се посочва код на страната, но знакът + или 00 в началото може да се посочи или пропусне. Номерът трябва да има дължина от 7 до 15 цифри. По този начин са възможни следните стойности:
  • +35799988877;
  • 0035799988877;
  • 35799988877.
НезадължителноworkPhoneString [7..15]Служебен телефон на притежателя на картата. Необходимо е винаги да се посочва код на страната, но знакът + или 00 в началото може да се посочи или пропусне. Номерът трябва да има дължина от 7 до 15 цифри. По този начин са възможни следните стойности:
  • +35799988877;
  • 0035799988877;
  • 35799988877.
НезадължителноmobilePhoneString [7..15]Номер на мобилния телефон на притежателя на картата. Необходимо е винаги да се посочва код на страната, но знакът + или 00 в началото може да се посочи или пропусне. Номерът трябва да има дължина от 7 до 15 цифри. По този начин са възможни следните стойности:
  • +35799988877;
  • 0035799988877;
  • 35799988877.

За плащания по VISA с 3DS авторизация е необходимо да се посочи или електронна поща, или номер на телефон на притежателя на картата. Ако имате настроено показване на номера на телефона на платежната страница и сте посочили неверен номер на телефон, клиентът ще може да го поправи на платежната страница.

По-долу са дадени параметрите на блока clientBrowserInfo (данни за браузъра на клиента).

ЗадължителностНазваниеТипОписание
НезадължителноuserAgentString [1..2048]Агент на браузъра.
НезадължителноOSStringОперационна система.
НезадължителноOSVersionStringВерсия на операционната система.
НезадължителноbrowserAcceptHeaderString [1..2048]Заглавка Accept, която съобщава на сървъра какви формати (или MIME-типове) поддържа браузъра.
НезадължителноbrowserIpAddressString [1..45]IP-адрес на браузъра.
НезадължителноbrowserLanguageString [1..8]Език на браузъра.
НезадължителноbrowserTimeZoneStringЧасова зона на браузъра.
НезадължителноbrowserTimeZoneOffsetString [1..5]Отместване на часовата зона в минути между локалното време на потребителя и UTC.
НезадължителноcolorDepthString [1..2]Дълбочина на цвета на екрана, в битове.
НезадължителноfingerprintStringОтпечатък на браузъра - уникален цифров идентификатор на браузъра.
НезадължителноisMobileBooleanВъзможни стойности: true или false. Флаг, указващ че се използва мобилно устройство.
НезадължителноjavaEnabledBooleanВъзможни стойности: true или false. Флаг, указващ че в браузъра е включена поддръжка на java.
НезадължителноjavascriptEnabledBooleanВъзможни стойности: true или false. Флаг, указващ че в браузъра е включена поддръжка на javascript.
НезадължителноpluginsStringСписък на плъгините, използвани в браузъра, разделени със запетая.
НезадължителноscreenHeightInteger [1..6]Височина на екрана в пиксели.
НезадължителноscreenWidthInteger [1..6]Ширина на екрана в пиксели.
НезадължителноscreenPrintStringДанни за параметрите за печат на браузъра, включително резолюция, дълбочина на цвета, плътност на пикселите.

Пример за блок 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":"x.x.x.x"
	}

Описание на параметрите на обекта paymentFacilitator:

ЗадължителностНаименованиеТипОписание
ЗадължителноpfIdString [1..11]Идентификатор на платежния фасилитатор.
ЗадължителноnameString [1..40]Наименование на платежния фасилитатор.
НезадължителноisoIdString [1..11]Идентификатор ISO.
ЗадължителноsubMerchantsArray of objectsМасив от обекти с допълнителна информация за субмерчантите. Вж. вложените параметри по-долу.

Параметри на елемента от масива subMerchants:

ЗадължителностНаименованиеТипОписание
ЗадължителноsubMerchantIdString [1..20]Идентификатор на субмерчанта.
ЗадължителноnameString [1..40]Наименование на субмерчанта.
ЗадължителноaddressObjectБлок с информация за адреса на субмерчанта. Вж. вложените параметри по-долу.

Параметри на обекта address:

ЗадължителностНаименованиеТипОписание
ЗадължителноcityString [1..50]Град на субмерчанта.
ЗадължителноpostalCodeString [1..16]Пощенски код на субмерчанта.
ЗадължителноcountryInteger [2]Код на страната на субмерчанта във формат ISO 3166-1.
НезадължителноstreetString [1..40]Улица на субмерчанта.

Пример за обекта paymentFacilitator:

"paymentFacilitator" :{
  "pfId": "PF123456",
  "name": "Payment Facilitator Name",
  "isoId": "ISO789",
  "subMerchants": [
    {
      "subMerchantId": "SM001",
      "name": "Sub Merchant 1",
      "address": {
        "city": "City 1",
        "postalCode": "101000",
        "country": "US",
        "street": "Street 1"
      }
    },
    {
      "subMerchantId": "SM002",
      "name": "Sub Merchant 2",
      "address": {
        "city": "City 2",
        "postalCode": "190000",
        "country": "US",
        "street": "Street 2"
      }
    }
  ]
}

Описание на параметрите на обекта marketplace:

ЗадължителностИмеТипОписание
ЗадължителноmarketplaceIdString [1..11]Идентификатор на маркетплейса в банката-акуайър.
УсловноforeignRetailerIndicatorBooleanУказва дали маркетплейсът има чуждестранни ритейлъри (дъщерни търговци). Ако в обекта marketplace се предава блок retailers, този параметър не е задължително да се предава, в противен случай – задължително.
НезадължителноretailersArray of objectsМасив от ритейлъри (дъщерни продавачи на маркетплейса). Съдържа само 1 елемент. Вложените елементи са описани по-долу.

Описание на параметрите на обекта, който е елемент от масива retailers.

ЗадължителностИмеТипОписание
ЗадължителноforeignRetailerIndicatorBooleanОпределя дали търговецът е чуждестранен.

Пример на обекта marketplace:

"marketplace": {
    "marketplaceId": "MKT12345678",
    "foreignRetailerIndicator": true,
    "retailers": [
        {
            "foreignRetailerIndicator": false
        }
    ]
}

Параметри на отговора

ЗадължителностИмеТипОписание
ЗадължителноerrorCodeString [1..2]Информационен параметър в случай на грешка, който може да има различни кодови стойности:
  • стойност 0 - указва успех на обработката;
  • друга положителна числова стойност - указва грешка, за получаване на по-подробна информация за която е необходимо да се провери параметърът error.
Може да отсъства, ако резултатът не е предизвикал грешки.
НезадължителноerrorString [1..512]Съобщение за грешка (ако в отговора се върна грешка) на езика, предаден в заявката.
НезадължителноorderIdString [1..36]Номер на поръчката в платежния шлюз. Уникален в рамките на платежния шлюз.
НезадължителноinfoStringВ случай на успешен отговор. Резултат от опита за плащане. По-долу са приведени възможните стойности.
  • Вашето плащане е обработено, извършва се пренасочване...
  • Операцията е отхвърлена. Проверете въведените данни, достатъчността на средствата на картата и повторете операцията. Извършва се пренасочване...
  • Извинете, плащането не може да бъде извършено. Извършва се пренасочване...
  • Операцията е отхвърлена. Обърнете се към магазина. Извършва се пренасочване...
  • Операцията е отхвърлена. Обърнете се към банката, издала картата. Извършва се пренасочване...
  • Операцията е невъзможна. Удостоверяването на притежателя на картата завърши неуспешно. Извършва се пренасочване...
  • Няма връзка с банката. Повторете по-късно. Извършва се пренасочване...
  • Изтече срокът за изчакване на въвеждане на данни. Извършва се пренасочване...
  • Не е получен отговор от банката. Повторете по-късно. Извършва се пренасочване...
НезадължителноredirectString [1..512]Този параметър се връща, ако плащането е преминало успешно и за плащането не е извършвана проверка на картата за участие в 3-D Secure. Продавачите могат да го използват, ако искат да пренасочат потребителя към страницата на платежния шлюз. Ако продавачът използва собствена страница, тази стойност може да бъде игнорирана.
НезадължителноtermUrlString [1..512]При успешен отговор в случай на плащане 3D-Secure. Това е URL-адрес, към който ACS пренасочва притежателя на картата след удостоверяване. Подробно вж. Пренасочване към ACS.
НезадължителноacsUrlString [1..512]При успешен отговор в случай на плащане 3D-Secure. URL-адрес за пренасочване към ACS. Задължителен, ако е необходимо пренасочване към ACS. За повече информация вижте Пренасочване към ACS.
НезадължителноpaReqString [1..255]PAReq (Payment Authentication Request) — съобщение, което трябва да бъде изпратено в ACS заедно с пренасочването. Връща се при успешен отговор в случай на плащане 3D-Secure, ако е необходимо пренасочване към ACS. Това съобщение съдържа данни в кодировка Base64, необходими за автентификация на притежателя на картата. За повече подробности вижте Пренасочване към ACS.
УсловноorderStatusObjectСъдържа параметрите на статуса на поръчката и се връща само в случай, че платежният шлюз разпознае всички параметри на заявката като правилни. Вж. описанието по-долу.

Когато е необходима автентикация с използване на протокола 3DS v2.0, следните параметри ще бъдат получени в отговор на заявката:

ЗадължителностИмеТипОписание
Задължителноis3DSVer2BooleanВъзможни стойности: true или false Флаг, показващ, че плащането постъпва от 3DS2.
ЗадължителноthreeDSServerTransIdString [1..36]Идентификатор на транзакцията, създаден на 3DS сървъра. Задължителен за 3DS автентикация.
НезадължителноthreeDSMethodUrlString [1..512]URL-адрес на ACS сървъра за събиране на данни от браузъра.
ЗадължителноthreeDSMethodUrlServerString [1..512]URL-адрес на 3DS сървъра за събиране на данни от браузъра, които ще бъдат включени в AReq (Authentication Request) от 3DS сървъра към ACS сървъра.
НезадължителноthreeDSMethodDataPackedString [1..1024]Данни CReq (Challenge Response) в кодировка Base-64 за изпращане на сървър ACS.
НезадължителноthreeDSMethodURLServerDirectString [1..512]URL адрес 3dsmethod.do за изпълнение на 3DS метода на 3DS сървъра чрез платежния шлюз (при наличие на съответното разрешение на ниво продавач).

Елементът payerData съдържа следните параметри.

ЗадължителностИмеТипОписание
НезадължителноpaymentAccountReferenceString [1..29]Уникален номер на сметката на клиента, свързващ всичките му платежни средства в рамките на МПС (карти и токени).

Блокът orderStatus съдържа следните елементи.

ЗадължителностИмеТипОписание
НезадължителноErrorCodeString [1..2]Информационен параметър в случай на грешка, който може да има различни кодови стойности:
  • стойност 0 - указва успешна обработка;
  • друга числова стойност (1-99) - указва грешка, за получаване на по-подробна информация за която е необходимо да се провери параметърът ErrorMessage.
Може да отсъства, ако резултатът не е предизвикал грешки.
НезадължителноErrorMessageString [1..512]Информационен параметър, представляващ описание на грешката в случай на възникване на грешка. Стойността на ErrorMessage може да варира, затова не трябва да се препраща изрично към неговите стойности в кода.
Езикът на описанието се задава в параметъра language на заявката.
НезадължителноOrderNumberString [1..36]Номер на поръчка (ID) в системата на търговеца; трябва да бъде уникален за всяка поръчка.
НезадължителноOrderStatusIntegerСтойността на този параметър указва статуса на поръчката в платежната шлюз. Отсъства, ако поръчката не е била намерена. По-долу е приведен списък на достъпните стойности:
  • 0 - поръчката е регистрирана, но не е платена;
  • 1 - Предавторизираната сума е задържана (за двуетапни плащания);
  • 2 - проведена е пълна авторизация на сумата на поръчката;
  • 3 - авторизацията е отменена;
  • 4 - по транзакцията е била проведена операция връщане;
  • 5 - инициирана е авторизация чрез ACS на банката-емитент;
  • 6 - авторизацията е отхвърлена;
  • 7 - очакване на плащане на поръчката;
  • 8 - междинно завършване за многократно частично завършване.
НезадължителноexpirationInteger [6]Срок на валидност на картата в следния формат: YYYYMM.
НезадължителноcardholderNameString [1..26]Име на притежателя на картата (при наличие).
НезадължителноapprovedAmountInteger [0..12]Сума в минимални единици валута (например, в центове), която е била блокирана на сметката на купувача. Използва се само в двуетапни плащания.
НезадължителноdepositAmountInteger [1..12]Сума на списване в минимални единици валута (например, в стотинки).
НезадължителноcurrencyString [3]Код на валутата на плащането ISO 4217. Ако не е посочен, се използва стойността по подразбиране. Позволени са само цифри.
НезадължителноapprovalCodeString [6]Код за оторизация на МПС. Това поле има фиксирана дължина (шест символа) и може да съдържа цифри и латински букви.
НезадължителноauthCodeInteger [6]Остарял параметър (не се използва). Неговата стойност винаги е 2 независимо от статуса на поръчката и кода за оторизация на процесинговата система.
НезадължителноPanString [1..19]Маскиран номер на картата, която е използвана за плащане. Указва се само след плащането на поръчката. При плащане с Apple Pay се използва DPAN. Това е номер, свързан с мобилното устройство на купувача и изпълняващ функциите на номера на платежната карта в системата Apple Pay.
НезадължителноamountInteger [0..12]Сума на плащането в минимални единици валута (например, в стотинки).
НезадължителноIpString [1..39]IP адрес на платеца. IPv6 се поддържа във всички заявки (до 39 символа).
НезадължителноoriginalActionCodeString [1..15]Код на отговор, получен от процесинга. За да включите получаването на това поле, обърнете се към службата за техническа поддръжка.
НезадължителноrrnInteger [1..12]Reference Retrieval Number - идентификатор на транзакцията, присвоен от банката-акуайър.
НезадължителноpaymentNetRefNumString [1..512]Original Network Reference Number - това е идентификатор, който присвоява платежната мрежа (Mastercard, Visa и т.н.) при провеждане на първата транзакция (например, покупка). При изпълнение на обратна операция (връщане, повторен платеж), този номер:
  • се копира от оригиналната транзакция
  • се предава в полето Original Network Reference Number
  • позволява на платежната система да свърже новата операция с първоначалната

Примери

Пример заявка

curl --request POST \
--url  https://uat.dskbank.bg/payment/rest/instantPayment.do \
--header 'content-type: application/x-www-form-urlencoded' \
--data userName=test_user \
--data password=test_user_password \
--data amount=100 \
--data currency=975 \
--data description=my_first_order \
--data orderNumber=1218637308 \
--data pan=4000001111111118  \
--data cvc=123 \
--data expiry=203012 \
--data cardHolderName="TEST CARDHOLDER" \
--data email="demo@example.com" \
--data phone="+449998887766" \
--data language=en \
--data returnUrl=https://mybestmerchantreturnurl.com \
--data failUrl=https://mybestmerchantreturnurl.com

Пример отговор

{
    "errorCode": "0",
    "orderId": "eee72f6e-b980-79c5-92e8-6f4200b1eae0",
    "info": "Your order is proceeded, redirecting...",
    "redirect": "https://www.test.com/payment/merchants/gateway/finish.html?orderId=eee72f6e-b980-79c5-92e8-6f4200b1eae0&lang=en",
    "orderStatus": {
        "expiration": "202412",
        "cardholderName": "TEST CARDHOLDER",
        "depositAmount": 100,
        "currency": "975",
        "approvalCode": "123456",
        "authCode": 2,
        "originalActionCode": "S1",
        "rrn": "311489272111",
        "ErrorCode": "0",
        "ErrorMessage": "Success",
        "OrderStatus": 2,
        "OrderNumber": "2011",
        "Pan": "500000**1115",
        "Amount": 100,
        "Ip": "x.x.x.x"
    }
}

Пренасочване към ACS (опростено)

Ако се изисква 3-D Secure, то след получаване на отговор на заявка за плащане клиентът трябва да бъде пренасочен към ACS. В този случай отговорът на заявката за плащане съдържа параметър acsUrl, който ще се използва за пренасочване.

Заявката https://uat.dskbank.bg/payment/acsRedirect.do?orderId={orderId} позволява да се пренасочи клиентът към страницата за автентификация на ACS по опростен начин - просто използвайки параметъра orderId, получен след регистрация на поръчката.

Също така е възможно пренасочване на клиента към ACS чрез POST-заявка (обичайно пренасочване). Описанието на този метод е достъпно тук.

Без никакви други действия, изисквани от клиента, платежният шлюз го пренасочва към страницата на ACS, където клиентът се автентифицира.

След това, в зависимост от резултата от автентификацията, клиентът се пренасочва към следния URL-адрес:

За да пренасочите клиента към ACS, използвайте следния URL-адрес:

https://uat.dskbank.bg/payment/acsRedirect.do?orderId={Номер на поръчка в платежния шлюз}

Параметри на заявката

ЗадължителностНаименованиеТипОписание
ЗадължителноorderIdString [1..36]Номер на поръчката в платежния шлюз. Уникален в рамките на платежния шлюз.

Параметри на отговора

Пример

Пример за заявка

curl -X GET https://uat.dskbank.bg/payment/acsRedirect.do?orderId=85eb9a84-2a47-7cca-b0ae-662c000016d1

Пример за URL на пренасочване

https://mybestmerchantreturnurl.com/?orderId=85eb9a84-2a47-7cca-b0ae-662c000016d1

Портфейли

Регистрация на поръчка Apple Pay

За регистрация и плащане на поръчка се използва методът https://uat.dskbank.bg/payment/applepay/payment.do.


При изпълнение на заявката е необходимо да се използва заглавката: Content-Type: application/json

Параметри на заявката

ЗадължителностИмеТипОписание
ЗадължителноmerchantString [1..255]За да регистрирате и платите поръчка от името на друг търговец, посочете неговия логин (за API-акаунт) в този параметър.
Може да се използва само ако имате разрешение за преглед на транзакции на други продавачи или ако посоченият продавач е ваш дъщерен продавач.
ЗадължителноorderNumberString [1..36]Номер на поръчката (ID) в системата на търговеца; трябва да бъде уникален за всяка поръчка.
НезадължителноdescriptionString [1..598]Описание на поръчката в произволен формат.
За да включите изпращането на това поле в процесинговата система, обърнете се към службата за техническа поддръжка.
В това поле е недопустимо да се предават лични данни или платежни данни (номера на карти и т.н.). Това изискване се дължи на факта, че описанието на поръчката никъде не се маскира.
НезадължителноlanguageString [2]Ключ на езика по ISO 639-1. Ако езикът не е указан, се използва езикът по подразбиране, указан в настройките на магазина.
Поддържани езици: en,ru,el,ro,bg,pt,sw,hu,it,pl,de,fr,kh,cn,es,ka,da,et,fi,lt,lv,nl,sv.
НезадължителноadditionalParametersObjectДопълнителни параметри на поръчката, които се съхраняват в личния кабинет на продавача за последващ преглед. Всяка нова двойка име на параметър и неговата стойност трябва да бъде разделена със запетая. По-долу е даден пример за използване.
{ "firstParamName": "firstParamValue", "secondParamName": "secondParamValue"}
При създаване на връзка в този таг могат да бъдат предадени параметри, определящи типа на създаваната връзка. Вж. списък на параметрите.
НезадължителноpreAuthBooleanПараметър, определящ необходимостта от предварителна оторизация (блокиране на средства по сметката на клиента преди тяхното списване). Достъпни са следните стойности:
  • true - включено е двуетапно плащане;
  • false - включено е едноетапно плащане (парите се списват веднага).
Ако параметърът липсва, извършва се едноетапно плащане.
НезадължителноautocompletionDateString [19]Дата и време на автоматичното завършване на двуетапното плащане в следния формат: 2025-12-29T13:02:51. Използван часови пояс: UTC+0. За да включите изпращането на това поле в процесинговата система, обърнете се към службата за техническа поддръжка.
НезадължителноautoReverseDateString [19]Дата и час на автоматично анулиране на двуетапното плащане в следния формат: 2025-06-23T13:02:51. Използван часови пояс: UTC+0. За да включите изпращането на това поле в процесинговата система, обърнете се към службата за техническа поддръжка.
ЗадължителноpaymentTokenString [1..8192]Параметърът paymentToken трябва да съдържа разшифрованата и кодирана в Base64 стойност на свойството paymentData, получено от обекта PKPaymentToken Object от системата Apple Pay (за повече подробности вижте документацията на Apple Pay). По този начин, за да направи заявка за плащане към платежния шлюз, продавачът трябва да:
  1. получи PKPaymentToken Object, съдържащ paymentData от Apple Pay;
  2. извлече стойността на paymentData и я кодира в Base64;
  3. включи кодираната стойност на свойството paymentData като стойност на параметъра paymentToken в заявката за плащане, която продавачът ще изпрати към платежния шлюз.
НезадължителноtiiStringИдентификатор на инициатора на транзакцията. Параметър, указващ какъв тип операция ще изпълнява инициаторът (Клиент или Търговец). Възможни стойности.
УсловноclientIdString [0..255]Номер на клиента (ID) в системата на търговеца — до 255 символа. Използва се за реализиране на функционалността на връзките. Може да се връща в отговора, ако на търговеца е разрешено да създава връзки.
Указването на този параметър при обработка на плащания по връзка е задължително. В противен случай плащането ще бъде невъзможно.
УсловноemailString [1..40]Електронна поща за показване на платежната страница. Ако за продавача са настроени известия на клиента, електронната поща трябва да бъде посочена. Пример: client_mail@email.com.
За плащания по VISA с 3DS авторизация е необходимо да се посочи или електронна поща, или телефонен номер на притежателя на картата.
НезадължителноmccInteger [4]Merchant Category Code (код на категория на търговеца).
За предаване на този параметър е необходимо специално разрешение. Могат да се използват стойности само от разрешения списък MCC. За получаване на по-подробна информация се обърнете към техническата поддръжка.
НезадължителноmvvString [1..10]Потвърждение на търговеца от Mastercard за токенизирани транзакции.
За предаване на този параметър трябва да бъде включена специална настройка (обърнете се към техническата поддръжка).
НезадължителноpaymentFacilitatorObjectБлок с информация за платежния фасилитатор, т.е. за търговеца, който позволява на няколко субтърговци да приемат плащания под неговия акаунт.
За предаване на този параметър трябва да бъде включена специална настройка (обърнете се към техническата поддръжка). Вж. вложени параметри.
УсловноphoneString [7..15]Телефонен номер на притежателя на картата. Необходимо е винаги да се посочва кода на страната, но знакът + или 00 в началото може да се посочи или да се пропусне. Номерът трябва да има дължина от 7 до 15 цифри. По този начин са възможни следните стойности:
  • +35799988877;
  • 0035799988877;
  • 35799988877.

За плащания по VISA с 3DS авторизация е необходимо да се посочи или електронната поща, или телефонният номер на притежателя на картата.
НезадължителноthreeDSProtocolVersionStringВерсия на протокола 3DS. Възможни стойности: "2.1.0", "2.2.0" за 3DS2.
Ако в заявката не се предава threeDSProtocolVersion, то за оторизация 3D Secure ще се използва стойността по подразбиране (2.1.0 - за 3DS 2).
НезадължителноmarketplaceObjectБлок с параметри на маркетплейса, т.е. продавача, който предлага стоки или услуги от различни търговци на дребно (ритейлъри).
Този параметър се използва, ако е включена специална настройка (обърнете се към службата за поддръжка). Вж. вложени параметри.
НезадължителноexternalScaExemptionIndicatorStringТип на изключение SCA (Strong Customer Authentication). Ако е посочен този параметър, транзакцията ще бъде обработена в зависимост от вашите настройки в платежния шлюз: или ще бъде изпълнена принудителна операция SSL, или банката-издател ще получи информация за изключението SCA и ще вземе решение за провеждане на операцията с 3DS-автентификация или без нея (за получаване на подробна информация се свържете с нашата служба за поддръжка). Допустими стойности:
  • LVP – транзакция от тип Low Value Payments. Транзакцията може да бъде отнесена към транзакции с ниско ниво на риск въз основа на сумата на транзакцията, броя на транзакциите на клиента в деня или общата дневна сума на плащанията на клиента.
  • TRA – транзакция от тип Transaction Risk Analysis, т.е. транзакция, преминала успешна антифрод-проверка.

За предаване на този параметър трябва да имате достатъчни права в платежния шлюз.

Допълнителни параметри, определящи типа на създаваната връзка и предавани в additionalParameters:

ЗадължителностНаименованиеТипОписание
УсловиеinstallmentsInteger [3]Максимален брой разрешени упълномощавания за плащания на вноски.
Посочва се в случай на създаване на връзка за извършване на плащания на вноски.
УсловиеrecurringFrequencyInteger [2]Минимален брой дни между авторизациите. Цяло положително число от 1 до 28 включително.
Указва се в случай на създаване на връзка за изпълнение на рекурентни плащания.
Задължително за предаване в случай на създаване на връзка за изпълнение на плащания на вноски при включен 3DS2.
УсловиеrecurringExpiryString [8]Дата, след която по-нататъшни оторизации не трябва да се изпълняват. Формат: YYYYMMDD.
Указва се в случай на създаване на връзка за изпълнение на рекурентни плащания.
Задължително за предаване в случай на създаване на връзка за изпълнение на плащания на вноски при включен 3DS2.

Възможни стойности tii (Повече за типовете връзки, поддържани от платежната шлюз, четете тук).

Стойност tiiОписаниеТип транзакцияИнициатор на транзакциятаДанни на картата за транзакциятаЗапазване на данните на картата след транзакциятаЗабележка
ПразноОбичайнаКупувачВъвежда се от купувачаНеТранзакция на електронна търговия без запазване на връзка.
CIИнициираща - Обичайна (CIT)ИницииращаКупувачВъвежда се от купувачаДаТранзакция на електронна търговия със запазване на връзка. Тази стойност е възможно да се предаде само при наличие на разрешение "Разрешено създаване на vendor pays common връзки".
RIИнициираща - Рекурентни (CIT)ИницииращаКупувачВъвежда се от купувачаДаТранзакция на електронна търговия със запазване на връзка.

Описание на параметрите на обекта paymentFacilitator:

ЗадължителностНаименованиеТипОписание
ЗадължителноpfIdString [1..11]Идентификатор на платежния фасилитатор.
ЗадължителноnameString [1..40]Наименование на платежния фасилитатор.
НезадължителноisoIdString [1..11]Идентификатор ISO.
ЗадължителноsubMerchantsArray of objectsМасив от обекти с допълнителна информация за субмерчантите. Вж. вложените параметри по-долу.

Параметри на елемента от масива subMerchants:

ЗадължителностНаименованиеТипОписание
ЗадължителноsubMerchantIdString [1..20]Идентификатор на субмерчанта.
ЗадължителноnameString [1..40]Наименование на субмерчанта.
ЗадължителноaddressObjectБлок с информация за адреса на субмерчанта. Вж. вложените параметри по-долу.

Параметри на обекта address:

ЗадължителностНаименованиеТипОписание
ЗадължителноcityString [1..50]Град на субмерчанта.
ЗадължителноpostalCodeString [1..16]Пощенски код на субмерчанта.
ЗадължителноcountryInteger [2]Код на страната на субмерчанта във формат ISO 3166-1.
НезадължителноstreetString [1..40]Улица на субмерчанта.

Пример за обекта paymentFacilitator:

"paymentFacilitator" :{
  "pfId": "PF123456",
  "name": "Payment Facilitator Name",
  "isoId": "ISO789",
  "subMerchants": [
    {
      "subMerchantId": "SM001",
      "name": "Sub Merchant 1",
      "address": {
        "city": "City 1",
        "postalCode": "101000",
        "country": "US",
        "street": "Street 1"
      }
    },
    {
      "subMerchantId": "SM002",
      "name": "Sub Merchant 2",
      "address": {
        "city": "City 2",
        "postalCode": "190000",
        "country": "US",
        "street": "Street 2"
      }
    }
  ]
}

Описание на параметрите на обекта marketplace:

ЗадължителностИмеТипОписание
ЗадължителноmarketplaceIdString [1..11]Идентификатор на маркетплейса в банката-акуайър.
УсловноforeignRetailerIndicatorBooleanУказва дали маркетплейсът има чуждестранни ритейлъри (дъщерни търговци). Ако в обекта marketplace се предава блок retailers, този параметър не е задължително да се предава, в противен случай – задължително.
НезадължителноretailersArray of objectsМасив от ритейлъри (дъщерни продавачи на маркетплейса). Съдържа само 1 елемент. Вложените елементи са описани по-долу.

Описание на параметрите на обекта, който е елемент от масива retailers.

ЗадължителностИмеТипОписание
ЗадължителноforeignRetailerIndicatorBooleanОпределя дали търговецът е чуждестранен.

Пример на обекта marketplace:

"marketplace": {
    "marketplaceId": "MKT12345678",
    "foreignRetailerIndicator": true,
    "retailers": [
        {
            "foreignRetailerIndicator": false
        }
    ]
}

Параметри на отговора

ЗадължителностИмеТипОписание
ЗадължителноsuccessBooleanОсновен параметър, който указва, че заявката е преминала успешно. Достъпни са следните стойности:
  • true - заявката е успешно обработена;
  • false - заявката не е преминала.

Обърнете внимание, че стойността true означава, че заявката е била обработена, а не че поръчката е била платена.
По-подробна информация за това как да разберете дали плащането е било успешно или не, е достъпна тук.
УсловноdataObjectТози параметър се връща само в случай на успешно обработване на плащането. Вж. описанието по-долу.
УсловноerrorObjectТози параметър се връща само в случай на грешка при плащането. Вж. описанието по-долу.
УсловноorderStatusObjectСъдържа параметри на статуса на поръчката и се връща само в случай, че платежният шлюз разпознае всички параметри на заявката като правилни. Вж. описанието по-долу.

Блокът data съдържа следните елементи.

ЗадължителностИмеТипОписание
ЗадължителноorderIdString [1..36]Номер на поръчката в платежния шлюз. Уникален в рамките на платежния шлюз.

Блокът error съдържа следните елементи.

ЗадължителностИмеТипОписание
codeString [1..3]Код като информационен параметър, съобщаващ за грешка.
descriptionString [1..598]Подробно техническо обяснение на грешката - съдържанието на този параметър не е предназначено за показване на потребителя.
messageString [1..512]Информационен параметър, който представлява описание на грешката за показване на потребителя. Параметърът може да варира, затова не трябва да се прави експлицитна препратка към неговите стойности в кода.

Блокът orderStatus съдържа следните елементи.

ЗадължителностИмеТипОписание
НезадължителноerrorCodeString [1..2]Информационен параметър в случай на грешка, който може да има различни кодови стойности:
  • стойност 0 - указва успех на обработката на заявката;
  • друга числова стойност (1-99) - указва грешка, за получаване на по-подробна информация за която е необходимо да се провери параметър errorMessage.
Може да отсъства, ако резултатът не е предизвикал грешки.
НезадължителноerrorMessageString [1..512]Информационен параметър, който представлява описание на грешката в случай на възникване на грешка. Стойността на errorMessage може да варира, затова не трябва да се препраща изрично към неговите стойности в кода.
Езикът на описанието се задава в параметъра language на заявката.
НезадължителноorderNumberString [1..36]Номер на поръчката (ID) в системата на търговеца; трябва да бъде уникален за всяка поръчка.
НезадължителноorderStatusIntegerСтойността на този параметър указва статуса на поръчката в платежния шлюз. Отсъства, ако поръчката не е била намерена. По-долу е приведен списък на наличните стойности:
  • 0 - поръчката е регистрирана, но не е платена;
  • 1 - поръчката е само авторизирана и още не е завършена (за двуетапните плащания);
  • 2 - поръчката е авторизирана и завършена;
  • 3 - авторизацията е отменена;
  • 4 - по транзакцията е била проведена операция възстановяване;
  • 5 - инициирана е авторизация чрез ACS на банката-емитент;
  • 6 - авторизацията е отхвърлена;
  • 7 - очакване на плащане на поръчки;
  • 8 - междинно завършване за многократно частично завършване.
НезадължителноactionCodeStringКод за отговор от банковата обработка. Съдържа числова стойност. Вижте списъка с кодове за отговор тук.
НезадължителноactionCodeDescriptionString [1..512]Описание на actionCode, връщано от процесинга на банката.
НезадължителноamountInteger [0..12]Сума на плащането в минимални единици валута (например, в стотинки).
НезадължителноcurrencyString [3]Код на валутата на плащането ISO 4217. Ако не е посочен, се използва стойността по подразбиране. Позволени са само цифри.
НезадължителноdateIntegerДата на регистрация на поръчката като брой милисекунди, изминали от 00:00 GMT 1 януари 1970 година (Unix време). Пример: 1740392720718 (съответства на времето 24 февруари 2025 година, 10:25:20 (UTC)).
НезадължителноipString [1..39]IP адрес на платеца. IPv6 се поддържа във всички заявки (до 39 символа).
УсловноmerchantOrderParamsObjectОбект с атрибути, в които се предават допълнителни параметри на търговеца. Вж. описанието по-долу.
УсловноattributesObjectАтрибути на поръчката в платежната система (номер на поръчката). Вж. описанието по-долу.
УсловноcardAuthInfoObjectИнформация за платежната карта на купувача. Вж. описанието по-долу.
НезадължителноauthDateTimeIntegerДата и час на оторизация, показани като брой милисекунди, изминали от 00:00 GMT 1 януари 1970 година (Unix време). Пример: 1740392720718 (съответства на време 24 февруари 2025 година, 10:25:20 (UTC)).
НезадължителноterminalIdString [1..10]Идентификатор на терминала в системата, обработваща плащането.
НезадължителноauthRefNumString [1..24]Номер на авторизация на плащането, присвоен му при регистрация на плащането.
УсловноpaymentAmountInfoObjectПараметър, съдържащ вложени параметри с информация за сумите за потвърждение, списване и възстановяване. Вж. описанието по-долу.
УсловноbankInfoObjectСъдържа вложения параметър bankCountryName. Вж. описанието по-долу.

Елементът payerData съдържа следните параметри.

ЗадължителностИмеТипОписание
НезадължителноpaymentAccountReferenceString [1..29]Уникален номер на сметката на клиента, свързващ всичките му платежни средства в рамките на МПС (карти и токени).

Блокът merchantOrderParams съдържа следните елементи.

ЗадължителностИмеТипОписание
ЗадължителноnameString [1..255]Наименование на допълнителен параметър на търговеца.
ЗадължителноvalueString [1..1024]Стойност на допълнителния параметър на продавача - до 1024 символа.

Блокът attributes съдържа следните елементи.

ЗадължителностИмеТипОписание
ЗадължителноnameString [1..255]Име на допълнителния параметър.
ЗадължителноvalueString [1..1024]Стойност на допълнителния параметър - до 1024 символа.

Блокът cardAuthInfo съдържа следните елементи.

ЗадължителностИмеТипОписание
ЗадължителноexpirationInteger [6]Срок на валидност на картата в следния формат: YYYYMM.
ЗадължителноcardholderNameString [1..26]Име на притежателя на картата с латински букви. Допустими символи: латински букви, точка, интервал.
ЗадължителноapprovalCodeString [6]Код за оторизация на МПС. Това поле има фиксирана дължина (шест символа) и може да съдържа цифри и латински букви.
ЗадължителноpanString [1..19]Маскиран DPAN: номер, свързан с мобилното устройство на купувача и изпълняващ функциите на номер на платежна карта в системата Apple Pay.
НезадължителноdetokenizedPanRepresentationString [1..19]Детокенизиран номер на карта (последните 4 цифри или в маскиран вид).
НезадължителноdetokenizedPanExpiryDateStringДетокенизиран срок на валидност на картата в следния формат: YYYYMM.

Блокът paymentAmountInfo съдържа следните елементи.

ЗадължителностИмеТипОписание
ЗадължителноpaymentStateStringСъстояние на поръчката, параметърът може да приема следните стойности:
  • CREATED - поръчката е създадена (но не е платена);
  • APPROVED - поръчката е одобрена (средствата по сметката на купувача са блокирани);
  • DEPOSITED - поръчката е завършена (парите са отписани от сметката на купувача);
  • DECLINED - поръчката е отхвърлена;
  • REVERSED - поръчката е отхвърлена;
  • REFUNDED - възстановяване на средства.
ЗадължителноapprovedAmountInteger [0..12]Сума в минимални единици валута (например, в центове), която е била блокирана на сметката на купувача. Използва се само в двуетапни плащания.
ЗадължителноdepositedAmountInteger [1..12]Сума на списване в минимални единици валута (например, в стотинки).
ЗадължителноrefundedAmountInteger [1..12]Сума на възстановяване в минимални единици валута.

Блокът bankInfo съдържа следните елементи.

ЗадължителностИмеТипОписание
ЗадължителноbankCountryNameString [1..160]Държава на банката-издател.

Примери

Пример за заявка

curl --request POST \
--url https://uat.dskbank.bg/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" : "eyJtZXJjaGFudCI6ICJ...FnXCJ9In0=",
  "preAuth" : false
}'

Отговор в случай на успешно плащане

{
    "success": true,
    "data": {
        "orderId": "b926351f-a634-49cf-9484-ccb0a3b8cfad"
    },
    "orderStatus": {
        "errorCode": "0",
        "orderNumber": "229",
        "orderStatus": 1,
        "actionCode": 0,
        "actionCodeDescription": "",
        "amount": 960000,
        "currency": "975",
        "date": 1478682458102,
        "ip": "x.x.x.x",
        "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
}

Регистрация на поръчка Google Pay

За регистрация и плащане на поръчка се използва заявка https://uat.dskbank.bg/payment/google/payment.do.


При изпълнение на заявката е необходимо да се използва заглавие: Content-Type: application/json

Параметри на заявката

ЗадължителностИмеТипОписание
ЗадължителноmerchantString [1..255]За да регистрирате и платите поръчка от името на друг търговец, посочете неговия логин (за API-акаунт) в този параметър.
Може да се използва само ако имате разрешение за преглед на транзакции на други продавачи или ако посоченият продавач е ваш дъщерен продавач.
ЗадължителноorderNumberString [1..36]Номер на поръчката (ID) в системата на търговеца; трябва да бъде уникален за всяка поръчка.
НезадължителноdescriptionString [1..598]Описание на поръчката в произволен формат.
За да включите изпращането на това поле в процесинговата система, обърнете се към службата за техническа поддръжка.
В това поле е недопустимо да се предават лични данни или платежни данни (номера на карти и т.н.). Това изискване се дължи на факта, че описанието на поръчката никъде не се маскира.
НезадължителноlanguageString [2]Ключ на език по ISO 639-1. Ако езикът не е указан, се използва език по подразбиране, указан в настройките на магазина.
Поддържани езици: en,ru,el,ro,bg,pt,sw,hu,it,pl,de,fr,kh,cn,es,ka,da,et,fi,lt,lv,nl,sv.
НезадължителноadditionalParametersObjectДопълнителни параметри на поръчката, които се съхраняват в личния кабинет на продавача за последващ преглед. Всяка нова двойка от име на параметър и неговата стойност трябва да бъде разделена със запетая. По-долу е приведен пример за използване.
{ "firstParamName": "firstParamValue", "secondParamName": "secondParamValue"}
При създаване на връзка в този таг могат да бъдат предадени параметри, определящи типа на създаваната връзка. Вж. списък на параметрите.
НезадължителноpreAuthBooleanПараметър, определящ необходимостта от предварителна оторизация (блокиране на средства по сметката на клиента преди тяхното списване). Достъпни са следните стойности:
  • true - включено е двуетапно плащане;
  • false - включено е едноетапно плащане (парите се списват веднага).
Ако параметърът липсва, извършва се едноетапно плащане.
НезадължителноautocompletionDateString [19]Дата и време на автоматичното завършване на двуетапното плащане в следния формат: 2025-12-29T13:02:51. Използван часови пояс: UTC+0. За да включите изпращането на това поле в процесинговата система, обърнете се към службата за техническа поддръжка.
НезадължителноautoReverseDateString [19]Дата и час на автоматично анулиране на двуетапното плащане в следния формат: 2025-06-23T13:02:51. Използван часови пояс: UTC+0. За да включите изпращането на това поле в процесинговата система, обърнете се към службата за техническа поддръжка.
ЗадължителноclientIdString [0..255]Номер на клиента (ID) в системата на търговеца — до 255 символа. Използва се за реализиране на функционалността на връзките. Може да се връща в отговора, ако на търговеца е разрешено да създава връзки.
Указването на този параметър при обработка на плащания по връзка е задължително. В противен случай плащането ще бъде невъзможно.
НезадължителноtiiStringИдентификатор на инициатора на транзакцията. Параметър, указващ какъв тип операция ще изпълнява инициаторът (Клиент или Търговец). Възможни стойности.
ЗадължителноpaymentTokenString [1..8192]Токен, получен от Google Pay и кодиран в Base64.
ЗадължителноipString [1..39]IP адрес на платеца. IPv6 се поддържа във всички заявки (до 39 символа).
ЗадължителноamountInteger [0..12]Сума на плащането в минимални единици валута (например, в стотинки).
НезадължителноcurrencyCodeString [3]Цифров код на валутата на плащането ISO 4217. Ако не е посочен, то се използва стойността по подразбиране. Допускат се само цифри.
ЗадължителноreturnUrlString [1..512]Адрес, към който трябва да бъде пренасочен потребителят в случай на успешно плащане. Адресът трябва да бъде указан изцяло, включително използвания протокол (например, https://mybestmerchantreturnurl.com вместо mybestmerchantreturnurl.com). В противен случай потребителят ще бъде пренасочен на адрес от следния вид: https://uat.dskbank.bg/payment/<merchant_address>.
НезадължителноfailUrlString [1..512]Адрес, на който трябва да се пренасочи потребителят в случай на неуспешно плащане. Адресът трябва да бъде посочен напълно, включително използвания протокол (например, https://mybestmerchantreturnurl.com вместо mybestmerchantreturnurl.com). В противен случай потребителят ще бъде пренасочен по адрес от следния вид: https://uat.dskbank.bg/payment/<merchant_address>.
НезадължителноdynamicCallbackUrlString [1..512]Параметър за предаване на динамичен адрес за получаване на "платежни" callback-уведомления за поръчката, активирани за търговеца (успешна авторизация, успешно списване, връщане, отказ, отхвърляне на плащане по таймаут, отхвърляне на card present плащане).
"Не платежни" callback-уведомления (включване/изключване на връзка, създаване на връзка), ще бъдат изпращани на статичен callback адрес.
УсловноemailString [1..40]Електронна поща за показване на платежната страница. Ако за продавача са настроени известия на клиента, електронната поща трябва да бъде посочена. Пример: client_mail@email.com.
За плащания по VISA с 3DS авторизация е необходимо да се посочи или електронна поща, или телефонен номер на притежателя на картата.
НезадължителноmccInteger [4]Merchant Category Code (код на категория на търговеца).
За предаване на този параметър е необходимо специално разрешение. Могат да се използват стойности само от разрешения списък MCC. За получаване на по-подробна информация се обърнете към техническата поддръжка.
НезадължителноmvvString [1..10]Потвърждение на търговеца от Mastercard за токенизирани транзакции.
За предаване на този параметър трябва да бъде включена специална настройка (обърнете се към техническата поддръжка).
НезадължителноmarketplaceObjectБлок с параметри на маркетплейса, т.е. продавача, който предлага стоки или услуги от различни търговци на дребно (ритейлъри).
Този параметър се използва, ако е включена специална настройка (обърнете се към службата за поддръжка). Вж. вложени параметри.
НезадължителноpaymentFacilitatorObjectБлок с информация за платежния фасилитатор, т.е. за търговеца, който позволява на няколко субтърговци да приемат плащания под своя акаунт.
За предаване на този параметър трябва да е включена специална настройка (обърнете се към техническата поддръжка). Вж. вложени параметри.
НезадължителноbillingAndShippingAddressMatchIndicatorString [1]Индикатор за съответствие на платежния адрес на притежателя на картата и адреса за доставка. Този параметър се използва за по-нататъшна 3DS-автентификация на клиента.
Възможни стойности:
  • Y - съвпадение на платежния адрес на притежателя на картата и адреса за доставка;
  • N - платежният адрес на притежателя на картата и адресът за доставка не съвпадат.
НезадължителноclientBrowserInfoObjectБлок данни за браузъра на клиента, който се изпраща на ACS по време на 3DS удостоверяване. Този блок може да се предава, само ако е включена специална настройка (обърнете се към екипа за поддръжка). Вж. вложени параметри.

При автентификация по протокол 3DS2 се предават и следните параметри:

ЗадължителностИмеТипОписание
УсловноthreeDSServerTransIdString [1..36]Идентификатор на транзакцията, създаден на 3DS сървъра. Задължителен за 3DS автентикация.
НезадължителноthreeDSVer2FinishUrlString [1..512]URL-адрес, с който клиентът трябва да бъде пренасочен след автентификация на сървъра ACS.
НезадължителноthreeDSMethodNotificationUrlString [1..512]URL-адрес за изпращане на уведомление за преминаване на проверката в ACS.

Възможни стойности tii (Повече за типовете връзки, поддържани от платежната шлюз, четете тук).

Стойност tiiОписаниеТип транзакцияИнициатор на транзакциятаДанни на картата за транзакциятаЗапазване на данните на картата след транзакциятаЗабележка
ПразноОбичайнаКупувачВъвежда се от купувачаНеТранзакция на електронна търговия без запазване на връзка.
CIИнициираща - Обичайна (CIT)ИницииращаКупувачВъвежда се от купувачаДаТранзакция на електронна търговия със запазване на връзка. Тази стойност е възможно да се предаде само при наличие на разрешение "Разрешено създаване на vendor pays common връзки".
RIИнициираща - Рекурентни (CIT)ИницииращаКупувачВъвежда се от купувачаДаТранзакция на електронна търговия със запазване на връзка.

Допълнителни параметри, определящи типа на създаваната връзка и предавани в additionalParameters:

ЗадължителностНаименованиеТипОписание
УсловиеinstallmentsInteger [3]Максимален брой разрешени упълномощавания за плащания на вноски.
Посочва се в случай на създаване на връзка за извършване на плащания на вноски.
УсловиеrecurringFrequencyInteger [2]Минимален брой дни между авторизациите. Цяло положително число от 1 до 28 включително.
Указва се в случай на създаване на връзка за изпълнение на рекурентни плащания.
Задължително за предаване в случай на създаване на връзка за изпълнение на плащания на вноски при включен 3DS2.
УсловиеrecurringExpiryString [8]Дата, след която по-нататъшни оторизации не трябва да се изпълняват. Формат: YYYYMMDD.
Указва се в случай на създаване на връзка за изпълнение на рекурентни плащания.
Задължително за предаване в случай на създаване на връзка за изпълнение на плащания на вноски при включен 3DS2.

По-долу са посочени параметрите на блока billingPayerData (данни за адреса за регистрация на клиента).

ЗадължителностИмеТипОписание
НезадължителноbillingCityString [0..50]Град, регистриран за конкретната карта в Банката Емитент.
НезадължителноbillingCountryString [0..50]Страна, регистрирана за конкретната карта на банката-издател. Формат: ISO 3166-1 (Alpha 2 / Alpha 3 / Number-3) или наименование на страната. Препоръчваме предаване на двубуквен/трибуквен ISO код на страната.
НезадължителноbillingAddressLine1String [0..50]Адрес, регистриран по конкретна карта в Банката Емитент (адрес на платеца). Ред 1. Задължително за предаване за AVS-проверка.
НезадължителноbillingAddressLine2String [0..50]Адрес, регистриран за конкретната карта в Банката Емитент. Ред 2.
НезадължителноbillingAddressLine3String [0..50]Адрес, регистриран за конкретната карта в Банката Емитент. Ред 3.
НезадължителноbillingPostalCodeString [0..9]Пощенски код, регистриран за конкретната карта в Банката Издател. Задължително за предаване за AVS-проверка.
НезадължителноbillingStateString [0..50]Щат, регистриран за конкретната карта в Банката Емитент. Формат: пълна стойност на кода ISO 3166-2, негова част или наименование на щата/региона. Може да съдържа букви само от латинската азбука. Препоръчваме да се предава двубуквен ISO код на щата/региона.
ЗадължителноpayerAccountString [1..32]Номер на сметката на изпращача.
НезадължителноpayerLastNameString [1..64]Фамилия на изпращача.
НезадължителноpayerFirstNameString [1..35]Име на изпращача.
НезадължителноpayerMiddleNameString [1..35]Бащино име на изпращача.
НезадължителноpayerCombinedNameString [1..99]Пълно име на подателя.
НезадължителноpayerIdTypeString [1..8]Тип на предоставения идентифициращ документ на подателя.
Възможни стойности:
  • IDTP1 - Паспорт
  • IDTP2 - Шофьорска книжка
  • IDTP3 - Социална карта
  • IDTP4 - ID карта на гражданин
  • IDTP5 - Сертификат за водене на бизнес
  • IDTP6 - Сертификат на бежанец
  • IDTP7 - Разрешително за пребиваване
  • IDTP8 - Чужд паспорт
  • IDTP9 - Служебен паспорт
  • IDTP10 - Временен паспорт
  • IDTP11 - Паспорт на моряк
НезадължителноpayerIdNumberString [1..100]Номер на предоставения идентифициращ документ (например, паспорт) на изпращача.
НезадължителноpayerBirthdayString [1..20]Дата на раждане на изпращача във формат YYYYMMDD.

Описание на параметрите на обект shippingPayerData:

ЗадължителностНаименованиеТипОписание
НезадължителноshippingCityString [1..50]Град на поръчителя (от адреса за доставка)
НезадължителноshippingCountryString [1..50]Страна на поръчителя
НезадължителноshippingAddressLine1String [1..50]Основен адрес на клиента (от адреса за доставка)
НезадължителноshippingAddressLine2String [1..50]Основен адрес на клиента (от адреса за доставка)
НезадължителноshippingAddressLine3String [1..50]Основен адрес на клиента (от адреса за доставка)
НезадължителноshippingPostalCodeString [1..16]Пощенски код на клиента за доставка
НезадължителноshippingStateString [1..50]Щат/регион на купувача (от адреса за доставка)
НезадължителноshippingMethodIndicatorInteger [2]Индикатор за начин на доставка.
Възможни стойности:
  • 01 - доставка на платежния адрес на притежателя на карта.
  • 02 - доставка на друг адрес, проверен от Търговеца.
  • 03 - доставка на адрес, различен от основния адрес на притежателя на карта.
  • 04 - изпращане в магазин/самовземане (адресът на магазина трябва да бъде указан в съответните параметри за доставка)
  • 05 - Цифрово разпространение (включва онлайн услуги и електронни подаръчни карти)
  • 06 - билети за пътувания и събития, които не могат да бъдат доставени.
  • 07 - Други (например игри, цифрови стоки, които не подлежат на доставка, цифрови абонаменти и т.н.)
НезадължителноdeliveryTimeframeInteger [2]Срок за доставка на стоката.
Възможни стойности:
  • 01 - цифрова дистрибуция
  • 02 - доставка в същия ден
  • 03 - доставка на следващия ден
  • 04 - доставка в рамките на 2 дни след плащането и по-късно.
НезадължителноdeliveryEmail String [1..254]Целеви адрес на електронна поща за доставка на цифрово разпространение. Препоръчително е да предавате електронната поща в самостоятелен параметър на заявката email (но ако я предадете в този блок, към нея ще се прилагат същите правила).

Описание на параметрите на обекта preOrderPayerData:

ЗадължителностНаименованиеТипОписание
НезадължителноpreOrderDateString [10]Очаквана дата на доставка (за предварително поръчани покупки) във формат ГГГГММДД.
НезадължителноpreOrderPurchaseIndInteger [2]Индикатор за разполагане от клиента на поръчка за налична или бъдеща доставка.
Възможни стойности:
  • 01 - възможна е доставка;
  • 02 - бъдеща доставка
НезадължителноreorderItemsIndInteger [2]Индикатор, че клиентът преподръчва преди заплатена доставка в състава на нова поръчка.
Възможни стойности:
  • 01 - поръчката се разполага за първи път;
  • 02 - повторна поръчка

Описание на параметрите на обект orderPayerData.

ЗадължителностНаименованиеТипОписание
НезадължителноhomePhoneString [7..15]Домашен телефон на притежателя на картата. Необходимо е винаги да се посочва код на страната, но знакът + или 00 в началото може да се посочи или пропусне. Номерът трябва да има дължина от 7 до 15 цифри. По този начин са възможни следните стойности:
  • +35799988877;
  • 0035799988877;
  • 35799988877.
НезадължителноworkPhoneString [7..15]Служебен телефон на притежателя на картата. Необходимо е винаги да се посочва код на страната, но знакът + или 00 в началото може да се посочи или пропусне. Номерът трябва да има дължина от 7 до 15 цифри. По този начин са възможни следните стойности:
  • +35799988877;
  • 0035799988877;
  • 35799988877.
НезадължителноmobilePhoneString [7..15]Номер на мобилния телефон на притежателя на картата. Необходимо е винаги да се посочва код на страната, но знакът + или 00 в началото може да се посочи или пропусне. Номерът трябва да има дължина от 7 до 15 цифри. По този начин са възможни следните стойности:
  • +35799988877;
  • 0035799988877;
  • 35799988877.

За плащания по VISA с 3DS авторизация е необходимо да се посочи или електронна поща, или номер на телефон на притежателя на картата. Ако имате настроено показване на номера на телефона на платежната страница и сте посочили неверен номер на телефон, клиентът ще може да го поправи на платежната страница.

По-долу са дадени параметрите на блока clientBrowserInfo (данни за браузъра на клиента).

ЗадължителностНазваниеТипОписание
НезадължителноuserAgentString [1..2048]Агент на браузъра.
НезадължителноOSStringОперационна система.
НезадължителноOSVersionStringВерсия на операционната система.
НезадължителноbrowserAcceptHeaderString [1..2048]Заглавка Accept, която съобщава на сървъра какви формати (или MIME-типове) поддържа браузъра.
НезадължителноbrowserIpAddressString [1..45]IP-адрес на браузъра.
НезадължителноbrowserLanguageString [1..8]Език на браузъра.
НезадължителноbrowserTimeZoneStringЧасова зона на браузъра.
НезадължителноbrowserTimeZoneOffsetString [1..5]Отместване на часовата зона в минути между локалното време на потребителя и UTC.
НезадължителноcolorDepthString [1..2]Дълбочина на цвета на екрана, в битове.
НезадължителноfingerprintStringОтпечатък на браузъра - уникален цифров идентификатор на браузъра.
НезадължителноisMobileBooleanВъзможни стойности: true или false. Флаг, указващ че се използва мобилно устройство.
НезадължителноjavaEnabledBooleanВъзможни стойности: true или false. Флаг, указващ че в браузъра е включена поддръжка на java.
НезадължителноjavascriptEnabledBooleanВъзможни стойности: true или false. Флаг, указващ че в браузъра е включена поддръжка на javascript.
НезадължителноpluginsStringСписък на плъгините, използвани в браузъра, разделени със запетая.
НезадължителноscreenHeightInteger [1..6]Височина на екрана в пиксели.
НезадължителноscreenWidthInteger [1..6]Ширина на екрана в пиксели.
НезадължителноscreenPrintStringДанни за параметрите за печат на браузъра, включително резолюция, дълбочина на цвета, плътност на пикселите.

Пример за блок 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":"x.x.x.x"
	}

Описание на параметрите на обекта paymentFacilitator:

ЗадължителностНаименованиеТипОписание
ЗадължителноpfIdString [1..11]Идентификатор на платежния фасилитатор.
ЗадължителноnameString [1..40]Наименование на платежния фасилитатор.
НезадължителноisoIdString [1..11]Идентификатор ISO.
ЗадължителноsubMerchantsArray of objectsМасив от обекти с допълнителна информация за субмерчантите. Вж. вложените параметри по-долу.

Параметри на елемента от масива subMerchants:

ЗадължителностНаименованиеТипОписание
ЗадължителноsubMerchantIdString [1..20]Идентификатор на субмерчанта.
ЗадължителноnameString [1..40]Наименование на субмерчанта.
ЗадължителноaddressObjectБлок с информация за адреса на субмерчанта. Вж. вложените параметри по-долу.

Параметри на обекта address:

ЗадължителностНаименованиеТипОписание
ЗадължителноcityString [1..50]Град на субмерчанта.
ЗадължителноpostalCodeString [1..16]Пощенски код на субмерчанта.
ЗадължителноcountryInteger [2]Код на страната на субмерчанта във формат ISO 3166-1.
НезадължителноstreetString [1..40]Улица на субмерчанта.

Пример за обекта paymentFacilitator:

"paymentFacilitator" :{
  "pfId": "PF123456",
  "name": "Payment Facilitator Name",
  "isoId": "ISO789",
  "subMerchants": [
    {
      "subMerchantId": "SM001",
      "name": "Sub Merchant 1",
      "address": {
        "city": "City 1",
        "postalCode": "101000",
        "country": "US",
        "street": "Street 1"
      }
    },
    {
      "subMerchantId": "SM002",
      "name": "Sub Merchant 2",
      "address": {
        "city": "City 2",
        "postalCode": "190000",
        "country": "US",
        "street": "Street 2"
      }
    }
  ]
}

Описание на параметрите на обекта marketplace:

ЗадължителностИмеТипОписание
ЗадължителноmarketplaceIdString [1..11]Идентификатор на маркетплейса в банката-акуайър.
УсловноforeignRetailerIndicatorBooleanУказва дали маркетплейсът има чуждестранни ритейлъри (дъщерни търговци). Ако в обекта marketplace се предава блок retailers, този параметър не е задължително да се предава, в противен случай – задължително.
НезадължителноretailersArray of objectsМасив от ритейлъри (дъщерни продавачи на маркетплейса). Съдържа само 1 елемент. Вложените елементи са описани по-долу.

Описание на параметрите на обекта, който е елемент от масива retailers.

ЗадължителностИмеТипОписание
ЗадължителноforeignRetailerIndicatorBooleanОпределя дали търговецът е чуждестранен.

Пример на обекта marketplace:

"marketplace": {
    "marketplaceId": "MKT12345678",
    "foreignRetailerIndicator": true,
    "retailers": [
        {
            "foreignRetailerIndicator": false
        }
    ]
}

Параметри на отговора

ЗадължителностИмеТипОписание
ЗадължителноsuccessBooleanОсновен параметър, който указва, че заявката е преминала успешно. Достъпни са следните стойности:
  • true - заявката е успешно обработена;
  • false - заявката не е преминала.

Обърнете внимание, че стойността true означава, че заявката е била обработена, а не че поръчката е била платена.
По-подробна информация за това как да разберете дали плащането е било успешно или не, е достъпна тук.
УсловноdataObjectТози параметър се връща само в случай на успешна обработка на плащането. Вж. описанието по-долу.
УсловноerrorObjectТози параметър се връща само в случай на грешка в плащането. Вж. описанието по-долу.

Блокът data съдържа следните елементи.

ЗадължителностИмеТипОписание
ЗадължителноorderIdString [1..36]Номер на поръчката в платежния шлюз. Уникален в рамките на платежния шлюз.
НезадължителноtermUrlString [1..512]При успешен отговор в случай на плащане 3D-Secure. Това е URL-адрес, към който ACS пренасочва притежателя на картата след удостоверяване. Подробно вж. Пренасочване към ACS.
НезадължителноacsUrlString [1..512]При успешен отговор в случай на плащане 3D-Secure. URL-адрес за пренасочване към ACS. Задължителен, ако е необходимо пренасочване към ACS. За повече информация вижте Пренасочване към ACS.
НезадължителноpaReqString [1..255]PAReq (Payment Authentication Request) — съобщение, което трябва да бъде изпратено в ACS заедно с пренасочването. Връща се при успешен отговор в случай на плащане 3D-Secure, ако е необходимо пренасочване към ACS. Това съобщение съдържа данни в кодировка Base64, необходими за автентификация на притежателя на картата. За повече подробности вижте Пренасочване към ACS.
УсловноbindingIdString [1..255]Идентификатор на вече съществуваща връзка (идентификатор на карта, токенизирана от gateway). Може да се използва само ако търговецът има разрешение за работа с връзки. Ако този параметър се предава в тази заявка, това означава, че:
  • Тази поръчка може да бъде платена само чрез връзка;
  • Платецът ще бъде пренасочен към страница за плащане, където се изисква само въвеждане на CVC.
НезадължителноdetokenizedPanRepresentationString [1..19]Детокенизиран номер на карта (последните 4 цифри или в маскиран вид).
НезадължителноdetokenizedPanExpiryDateStringДетокенизиран срок на валидност на картата в следния формат: YYYYMM.

Блокът data може да включва още елемент payerData, който съдържа следните параметри.

ЗадължителностИмеТипОписание
НезадължителноpaymentAccountReferenceString [1..29]Уникален номер на сметката на клиента, свързващ всичките му платежни средства в рамките на МПС (карти и токени).

Ако се използва протокол 3DS2, отговорът на заявката включва и следните параметри в блока data:

ЗадължителностИмеТипОписание
Задължителноis3DSVer2BooleanВъзможни стойности: true или false Флаг, показващ, че плащането постъпва от 3DS2.
ЗадължителноthreeDSServerTransIdString [1..36]Идентификатор на транзакцията, създаден на 3DS сървъра. Задължителен за 3DS автентикация.
НезадължителноthreeDSMethodUrlString [1..512]URL-адрес на ACS сървъра за събиране на данни от браузъра.
ЗадължителноthreeDSMethodUrlServerString [1..512]URL-адрес на 3DS сървъра за събиране на данни от браузъра, които ще бъдат включени в AReq (Authentication Request) от 3DS сървъра към ACS сървъра.
НезадължителноthreeDSMethodDataPackedString [1..1024]Данни CReq (Challenge Response) в кодировка Base-64 за изпращане на сървър ACS.
НезадължителноthreeDSMethodURLServerDirectString [1..512]URL адрес 3dsmethod.do за изпълнение на 3DS метода на 3DS сървъра чрез платежния шлюз (при наличие на съответното разрешение на ниво продавач).

Блокът error съдържа следните елементи.

ЗадължителностИмеТипОписание
ЗадължителноcodeString [1..3]Код като информационен параметър, съобщаващ за грешка.
ЗадължителноmessageString [1..512]Информационен параметър, който представлява описание на грешката за показване на потребителя. Параметърът може да варира, затова не трябва да се прави експлицитна препратка към неговите стойности в кода.
ЗадължителноdescriptionString [1..598]Подробно техническо обяснение на грешката - съдържанието на този параметър не е предназначено за показване на потребителя.

Използвайте заявка getOrderStatusExtended.do, за да проверите статуса на транзакцията.

Примери

Пример заявка

curl --request POST \
--url https://uat.dskbank.bg/payment/google/payment.do \
--header 'Content-Type: application/json' \
--data-raw '{
  "merchant": "OurBestMerchantLogin",
  "orderNumber": "UAF-203974-DE",
  "language": "EN",
  "preAuth": true,
  "description" : "Test description",
  "additionalParameters":
  {
      "firstParamName": "firstParamValue",
      "secondParamName": "secondParamValue"
  },
  "paymentToken": "eyJtZXJjaGFudCI6ICJ...FnXCJ9In0=",
  "ip" : "127.0.0.1",
  "amount" : "230000",
  "currencyCode" : 978,
  "failUrl" : "https://mybestmerchantfailurl.com"
  "returnUrl" : "https://mybestmerchantreturnurl.com"
}'

Пример отговор

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

Статус на плащането

Най-простият начин да разберете статуса на плащането — да използвате специално извикване на API:

  1. Направете извикване getOrderStatusExtended.do;
  2. Проверете полето orderStatus в отговора: поръчката се счита за платена, само ако стойността orderStatus е равна на 1 или 2.

Още един начин да проверите дали плащането е преминало успешно или не, е да погледнете известието за обратно извикване.

Статус на поръчката (кратък)

За получаване на статуса на поръчката се използва методът https://uat.dskbank.bg/payment/rest/getOrderStatus.do.


При изпълнението на заявката е необходимо да се използва заглавката: Content-Type: application/x-www-form-urlencoded

Параметри на заявката

ЗадължителностНаименованиеТипОписание
ДаuserNameString [1..50]Потребителско име на API акаунта на продавача.
ДаpasswordString [1..30]Парола на API акаунта на продавача.
ДаorderIdString [1..36]Номер на поръчката в платежния шлюз. Уникален в рамките на платежния шлюз.
НеlanguageString [2]Ключ на езика по ISO 639-1. Ако езикът не е указан, се използва езикът по подразбиране, указан в настройките на магазина.
Поддържани езици: en,ru,el,ro,bg,pt,sw,hu,it,pl,de,fr,kh,cn,es,ka,da,et,fi,lt,lv,nl,sv.

Параметри на отговора

ЗадължителностНаименованиеТипОписание
НеErrorCodeString [1..2]Информационен параметър в случай на грешка, който може да има различни кодови стойности:
  • стойност 0 - указва успех на обработката;
  • друга числова стойност (1-99) - указва грешка, за получаване на по-подробна информация за която е необходимо да се провери параметърът errorMessage.
Може да отсъства, ако резултатът не е предизвикал грешки.
НеErrorMessageString [1..512]Информационен параметър, който представлява описание на грешката в случай на възникване на грешка. Стойността на errorMessage може да варира, поради което не следва да се позовавате изрично на нейните стойности в кода.
Езикът на описанието се задава в параметъра language на заявката.
ДаorderNumberString [1..36]Номер на поръчката (ID) в системата на търговеца; трябва да бъде уникален за всеки търговец.
НеorderStatusIntegerСтойността на този параметър указва статуса на поръчката в платежния gateway. Отсъства, ако поръчката не е била намерена. По-долу е приведен списък на наличните стойности:
  • 0 - поръчката е регистрирана, но не е платена;
  • 1 - Предавторизираната сума е задържана (за двуетапни плащания);
  • 2 - проведена е пълна авторизация на сумата на поръчката;
  • 3 - авторизацията е отменена;
  • 4 - по транзакцията е проведена операция възстановяване;
  • 5 - инициирана е авторизация чрез ACS на банката-издател;
  • 6 - авторизацията е отхвърлена.
ДаamountInteger [0..12]Сума на плащането в минимални единици валута (например, в стотинки).
НеcurrencyString [3]Код на валутата на плащането ISO 4217. Ако не е посочен, се използва стойността по подразбиране. Позволени са само цифри.
НеIpString [1..39]IP адрес на платеца. IPv6 се поддържа във всички заявки (до 39 символа).
НеPanString [1..19]Маскиран номер на картата, която е използвана за плащане. Указва се само след плащането на поръчката. При плащане с Apple Pay се използва DPAN. Това е номер, свързан с мобилното устройство на купувача и изпълняващ функциите на номера на платежната карта в системата Apple Pay.
НеexpirationInteger [6]Срок на валидност на картата в следния формат: YYYYMM.
НеcardholderNameString [1..26]Име на притежателя на картата с латински букви. Допустими символи: латински букви, точка, интервал.
НеapprovalCodeString [6]Код за оторизация на МПС. Това поле има фиксирана дължина (шест символа) и може да съдържа цифри и латински букви.
НеdepositedAmountInteger [1..12]Сума на списване в минимални единици валута (например, в стотинки).
НеclientIdString [0..255]Номер на клиента (ID) в системата на търговеца — до 255 символа. Използва се за реализиране на функционалността на връзките. Може да се връща в отговора, ако на търговеца е разрешено да създава връзки.
Указването на този параметър при обработка на плащания по връзка е задължително. В противен случай плащането ще бъде невъзможно.
НеbindingIdString [1..255]Идентификатор на вече съществуваща връзка (идентификатор на карта, токенизирана от gateway). Може да се използва само ако търговецът има разрешение за работа с връзки. Ако този параметър се предава в тази заявка, това означава, че:
  • Тази поръчка може да бъде платена само чрез връзка;
  • Платецът ще бъде пренасочен към страница за плащане, където се изисква само въвеждане на CVC.
НеpaymentNetRefNumString [1..512]Original Network Reference Number - това е идентификатор, който присвоява платежната мрежа (Mastercard, Visa и т.н.) при извършване на първата транзакция (например, покупка). При изпълнение на обратна операция (връщане, повторен платеж), този номер:
  • се копира от оригиналната транзакция
  • се предава в полето Original Network Reference Number
  • позволява на платежната система да свърже новата операция с първоначалната
Този параметър присъства в отговора само ако се използва заявка getP2PStatus version версия 7 или по-висока.

Примери

Ример заявка

curl --request POST \
  --url https://uat.dskbank.bg/payment/rest/getOrderStatus.do \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data userName=test_user \
  --data password=test_user_password \
  --data orderId=092ac72d-a41c-791b-8e05-a35500a8d2e6 \
  --data language=en

Ример отговор

{
  "expiration":"203012",
  "cardholderName":"TEST CARDHOLDER",
  "depositAmount":500000,
  "currency":"975",
  "approvalCode":"123456",
  "authCode":2,
  "clientId":"123",
  "bindingId":"deb8b6a8-0417-79e5-aad4-8d6400a8d2e6",
  "ErrorCode":"0",
  "ErrorMessage":"Success",
  "OrderStatus":2,
  "OrderNumber":"4005",
  "Pan":"400000**1118",
  "Amount":500000,
  "Ip":"x.x.x.x"
}

Статус на поръчката

За получаване на статуса на поръчката се използва методът https://uat.dskbank.bg/payment/rest/getOrderStatusExtended.do.


При изпълнение на заявката е необходимо да се използва заглавката: Content-Type: application/x-www-form-urlencoded

Допълнителна информация за причините за отказ е достъпна тук.

Параметри на заявката

ЗадължителностИмеТипОписание
УсловноuserNameString [1..50]Потребителско име на API акаунта на продавача. Ако за удостоверяване при регистрация вместо потребителско име и парола се използва открит токен (параметър token), паролата не е необходимо да се предава.
УсловноpasswordString [1..30]Парола на API акаунта на продавача. Ако за удостоверяване при регистрация вместо логин и парола се използва открит токен (параметър token), паролата не е необходимо да се предава.
УсловноtokenString [1..256]Стойност, използвана за автентификация на продавача при изпращане на заявки към платежната шлюз. Ако предавате този параметър, то не предавайте userName и password.
УсловноorderIdString [1..36]Номер на поръчка в платежния шлюз. Уникален в рамките на платежния шлюз.

УсловноorderNumberString [1..36]Номер на поръчката (ID) в системата на търговеца; трябва да бъде уникален за всеки търговец.
НезадължителноlanguageString [2]Ключ на езика по ISO 639-1. Ако езикът не е указан, се използва езикът по подразбиране, указан в настройките на магазина.
Поддържани езици: en,ru,el,ro,bg,pt,sw,hu,it,pl,de,fr,kh,cn,es,ka,da,et,fi,lt,lv,nl,sv.
НезадължителноmerchantLoginString [1..255]За да получите статуса на поръчката на определен търговец вместо текущия потребител, посочете логина на търговеца (за API-акаунт).
Може да се използва само ако имате разрешение за преглед на транзакциите на други продавачи или ако посоченият продавач е ваш дъщерен продавач.

Параметри на отговора

Съществуват няколко набора от параметри на отговора. Кой набор от параметри се връща в отговора зависи от версията на getOrderStatusExtended, посочена в настройките на търговеца в платежния шлюз.

Описание на версиите

ВерсияДобавени параметри
1orderBundle
2
  • authDateTime
  • terminalId
  • authRefNum
3
  • paymentAmountInfo->approvedAmount, depositedAmount, paymentState, refundedAmount
  • bankInfo->bankCountryCode, bankCountryName, bankName
4Няма промени
5refunds
6Няма промени
7cardAuthInfo->secureAuthInfo->paResStatus, veResStatus, paResCheckStatus
8cardAuthInfo->paymentSystem, product
9paymentWay
10depositedDate
11Няма промени
12
  • refundedDate
  • reversedDate
13payerData->email,phone,postAddress
14transactionAttributes
15
  • prepaymentMdOrder
  • partpaymentMdOrders
16feUtrnno
17cardAuthInfo->productCategory
18totalAmount
19avsCode
20bindingInfo->externalCreated
21refunds->externalRefundId
22Няма промени
23efectyOrderInfo
24ofdOrderBundle
25Няма промени
26refunds->approvalCode
27authRefNum
28pluginInfo
29Няма промени
30cardAuthInfo->secureAuthInfo->aResTransStatus, rReqTransStatus, threeDsProtocolVersion
31Няма промени
32Няма промени
33displayErrorMessage
34orderBundle->cartItems->items->depostedItemAmount,itemPrice
35cardAuthInfo->corporateCard
36Няма промени
37
  • tii
  • usedPsdIndicatorValue
38payerData ->paymentAccountReference
39cardAuthInfo -> detokenizedPanRepresentation, detokenizedPanExpiryDate
40Няма промени
41Няма промени
42cardAuthInfo->secureAuthInfo->threeDsType
43Нови параметри не са добавени. Премахнато: cardAuthInfo->secureAuthInfo-> authTypeIndicator
44Няма промени
45Няма промени
46mcc, mvv,paymentFacilitator
47cardAuthInfo->secureAuthInfo->aResTransStatusReason, rreqTransStatusReason,rreqChallengeCancel
48payerData ->billingPayerData,shippingPayerData
49schemeTransactionId
ВерсияЗадължителностИмеТипОписание
ВсичкиНезадължителноerrorCodeString [1..2]Информационен параметър в случай на грешка, който може да има различни кодови стойности:
  • стойност 0 - указва успех на обработката;
  • друга числова стойност (1-99) - указва грешка, за получаване на по-подробна информация за която е необходимо да се провери параметърът errorMessage.
Може да отсъства, ако резултатът не е предизвикал грешки.
ВсичкиНезадължителноerrorMessageString [1..512]Информационен параметър, който представлява описание на грешката в случай на възникване на грешка. Стойността на errorMessage може да варира, затова не трябва да се препраща изрично към неговите стойности в кода.
Езикът на описанието се задава в параметъра language на заявката.
ВсичкиУсловноorderNumberString [1..36]Номер на поръчка (ID) в системата на търговеца, трябва да бъде уникален за всеки търговец, регистриран в платежния шлюз. Ако номерът на поръчката се генерира от страната на платежния шлюз, този параметър не е задължително да се предава.
ВсичкиНезадължително orderStatusIntegerСтойността на този параметър указва статуса на поръчката в платежния шлюз. Отсъства, ако поръчката не е била намерена. По-долу е приведен списък на наличните стойности:
  • 0 - поръчката е регистрирана, но не е платена;
  • 1 - поръчката е само авторизирана и още не е завършена (за двуетапните плащания);
  • 2 - поръчката е авторизирана и завършена;
  • 3 - авторизацията е отменена;
  • 4 - по транзакцията е била проведена операция възстановяване;
  • 5 - инициирана е авторизация чрез ACS на банката-емитент;
  • 6 - авторизацията е отхвърлена;
  • 7 - очакване на плащане на поръчки;
  • 8 - междинно завършване за многократно частично завършване.
ВсичкиЗадължителноactionCodeStringКод за отговор от банковата обработка. Съдържа числова стойност. Вижте списъка с кодове за отговор тук.
ВсичкиЗадължителноactionCodeDescriptionString [1..512]Описание на actionCode, връщано от процесинга на банката.
ВсичкиЗадължителноamountInteger [0..12]Сума на плащането в минимални единици валута (например, в стотинки).
ВсичкиНезадължителноcurrencyString [3]Код на валутата на плащането ISO 4217. Ако не е посочено, се използва стойността по подразбиране.
ВсичкиЗадължителноdateIntegerДата на регистрация на поръчката като брой милисекунди, изминали от 00:00 GMT 1 януари 1970 година (Unix време). Пример: 1740392720718 (съответства на времето 24 февруари 2025 година, 10:25:20 (UTC)).
10+НезадължителноdepositedDateIntegerДата на плащане на поръчката като брой милисекунди, изминали от 00:00 GMT 1 януари 1970 година (Unix време). Пример: 1740392720718 (съответства на времето 24 февруари 2025 година, 10:25:20 (UTC)).
ВсичкиНезадължителноorderDescriptionString [1..600]Описание на поръчката, предавано на платежния шлюз при регистрация.
В това поле не е допустимо да се предават персонални данни или платежни данни (номера на карти и т.н.). Това изискване е свързано с факта, че описанието на поръчката никъде не се маскира.
ВсичкиЗадължителноipString [1..39]IP адрес на платеца. IPv6 се поддържа във всички заявки (до 39 символа).
27+НезадължителноauthRefNumString [1..24]Номер на авторизация на плащането, присвоен му при регистрация на плащането.
12+, задължително от 27НезадължителноrefundedDateIntegerДата и час на възстановяването, показани като брой милисекунди, изминали от 00:00 GMT 1 януари 1970 година (Unix време). Пример: 1740392720718 (съответства на времето 24 февруари 2025 година, 10:25:20 (UTC)).
12+НезадължителноreversedDateIntegerДата и час на отмяната на плащането, показани като брой милисекунди, изминали от 00:00 GMT 1 януари 1970 година (Unix време). Пример: 1740392720718 (съответства на време 24 февруари 2025 година, 10:25:20 (UTC)).
09+ЗадължителноpaymentWayStringНачин на извършване на плащане (плащане с въвеждане на данни от карта, плащане чрез връзка и т.н.). Допълнителни възможни стойности на параметъра са посочени по-долу
19+НезадължителноavsCodeStringКод на отговор за верификация AVS (проверка на адрес и пощенски код на притежателя на карта). Възможни стойности:
  • A – пощенският код и адресът съвпадат.
  • B – адресът съвпада, пощенският код не съвпада.
  • C - пощенският код съвпада, адресът не съвпада.
  • D - пощенският код и адресът не съвпадат.
  • E - заявена е проверка на данни, но резултатът е неуспешен.
  • F - некоректен формат на заявка за AVS/AVV проверка.
02+НезадължителноauthDateTimeIntegerДата и час на оторизация, показани като брой милисекунди, изминали от 00:00 GMT 1 януари 1970 година (Unix време). Пример: 1740392720718 (съответства на време 24 февруари 2025 година, 10:25:20 (UTC)).
02+НезадължителноterminalIdString [1..10]Идентификатор на терминала в системата, обработваща плащането.
01+НезадължителноorderBundleObjectОбект, съдържащ кошницата с продукти. Описанието на вложените елементи е дадено по-долу.
03+НезадължителноpaymentAmountInfoObjectОбект с информация за сумите на потвърждение, списване, възстановяване. Списък на вложените параметри вж. по-долу.
05+НезадължителноrefundsObjectОбект, съдържащ информация за възстановяване на средства. Присъства само при наличие на възстановявания в поръчката. Описанието на вложените елементи е дадено по-долу.
ВсичкиНезадължителноcardAuthInfoObjectБлок с данни за картата на платеца. Описанието на вложените елементи е приведено по-долу.
14+НезадължителноtransactionAttributesObjectНабор от допълнителни атрибути на транзакцията. Списък на вложените параметри вж. по-долу.
15+НезадължителноprepaymentMdOrderStringНомер на предхождащата поръчка за предплащане в платежната шлюза.
15+НезадължителноpartpaymentMdOrdersArray of StringМасив от последващи поръчки за частично плащане.
16+НезадължителноfeUtrnnoInteger [1..18]Номер на транзакция FE.
ВсичкиНезадължителноbindingInfoObjectОбект, съдържащ информация за връзката, по която се осъществява плащането. Вж. таблицата с описанието на bindingInfo.
23+НезадължителноefectyOrderInfoObjectБлок параметри, свързани с платежния метод EFECTY. Описанието на вложените елементи е дадено по-долу.
28+НезадължителноpluginInfoObjectПрисъства в отговора, ако плащането е било извършено чрез платежен plugin. Вж. вложените параметри по-долу.
33+НезадължителноdisplayErrorMessageStringПоказвано съобщение за грешка.
37+НезадължителноtiiStringИдентификатор на инициатора на транзакцията. Параметър, указващ какъв тип операция ще изпълнява инициаторът (Клиент или Търговец). Описанието на вложените елементи е дадено по-долу.
37+НезадължителноusedPsdIndicatorValueStringТип изключение SCA (Strong Customer Authentication). Съдържа стойност, предадена при плащане на поръчката в параметъра externalScaExemptionIndicator.
Допустими стойности:
  • LVP – транзакция тип Low Value Payments. Транзакцията може да бъде отнесена към транзакции с ниско ниво на риск въз основа на сумата на транзакцията, броя транзакции на клиента в ден или общата дневна сума на плащанията на клиента.
  • TRA – транзакция тип Transaction Risk Analysis, т.е. транзакция, преминала успешна антифрод-проверка.
46+НезадължителноmccInteger [4]Merchant Category Code (код на категория на търговеца).
За предаване на този параметър е необходимо специално разрешение. Могат да се използват стойности само от разрешения списък MCC. За получаване на по-подробна информация се обърнете към техническата поддръжка.
46+НезадължителноmvvString [1..10]Потвърждение на търговеца от Mastercard за токенизирани транзакции.
За предаване на този параметър трябва да бъде включена специална настройка (обърнете се към техническата поддръжка).
49+НезадължителноschemeTransactionIdString [1..22]Идентификатор на оригиналната успешна транзакция в Mastercard.
46+НезадължителноpaymentFacilitatorObjectБлок с информация за платежния фасилитатор, т.е. за търговеца, който позволява на няколко субтърговци да приемат плащания под неговия акаунт.
За предаване на този параметър трябва да бъде включена специална настройка (обърнете се към техническата поддръжка). Виж вложени параметри.

Описание на параметрите на обекта paymentFacilitator:

ЗадължителностНаименованиеТипОписание
ЗадължителноpfIdString [1..11]Идентификатор на платежния фасилитатор.
ЗадължителноnameString [1..40]Наименование на платежния фасилитатор.
НезадължителноisoIdString [1..11]Идентификатор ISO.
ЗадължителноsubMerchantsArray of objectsМасив от обекти с допълнителна информация за субмерчантите. Вж. вложените параметри по-долу.

Параметри на елемента от масива subMerchants:

ЗадължителностНаименованиеТипОписание
ЗадължителноsubMerchantIdString [1..20]Идентификатор на субмерчанта.
ЗадължителноnameString [1..40]Наименование на субмерчанта.
ЗадължителноaddressObjectБлок с информация за адреса на субмерчанта. Вж. вложените параметри по-долу.

Параметри на обекта address:

ЗадължителностНаименованиеТипОписание
ЗадължителноcityString [1..50]Град на субмерчанта.
ЗадължителноpostalCodeString [1..16]Пощенски код на субмерчанта.
ЗадължителноcountryInteger [2]Код на страната на субмерчанта във формат ISO 3166-1.
НезадължителноstreetString [1..40]Улица на субмерчанта.

Пример за обекта paymentFacilitator:

"paymentFacilitator" :{
  "pfId": "PF123456",
  "name": "Payment Facilitator Name",
  "isoId": "ISO789",
  "subMerchants": [
    {
      "subMerchantId": "SM001",
      "name": "Sub Merchant 1",
      "address": {
        "city": "City 1",
        "postalCode": "101000",
        "country": "US",
        "street": "Street 1"
      }
    },
    {
      "subMerchantId": "SM002",
      "name": "Sub Merchant 2",
      "address": {
        "city": "City 2",
        "postalCode": "190000",
        "country": "US",
        "street": "Street 2"
      }
    }
  ]
}

Стойности на параметъра paymentWay:

Възможни стойности tii (Подробно за типовете съхранени платежни данни, поддържани от платежния шлюз, четете тук).

Стойност tiiОписаниеТип транзакцияИнициатор на транзакциятаДанни на картата за транзакциятаЗапазване на данните на картата след транзакциятаЗабележка
ПразноОбичайнаКупувачВъвежда се от купувачаНеТранзакция на електронна търговия без запазване на съхранени платежни данни.
CIИнициираща - Обичайна (CIT)ИницииращаКупувачВъвежда се от купувачаДаТранзакция на електронна търговия със запазване на съхранени платежни данни.
FИзвънпланов платеж (CIT)ПоследващаКупувачКлиентът избира карта вместо ръчно въвежданеНеТранзакция на електронна търговия, използваща предварително запазени обичайни съхранени платежни данни.
UИзвънпланов платеж (MIT)ПоследващаПродавачНяма ръчно въвеждане, продавачът предава даннитеНеТранзакция на електронна търговия, използваща предварително запазени обичайни съхранени платежни данни. Използва се само за едностадийни плащания.
RIИнициираща - Рекурентни (CIT)ИницииращаКупувачВъвежда се от купувачаДаТранзакция на електронна търговия със запазване на съхранени платежни данни.
RРекурентен платеж (MIT)ПоследващаПродавачНяма ръчно въвеждане, продавачът предава даннитеНеРекурентна операция, използваща запазени съхранени платежни данни. Използва се само за едностадийни плащания.

Блокът refunds съдържа следните параметри.

ВерсияЗадължителностИмеТипОписание
05+НезадължителноdateStringДата за връщане на поръчката
21+НезадължителноexternalRefundIdString [1..32]Идентификатор на възстановяването. При опит за възстановяване се проверява externalRefundId: ако съществува, се връща успешен отговор с данни за възстановяването, ако не — се осъществява възстановяване.
26+ за всички начини на плащанеНезадължителноapprovalCodeString [6]Код за оторизация на МПС. Това поле има фиксирана дължина (шест символа) и може да съдържа цифри и латински букви.
05+НезадължителноactionCodeStringКод за отговор от банковата обработка. Съдържа числова стойност. Вижте списъка с кодове за отговор тук.
05+НезадължителноreferenceNumberString [12]Уникален идентификационен номер, който се присвоява на операцията при нейното завършване.
05+НезадължителноamountInteger [0..12]Сума на плащането в минимални единици валута (например, в стотинки).

Блок attributes съдържа информация за номера на поръчката в платежния шлюз. Параметър name винаги приема стойност mdOrder, а параметър value - номера на поръчката в платежната система.

ВерсияЗадължителностИмеТипОписание
ВсичкиНезадължителноnameString [1..255]Име на допълнителния параметър.
ВсичкиНезадължителноvalueString [1..1024]Стойност на допълнителния параметър - до 1024 символа.

Блок transactionAttributes съдържа набор от допълнителни атрибути на транзакцията. Използва се за версия 14 и по-висока. По-долу е приведен списък на включените параметри.

ВерсияЗадължителностИмеТипОписание
14+НезадължителноnameString [1..255]Име на допълнителен параметър.
14+НезадължителноvalueString [1..1024]Стойност на допълнителния параметър - до 1024 символа.

блок merchantOrderParams се предава в отговора, ако в поръчката има допълнителни параметри на търговеца. Всеки допълнителен параметър се предава в отделен елемент merchantOrderParams.

ВерсияЗадължителностИмеТипОписание
ВсичкиНезадължителноnameString [1..255]Име на допълнителния параметър.
ВсичкиНезадължителноvalueString [1..1024]Стойност на допълнителния параметър - до 1024 символа.

В елемент cardAuthInfo се намира структура, състояща се от списък на елемент secureAuthInfo и следните параметри.

ВерсияЗадължителностИмеТипОписание
01+НезадължителноmaskedPanString [1..19]Маскиран номер на карта, използвана за плащането. Съдържа реалните първи 6 и последни 4 цифри от номера на картата във формат XXXXXX**XXXX.
01+НезадължителноexpirationInteger [6]Срок на валидност на картата в следния формат: YYYYMM.
01+НезадължителноcardholderNameString [1..26]Име на притежателя на картата с латински букви. Допустими символи: латински букви, точка, интервал.
01+НезадължителноapprovalCodeString [6]Код за оторизация на МПС. Това поле има фиксирана дължина (шест символа) и може да съдържа цифри и латински букви.
08+ЗадължителноpaymentSystemStringНаименование на платежната система. Възможни са следните стойности:
  • VISA
  • MASTERCARD
  • AMEX
  • JCB
  • CUP
08+ЗадължителноproductString [1..255]Допълнителна информация за корпоративните карти. Тази информация се попълва от службата за техническа поддръжка. Ако такава информация липсва, се връща празна стойност.
17+ЗадължителноproductCategoryStringДопълнителна информация за категорията на корпоративните карти. Тази информация се попълва от службата за техническа поддръжка. Ако такава информация липсва, се връща празна стойност. Възможни стойности: DEBIT, CREDIT, PREPAID, NON_MASTERCARD, CHARGE, DIFFERED_DEBIT.
35+НезадължителноcorporateCardString [1..5]Указва дали тази карта е корпоративна. Възможни стойности: false - не е корпоративна карта, true - е корпоративна карта. Може да връща празна стойност, което означава, че стойността не е намерена.
39+НезадължителноdetokenizedPanRepresentationString [1..19]Детокенизиран номер на карта (последните 4 цифри или в маскиран вид).
39+НезадължителноdetokenizedPanExpiryDateStringДетокенизиран срок на валидност на картата в следния формат: YYYYMM.

Елемент secureAuthInfo се състои от следните елементи (параметри cavv и xid са включени в елемент threeDSInfo).

ВерсияЗадължителностИмеТипОписание
01+НезадължителноeciInteger [1..4]Електронен търговски индикатор. Посочен само след плащане на поръчката и в случай на наличие на съответното разрешение. По-долу се дава разшифровката на ECI-кодовете.
  • ECI=01 или ECI=06 - търговецът поддържа 3-D Secure, платежната карта не поддържа 3-D Secure, плащането се обработва на базата на код CVV2/CVC.
  • ECI=02 или ECI=05 - и търговецът, и платежната карта поддържат 3-D Secure;
  • ECI=07 - търговецът не поддържа 3-D Secure, плащането се обработва на базата на код CVV2/CVC.
01 - 42НезадължителноauthTypeIndicatorStringТип на удостоверяване 3DS (достъпен до версия 42). Този параметър е задължителен за плащане чрез вашия 3DS сървър с 3DS 2. За SSL плащания този параметър не е задължителен и се определя в зависимост от стойността на ECI. Допустими стойности:
  • 0 - SSL-удостоверяване
  • 1 - Удостоверяване 3DS 1
  • 2 - Опит за удостоверяване 3DS 1
  • 3 - Строго удостоверяване на клиенти (SCA) с 3DS 2
  • 4 - Удостоверяване на базата на риск (RBA) с 3DS 2
  • 5 - Опит за удостоверяване 3DS 2
42+НезадължителноthreeDsTypeStringТип на удостоверяването 3DS. Този параметър е задължителен за плащане чрез вашия 3DS сървър с 3DS 2. За SSL плащания този параметър не е задължителен и се определя в зависимост от стойността на ECI. Допустими стойности:
  • 0 - SSL-удостоверяване
  • 3 - Строго удостоверяване на клиенти (SCA) с 3DS 2
  • 4 - Удостоверяване базирано на риск (RBA) с 3DS 2
  • 5 - Опит за удостоверяване 3DS 2
  • 7 - 3RI удостоверяване с 3DS 2
  • 8 - Опит за 3RI удостоверяване с 3DS 2
01+НезадължителноcavvString [0..200]Стойност за проверка на автентификацията на притежателя на картата. Посочва се само след плащането на поръчката и в случай на наличие на съответното разрешение.
01+НезадължителноxidString [1..80]Електронен търговски идентификатор на транзакцията. Посочен само след плащане на поръчката и при наличие на съответното разрешение.
30+НезадължителноthreeDSProtocolVersionStringВерсия на протокола 3DS. Възможни стойности: "2.1.0", "2.2.0" за 3DS2.
Ако в заявката не се предава threeDSProtocolVersion, то за оторизация 3D Secure ще се използва стойността по подразбиране (2.1.0 - за 3DS 2).
30+НезадължителноrreqTransStatusString [1]Статус на транзакцията от заявката за предаване на резултатите от автентификацията на потребителя от ACS (RReq). Предава се при използване на 3DS2.
30+НезадължителноaresTransStatusStringСъстояние на транзакцията от отговора на ACS към заявката за удостоверяване (ARes). Предава се при използване на 3DS2.
47+НезадължителноaResTransStatusReasonStringПричина на статуса на транзакцията в ARes съобщението. Предава се при използване на 3DS2. Параметърът предоставя допълнителна информация за причината на конкретния статус на автентификация. Приема стойности от 2 цифри, например 01, 02. Вижте пълния списък със стойности по-долу.
47+НезадължителноrreqTransStatusReasonStringПричина за статуса на транзакцията в RReq съобщението. Предава се при използване на 3DS2. Параметърът предоставя допълнителна информация за причината за конкретния резултат от автентификацията на притежателя на картата. Приема стойности от 2 цифри, например 01, 02. Вижте пълния списък на стойностите по-долу.
47+НезадължителноrreqChallengeCancelStringИндикатор за отказ на процеса Challenge в RReq съобщението. Предава се при използване на 3DS2. Параметърът указва кой е инициирал отказа на удостоверяването: притежателят на картата, търговецът или емитентът. Приема стойности от 2 цифри, например, 01, 03. Вж. пълния списък на стойностите по-долу.

Допустими стойности aResTransStatusReason и rreqTransStatusReason:

Допустими стойности rreqChallengeCancel:

Елемент bindingInfo съдържа следните параметри.

ВерсияЗадължителноИмеТипОписание
ВсичкиНезадължителноclientIdString [0..255]Номер на клиента (ID) в системата на търговеца — до 255 символа. Използва се за реализиране на функционалността на връзките. Може да се връща в отговора, ако на търговеца е разрешено да създава връзки.
Указването на този параметър при обработка на плащания по връзка е задължително. В противен случай плащането ще бъде невъзможно.
ВсичкиНезадължителноbindingIdString [1..255]Идентификатор на вече съществуваща връзка (идентификатор на карта, токенизирана от gateway). Може да се използва само ако търговецът има разрешение за работа с връзки. Ако този параметър се предава в тази заявка, това означава, че:
  • Тази поръчка може да бъде платена само чрез връзка;
  • Платецът ще бъде пренасочен към страница за плащане, където се изисква само въвеждане на CVC.
02+НезадължителноauthDateTimeIntegerДата и час на оторизация, показани като брой милисекунди, изминали от 00:00 GMT 1 януари 1970 година (Unix време). Пример: 1740392720718 (съответства на време 24 февруари 2025 година, 10:25:20 (UTC)).
02+НезадължителноauthRefNumString [1..24]Номер на авторизация на плащането, присвоен му при регистрация на плащането.
02+НезадължителноterminalIdString [1..10]Идентификатор на терминала в системата, обработваща плащането.
20+НезадължителноexternalCreatedBooleanПризнак, показващ дали връзката е създадена във външна услуга.

Елемент paymentAmountInfo съдържа следните параметри.

ВерсияЗадължителноИмеТипОписание
03+НезадължителноapprovedAmountInteger [0..12]Сума в минимални единици валута (например, в центове), която е била блокирана на сметката на купувача. Използва се само в двуетапни плащания.
03+НезадължителноdepositedAmountInteger [1..12]Сума на списване в минимални единици валута (например, в стотинки).
03+НезадължителноrefundedAmountInteger [1..12]Сума на възстановяване в минимални единици валута.
03+НезадължителноpaymentStateStringСъстояние на поръчката, параметърът може да приема следните стойности:
  • CREATED - поръчката е създадена (но не е платена);
  • APPROVED - поръчката е одобрена (средствата по сметката на купувача са блокирани);
  • DEPOSITED - поръчката е завършена (парите са отписани от сметката на купувача);
  • DECLINED - поръчката е отхвърлена;
  • REVERSED - поръчката е отхвърлена;
  • REFUNDED - възстановяване на средства.
18+НезадължителноtotalAmountInteger [1..20]Сума на поръчката плюс комисионна, ако такава има.

Елемент bankInfo съдържа следните параметри.

ВерсияЗадължителностИмеТипОписание
03+НезадължителноbankNameString [1..50]Наименование на банката-емитент.
03+НезадължителноbankCountryCodeString [1..4]Код на страната на банката-издател.
03+НезадължителноbankCountryNameString [1..160]Държава на банката-издател.

Елемент payerData съдържа следните параметри.

ВерсияЗадължителностИмеТипОписание
13+НезадължителноemailString [1..40]Електронна поща на платеца.
13+НезадължителноphoneString [7..15]Телефонен номер на притежателя на картата. Необходимо е винаги да се посочва кода на страната, но знакът + или 00 в началото може да се посочи или да се пропусне. Номерът трябва да има дължина от 7 до 15 цифри. По този начин са възможни следните стойности:
  • +35799988877;
  • 0035799988877;
  • 35799988877.

За плащания по VISA с 3DS авторизация е необходимо да се посочи или електронната поща, или телефонният номер на притежателя на картата.
13+НезадължителноpostAddressString [1..255]Адрес за доставка.
38+НезадължителноpaymentAccountReferenceString [1..29]Уникален номер на сметката на клиента, свързващ всичките му платежни средства в рамките на МПС (карти и токени).
48+НезадължителноbillingPayerDataObjectБлок с регистрационни данни на клиента (адрес, пощенски код), необходим за преминаване на проверка на адреса в рамките на услугите AVS/AVV. Задължително, ако функцията е включена за продавача от страна на Платежния шлюз. Вж вложени параметри.
48+НезадължителноshippingPayerDataObjectОбект, съдържащ данни за доставка до клиента. Този параметър се използва за по-нататъшна 3DS-автентикация на клиента. Вж. вложени параметри.

По-долу са посочени параметрите на блока billingPayerData (данни за адреса за регистрация на клиента).

ЗадължителностИмеТипОписание
НезадължителноbillingCityString [0..50]Град, регистриран за конкретната карта в Банката Емитент.
НезадължителноbillingCountryString [0..50]Страна, регистрирана за конкретната карта на банката-издател. Формат: ISO 3166-1 (Alpha 2 / Alpha 3 / Number-3) или наименование на страната. Препоръчваме предаване на двубуквен/трибуквен ISO код на страната.
НезадължителноbillingAddressLine1String [0..50]Адрес, регистриран по конкретна карта в Банката Емитент (адрес на платеца). Ред 1. Задължително за предаване за AVS-проверка.
НезадължителноbillingAddressLine2String [0..50]Адрес, регистриран за конкретната карта в Банката Емитент. Ред 2.
НезадължителноbillingAddressLine3String [0..50]Адрес, регистриран за конкретната карта в Банката Емитент. Ред 3.
НезадължителноbillingPostalCodeString [0..9]Пощенски код, регистриран за конкретната карта в Банката Издател. Задължително за предаване за AVS-проверка.
НезадължителноbillingStateString [0..50]Щат, регистриран за конкретната карта в Банката Емитент. Формат: пълна стойност на кода ISO 3166-2, негова част или наименование на щата/региона. Може да съдържа букви само от латинската азбука. Препоръчваме да се предава двубуквен ISO код на щата/региона.
ЗадължителноpayerAccountString [1..32]Номер на сметката на изпращача.
НезадължителноpayerLastNameString [1..64]Фамилия на изпращача.
НезадължителноpayerFirstNameString [1..35]Име на изпращача.
НезадължителноpayerMiddleNameString [1..35]Бащино име на изпращача.
НезадължителноpayerCombinedNameString [1..99]Пълно име на подателя.
НезадължителноpayerIdTypeString [1..8]Тип на предоставения идентифициращ документ на подателя.
Възможни стойности:
  • IDTP1 - Паспорт
  • IDTP2 - Шофьорска книжка
  • IDTP3 - Социална карта
  • IDTP4 - ID карта на гражданин
  • IDTP5 - Сертификат за водене на бизнес
  • IDTP6 - Сертификат на бежанец
  • IDTP7 - Разрешително за пребиваване
  • IDTP8 - Чужд паспорт
  • IDTP9 - Служебен паспорт
  • IDTP10 - Временен паспорт
  • IDTP11 - Паспорт на моряк
НезадължителноpayerIdNumberString [1..100]Номер на предоставения идентифициращ документ (например, паспорт) на изпращача.
НезадължителноpayerBirthdayString [1..20]Дата на раждане на изпращача във формат YYYYMMDD.

Описание на параметрите на обект shippingPayerData:

ЗадължителностНаименованиеТипОписание
НезадължителноshippingCityString [1..50]Град на поръчителя (от адреса за доставка)
НезадължителноshippingCountryString [1..50]Страна на поръчителя
НезадължителноshippingAddressLine1String [1..50]Основен адрес на клиента (от адреса за доставка)
НезадължителноshippingAddressLine2String [1..50]Основен адрес на клиента (от адреса за доставка)
НезадължителноshippingAddressLine3String [1..50]Основен адрес на клиента (от адреса за доставка)
НезадължителноshippingPostalCodeString [1..16]Пощенски код на клиента за доставка
НезадължителноshippingStateString [1..50]Щат/регион на купувача (от адреса за доставка)
НезадължителноshippingMethodIndicatorInteger [2]Индикатор за начин на доставка.
Възможни стойности:
  • 01 - доставка на платежния адрес на притежателя на карта.
  • 02 - доставка на друг адрес, проверен от Търговеца.
  • 03 - доставка на адрес, различен от основния адрес на притежателя на карта.
  • 04 - изпращане в магазин/самовземане (адресът на магазина трябва да бъде указан в съответните параметри за доставка)
  • 05 - Цифрово разпространение (включва онлайн услуги и електронни подаръчни карти)
  • 06 - билети за пътувания и събития, които не могат да бъдат доставени.
  • 07 - Други (например игри, цифрови стоки, които не подлежат на доставка, цифрови абонаменти и т.н.)
НезадължителноdeliveryTimeframeInteger [2]Срок за доставка на стоката.
Възможни стойности:
  • 01 - цифрова дистрибуция
  • 02 - доставка в същия ден
  • 03 - доставка на следващия ден
  • 04 - доставка в рамките на 2 дни след плащането и по-късно.
НезадължителноdeliveryEmail String [1..254]Целеви адрес на електронна поща за доставка на цифрово разпространение. Препоръчително е да предавате електронната поща в самостоятелен параметър на заявката email (но ако я предадете в този блок, към нея ще се прилагат същите правила).

Блок efectyOrderInfo съдържа следните параметри.

ВерсияЗадължителностИмеТипОписание
23+НезадължителноreferenceNumberIntegerНомер на препратка Efecty на поръчката, генериран от страна на Efecty
23+НезадължителноreferenceDateIntegerДата/време на създаване на препратката
23+НезадължителноreferenceStatusStringСъстояние на Efecty поръчката
23+НезадължителноreferenceTermIntegerВреме на живот на Efecty поръчката (в часове)
23+НезадължителноnetworkIDIntegerИдентификатор на мрежата за приемане на плащане в брой (за Efecty постоянна стойност - 1)
23+НезадължителноnetworkNameStringНаименование на мрежата за приемане на плащане в брой (за Efecty постоянна стойност - efecty)

Елементът pluginInfo (JSON обект) е присъстващ в отговора, ако плащането е било извършено чрез платежен плъгин. Съдържа следните параметри.

ВерсияЗадължителностИмеТипОписание
28+НезадължителноnameString [1..32]Уникално наименование на плащащия плъгин.
28+НезадължителноparamsObjectПараметрите за конкретния начин на плащане трябва да се предават по следния начин {"param":"value","param2":"value2"}.

Описание на параметрите в обекта orderBundle:

ЗадължителностИмеТипОписание
НезадължителноorderCreationDateString [19]Дата на създаване на поръчката във формат YYYY-MM-DDTHH:MM:SS.
НезадължителноcustomerDetailsObjectБлок, съдържащ атрибутите на клиента. Описанието на атрибутите на тага е дадено по-долу.
ЗадължителноcartItemsObjectОбект, съдържащ атрибутите на стоките в кошницата. Описанието на вложените елементи е дадено по-долу.

Описание на параметрите в обекта loyalties:

ЗадължителностНазваниеТипОписание
НезадължителноbonusAmountForCreditString [0..18]Общата сума бонуси за всички стоки от дадения positionId за зачисляване в бонусната сметка на клиента в минимални валутни единици.
НезадължителноbonusAmountForDebitString [0..18]Обща сума от бонуси по всички стоки с дадения positionId за списване от бонусовата сметка на клиента в минимални единици валута.
ЗадължителноbonusAmountRefundedString [0..18]Обща сума на възстановените бонуси за дадения positionId в минимални единици валута.

Описание на параметрите в обект customerDetails:

ЗадължителностНаименованиеТипОписание
НезадължителноcontactString [0..40]Предпочитан от клиента начин за връзка.
НезадължителноfullNameString [1..100]ФИО на платеца.
НезадължителноpassportString [1..100]Серия и номер на паспорта на платеца в следния формат: 2222888888
НезадължителноdeliveryInfoObjectОбект, съдържащ атрибутите на адреса за доставка. Описанието на вложените елементи е приведено по-долу.

Описание на параметрите в обекта deliveryInfo:

ЗадължителностНаименованиеТипОписание
НезадължителноdeliveryTypeString [1..20]Начин на доставка.
ЗадължителноcountryString [2]Двубуквен код на страната за доставка.
ЗадължителноcityString [0..40]Град на назначение.
ЗадължителноpostAddressString [1..255]Адрес за доставка.

Описание на параметрите в обекта cartItems:

ЗадължителностНаименованиеТипОписание
ЗадължителноitemsObjectЕлемент на масив с атрибути на стокова позиция. Описанието на вложените елементи е дадено по-долу.

Описание на параметрите в обект items:

ЗадължителностНаименованиеТипОписание
ЗадължителноpositionIdInteger [1..12]Уникален идентификатор на стоковата позиция в кошницата.
ЗадължителноnameString [1..255]Наименование или описание на стокова позиция в свободна форма.
НезадължителноitemDetailsObjectОбект с параметри за описанието на стоковата позиция. Описанието на вложените елементи е приведено по-долу.
ЗадължителноquantityObjectЕлемент, описващ общото количество стокови позиции на един positionId и неговите мерни единици. Описанието на вложените елементи е приведено по-долу.
НезадължителноitemAmountInteger [1..12]Сума на стойността на всички стокови позиции за един positionId в минимални единици валута. itemAmount е задължителен за предаване, само ако не е предаден параметърът itemPrice. В противен случай предаването на itemAmount не се изисква. Ако в заявката се предават и двата параметъра: itemPrice и itemAmount, то itemAmount трябва да се равнява на itemPrice * quantity, в противен случай заявката ще завърши с грешка.
НезадължителноitemPriceInteger [1..18]Сума на стойността на стоковата позиция на един positionId в пари в минимални единици валута.
НезадължителноdepositedItemAmountString [1..18]Сума на списване за един positionId в минимални валутни единици (например, в стотинки).
НезадължителноitemCurrencyInteger [3]Код на валута ISO 4217. Ако не е посочен, се счита равен на валутата на поръчката.
ЗадължителноitemCodeString [1..100]Номер (идентификатор) на стокова позиция в системата на магазина.

Описание на параметрите в обект quantity:

ЗадължителностИмеТипОписание
ЗадължителноvalueNumber [1..18]Количество на стокови позиции от дадения positionId. За указване на дробни числа използвайте десетична точка. Допуска се максимум 3 знака след точката.
ЗадължителноmeasureString [1..20]Мерна единица за количеството по позицията.

Описание на параметрите в обекта itemDetails:

ЗадължителностНазваниеТипОписание
НезадължителноitemDetailsParamsObjectПараметър, описващ допълнителна информация по стоковата позиция. Описанието на вложените елементи е приведено по-долу.

Примери

Пример заявка

curl --request POST \
  --url https://uat.dskbank.bg/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": "975",
  "date": 1617972915659,
  "orderDescription": "",
  "merchantOrderParams": [],
  "transactionAttributes": [],
  "attributes": [
    {
      "name": "mdOrder",
      "value": "01491d0b-c848-7dd6-a20d-e96900a7d8c0"
    }
  ],
  "cardAuthInfo": {
    "maskedPan": "411111**1111",
    "expiration": "203412",
    "cardholderName": "TEST CARDHOLDER",
    "approvalCode": "12345678",
    "pan": "411111**1111"
  },
  "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://uat.dskbank.bg/payment/rest/deposit.do.


При изпълнение на заявката е необходимо да се използва заглавка: Content-Type: application/x-www-form-urlencoded

Параметри на заявката

ЗадължителностНаименованиеТипОписание
ЗадължителноuserNameString [1..50]Потребителско име на API акаунта на продавача.
ЗадължителноpasswordString [1..30]Парола на API акаунта на продавача.
УсловиеorderIdString [1..36]Номер на поръчката в платежния шлюз. Уникален в рамките на платежния шлюз.
Необходимо е да се предаде orderId или orderNumber+merchantLogin.
УсловиеorderNumberString [1..36]Номер на поръчката (ID) в системата на търговеца; трябва да бъде уникален за всяка поръчка.
Необходимо е да се предаде orderId или orderNumber+merchantLogin.
УсловиеmerchantLoginString [1..255]За да извършвате определени действия с плащането на поръчката от името на друг търговец, посочете неговия логин (за API-акаунта) в този параметър.
Може да се използва само ако имате разрешение за преглед на транзакциите на други продавачи или ако посоченият продавач е ваш дъщерен продавач.
Необходимо е да се предаде orderId или orderNumber+merchantLogin.
ЗадължителноamountString [0..12]Сума на завършване в минимални единици валута (например, в стотинки). Сумата на завършване трябва да съответства на общата сума на всички стоки, за които се извършва завършване. Ако в заявката се посочи amount=0, ще се формира завършване на цялата сума на поръчката.
НезадължителноdepositItemsObjectОбект, съдържащ атрибутите на стоките в кошницата. По-долу е приведено описание на включените атрибути.
НезадължителноlanguageString [2]Ключ на езика по ISO 639-1. Ако езикът не е указан, се използва езикът по подразбиране, указан в настройките на магазина.
Поддържани езици: en,ru,el,ro,bg,pt,sw,hu,it,pl,de,fr,kh,cn,es,ka,da,et,fi,lt,lv,nl,sv.
НезадължителноcurrencyString [3]Код на валутата на плащането ISO 4217. Ако не е посочен, се използва стойността по подразбиране. Позволени са само цифри.
НезадължителноjsonParamsObjectНабор от допълнителни атрибути с произволна форма, структура:
jsonParams={"param_1_name":"param_1_value",...,"param_n_name":"param_n_value"}
Могат да бъдат предадени в Процесинговия Център, за последваща обработка (изисква се допълнителна настройка - обърнете се към поддръжката).
Някои предопределени атрибути jsonParams:
  • backToShopUrl - добавя на страницата за плащане бутон, който ще върне притежателя на картата на URL-адреса предаден в този параметър
  • backToShopName - настройва текстовия етикет на бутона Върни се в магазина по подразбиране, ако се използва заедно с backToShopUrl
  • recurringFrequency - минимален брой дни между оторизациите. Изисква се за създаване на рекурентна връзка, препоръчва се за създаване на връзка за разсрочване (ако се използва 3DS2, параметърът е задължителен).
  • recurringExpiry - дата, след която оторизациите не са разрешени, във формат ГГГГММДД. Изисква се за създаване на рекурентна връзка, препоръчва се за създаване на връзка за разсрочване (ако се използва 3DS2, параметърът е задължителен).

Описание на параметрите в обекта deposititems:

ЗадължителностНаименованиеТипОписание
ЗадължителноitemsObjectЕлемент на масив с атрибути на стокова позиция. Описанието на вложените елементи е дадено по-долу.

Описание на параметрите в обект items:

ЗадължителностНаименованиеТипОписание
ЗадължителноpositionIdInteger [1..12]Уникален идентификатор на стоковата позиция в кошницата.
ЗадължителноnameString [1..255]Наименование или описание на стокова позиция в свободна форма.
НезадължителноitemDetailsObjectОбект с параметри за описанието на стоковата позиция. Описанието на вложените елементи е приведено по-долу.
ЗадължителноquantityObjectЕлемент, описващ общото количество стокови позиции на един positionId и неговите мерни единици. Описанието на вложените елементи е приведено по-долу.
НезадължителноitemAmountInteger [1..12]Сума на стойността на всички стокови позиции за един positionId в минимални единици валута. itemAmount е задължителен за предаване, само ако не е предаден параметърът itemPrice. В противен случай предаването на itemAmount не се изисква. Ако в заявката се предават и двата параметъра: itemPrice и itemAmount, то itemAmount трябва да се равнява на itemPrice * quantity, в противен случай заявката ще завърши с грешка.
НезадължителноitemPriceInteger [1..18]Сума на стойността на стоковата позиция на един positionId в пари в минимални единици валута.
НезадължителноdepositedItemAmountString [1..18]Сума на списване за един positionId в минимални валутни единици (например, в стотинки).
НезадължителноitemCurrencyInteger [3]Код на валута ISO 4217. Ако не е посочен, се счита равен на валутата на поръчката.
ЗадължителноitemCodeString [1..100]Номер (идентификатор) на стокова позиция в системата на магазина.

Описание на параметрите в обекта itemDetails:

ЗадължителностНазваниеТипОписание
НезадължителноitemDetailsParamsObjectПараметър, описващ допълнителна информация по стоковата позиция. Описанието на вложените елементи е приведено по-долу.

Описание на параметрите в обекта itemDetailsParams:

ЗадължителностНаименованиеТипОписание
ЗадължителноvalueString [1..2000]Допълнителна информация за товарната позиция.
ЗадължителноnameString [1..255]Наименование на параметъра за описанието на детайлизацията на стоковата позиция

Описание на параметрите в обект quantity:

ЗадължителностИмеТипОписание
ЗадължителноvalueNumber [1..18]Количество на стокови позиции от дадения positionId. За указване на дробни числа използвайте десетична точка. Допуска се максимум 3 знака след точката.
ЗадължителноmeasureString [1..20]Мерна единица за количеството по позицията.

Параметри на отговора

ЗадължителностНаименованиеТипОписание
НезадължителноerrorCodeString [1..2]Информационен параметър в случай на грешка, който може да има различни кодови стойности:
  • стойност 0 - указва успех на обработката на заявката;
  • друга числова стойност (1-99) - указва грешка, за получаване на по-подробна информация за която е необходимо да се провери параметър errorMessage.
Може да отсъства, ако резултатът не е предизвикал грешки.
НезадължителноerrorMessageString [1..512]Информационен параметър, който представлява описание на грешката в случай на възникване на грешка. Стойността на errorMessage може да варира, затова не трябва да се препраща изрично към неговите стойности в кода.
Езикът на описанието се задава в параметъра language на заявката.

Примери

Пример за заявка

curl --request POST \
  --url https://uat.dskbank.bg/payment/rest/deposit.do \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data userName=test_user \
  --data password=test_user_password \
  --data currency=975 \
  --data amount=2000 \
  --data orderId=01492437-d2fb-77fa-8db7-9e2900a7d8c0 \
  --data language=en

Пример за отговор

{
  "errorCode": 0,
  "errorMessage":"Success"
}

Отмяна на плащане

За отмяна на плащане се използва заявка https://uat.dskbank.bg/payment/rest/reverse.do. Отмяната е възможна само в рамките на определен период от време след плащането. Свържете се с Поддръжката, за да разберете точния период, тъй като той варира.


При изпълнение на заявката е необходимо да се използва заглавката: Content-Type: application/x-www-form-urlencoded

Плащането може да бъде отменено само веднъж. Ако завърши с грешка, последващите операции за отмяна на плащането няма да работят.

Наличието на тази функция е възможно след съгласуване с банката. Отмяната може да се изпълнява само от потребители, на които са предоставени съответните системни разрешения.

Параметри на заявката

ЗадължителностНазваниеТипОписание
ЗадължителноuserNameString [1..50]Потребителско име на API акаунта на продавача. Ако за удостоверяване при регистрация вместо потребителско име и парола се използва открит токен (параметър token), паролата не е необходимо да се предава.
ЗадължителноpasswordString [1..30]Парола на API акаунта на продавача.
УсловиеorderIdString [1..36]Номер на поръчката в платежния шлюз. Уникален в рамките на платежния шлюз.
Необходимо е да се предаде orderId или orderNumber+merchantLogin.
УсловиеorderNumberString [1..36]Номер на поръчката (ID) в системата на търговеца; трябва да бъде уникален за всяка поръчка.
Необходимо е да се предаде orderId или orderNumber+merchantLogin.
УсловиеmerchantLoginString [1..255]За да отмените поръчка от името на друг търговец, посочете неговия login (за API-акаунт) в този параметър.
Може да се използва само ако имате разрешение за преглед на транзакциите на други продавачи или ако посоченият продавач е ваш дъщерен продавач.
Необходимо е да се предаде orderId или orderNumber+merchantLogin.
НезадължителноlanguageString [2]Ключ на езика по ISO 639-1. Ако езикът не е указан, се използва езикът по подразбиране, указан в настройките на магазина.
Поддържани езици: en,ru,el,ro,bg,pt,sw,hu,it,pl,de,fr,kh,cn,es,ka,da,et,fi,lt,lv,nl,sv.
НезадължителноjsonParamsStringПолета за съхранение на допълнителни данни трябва да се предават по следния начин: {"param":"value","param2":"value2"}.
НезадължителноamountString [0..12]Сума на отмяна в минимални единици валута (например, в стотинки). Сумата на отмяна трябва да бъде по-малка или равна на оторизираната сума на поръчката (за двуетапни поръчки - общата предварително оторизирана сума на поръчката).
НезадължителноcurrencyString [3]Код на валутата на плащането ISO 4217. Ако не е посочен, се използва стойността по подразбиране. Позволени са само цифри.

Параметри на отговора

ЗадължителностНазваниеТипОписание
НезадължителноerrorCodeString [1..2]Информационен параметър в случай на грешка, който може да има различни кодови стойности:
  • стойност 0 - указва успех на обработката на заявката;
  • друга числова стойност (1-99) - указва грешка, за получаване на по-подробна информация за която е необходимо да се провери параметър errorMessage.
Може да отсъства, ако резултатът не е предизвикал грешки.
НезадължителноerrorMessageString [1..512]Информационен параметър, който представлява описание на грешката в случай на възникване на грешка. Стойността на errorMessage може да варира, затова не трябва да се препраща изрично към неговите стойности в кода.
Езикът на описанието се задава в параметъра language на заявката.

Примери

Пример за заявка

curl --request POST \
  --url https://uat.dskbank.bg/payment/rest/reverse.do \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data userName=test_user \
  --data password=test_user_password \
  --data currency=975 \
  --data orderId=01491d0b-c848-7dd6-a20d-e96900a7d8c0 \
  --data language=en

Пример за отговор

{
  "errorCode": 0,
  "errorMessage":"Success"
}

Възстановяване на средства

Използвайте https://uat.dskbank.bg/payment/rest/refund.do за изпращане на заявки за възстановяване на средства.


При изпълнение на заявката е необходимо да използвате заглавката: Content-Type: application/x-www-form-urlencoded

Не може да се осъществява възстановяване на средства по поръчки, които инициират редовни плащания, тъй като в този случай не се извършва списване на средства.

По тази заявка средствата по указаната поръчка ще бъдат възстановени на платеца. Заявката ще завърши с грешка, ако средствата по тази поръчка не са били списани. Системата позволява възстановяване на средства повече от един път, но общо не повече от първоначалната сума на списването.

Параметри на заявката

ЗадължителностНаименованиеТипОписание
ЗадължителноuserNameString [1..50]Потребителско име на API акаунта на продавача.
ЗадължителноpasswordString [1..30]Парола на API акаунта на продавача.
УсловиеorderIdString [1..36]Номер на поръчката в платежния шлюз. Уникален в рамките на платежния шлюз.
Необходимо е да се предаде orderId или orderNumber+merchantLogin.
УсловиеorderNumberString [1..36]Номер на поръчката (ID) в системата на търговеца; трябва да бъде уникален за всяка поръчка.
Необходимо е да се предаде orderId или orderNumber+merchantLogin.
УсловиеmerchantLoginString [1..255]За да извършвате определени действия с плащането на поръчката от името на друг търговец, посочете неговия логин (за API-акаунта) в този параметър.
Може да се използва само ако имате разрешение за преглед на транзакциите на други продавачи или ако посоченият продавач е ваш дъщерен продавач.
Необходимо е да се предаде orderId или orderNumber+merchantLogin.
ЗадължителноamountString [0..12]Сума за възстановяване в минимални единици валута (например, в стотинки). Сумата за възстановяване трябва да бъде по-малка или равна на сумата на поръчката (за двуетапни поръчки - общата сума на завършване по поръчката). Ако в заявката се посочи amount=0, то ще бъде възстановена цялата сума на поръчката.
НезадължителноlanguageString [2]Ключ на езика по ISO 639-1. Ако езикът не е указан, се използва езикът по подразбиране, указан в настройките на магазина.
Поддържани езици: en,ru,el,ro,bg,pt,sw,hu,it,pl,de,fr,kh,cn,es,ka,da,et,fi,lt,lv,nl,sv.
НезадължителноjsonParamsStringПолета за съхранение на допълнителни данни трябва да се предават по следния начин: {"param":"value","param2":"value2"}.
НезадължителноexpectedDepositedAmountInteger [1..12]Параметърът служи за определяне, че заявката е повторна. Ако параметърът е предаден, неговата стойност се сравнява с текущата стойност на depositedAmount в поръчката. Операцията ще бъде изпълнена само в случай, че стойностите съвпадат. Ако два връщания пристигат с еднакъв expectedDepositedAmount, ще бъде изпълнено само едно връщане. Това връщане ще промени стойността на depositedAmount, а след това второто връщане ще бъде отхвърлено.
НезадължителноexternalRefundIdString [1..32]Идентификатор на възстановяването. При опит за възстановяване се проверява externalRefundId: ако съществува, се връща успешен отговор с данни за възстановяването, ако не — се осъществява възстановяване.
НезадължителноcurrencyString [3]Код на валутата на плащането ISO 4217. Ако не е посочен, се използва стойността по подразбиране. Позволени са само цифри.
НезадължителноrefundItemsObjectОбект за предаване на информация за възвръщаните стоки - номер на позицията на стоката в заявката, наименование, детайли, мерна единица, количество, валута, код на стоката, печалба на агента.

Параметърът refundItems включва в себе си:

ЗадължителностНаименованиеТипОписание
НезадължителноitemsObjectЕлемент на масив с атрибути на стокова позиция. Описанието на вложените елементи е дадено по-долу.

Описание на параметрите в обект items:

ЗадължителностНаименованиеТипОписание
ЗадължителноpositionIdInteger [1..12]Уникален идентификатор на стоковата позиция в кошницата.
ЗадължителноnameString [1..255]Наименование или описание на стокова позиция в свободна форма.
НезадължителноitemDetailsObjectОбект с параметри за описанието на стоковата позиция. Описанието на вложените елементи е приведено по-долу.
ЗадължителноquantityObjectЕлемент, описващ общото количество стокови позиции на един positionId и неговите мерни единици. Описанието на вложените елементи е приведено по-долу.
НезадължителноitemAmountInteger [1..12]Сума на стойността на всички стокови позиции за един positionId в минимални единици валута. itemAmount е задължителен за предаване, само ако не е предаден параметърът itemPrice. В противен случай предаването на itemAmount не се изисква. Ако в заявката се предават и двата параметъра: itemPrice и itemAmount, то itemAmount трябва да се равнява на itemPrice * quantity, в противен случай заявката ще завърши с грешка.
НезадължителноitemPriceInteger [1..18]Сума на стойността на стоковата позиция на един positionId в пари в минимални единици валута.
НезадължителноdepositedItemAmountString [1..18]Сума на списване за един positionId в минимални валутни единици (например, в стотинки).
НезадължителноitemCurrencyInteger [3]Код на валута ISO 4217. Ако не е посочен, се счита равен на валутата на поръчката.
ЗадължителноitemCodeString [1..100]Номер (идентификатор) на стокова позиция в системата на магазина.

Описание на параметрите в обекта itemAttributes:

Параметърът itemAttributes трябва да съдържа масив attributes, а вече в този масив са разположени атрибутите на стоковата позиция (вж. примера и таблицата по-долу).

"itemAttributes":{"attributes":[{"name":"paymentMethod","value":"1"},{"name":"paymentObject","value":"1"}]}
ЗадължителностНазваниеТипОписание
ЗадължителноpaymentMethodInteger [1..2]Тип плащане, достъпни стойности:
  • 1 - пълна предплата;
  • 2 - частична предплата;
  • 3 - аванс;
  • 4 - пълно плащане;
  • 5 - частично плащане с последващо плащане на кредит;
  • 6 - без плащане с последващо плащане на кредит;
  • 7 - плащане с последващо плащане на кредит.
УсловиеnomenclatureString [1..95]Код на стоковата номенклатура в шестнадесетично представяне с интервали. Максимална дължина – 32 байта. Задължително, ако е предадено markQuantity.
НезадължителноmarkQuantityObjectДробно количество на маркирания стока.
НезадължителноuserDataString [1..64]Стойност на реквизита на потребителя. Може да се предава само след съгласуване с ФНС.
Незадължителноagent_infoObjectОбект с данни за платежния агент за стоковата позиция. Описанието на вложените елементи е дадено по-долу.
Незадължителноsupplier_infoObjectОбект с данни за доставчика за стоковата позиция. Описанието на вложените елементи е дадено по-долу.

Описание на параметрите в обекта agent_info:

ЗадължителностНазваниеТипОписание
ЗадължителноtypeIntegerТип на агента, достъпни стойности:
  • 1 - банков платежен агент;
  • 2 - банков платежен субагент;
  • 3 - платежен агент;
  • 4 - платежен субагент;
  • 5 - пълномощник;
  • 6 - комисионер;
  • 7 - друг агент.
НезадължителноpayingObjectОбект с данни за платежния агент. Описанието на вложените елементи е дадено по-долу.
НезадължителноpaymentsOperatorObjectОбект с информация за оператора за приемане на плащания. Описанието на вложените елементи е дадено по-долу.
НезадължителноMTOperatorObjectОбект с данни за Оператора на превода. Описанието на вложените елементи е дадено по-долу.

Описание на параметрите в обекта paying:

ЗадължителностНазваниеТипОписание
НезадължителноoperationString [1..24]Име на транзакцията на платежния агент.
НезадължителноphonesArray of stringsМасив от телефонни номера на платежния агент във формат +N.

Описание на параметрите в обекта paymentsOperator:

ЗадължителностИмеТипОписание
НезадължителноphonesArray of stringsМасив от телефонни номера на платежния агент във формат +N.

Описание на параметрите в обекта MTOperator:

ЗадължителностИмеТипОписание
НезадължителноphonesArray of stringsМасив от телефонни номера на оператора за превод в формат +N.
НезадължителноnameString [1..256]Име на оператора за превод.
НезадължителноaddressString [1..256]Адрес на оператора за превод.
НезадължителноinnString [10..12]ИНН на оператора на превода.

Описание на параметрите в обекта supplier_info:

ЗадължителностНазваниеТипОписание
НезадължителноphonesArray of stringsМасив от телефонни номера на доставчика във формат +N.
НезадължителноnameString [1..256]Наименование на доставчика.
НезадължителноinnInteger [10..12]ИНН на доставчика

Описание на параметрите на обекта markQuantity.

ЗадължителностНаименованиеТипОписание
ЗадължителноnumeratorInteger [1..12]Числител на дробната част на обекта на плащане.
ЗадължителноdenominatorInteger [1..12]Знаменател на дробната част на обекта за плащане.

Описание на параметрите в обект quantity:

ЗадължителностИмеТипОписание
ЗадължителноvalueNumber [1..18]Количество на стокови позиции от дадения positionId. За указване на дробни числа използвайте десетична точка. Допуска се максимум 3 знака след точката.
ЗадължителноmeasureString [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:

ЗадължителностНазваниеТипОписание
НезадължителноitemDetailsParamsObjectПараметър, описващ допълнителна информация по стоковата позиция. Описанието на вложените елементи е приведено по-долу.

Описание на параметрите в обекта itemDetailsParams:

ЗадължителностНаименованиеТипОписание
ЗадължителноvalueString [1..2000]Допълнителна информация за товарната позиция.
ЗадължителноnameString [1..255]Наименование на параметъра за описанието на детайлизацията на стоковата позиция

Параметри на отговора

ЗадължителностНаименованиеТипОписание
НезадължителноerrorCodeString [1..2]Информационен параметър в случай на грешка, който може да има различни кодови стойности:
  • стойност 0 - указва успех на обработката на заявката;
  • друга числова стойност (1-99) - указва грешка, за получаване на по-подробна информация за която е необходимо да се провери параметър errorMessage.
Може да отсъства, ако резултатът не е предизвикал грешки.
НезадължителноerrorMessageString [1..512]Информационен параметър, който представлява описание на грешката в случай на възникване на грешка. Стойността на errorMessage може да варира, затова не трябва да се препраща изрично към неговите стойности в кода.
Езикът на описанието се задава в параметъра language на заявката.

Примери

Пример за заявка

curl --request POST \
  --url https://uat.dskbank.bg/payment/rest/refund.do \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data userName=test_user \
  --data password=test_user_password \
  --data currency=975 \
  --data orderId=01491d0b-c848-7dd6-a20d-e96900a7d8c0 \
  --data amount=2000 \
  --data language=en

Пример за отговор

{
  "errorCode": 0,
  "errorMessage":"Success"
}

Отказ на поръчка

За да откажете още неплатена поръчка, използвайте заявка https://uat.dskbank.bg/payment/rest/decline.do. Може да се откаже само поръчка, която не е била завършена. След успешното изпълнение на тази заявка поръчката преминава в статус DECLINED.


При изпълнение на заявката е необходимо да се използва заглавие: Content-Type: application/x-www-form-urlencoded

Параметри на заявката

ЗадължителностНаименованиеТипОписание
ЗадължителноuserNameString [1..50]Потребителско име на API акаунта на продавача.
ЗадължителноpasswordString [1..30]Парола на API акаунта на продавача.
НезадължителноmerchantLoginString [1..255]За да регистрирате поръчка от името на друг търговец, посочете неговия логин (за API-акаунта) в този параметър.
Може да се използва само ако имате разрешение за преглед на транзакциите на други продавачи или ако посоченият продавач е ваш дъщерен продавач.
НезадължителноlanguageString [2]Ключ на езика по ISO 639-1. Ако езикът не е указан, се използва езикът по подразбиране, указан в настройките на магазина.
Поддържани езици: en,ru,el,ro,bg,pt,sw,hu,it,pl,de,fr,kh,cn,es,ka,da,et,fi,lt,lv,nl,sv.
ЗадължителноorderIdString [1..36]Номер на поръчката в платежния шлюз. Уникален в рамките на платежния шлюз.
ЗадължителноorderNumberString [1..36]Номер на поръчката (ID) в системата на търговеца; трябва да бъде уникален за всяка поръчка.

Параметри на отговора

ЗадължителностНаименованиеТипОписание
ЗадължителноerrorCodeString [1..2]Информационен параметър в случай на грешка, който може да има различни кодови стойности:
  • стойност 0 - указва успех на обработката на заявката;
  • друга числова стойност (1-99) - указва грешка, за получаване на по-подробна информация за която е необходимо да се провери параметър errorMessage.
Може да отсъства, ако резултатът не е предизвикал грешки.
ЗадължителноerrorMessageString [1..512]Информационен параметър, който представлява описание на грешката в случай на възникване на грешка. Стойността на errorMessage може да варира, затова не трябва да се препраща изрично към неговите стойности в кода.
Езикът на описанието се задава в параметъра language на заявката.

Примери

Пример за заявка

curl --request POST \
  --url https://uat.dskbank.bg/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://uat.dskbank.bg/payment/rest/paymentOrderBinding.do.


При изпълнение на заявката е необходимо да се използва заглавието: Content-Type: application/x-www-form-urlencoded

Параметри на заявката

ЗадължителностИмеТипОписание
ЗадължителноuserNameString [1..50]Потребителско име на API акаунта на продавача.
ЗадължителноpasswordString [1..30]Парола на API акаунта на продавача.
ЗадължителноmdOrderString [1..36]Номер на поръчката в платежния шлюз. Уникален в рамките на платежния шлюз.
ЗадължителноbindingIdString [1..255]Идентификатор на вече съществуваща връзка (идентификатор на карта, токенизирана от gateway). Може да се използва само ако търговецът има разрешение за работа с връзки. Ако този параметър се предава в тази заявка, това означава, че:
  • Тази поръчка може да бъде платена само чрез връзка;
  • Платецът ще бъде пренасочен към страница за плащане, където се изисква само въвеждане на CVC.
НезадължителноlanguageString [2]Ключ на езика по ISO 639-1. Ако езикът не е указан, се използва езикът по подразбиране, указан в настройките на магазина.
Поддържани езици: en,ru,el,ro,bg,pt,sw,hu,it,pl,de,fr,kh,cn,es,ka,da,et,fi,lt,lv,nl,sv.
НезадължителноipString [1..39]IP адрес на платеца. IPv6 се поддържа във всички заявки (до 39 символа).
НезадължителноcvcString [3]Предаването на параметъра се определя от типа на плащането:
  • предаването на cvc не е предвидено за всички токенизирани плащания;
  • предаването на cvc не е предвидено за MIT плащания;
  • предаването на cvc е задължително по подразбиране за всички други типове плащания; но ако за търговеца е избрано разрешението Може да извършва плащане без потвърждение на CVC, то в такъв случай предаването на cvc става незадължително.

Допускат се само цифри.
НезадължителноthreeDSSDKBooleanВъзможни стойности: true или false Флаг, показващ, че плащането постъпва от 3DS SDK.
ЗадължителноtiiStringИдентификатор на инициатора на транзакцията. Параметър, указващ какъв тип операция ще изпълнява инициаторът (Клиент или Мерчант). Възможни стойности: F, U. Вижте описанието на стойностите.
УсловноemailString [1..40]Електронна поща за показване на платежната страница. Ако за продавача са настроени известия на клиента, електронната поща трябва да бъде посочена. Пример: client_mail@email.com.
За плащания по VISA с 3DS авторизация е необходимо да се посочи или електронна поща, или телефонен номер на притежателя на картата.
НезадължителноmccInteger [4]Merchant Category Code (код на категория на търговеца).
За предаване на този параметър е необходимо специално разрешение. Могат да се използват стойности само от разрешения списък MCC. За получаване на по-подробна информация се обърнете към техническата поддръжка.
НезадължителноthreeDSProtocolVersionStringВерсия на протокола 3DS. Възможни стойности: "2.1.0", "2.2.0" за 3DS2.
Ако в заявката не се предава threeDSProtocolVersion, то за оторизация 3D Secure ще се използва стойността по подразбиране (2.1.0 - за 3DS 2).
НезадължителноexternalScaExemptionIndicatorStringТип на изключение SCA (Strong Customer Authentication). Ако е посочен този параметър, транзакцията ще бъде обработена в зависимост от вашите настройки в платежния шлюз: или ще бъде изпълнена принудителна операция SSL, или банката-издател ще получи информация за изключението SCA и ще вземе решение за провеждане на операцията с 3DS-автентификация или без нея (за получаване на подробна информация се свържете с нашата служба за поддръжка). Допустими стойности:
  • LVP – транзакция от тип Low Value Payments. Транзакцията може да бъде отнесена към транзакции с ниско ниво на риск въз основа на сумата на транзакцията, броя на транзакциите на клиента в деня или общата дневна сума на плащанията на клиента.
  • TRA – транзакция от тип Transaction Risk Analysis, т.е. транзакция, преминала успешна антифрод-проверка.

За предаване на този параметър трябва да имате достатъчни права в платежния шлюз.
УсловноseTokenString [1..8192]Криптирани данни на картата. Задължително, ако се използва вместо данни на картата.
Задължителни параметри за низа seToken: timestamp, UUID, bindingId, MDORDER. Подробно за генериране на seToken вижте тук.
НезадължителноmarketplaceObjectБлок с параметри на маркетплейса, т.е. продавач, който предлага стоки или услуги от различни дребни продавачи (ритейлъри).
Този параметър се използва, ако е включена специална настройка (обърнете се към поддръжката). Вж. вложени параметри.
OptionalclientBrowserInfoObjectБлок данни за браузъра на клиента, който се изпраща към ACS по време на 3DS автентикация. Този блок може да се предава само ако е включена специална настройка (обърнете се към екипа за поддръжка). Вж. вложени параметри.
НезадължителноacsInIFrameBooleanФлаг, показващ, че за финишния URL ще се връща iFrame версия. Възможни стойности true или false. За свързване на тази функционалност се обърнете към службата за поддръжка.

Възможни стойности tii (Подробнее за типовете запазени платежни данни, поддържани от платежния шлюз, четете тук).

Стойност tiiОписаниеТип транзакцияИнициатор на транзакциятаДанни на картата за транзакциятаЗапазване на данните на картата след транзакциятаЗабележка
FИзвънпланово плащане (CIT)ПоследващаКупувачКлиентът избира карта вместо ръчно въвежданеНеТранзакция на електронна търговия, използваща предварително запазени обичайни запазени платежни данни.
UИзвънпланово плащане (MIT)ПоследващаПродавачНяма ръчно въвеждане, продавачът предава даннитеНеТранзакция на електронна търговия, използваща предварително запазени обичайни запазени платежни данни. Използва се само за едностадийни плащания.

По-долу са дадени параметрите на блока clientBrowserInfo (данни за браузъра на клиента).

ЗадължителностНазваниеТипОписание
НезадължителноuserAgentString [1..2048]Агент на браузъра.
НезадължителноOSStringОперационна система.
НезадължителноOSVersionStringВерсия на операционната система.
НезадължителноbrowserAcceptHeaderString [1..2048]Заглавка Accept, която съобщава на сървъра какви формати (или MIME-типове) поддържа браузъра.
НезадължителноbrowserIpAddressString [1..45]IP-адрес на браузъра.
НезадължителноbrowserLanguageString [1..8]Език на браузъра.
НезадължителноbrowserTimeZoneStringЧасова зона на браузъра.
НезадължителноbrowserTimeZoneOffsetString [1..5]Отместване на часовата зона в минути между локалното време на потребителя и UTC.
НезадължителноcolorDepthString [1..2]Дълбочина на цвета на екрана, в битове.
НезадължителноfingerprintStringОтпечатък на браузъра - уникален цифров идентификатор на браузъра.
НезадължителноisMobileBooleanВъзможни стойности: true или false. Флаг, указващ че се използва мобилно устройство.
НезадължителноjavaEnabledBooleanВъзможни стойности: true или false. Флаг, указващ че в браузъра е включена поддръжка на java.
НезадължителноjavascriptEnabledBooleanВъзможни стойности: true или false. Флаг, указващ че в браузъра е включена поддръжка на javascript.
НезадължителноpluginsStringСписък на плъгините, използвани в браузъра, разделени със запетая.
НезадължителноscreenHeightInteger [1..6]Височина на екрана в пиксели.
НезадължителноscreenWidthInteger [1..6]Ширина на екрана в пиксели.
НезадължителноscreenPrintStringДанни за параметрите за печат на браузъра, включително резолюция, дълбочина на цвета, плътност на пикселите.

Пример за блок 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":"x.x.x.x"
	}

Описание на параметрите на обекта marketplace:

ЗадължителностИмеТипОписание
ЗадължителноmarketplaceIdString [1..11]Идентификатор на маркетплейса в банката-акуайър.
УсловноforeignRetailerIndicatorBooleanУказва дали маркетплейсът има чуждестранни ритейлъри (дъщерни търговци). Ако в обекта marketplace се предава блок retailers, този параметър не е задължително да се предава, в противен случай – задължително.
НезадължителноretailersArray of objectsМасив от ритейлъри (дъщерни продавачи на маркетплейса). Съдържа само 1 елемент. Вложените елементи са описани по-долу.

Описание на параметрите на обекта, който е елемент от масива retailers.

ЗадължителностИмеТипОписание
ЗадължителноforeignRetailerIndicatorBooleanОпределя дали търговецът е чуждестранен.

Пример на обекта marketplace:

"marketplace": {
    "marketplaceId": "MKT12345678",
    "foreignRetailerIndicator": true,
    "retailers": [
        {
            "foreignRetailerIndicator": false
        }
    ]
}

Параметри на отговора

ЗадължителностИмеТипОписание
ЗадължителноerrorCodeString [1..2]Информационен параметър в случай на грешка, който може да има различни кодови стойности:
  • стойност 0 - указва успех на обработката на заявката;
  • друга числова стойност (1-99) - указва грешка, за получаване на по-подробна информация за която е необходимо да се провери параметър errorMessage.
Може да отсъства, ако резултатът не е предизвикал грешки.
НезадължителноerrorMessageString [1..512]Информационен параметър, който представлява описание на грешката в случай на възникване на грешка. Стойността на errorMessage може да варира, затова не трябва да се препраща изрично към неговите стойности в кода.
Езикът на описанието се задава в параметъра language на заявката.
НезадължителноredirectString [1..512]Този параметър се връща, ако плащането е преминало успешно и за плащането не е извършвана проверка на картата за участие в 3-D Secure. Продавачите могат да го използват, ако искат да пренасочат потребителя към страницата на платежния шлюз. Ако продавачът използва собствена страница, тази стойност може да бъде игнорирана.
НезадължителноinfoStringВ случай на успешен отговор. Резултат от опита за плащане. По-долу са приведени възможните стойности.
  • Вашето плащане е обработено, извършва се пренасочване...
  • Операцията е отхвърлена. Проверете въведените данни, достатъчността на средствата на картата и повторете операцията. Извършва се пренасочване...
  • Извинете, плащането не може да бъде извършено. Извършва се пренасочване...
  • Операцията е отхвърлена. Обърнете се към магазина. Извършва се пренасочване...
  • Операцията е отхвърлена. Обърнете се към банката, издала картата. Извършва се пренасочване...
  • Операцията е невъзможна. Удостоверяването на притежателя на картата завърши неуспешно. Извършва се пренасочване...
  • Няма връзка с банката. Повторете по-късно. Извършва се пренасочване...
  • Изтече срокът за изчакване на въвеждане на данни. Извършва се пренасочване...
  • Не е получен отговор от банката. Повторете по-късно. Извършва се пренасочване...
НезадължителноerrorString [1..512]Съобщение за грешка (ако в отговора се върна грешка) на езика, предаден в заявката.
НезадължителноprocessingErrorTypeStringТип на грешка при обработката. Предава се, ако грешката възниква от страна на обработката, а не в платежния шлюз, при това броят на опитите за плащане не е превишен и все още не е имало пренасочване към финалната страница.
НезадължителноdisplayErrorMessageStringПоказвано съобщение за грешка.
Незадължително*errorTypeNameStringПараметър, необходим за frontend страницата за определяне на типа грешка. Задължителен за неуспешни плащания.
НезадължителноacsUrlString [1..512]При успешен отговор в случай на плащане 3D-Secure. URL-адрес за пренасочване към ACS. Задължителен, ако е необходимо пренасочване към ACS. За повече информация вижте Пренасочване към ACS.
НезадължителноpaReqString [1..255]PAReq (Payment Authentication Request) — съобщение, което трябва да бъде изпратено в ACS заедно с пренасочването. Връща се при успешен отговор в случай на плащане 3D-Secure, ако е необходимо пренасочване към ACS. Това съобщение съдържа данни в кодировка Base64, необходими за автентификация на притежателя на картата. За повече подробности вижте Пренасочване към ACS.
НезадължителноtermUrlString [1..512]При успешен отговор в случай на плащане 3D-Secure. Това е URL-адрес, към който ACS пренасочва притежателя на картата след удостоверяване. Подробно вж. Пренасочване към ACS.
НезадължителноbindingIdString [1..255]Идентификатор на връзката, създадена по-рано или използвана за плащане. Присъства само ако търговецът има разрешение за работа със връзки.

Елементът payerData съдържа следните параметри.

ЗадължителностИмеТипОписание
НезадължителноpaymentAccountReferenceString [1..29]Уникален номер на сметката на клиента, свързващ всичките му платежни средства в рамките на МПС (карти и токени).

Примери

Пример за заявка

curl --request POST \
  --url https://uat.dskbank.bg/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://uat.dskbank.bg/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://uat.dskbank.bg/payment/rest/finish3ds.do?lang=en"
}

Пример за отговор с грешка

{
  "error": "[clientId] is empty",
  "errorCode": 5,
  "is3DSVer2": false,
  "errorMessage": "[clientId] is empty"
}

Получаване на връзки

За получаване на списък с клиентски връзки се използва заявка https://uat.dskbank.bg/payment/rest/getBindings.do.


При изпълнение на заявката е необходимо да се използва заглавка: Content-Type: application/x-www-form-urlencoded

Параметри на заявката

ЗадължителностНаименованиеТипОписание
ЗадължителноclientIdString [0..255]Номер на клиента (ID) в системата на търговеца — до 255 символа. Използва се за реализиране на функционалността на връзките. Може да се връща в отговора, ако на търговеца е разрешено да създава връзки.
Указването на този параметър при обработка на плащания по връзка е задължително. В противен случай плащането ще бъде невъзможно.
НезадължителноlanguageString [2]Ключ на езика по ISO 639-1. Ако езикът не е указан, се използва езикът по подразбиране, указан в настройките на магазина.
Поддържани езици: en,ru,el,ro,bg,pt,sw,hu,it,pl,de,fr,kh,cn,es,ka,da,et,fi,lt,lv,nl,sv.
ЗадължителноuserNameString [1..50]Потребителско име на API акаунта на продавача. Ако за удостоверяване при регистрация вместо потребителско име и парола се използва открит токен (параметър token), паролата не е необходимо да се предава.
ЗадължителноpasswordString [1..30]Парола на API акаунта на продавача. Ако за удостоверяване при регистрация вместо логин и парола се използва открит токен (параметър token), паролата не е необходимо да се предава.
НезадължителноbindingIdString [1..255]Идентификатор на вече съществуваща връзка (идентификатор на карта, токенизирана от gateway). Може да се използва само ако търговецът има разрешение за работа с връзки. Ако този параметър се предава в тази заявка, това означава, че:
  • Тази поръчка може да бъде платена само чрез връзка;
  • Платецът ще бъде пренасочен към страница за плащане, където се изисква само въвеждане на CVC.
НезадължителноbindingTypeStringТип на връзката, който се очаква в отговора (ако не е посочен, се връщат всички типове). Възможни стойности:
  • C – обичайна връзка.
  • R – рекурентна връзка.
НезадължителноshowExpiredBooleantrue/false параметър, определящ дали да се показват връзки с изтекли карти. Стойност по подразбиране: false.
НезадължителноmerchantLoginString [1..255]За да получите списък със запазените от клиента удостоверения за самоличност на друг търговец, посочете в този параметър логина на търговеца (за API-акаунта).
Може да се използва само ако имате разрешение за преглед на транзакциите на други продавачи или ако посоченият продавач е ваш дъщерен продавач. И вие, и посоченият продавач трябва да имате разрешение за работа със запазени удостоверения за самоличност (връзки).

Параметри на отговора

ЗадължителностНаименованиеТипОписание
ЗадължителноerrorCodeString [1..2]Информационен параметър в случай на грешка, който може да има различни кодови стойности:
  • стойност 0 - указва успех на обработката на заявката;
  • друга числова стойност (1-99) - указва грешка, за получаване на по-подробна информация за която е необходимо да се провери параметър errorMessage.
Може да отсъства, ако резултатът не е предизвикал грешки.
НезадължителноerrorMessageString [1..512]Информационен параметър, който представлява описание на грешката в случай на възникване на грешка. Стойността на errorMessage може да варира, затова не трябва да се препраща изрично към неговите стойности в кода.
Езикът на описанието се задава в параметъра language на заявката.
НезадължителноbindingsObjectЕлемент с блокове, съдържащи параметри на връзките. Вж. описанието по-долу.

Елементът bindings съдържа следните параметри.

ЗадължителностНаименованиеТипОписание
НезадължителноmaskedPanString [1..19]Маскиран номер на карта, използвана за плащането. Съдържа реалните първи 6 и последни 4 цифри от номера на картата във формат XXXXXX**XXXX.
НезадължителноpaymentWayStringНачин на извършване на плащане (плащане с въвеждане на данни от карта, плащане чрез връзка и т.н.). Допълнителни възможни стойности на параметъра са посочени по-долу
ЗадължителноbindingIdString [1..255]Идентификатор на вече съществуваща връзка (идентификатор на карта, токенизирана от gateway). Може да се използва само ако търговецът има разрешение за работа с връзки. Ако този параметър се предава в тази заявка, това означава, че:
  • Тази поръчка може да бъде платена само чрез връзка;
  • Платецът ще бъде пренасочен към страница за плащане, където се изисква само въвеждане на CVC.
ЗадължителноexpiryDateString [6]Срок на валидност на картата в следния формат: YYYYMM.
НезадължителноbindingCategoryStringПредназначение на връзката, очаквана в отговора. Възможни стойности: COMMON, RECURRENT.
НезадължителноclientIdString [0..255]Номер на клиента (ID) в системата на търговеца — до 255 символа. Използва се за реализиране на функционалността на връзките. Може да се връща в отговора, ако на търговеца е разрешено да създава връзки.
Указването на този параметър при обработка на плащания по връзка е задължително. В противен случай плащането ще бъде невъзможно.
НезадължителноdisplayLabelString [1..16]Последните 4 цифри на оригиналния PAN преди токенизация.
НезадължителноpaymentSystemStringНаименование на платежната система. Възможни са следните стойности:
  • VISA
  • MASTERCARD
  • AMEX
  • JCB
  • CUP

Примери

Пример за заявка

curl --request POST \
  --url https://uat.dskbank.bg/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": "44779116-41a5-7798-b072-c0a30760e2b0",
            "maskedPan": "411111**1111",
            "expiryDate": "203412",
            "paymentWay": "TOKEN_PAY",
            "paymentSystem": "CARD",
            "displayLabel": "XXXXXXXXXXXX1111",
            "bindingCategory": "COMMON"
        }
    ]
 }

Получаване на връзки по номер на карта

За получаване на списък с всички връзки на банкова карта се използва заявка https://uat.dskbank.bg/payment/rest/getBindingsByCardOrId.do.


При изпълнение на заявката е необходимо да се използва заглавка: Content-Type: application/x-www-form-urlencoded

Параметри на заявката

ЗадължителностНаименованиеТипОписание
ЗадължителноuserNameString [1..50]Потребителско име на API акаунта на продавача.
ЗадължителноpasswordString [1..30]Парола на API акаунта на продавача.
УсловиеpanString [1..19]Номер на платежна карта (задължително, ако bindinId не се предава). Стойността pan заменя стойността bindingId.
УсловиеbindingIdString [1..255]Идентификатор на вече съществуваща връзка (идентификатор на карта, токенизирана от gateway). Може да се използва само ако търговецът има разрешение за работа с връзки. Ако този параметър се предава в тази заявка, това означава, че:
  • Тази поръчка може да бъде платена само чрез връзка;
  • Платецът ще бъде пренасочен към страница за плащане, където се изисква само въвеждане на CVC.
НезадължителноshowExpiredBooleantrue/false параметър, определящ дали да се показват връзки с изтекли карти. Стойност по подразбиране: false.

Параметри на отговора

ЗадължителностНаименованиеТипОписание
ЗадължителноerrorCodeString [1..2]Информационен параметър в случай на грешка, който може да има различни кодови стойности:
  • стойност 0 - указва успех на обработката на заявката;
  • друга числова стойност (1-99) - указва грешка, за получаване на по-подробна информация за която е необходимо да се провери параметър errorMessage.
Може да отсъства, ако резултатът не е предизвикал грешки.
НезадължителноerrorMessageString [1..512]Информационен параметър, който представлява описание на грешката в случай на възникване на грешка. Стойността на errorMessage може да варира, затова не трябва да се препраща изрично към неговите стойности в кода.
Езикът на описанието се задава в параметъра language на заявката.
НезадължителноbindingsObjectЕлемент с блокове, съдържащи параметри на връзки: bindingId, maskedPan, expiryDate, clientId
НезадължителноbindingIdString [1..255]Идентификатор на вече съществуваща връзка (идентификатор на карта, токенизирана от gateway). Може да се използва само ако търговецът има разрешение за работа с връзки. Ако този параметър се предава в тази заявка, това означава, че:
  • Тази поръчка може да бъде платена само чрез връзка;
  • Платецът ще бъде пренасочен към страница за плащане, където се изисква само въвеждане на CVC.
НезадължителноmaskedPanString [1..19]Маскиран номер на карта, използвана за плащането. Съдържа реалните първи 6 и последни 4 цифри от номера на картата във формат XXXXXX**XXXX.
НезадължителноexpiryDateString [6]Срок на валидност на картата в следния формат: YYYYMM.
НезадължителноclientIdString [0..255]Номер на клиента (ID) в системата на търговеца — до 255 символа. Използва се за реализиране на функционалността на връзките. Може да се връща в отговора, ако на търговеца е разрешено да създава връзки.
Указването на този параметър при обработка на плащания по връзка е задължително. В противен случай плащането ще бъде невъзможно.

Примери

Пример за заявка

curl --request POST \
  --url https://uat.dskbank.bg/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://uat.dskbank.bg/payment/rest/unBindCard.do.


При изпълнение на заявката е необходимо да се използва заглавка: Content-Type: application/x-www-form-urlencoded

Параметри на заявката

ЗадължителностНаименованиеТипОписание
ЗадължителноuserNameString [1..50]Потребителско име на API акаунта на продавача.
ЗадължителноpasswordString [1..30]Парола на API акаунта на продавача.
ЗадължителноbindingIdString [1..255]Идентификатор на вече съществуваща връзка (идентификатор на карта, токенизирана от gateway). Може да се използва само ако търговецът има разрешение за работа с връзки. Ако този параметър се предава в тази заявка, това означава, че:
  • Тази поръчка може да бъде платена само чрез връзка;
  • Платецът ще бъде пренасочен към страница за плащане, където се изисква само въвеждане на CVC.

Параметри на отговора

ЗадължителностНаименованиеТипОписание
НезадължителноerrorCodeString [1..2]Информационен параметър в случай на грешка, който може да има различни кодови стойности:
  • стойност 0 - указва успех на обработката на заявката;
  • друга числова стойност (1-99) - указва грешка, за получаване на по-подробна информация за която е необходимо да се провери параметър errorMessage.
Може да отсъства, ако резултатът не е предизвикал грешки.
НезадължителноerrorMessageString [1..512]Информационен параметър, който представлява описание на грешката в случай на възникване на грешка. Стойността на errorMessage може да варира, затова не трябва да се препраща изрично към неговите стойности в кода.
Езикът на описанието се задава в параметъра language на заявката.

Примери

Пример на заявка

curl --request POST \
  --url https://uat.dskbank.bg/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://uat.dskbank.bg/payment/rest/bindCard.do.


При изпълнение на заявката е необходимо да се използва заглавие: Content-Type: application/x-www-form-urlencoded

Параметри на заявката

ЗадължителностНаименованиеТипОписание
ЗадължителноuserNameString [1..50]Потребителско име на API акаунта на продавача.
ЗадължителноpasswordString [1..30]Парола на API акаунта на продавача.
ЗадължителноbindingIdString [1..255]Идентификатор на вече съществуваща връзка (идентификатор на карта, токенизирана от gateway). Може да се използва само ако търговецът има разрешение за работа с връзки. Ако този параметър се предава в тази заявка, това означава, че:
  • Тази поръчка може да бъде платена само чрез връзка;
  • Платецът ще бъде пренасочен към страница за плащане, където се изисква само въвеждане на CVC.

Параметри на отговора

ЗадължителностНаименованиеТипОписание
НезадължителноerrorCodeString [1..2]Информационен параметър в случай на грешка, който може да има различни кодови стойности:
  • стойност 0 - указва успех на обработката на заявката;
  • друга числова стойност (1-99) - указва грешка, за получаване на по-подробна информация за която е необходимо да се провери параметър errorMessage.
Може да отсъства, ако резултатът не е предизвикал грешки.
НезадължителноerrorMessageString [1..512]Информационен параметър, който представлява описание на грешката в случай на възникване на грешка. Стойността на errorMessage може да варира, затова не трябва да се препраща изрично към неговите стойности в кода.
Езикът на описанието се задава в параметъра language на заявката.

Примери

Пример за заявка

curl --request POST \
  --url https://uat.dskbank.bg/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://uat.dskbank.bg/payment/rest/extendBinding.do.


При изпълнение на заявката е необходимо да се използва заглавка: Content-Type: application/x-www-form-urlencoded

Параметри на заявката

ЗадължителностНаименованиеТипОписание
ЗадължителноuserNameString [1..50]Потребителско име на API акаунта на продавача.
ЗадължителноpasswordString [1..30]Парола на API акаунта на продавача.
ЗадължителноbindingIdString [1..255]Идентификатор на вече съществуваща връзка (идентификатор на карта, токенизирана от gateway). Може да се използва само ако търговецът има разрешение за работа с връзки. Ако този параметър се предава в тази заявка, това означава, че:
  • Тази поръчка може да бъде платена само чрез връзка;
  • Платецът ще бъде пренасочен към страница за плащане, където се изисква само въвеждане на CVC.
ЗадължителноnewExpiryInteger [6]Нова дата (година и месец) на изтичане на срока на валидност във формат YYYYMM.
ЗадължителноlanguageString [2]Ключ на езика по ISO 639-1. Ако езикът не е указан, се използва езикът по подразбиране, указан в настройките на магазина.
Поддържани езици: en,ru,el,ro,bg,pt,sw,hu,it,pl,de,fr,kh,cn,es,ka,da,et,fi,lt,lv,nl,sv.

Параметри на отговора

ЗадължителностНаименованиеТипОписание
НезадължителноerrorCodeString [1..2]Информационен параметър в случай на грешка, който може да има различни кодови стойности:
  • стойност 0 - указва успех на обработката на заявката;
  • друга числова стойност (1-99) - указва грешка, за получаване на по-подробна информация за която е необходимо да се провери параметър errorMessage.
Може да отсъства, ако резултатът не е предизвикал грешки.
НезадължителноerrorMessageString [1..512]Информационен параметър, който представлява описание на грешката в случай на възникване на грешка. Стойността на errorMessage може да варира, затова не трябва да се препраща изрично към неговите стойности в кода.
Езикът на описанието се задава в параметъра language на заявката.

Примери

Ример за заявка

curl --request POST \
  --url https://uat.dskbank.bg/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://uat.dskbank.bg/payment/recurrentPayment.do. Заявката се използва за регистрация и плащане на поръчка.


При изпълнение на заявката е необходимо да се използва заглавката: Content-Type: application/json

Параметри на заявката

ЗадължителностНаименованиеТипОписание
ЗадължителноuserNameString [1..50]Потребителско име на API акаунта на продавача.
ЗадължителноpasswordString [1..30]Парола на API акаунта на продавача.
ЗадължителноorderNumberString [1..36]Номер на поръчката (ID) в системата на търговеца; трябва да бъде уникален за всяка поръчка.
НезадължителноlanguageString [2]Ключ на езика по ISO 639-1. Ако езикът не е указан, се използва езикът по подразбиране, указан в настройките на магазина.
Поддържани езици: en,ru,el,ro,bg,pt,sw,hu,it,pl,de,fr,kh,cn,es,ka,da,et,fi,lt,lv,nl,sv.
НезадължителноfeeInputInteger [0..8]Размер на комисионната в минимални единици валута. Функционалността трябва да бъде включена на ниво продавач в gateway-я.
ЗадължителноbindingIdString [1..255]Идентификатор на вече съществуваща връзка (идентификатор на карта, токенизирана от gateway). Може да се използва само ако търговецът има разрешение за работа с връзки. Ако този параметър се предава в тази заявка, това означава, че:
  • Тази поръчка може да бъде платена само чрез връзка;
  • Платецът ще бъде пренасочен към страница за плащане, където се изисква само въвеждане на CVC.
ЗадължителноamountInteger [0..12]Сума на плащането в минимални единици валута (например, в стотинки).
НезадължителноcurrencyString [3]Код на валутата на плащането ISO 4217. Ако не е посочен, се използва стойността по подразбиране. Позволени са само цифри.
НезадължителноdescriptionString [1..598]Описание на поръчката в произволен формат.
За да включите изпращането на това поле в процесинговата система, обърнете се към службата за техническа поддръжка.
В това поле е недопустимо да се предават лични данни или платежни данни (номера на карти и т.н.). Това изискване се дължи на факта, че описанието на поръчката никъде не се маскира.
НезадължителноpreAuthBooleanПараметър, определящ необходимостта от предварителна оторизация (блокиране на средства по сметката на клиента преди тяхното списване). Достъпни са следните стойности:
  • true - включено е двуетапно плащане;
  • false - включено е едноетапно плащане (парите се списват веднага).
Ако параметърът липсва, извършва се едноетапно плащане.
НезадължителноautocompletionDateString [19]Дата и време на автоматичното завършване на двуетапното плащане в следния формат: 2025-12-29T13:02:51. Използван часови пояс: UTC+0. За да включите изпращането на това поле в процесинговата система, обърнете се към службата за техническа поддръжка.
НезадължителноautoReverseDateString [19]Дата и час на автоматично анулиране на двуетапното плащане в следния формат: 2025-06-23T13:02:51. Използван часови пояс: UTC+0. За да включите изпращането на това поле в процесинговата система, обърнете се към службата за техническа поддръжка.
НезадължителноfeaturesStringФункции на поръчката. За да посочите няколко функции, използвайте този параметър няколко пъти в една заявка. По-долу са изброени възможните стойности.
  • VERIFY - ако се предаде тази стойност в заявката за оформяне на поръчка, притежателят на картата ще бъде верифициран, но няма да се извърши списване на средства, така че в този случай параметърът amount може да има стойност 0. Верификацията позволява да се убедите, че картата се намира в ръцете на притежателя, и впоследствие да списвате от тази карта средства, без да прибягвате до проверка на автентификационните данни (CVC, 3D-Secure) при извършване на последващи плащания. Дори ако сумата на плащането бъде предадена в заявката, тя няма да бъде списана от сметката на клиента при предаване на стойността VERIFY. Тази стойност също може да се използва за създаване на връзка — в този случай параметърът clientId също трябва да бъде предаден. Подробности четете тук.
  • FORCE_TDS - Принудително извършване на плащане с използване на 3-D Secure. Ако картата не поддържа 3-D Secure, транзакцията няма да премине.
  • FORCE_SSL - Принудително извършване на плащане чрез SSL (без използване на 3-D Secure).
  • FORCE_FULL_TDS - След извършване на автентификация с помощта на 3-D Secure статусът PaRes трябва да бъде само Y, което гарантира успешна автентификация на потребителя. В противен случай транзакцията няма да премине.
  • FORCE_CREATE_BINDING - предаването на тази стойност в заявката за оформяне на поръчка принудително създава връзка. Тази функционалност трябва да бъде включена на ниво продавач в шлюза. Тази стойност не може да се предаде в заявка със съществуващ bindingId или bindingNotNeeded = true (ще предизвика грешка при проверка). Когато се предава тази функция, параметърът clientId също трябва да бъде предаден. Ако в блока features се предадат и двете стойности FORCE_CREATE_BINDING и VERIFY, тогава поръчката ще бъде създадена САМО за създаване на връзка (без плащане).
НезадължителноadditionalParametersObjectДопълнителни параметри на поръчката, които се съхраняват в личния кабинет на продавача за последващ преглед. Всяка нова двойка от име на параметър и неговата стойност трябва да бъде разделена със запетая. По-долу е даден пример за използване.
{ "firstParamName": "firstParamValue", "secondParamName": "secondParamValue"}
НезадължителноbillingPayerDataObjectБлок с регистрационни данни на клиента (адрес, пощенски код), необходим за преминаване на проверка на адреса в рамките на услугите AVS/AVV. Задължително, ако функцията е включена за продавача от страна на платежния шлюз. Вж. вложени параметри.
НезадължителноshippingPayerDataObjectОбект, съдържащ данни за доставката на клиента. Този параметър се използва за по-нататъшно 3DS-удостоверяване на клиента. Вж. вложени параметри.
НезадължителноpreOrderPayerDataObjectОбект, съдържащ данни за предварителна поръчка. Този параметър се използва за по-нататъшно 3DS-удостоверяване на клиента. Вж. вложени параметри.
НезадължителноorderPayerDataObjectОбект, съдържащ данни за плащащия на поръчката. Този параметър се използва за по-нататъшно 3DS-удостоверяване на клиента. Вж. вложени параметри.
НезадължителноbillingAndShippingAddressMatchIndicatorString [1]Индикатор за съответствие на платежния адрес на притежателя на картата и адреса за доставка. Този параметър се използва за по-нататъшна 3DS-автентификация на клиента.
Възможни стойности:
  • Y - съвпадение на платежния адрес на притежателя на картата и адреса за доставка;
  • N - платежният адрес на притежателя на картата и адресът за доставка не съвпадат.

По-долу са посочени параметрите на блока billingPayerData (данни за адреса за регистрация на клиента).

ЗадължителностИмеТипОписание
НезадължителноbillingCityString [0..50]Град, регистриран за конкретната карта в Банката Емитент.
НезадължителноbillingCountryString [0..50]Страна, регистрирана за конкретната карта на банката-издател. Формат: ISO 3166-1 (Alpha 2 / Alpha 3 / Number-3) или наименование на страната. Препоръчваме предаване на двубуквен/трибуквен ISO код на страната.
НезадължителноbillingAddressLine1String [0..50]Адрес, регистриран по конкретна карта в Банката Емитент (адрес на платеца). Ред 1. Задължително за предаване за AVS-проверка.
НезадължителноbillingAddressLine2String [0..50]Адрес, регистриран за конкретната карта в Банката Емитент. Ред 2.
НезадължителноbillingAddressLine3String [0..50]Адрес, регистриран за конкретната карта в Банката Емитент. Ред 3.
НезадължителноbillingPostalCodeString [0..9]Пощенски код, регистриран за конкретната карта в Банката Издател. Задължително за предаване за AVS-проверка.
НезадължителноbillingStateString [0..50]Щат, регистриран за конкретната карта в Банката Емитент. Формат: пълна стойност на кода ISO 3166-2, негова част или наименование на щата/региона. Може да съдържа букви само от латинската азбука. Препоръчваме да се предава двубуквен ISO код на щата/региона.
ЗадължителноpayerAccountString [1..32]Номер на сметката на изпращача.
НезадължителноpayerLastNameString [1..64]Фамилия на изпращача.
НезадължителноpayerFirstNameString [1..35]Име на изпращача.
НезадължителноpayerMiddleNameString [1..35]Бащино име на изпращача.
НезадължителноpayerCombinedNameString [1..99]Пълно име на подателя.
НезадължителноpayerIdTypeString [1..8]Тип на предоставения идентифициращ документ на подателя.
Възможни стойности:
  • IDTP1 - Паспорт
  • IDTP2 - Шофьорска книжка
  • IDTP3 - Социална карта
  • IDTP4 - ID карта на гражданин
  • IDTP5 - Сертификат за водене на бизнес
  • IDTP6 - Сертификат на бежанец
  • IDTP7 - Разрешително за пребиваване
  • IDTP8 - Чужд паспорт
  • IDTP9 - Служебен паспорт
  • IDTP10 - Временен паспорт
  • IDTP11 - Паспорт на моряк
НезадължителноpayerIdNumberString [1..100]Номер на предоставения идентифициращ документ (например, паспорт) на изпращача.
НезадължителноpayerBirthdayString [1..20]Дата на раждане на изпращача във формат YYYYMMDD.

Описание на параметрите на обект shippingPayerData:

ЗадължителностНаименованиеТипОписание
НезадължителноshippingCityString [1..50]Град на поръчителя (от адреса за доставка)
НезадължителноshippingCountryString [1..50]Страна на поръчителя
НезадължителноshippingAddressLine1String [1..50]Основен адрес на клиента (от адреса за доставка)
НезадължителноshippingAddressLine2String [1..50]Основен адрес на клиента (от адреса за доставка)
НезадължителноshippingAddressLine3String [1..50]Основен адрес на клиента (от адреса за доставка)
НезадължителноshippingPostalCodeString [1..16]Пощенски код на клиента за доставка
НезадължителноshippingStateString [1..50]Щат/регион на купувача (от адреса за доставка)
НезадължителноshippingMethodIndicatorInteger [2]Индикатор за начин на доставка.
Възможни стойности:
  • 01 - доставка на платежния адрес на притежателя на карта.
  • 02 - доставка на друг адрес, проверен от Търговеца.
  • 03 - доставка на адрес, различен от основния адрес на притежателя на карта.
  • 04 - изпращане в магазин/самовземане (адресът на магазина трябва да бъде указан в съответните параметри за доставка)
  • 05 - Цифрово разпространение (включва онлайн услуги и електронни подаръчни карти)
  • 06 - билети за пътувания и събития, които не могат да бъдат доставени.
  • 07 - Други (например игри, цифрови стоки, които не подлежат на доставка, цифрови абонаменти и т.н.)
НезадължителноdeliveryTimeframeInteger [2]Срок за доставка на стоката.
Възможни стойности:
  • 01 - цифрова дистрибуция
  • 02 - доставка в същия ден
  • 03 - доставка на следващия ден
  • 04 - доставка в рамките на 2 дни след плащането и по-късно.
НезадължителноdeliveryEmail String [1..254]Целеви адрес на електронна поща за доставка на цифрово разпространение. Препоръчително е да предавате електронната поща в самостоятелен параметър на заявката email (но ако я предадете в този блок, към нея ще се прилагат същите правила).

Описание на параметрите на обекта preOrderPayerData:

ЗадължителностНаименованиеТипОписание
НезадължителноpreOrderDateString [10]Очаквана дата на доставка (за предварително поръчани покупки) във формат ГГГГММДД.
НезадължителноpreOrderPurchaseIndInteger [2]Индикатор за разполагане от клиента на поръчка за налична или бъдеща доставка.
Възможни стойности:
  • 01 - възможна е доставка;
  • 02 - бъдеща доставка
НезадължителноreorderItemsIndInteger [2]Индикатор, че клиентът преподръчва преди заплатена доставка в състава на нова поръчка.
Възможни стойности:
  • 01 - поръчката се разполага за първи път;
  • 02 - повторна поръчка

Описание на параметрите на обект orderPayerData.

ЗадължителностНаименованиеТипОписание
НезадължителноhomePhoneString [7..15]Домашен телефон на притежателя на картата. Необходимо е винаги да се посочва код на страната, но знакът + или 00 в началото може да се посочи или пропусне. Номерът трябва да има дължина от 7 до 15 цифри. По този начин са възможни следните стойности:
  • +35799988877;
  • 0035799988877;
  • 35799988877.
НезадължителноworkPhoneString [7..15]Служебен телефон на притежателя на картата. Необходимо е винаги да се посочва код на страната, но знакът + или 00 в началото може да се посочи или пропусне. Номерът трябва да има дължина от 7 до 15 цифри. По този начин са възможни следните стойности:
  • +35799988877;
  • 0035799988877;
  • 35799988877.
НезадължителноmobilePhoneString [7..15]Номер на мобилния телефон на притежателя на картата. Необходимо е винаги да се посочва код на страната, но знакът + или 00 в началото може да се посочи или пропусне. Номерът трябва да има дължина от 7 до 15 цифри. По този начин са възможни следните стойности:
  • +35799988877;
  • 0035799988877;
  • 35799988877.

За плащания по VISA с 3DS авторизация е необходимо да се посочи или електронна поща, или номер на телефон на притежателя на картата. Ако имате настроено показване на номера на телефона на платежната страница и сте посочили неверен номер на телефон, клиентът ще може да го поправи на платежната страница.

Параметри на отговора

ЗадължителностНаименованиеТипОписание
ЗадължителноsuccessBooleanОсновен параметър, който указва, че заявката е преминала успешно. Достъпни са следните стойности:
  • true - заявката е успешно обработена;
  • false - заявката не е преминала.

Обърнете внимание, че стойността true означава, че заявката е била обработена, а не че поръчката е била платена.
По-подробна информация за това как да разберете дали плащането е било успешно или не, е достъпна тук.
Условие[data](#data Recurrent payment rest)N/AТози параметър се връща само в случай на успешна обработка на плащането. Вж. описанието по-долу.
Условие[error](#error Recurrent payment rest)N/AТози параметър се връща само в случай на грешка при плащането. Вж. описанието по-долу.

Елементът payerData съдържа следните параметри.

ЗадължителностНаименованиеТипОписание
НезадължителноpaymentAccountReferenceString [1..29]Уникален номер на сметката на клиента, свързващ всичките му платежни средства в рамките на МПС (карти и токени).

Блокът data съдържа следните елементи.

ЗадължителностНаименованиеТипОписание
ЗадължителноorderIdString [1..36]Номер на поръчката в платежния шлюз. Уникален в рамките на платежния шлюз.

Блокът error съдържа следните елементи.

ЗадължителностНаименованиеТипОписание
ЗадължителноcodeString [1..3]Код като информационен параметър, съобщаващ за грешка.
ЗадължителноdescriptionString [1..598]Подробно техническо обяснение на грешката - съдържанието на този параметър не е предназначено за показване на потребителя.
ЗадължителноmessageString [1..512]Информационен параметър, който представлява описание на грешката за показване на потребителя. Параметърът може да варира, затова не трябва да се прави експлицитна препратка към неговите стойности в кода.

Примери

Ример на заявка

curl --request POST \
--url https://uat.dskbank.bg/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" : "975",
  "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": "975",
        "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>"
        },
        "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://uat.dskbank.bg/payment/rest/createBindingNoPayment.do.


При изпълнение на заявката е необходимо да се използва заглавие: Content-Type: application/x-www-form-urlencoded

Параметри на заявката

ЗадължителностНаименованиеТипОписание
ЗадължителноuserNameString [1..50]Потребителско име на API акаунта на продавача.
ЗадължителноpasswordString [1..30]Парола на API акаунта на продавача.
ЗадължителноclientIdString [0..255]Номер на клиента (ID) в системата на търговеца. Използва се за реализиране на функционалността на връзките.
НезадължителноbindingStrengthStringТип на плащането, въз основа на който е създадено съхранените платежни данни. Използва се за миграция на съхранените платежни данни от системата на търговеца.
Възможни стойности:
  • TDS - съхранените платежни данни са създадени въз основа на пълно 3DS плащане (ECI=02 или 05)
  • SSL - съхранените платежни данни са създадени въз основа на SSL-плащане (ECI=07)
  • TDS_SSL - съхранените платежни данни въз основа на SSL-плащане с опит за автентификация 3DS (ECI=01 или 06)
  • NO_PAYMENT - съхранените платежни данни са създадени без плащане (стойност по подразбиране)

За всички стойности, различни от NO_PAYMENT е необходимо да се предават допълнителни параметри:
  • initNetworkReferenceNumber - идентификатор на инициращото плащане за съхранените платежни данни
  • networkReferenceNumber - идентификатор на последното плащане по съхранените платежни данни
ЗадължителноcardholderNameString [1..26]Име на притежателя на картата с латински букви. Допустими символи: латински букви, точка, интервал.
ЗадължителноexpiryDateString [6]Срок на валидност на картата в следния формат: YYYYMM.
ЗадължителноpanString [1..19]Номер на платежна карта
НезадължителноadditionalParametersObjectДопълнителни параметри на поръчката, които се съхраняват в личния кабинет на продавача за последващ преглед. Всяка нова двойка от име на параметър и неговата стойност трябва да бъде разделена със запетая. По-долу е даден пример за използване.
{ "firstParamName": "firstParamValue", "secondParamName": "secondParamValue"}
НезадължителноmerchantLoginString [1..255]За да създадете запазени платежни данни за друг търговец, посочете неговия логин (за API-акаунт) в този параметър.
Може да се използва само ако имате разрешение за преглед на транзакции на други продавачи или ако посоченият продавач е ваш дъщерен продавач.
НезадължителноemailString [1..40]Електронна поща на платеца.
НезадължителноphoneString [7..15]Телефонен номер на притежателя на картата. Необходимо е винаги да се посочва код на страната, но знакът + или 00 в началото може да се посочи или пропусне. Номерът трябва да има дължина от 7 до 15 цифри. По този начин са възможни следните стойности:
  • +35799988877;
  • 0035799988877;
  • 35799988877.

Параметри на отговора

ЗадължителностНаименованиеТипОписание
ЗадължителноerrorCodeString [1..2]Информационен параметър в случай на грешка, който може да има различни кодови стойности:
  • стойност 0 - указва успех на обработката на заявката;
  • друга числова стойност (1-99) - указва грешка, за получаване на по-подробна информация за която е необходимо да се провери параметър errorMessage.
Може да отсъства, ако резултатът не е предизвикал грешки.
НезадължителноerrorMessageString [1..512]Информационен параметър, който представлява описание на грешката в случай на възникване на грешка. Стойността на errorMessage може да варира, затова не трябва да се препраща изрично към неговите стойности в кода.
Езикът на описанието се задава в параметъра language на заявката.
НезадължителноerrorBooleanФлаг, показващ, че в отговора е върната грешка. Допустими стойности: true или false. Приема стойност true, ако errorCode съдържа стойност, различна от 0.
НезадължителноbindingIdString [1..255]Идентификатор на връзката, създадена по-рано или използвана за плащане. Присъства само ако търговецът има разрешение за работа със връзки.
НезадължителноclientIdString [0..255]Номер на клиента (ID) в системата на търговеца — до 255 символа. Използва се за реализиране на функционалността на връзките. Може да се връща в отговора, ако на търговеца е разрешено да създава връзки.
Указването на този параметър при обработка на плащания по връзка е задължително. В противен случай плащането ще бъде невъзможно.
НезадължителноcardholderNameString [1..26]Име на притежателя на картата с латински букви. Допустими символи: латински букви, точка, интервал.
НезадължителноexpiryDateString [6]Срок на валидност на картата в следния формат: YYYYMM.
НезадължителноmaskedPanString [1..19]Маскиран номер на карта, използвана за плащането. Съдържа реалните първи 6 и последни 4 цифри от номера на картата във формат XXXXXX**XXXX.

Примери

Пример за заявка

curl --request POST \
  --url https://uat.dskbank.bg/payment/rest/createBindingNoPayment.do \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data userName=test_user \
  --data password=test_user_password \
  --data clientId=159753456
  --data pan=5555555555555599
  --data expiryDate=203412
  --data cardholderName=TEST CARDHOLDER

Пример за заявка за миграция на връзки

curl --request POST \
  --url https://uat.dskbank.bg/payment/rest/createBindingNoPayment.do \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data userName=test_user \
  --data password=test_user_password \
  --data merchantLogin=some_merchant \
  --data pan=5555555555555599 \
  --data expiryDate=203412 \
  --data 'cardholderName=TEST CARDHOLDER ' \
  --data clientId=client_id \
  --data bindingStrength=TDS \
  --data email=email@test.com \
  --data 'phone=+995555000000' \
  --data 'additionalParameters={
	"networkReferenceNumber": "network_reference_number",
	"initNetworkReferenceNumber": "init_network_reference_number"
}'

Пример за отговор

{
  "maskedPan": "555555**5599",
  "expiryDate": "203412",
  "cardholderName": "TEST CARDHOLDER",
  "clientId": "159753456",
  "bindingId": "47dbe208-e531-4997-9c36-25a5707d3cb9",
  "errorCode": 0,
  "error": false
}

3DS

Завършване на плащане 3DS2 чрез API

За завършване на поръчка 3DS2 чрез API се използва метод https://uat.dskbank.bg/payment/rest/finish3dsVer2Payment.do.


При изпълнение на заявка е необходимо да се използва заглавка: Content-Type: application/x-www-form-urlencoded

Параметри на заявката

ЗадължителностНаименованиеТипОписание
ЗадължителноuserNameString [1..50]Потребителско име на API акаунта на продавача.
ЗадължителноpasswordString [1..30]Парола на API акаунта на продавача.
ЗадължителноthreeDSServerTransIdString [1..36]Идентификатор на транзакцията, създаден на 3DS сървъра. Задължителен за 3DS автентикация.
ЗадължителностНаименованиеТипОписание
НезадължителноthreeDSVer2MdOrderString [1..36]Номер на поръчка, който е регистриран в първата част от заявката в рамките на 3DS2 операция. Задължителен за удостоверяване 3DS.
Ако този параметър присъства в заявката, тогава се използва mdOrder, който се предава в настоящия параметър. В такъв случай регистрацията на поръчката не се извършва, а се извършва веднага плащането на поръчката.
Този параметър се предава само при използване на методи за мгновено плащане, т.е., когато поръчката се регистрира и се заплаща в рамките на една заявка.

Параметри на отговора

ЗадължителностНаименованиеТипОписание
ЗадължителноerrorCodeString [1..2]Информационен параметър в случай на грешка, който може да има различни кодови стойности:
  • стойност 0 - указва успех на обработката на заявката;
  • друга числова стойност (1-99) - указва грешка, за получаване на по-подробна информация за която е необходимо да се провери параметър errorMessage.
Може да отсъства, ако резултатът не е предизвикал грешки.
ЗадължителноerrorMessageString [1..512]Информационен параметър, който представлява описание на грешката в случай на възникване на грешка. Стойността на errorMessage може да варира, затова не трябва да се препраща изрично към неговите стойности в кода.
Езикът на описанието се задава в параметъра language на заявката.
НезадължителноredirectString [1..512]Този параметър се връща, ако плащането е преминало успешно и за плащането не е извършвана проверка на картата за участие в 3-D Secure. Продавачите могат да го използват, ако искат да пренасочат потребителя към страницата на платежния шлюз. Ако продавачът използва собствена страница, тази стойност може да бъде игнорирана.
Незадължителноis3DSVer2BooleanВъзможни стойности: true или false Флаг, показващ, че плащането постъпва от 3DS2.

Примери

Пример за заявка

curl --request POST \
  --url https://uat.dskbank.bg/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://uat.dskbank.bg/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 \

Пример за отговор с параметър threeDSVer2MdOrder

{
    "redirect": "http://test.com?orderId=f61e2a41-34b9-7a2d-b4d6-83ac00c305c8&lang=en",
    "errorCode": 0,
    "is3DSVer2": true
}

Разни

Верификация на карта

Методът https://uat.dskbank.bg/payment/rest/verifyCard.do се използва за проверка на карта. Плащане не се извършва и поръчката веднага преминава в статус REVERSED.


При изпълнение на заявката е необходимо да се използва заглавката: Content-Type: application/x-www-form-urlencoded

Параметри на заявката

ЗадължителностНаименованиеТипОписание
НезадължителноuserNameString [1..50]Потребителско име на API акаунта на продавача. Ако за удостоверяване при регистрация вместо потребителско име и парола се използва открит токен (параметър token), паролата не е необходимо да се предава.
НезадължителноpasswordString [1..30]Парола на API акаунта на продавача. Ако за удостоверяване при регистрация вместо логин и парола се използва открит токен (параметър token), паролата не е необходимо да се предава.
НезадължителноtokenString [1..256]Стойност, използвана за автентификация на продавача при изпращане на заявки към платежната шлюз. Ако предавате този параметър, то не предавайте userName и password.
ЗадължителноamountInteger [0..12]Сума на плащането в минимални единици валута (например, в стотинки).
НезадължителноcurrencyString [3]Код на валутата на плащането ISO 4217. Ако не е посочен, се използва стойността по подразбиране. Позволени са само цифри.
НезадължителноpanString [1..19]Номер на платежна карта
НезадължителноcvcString [3]Предаването на параметъра се определя от типа на плащането:
  • предаването на cvc не е предвидено за всички токенизирани плащания;
  • предаването на cvc не е предвидено за MIT плащания;
  • предаването на cvc е задължително по подразбиране за всички други типове плащания; но ако за търговеца е избрано разрешението Може да извършва плащане без потвърждение на CVC, то в такъв случай предаването на cvc става незадължително.

Допускат се само цифри.
НезадължителноexpiryInteger [6]Срок на валидност на картата в следния формат: YYYYMM. Задължително, ако не са предадени нито seToken, нито bindingId.
НезадължителноcardholderNameString [1..26]Име на притежателя на картата с латински букви. Допустими символи: латински букви, точка, интервал.
НезадължителноbackUrlString [1..512]URL-адрес, на който потребителят ще бъде пренасочен в случай на успешно плащане.
Използвайте пълен път с указване на протокола, например https://test.com (а не test.com).
В противен случай потребителят ще бъде пренасочен към URL-адрес от следния вид: http://paymentGatewayURL/merchantURL
НезадължителноfailUrlString [1..512]Адрес, на който трябва да се пренасочи потребителят в случай на неуспешно плащане. Адресът трябва да бъде посочен напълно, включително използвания протокол (например, https://mybestmerchantreturnurl.com вместо mybestmerchantreturnurl.com). В противен случай потребителят ще бъде пренасочен по адрес от следния вид: https://uat.dskbank.bg/payment/<merchant_address>.
НезадължителноdescriptionString [1..598]Описание на поръчката в произволен формат.
За да включите изпращането на това поле в процесинговата система, обърнете се към службата за техническа поддръжка.
В това поле е недопустимо да се предават лични данни или платежни данни (номера на карти и т.н.). Това изискване се дължи на факта, че описанието на поръчката никъде не се маскира.
НезадължителноlanguageString [2]Ключ на езика по ISO 639-1. Ако езикът не е указан, се използва езикът по подразбиране, указан в настройките на магазина.
Поддържани езици: en,ru,el,ro,bg,pt,sw,hu,it,pl,de,fr,kh,cn,es,ka,da,et,fi,lt,lv,nl,sv.
НезадължителноreturnUrlString [1..512]Адрес, към който трябва да бъде пренасочен потребителят в случай на успешно плащане. Адресът трябва да бъде указан изцяло, включително използвания протокол (например, https://mybestmerchantreturnurl.com вместо mybestmerchantreturnurl.com). В противен случай потребителят ще бъде пренасочен на адрес от следния вид: https://uat.dskbank.bg/payment/<merchant_address>.
НезадължителноthreeDSServerTransIdString [1..36]Идентификатор на транзакцията, създаден на 3DS сървъра. Задължителен за 3DS автентикация.
НезадължителноthreeDSVer2FinishUrlString [1..512]URL-адрес, с който клиентът трябва да бъде пренасочен след автентификация на сървъра ACS.
УсловиеthreeDSVer2MdOrderString [1..36]Номер на поръчка, който е регистриран в първата част от заявката в рамките на 3DS2 операция. Задължителен за удостоверяване 3DS.
Ако този параметър присъства в заявката, тогава се използва mdOrder, който се предава в настоящия параметър. В такъв случай регистрацията на поръчката не се извършва, а се извършва веднага плащането на поръчката.
Този параметър се предава само при използване на методи за мгновено плащане, т.е., когато поръчката се регистрира и се заплаща в рамките на една заявка.
НезадължителноthreeDSSDKBooleanВъзможни стойности: true или false Флаг, показващ, че плащането постъпва от 3DS SDK.
НезадължителноbillingPayerDataObjectБлок с регистрационни данни на клиента (адрес, пощенски индекс), необходим за преминаване на проверката на адреса в рамките на услугите AVS/AVV. Задължително, ако функцията е включена за продавача от страна на Платежния шлюз. Вж. вложени параметри.
НезадължителноshippingPayerDataObjectОбект, съдържащ данни за доставката до клиента. Този параметър се използва за по-нататъшна 3DS-удостоверяване на клиента. Вж. вложени параметри.
НезадължителноpreOrderPayerDataObjectОбект, съдържащ данни за предварителната поръчка. Този параметър се използва за по-нататъшна 3DS-удостоверяване на клиента. Вж. вложени параметри.
НезадължителноorderPayerDataObjectОбект, съдържащ данни за платеца на поръчката. Този параметър се използва за по-нататъшна 3DS-удостоверяване на клиента. Вж. вложени параметри.
НезадължителноbillingAndShippingAddressMatchIndicatorString [1]Индикатор за съответствие на платежния адрес на притежателя на картата и адреса за доставка. Този параметър се използва за по-нататъшна 3DS-автентификация на клиента.
Възможни стойности:
  • Y - съвпадение на платежния адрес на притежателя на картата и адреса за доставка;
  • N - платежният адрес на притежателя на картата и адресът за доставка не съвпадат.

По-долу са посочени параметрите на блока billingPayerData (данни за адреса за регистрация на клиента).

ЗадължителностИмеТипОписание
НезадължителноbillingCityString [0..50]Град, регистриран за конкретната карта в Банката Емитент.
НезадължителноbillingCountryString [0..50]Страна, регистрирана за конкретната карта на банката-издател. Формат: ISO 3166-1 (Alpha 2 / Alpha 3 / Number-3) или наименование на страната. Препоръчваме предаване на двубуквен/трибуквен ISO код на страната.
НезадължителноbillingAddressLine1String [0..50]Адрес, регистриран по конкретна карта в Банката Емитент (адрес на платеца). Ред 1. Задължително за предаване за AVS-проверка.
НезадължителноbillingAddressLine2String [0..50]Адрес, регистриран за конкретната карта в Банката Емитент. Ред 2.
НезадължителноbillingAddressLine3String [0..50]Адрес, регистриран за конкретната карта в Банката Емитент. Ред 3.
НезадължителноbillingPostalCodeString [0..9]Пощенски код, регистриран за конкретната карта в Банката Издател. Задължително за предаване за AVS-проверка.
НезадължителноbillingStateString [0..50]Щат, регистриран за конкретната карта в Банката Емитент. Формат: пълна стойност на кода ISO 3166-2, негова част или наименование на щата/региона. Може да съдържа букви само от латинската азбука. Препоръчваме да се предава двубуквен ISO код на щата/региона.
ЗадължителноpayerAccountString [1..32]Номер на сметката на изпращача.
НезадължителноpayerLastNameString [1..64]Фамилия на изпращача.
НезадължителноpayerFirstNameString [1..35]Име на изпращача.
НезадължителноpayerMiddleNameString [1..35]Бащино име на изпращача.
НезадължителноpayerCombinedNameString [1..99]Пълно име на подателя.
НезадължителноpayerIdTypeString [1..8]Тип на предоставения идентифициращ документ на подателя.
Възможни стойности:
  • IDTP1 - Паспорт
  • IDTP2 - Шофьорска книжка
  • IDTP3 - Социална карта
  • IDTP4 - ID карта на гражданин
  • IDTP5 - Сертификат за водене на бизнес
  • IDTP6 - Сертификат на бежанец
  • IDTP7 - Разрешително за пребиваване
  • IDTP8 - Чужд паспорт
  • IDTP9 - Служебен паспорт
  • IDTP10 - Временен паспорт
  • IDTP11 - Паспорт на моряк
НезадължителноpayerIdNumberString [1..100]Номер на предоставения идентифициращ документ (например, паспорт) на изпращача.
НезадължителноpayerBirthdayString [1..20]Дата на раждане на изпращача във формат YYYYMMDD.

Описание на параметрите на обект shippingPayerData:

ЗадължителностНаименованиеТипОписание
НезадължителноshippingCityString [1..50]Град на поръчителя (от адреса за доставка)
НезадължителноshippingCountryString [1..50]Страна на поръчителя
НезадължителноshippingAddressLine1String [1..50]Основен адрес на клиента (от адреса за доставка)
НезадължителноshippingAddressLine2String [1..50]Основен адрес на клиента (от адреса за доставка)
НезадължителноshippingAddressLine3String [1..50]Основен адрес на клиента (от адреса за доставка)
НезадължителноshippingPostalCodeString [1..16]Пощенски код на клиента за доставка
НезадължителноshippingStateString [1..50]Щат/регион на купувача (от адреса за доставка)
НезадължителноshippingMethodIndicatorInteger [2]Индикатор за начин на доставка.
Възможни стойности:
  • 01 - доставка на платежния адрес на притежателя на карта.
  • 02 - доставка на друг адрес, проверен от Търговеца.
  • 03 - доставка на адрес, различен от основния адрес на притежателя на карта.
  • 04 - изпращане в магазин/самовземане (адресът на магазина трябва да бъде указан в съответните параметри за доставка)
  • 05 - Цифрово разпространение (включва онлайн услуги и електронни подаръчни карти)
  • 06 - билети за пътувания и събития, които не могат да бъдат доставени.
  • 07 - Други (например игри, цифрови стоки, които не подлежат на доставка, цифрови абонаменти и т.н.)
НезадължителноdeliveryTimeframeInteger [2]Срок за доставка на стоката.
Възможни стойности:
  • 01 - цифрова дистрибуция
  • 02 - доставка в същия ден
  • 03 - доставка на следващия ден
  • 04 - доставка в рамките на 2 дни след плащането и по-късно.
НезадължителноdeliveryEmail String [1..254]Целеви адрес на електронна поща за доставка на цифрово разпространение. Препоръчително е да предавате електронната поща в самостоятелен параметър на заявката email (но ако я предадете в този блок, към нея ще се прилагат същите правила).

Описание на параметрите на обекта preOrderPayerData:

ЗадължителностНаименованиеТипОписание
НезадължителноpreOrderDateString [10]Очаквана дата на доставка (за предварително поръчани покупки) във формат ГГГГММДД.
НезадължителноpreOrderPurchaseIndInteger [2]Индикатор за разполагане от клиента на поръчка за налична или бъдеща доставка.
Възможни стойности:
  • 01 - възможна е доставка;
  • 02 - бъдеща доставка
НезадължителноreorderItemsIndInteger [2]Индикатор, че клиентът преподръчва преди заплатена доставка в състава на нова поръчка.
Възможни стойности:
  • 01 - поръчката се разполага за първи път;
  • 02 - повторна поръчка

Описание на параметрите на обект orderPayerData.

ЗадължителностНаименованиеТипОписание
НезадължителноhomePhoneString [7..15]Домашен телефон на притежателя на картата. Необходимо е винаги да се посочва код на страната, но знакът + или 00 в началото може да се посочи или пропусне. Номерът трябва да има дължина от 7 до 15 цифри. По този начин са възможни следните стойности:
  • +35799988877;
  • 0035799988877;
  • 35799988877.
НезадължителноworkPhoneString [7..15]Служебен телефон на притежателя на картата. Необходимо е винаги да се посочва код на страната, но знакът + или 00 в началото може да се посочи или пропусне. Номерът трябва да има дължина от 7 до 15 цифри. По този начин са възможни следните стойности:
  • +35799988877;
  • 0035799988877;
  • 35799988877.
НезадължителноmobilePhoneString [7..15]Номер на мобилния телефон на притежателя на картата. Необходимо е винаги да се посочва код на страната, но знакът + или 00 в началото може да се посочи или пропусне. Номерът трябва да има дължина от 7 до 15 цифри. По този начин са възможни следните стойности:
  • +35799988877;
  • 0035799988877;
  • 35799988877.

За плащания по VISA с 3DS авторизация е необходимо да се посочи или електронна поща, или номер на телефон на притежателя на картата. Ако имате настроено показване на номера на телефона на платежната страница и сте посочили неверен номер на телефон, клиентът ще може да го поправи на платежната страница.

Параметри на отговора

ЗадължителностНаименованиеТипОписание
НезадължителноerrorCodeString [1..2]Информационен параметър в случай на грешка, който може да има различни кодови стойности:
  • стойност 0 - указва успех на обработката на заявката;
  • друга числова стойност (1-99) - указва грешка, за получаване на по-подробна информация за която е необходимо да се провери параметър errorMessage.
Може да отсъства, ако резултатът не е предизвикал грешки.
НезадължителноerrorMessageString [1..512]Информационен параметър, който представлява описание на грешката в случай на възникване на грешка. Стойността на errorMessage може да варира, затова не трябва да се препраща изрично към неговите стойности в кода.
Езикът на описанието се задава в параметъра language на заявката.
НезадължителноorderIdString [1..36]Номер на поръчката в платежния шлюз. Уникален в рамките на платежния шлюз.
НезадължителноorderNumberString [1..36]Номер на поръчката (ID) в системата на търговеца; трябва да бъде уникален за всяка поръчка.
НезадължителноauthCodeInteger [6]Остарял параметър (не се използва). Неговата стойност винаги е 2 независимо от статуса на поръчката и кода за оторизация на процесинговата система.
НезадължителноactionCodeStringКод за отговор от банковата обработка. Съдържа числова стойност. Вижте списъка с кодове за отговор тук.
НезадължителноactionCodeDescriptionString [1..512]Описание на actionCode, връщано от процесинга на банката.
НезадължителноtimeIntegerВреме на извършване на транзакцията като брой милисекунди, изминали от 00:00 GMT 1 януари 1970 година (време Unix). Пример: 1740392720718 (съответства на време 24 февруари 2025 година, 10:25:20 (UTC)).
НезадължителноeciInteger [1..4]Електронен търговски индикатор. Посочен само след плащане на поръчката и в случай на наличие на съответното разрешение. По-долу се дава разшифровката на ECI-кодовете.
  • ECI=01 или ECI=06 - търговецът поддържа 3-D Secure, платежната карта не поддържа 3-D Secure, плащането се обработва на базата на код CVV2/CVC.
  • ECI=02 или ECI=05 - и търговецът, и платежната карта поддържат 3-D Secure;
  • ECI=07 - търговецът не поддържа 3-D Secure, плащането се обработва на базата на код CVV2/CVC.
НезадължителноamountInteger [0..12]Сума на плащането в минимални единици валута (например, в стотинки).
НезадължителноcurrencyString [3]Код на валутата на плащането ISO 4217. Ако не е посочен, се използва стойността по подразбиране. Позволени са само цифри.
НезадължителноrrnInteger [1..12]Reference Retrieval Number - идентификатор на транзакцията, присвоен от банката-акуайър.
НезадължителноacsUrlString [1..512]При успешен отговор в случай на плащане 3D-Secure. URL-адрес за пренасочване към ACS. Задължителен, ако е необходимо пренасочване към ACS. За повече информация вижте Пренасочване към ACS.
НезадължителноtermUrlString [1..512]При успешен отговор в случай на плащане 3D-Secure. Това е URL-адрес, към който ACS пренасочва притежателя на картата след удостоверяване. Подробно вж. Пренасочване към ACS.
НезадължителноpaReqString [1..255]PAReq (Payment Authentication Request) — съобщение, което трябва да бъде изпратено в ACS заедно с пренасочването. Връща се при успешен отговор в случай на плащане 3D-Secure, ако е необходимо пренасочване към ACS. Това съобщение съдържа данни в кодировка Base64, необходими за автентификация на притежателя на картата. За повече подробности вижте Пренасочване към ACS.

Примери

Пример за заявка

curl --request POST \
  --url https://uat.dskbank.bg/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": "975"
}

API на повтарящите се плащания

Приведените по-долу API заявки позволяват настройването на задачи за повтарящи се плащания. В последствие плащанията се изпълняват автоматично според зададеното разписание.

Създаване на задача

За създаване на рекурентна задача се използва заявка https://uat.dskbank.bg/recurrent/v1/task/create.


При изпълнение на заявката е необходимо да се използва заглавка: Content-Type: application/json

Параметри на заявката

ЗадължителностНаименованиеТипОписание
НезадължителноlocaleString [2]Ключ на езика по ISO 639-1. Ако езикът не е посочен, се използва езикът по подразбиране, посочен в настройките на магазина.
НезадължителноmerchantLoginString [1..30]За да създадете задача от името на друг търговец, посочете неговия логин (за API-акаунта) в този параметър.
Може да се използва, само ако имате разрешение за преглед на транзакциите на други продавачи или ако посоченият продавач е ваш дъщерен продавач.
ЗадължителноuserNameString [1..50]Потребителско име на API акаунта на продавача.
ЗадължителноpasswordString [1..30]Парола на API акаунта на продавача.
ЗадължителноtaskObjectИнформация за създаваната рекурентна задача. Вж. вложени параметри.

По-долу са изброени параметрите на блока task (данни за създаваната рекурентна задача).

ЗадължителностНаименованиеТипОписание
ЗадължителноamountInteger [0..12]Сума на плащането в минимални единици валута (например, в стотинки).
НезадължителноbindingIdString [1..255]Идентификатор на вече съществуваща връзка (идентификатор на карта, токенизирана от gateway). Може да се използва само ако търговецът има разрешение за работа с връзки.
НезадължителноcardHolderString [1..26]Име на притежателя на картата с латински букви.
НезадължителноclientIdString [0..255]Номер на клиента (ID) в системата на търговеца — до 255 символа. Използва се за реализиране на функционалността на връзките. Може да се връща в отговора, ако на търговеца е разрешено да създава връзки.
Указването на този параметър при обработка на плащания по връзка е задължително. В противен случай плащането ще бъде невъзможно.
ЗадължителноcurrencyString [3]Код на валутата на плащането ISO 4217. Ако не е посочен, се използва стойността по подразбиране. Позволени са само цифри.
НезадължителноexpiryIntegerСрок на валидност на картата в следния формат: YYYYMM.
ЗадължителноmerchantTaskUuidStringУникален идентификатор на задачата в системата на търговеца.
НезадължителноpanString [1..19]Маскиран номер на картата, която е използвана за плащане.
НезадължителноattributesObjectНабор от атрибути на задачата, структура:
{name1:value1,…,nameN:valueN}. Точният набор от атрибути трябва да бъде съгласуван с Банката.
НезадължителноparamsObjectНабор от допълнителни параметри с произволна форма, структура:
{name1:value1,…,nameN:valueN}
ЗадължителноscheduleDataObjectНабор от данни за разписанието на задачата. Вж. вложени параметри.

По-долу са изброени параметрите на блока scheduleData (данни за разписанието на плащанията).

ЗадължителностНаименованиеТипОписание
MandatoryscheduledSinceString [26]Дата и време, когато задачата трябва да започне да се изпълнява. Формат: yyyy-MM-dd'T'HH:mm:ss.SSSZ
MandatoryscheduledTillString [26]Дата и време, до което задачата трябва да завърши. Формат: yyyy-MM-dd'T'HH:mm:ss.SSSZ
MandatorytimeUnitStringЕдиница време. Допустими стойности: Nanos, Micros, Millis, Seconds, Minutes, Hours, HalfDays, Days, Weeks, Months, Years, Decades, Centuries, Millennia, Eras, Forever
MandatoryvalueintegerСтойност на честотата

Параметри на отговора

ЗадължителностНаименованиеТипОписание
ЗадължителноstatusStringСтатус на отговора. Допустими стойности: SUCCESS, FAIL.
ЗадължителноtaskObjectИнформация за създадената рекурентна задача. Вж. вложени параметри.

По-долу са изброени параметрите на блока task (данни за създадената рекурентна задача).

ЗадължителностНаименованиеТипОписание
ЗадължителноcreatedStringДата и час на създаване на задачата.
ЗадължителноmerchantLoginStringLogin на търговеца.
ЗадължителноmerchantTaskUuidStringУникален идентификатор на задачата в системата на търговеца.
ЗадължителноnextPaymentDateStringДата на следващото плащане.
ЗадължителноstateStringСъстояние на задачата. Допустими стойности:
  • CREATED - създадена, но няма плащания
  • ACTIVE - създадена, изпълнено е поне едно плащане
  • FAILED - превишен е броят опити, задачата е деактивирана
  • COMPLETED - достигната е датата EOL, всички плащания са завършени
  • TERMINATED - прекратена или от клиента, или от търговеца
  • EXPIRED - срокът на валидност на картата е изтекъл
ЗадължителноtaskUuidStringУникален идентификатор в службата за рекурентни списвания.

Примери

Пример за заявка

curl --request POST \
--url https://uat.dskbank.bg/recurrent/v1/task/create \
--header 'Content-Type: application/json' \
--data '{
    "username":"test_user",
    "password":"test_user_password",
    "locale":"en",
    "task":{
        "merchantTaskUuid":"c0fdc30e-0ba9-4d14-ac0b-44fe9d4d7c82",
        "clientId":"TestClient",
        "bindingId": "5eb094e1-4a96-7b33-af5f-a29407a73a93",
        "scheduleData": {
            "value":"1",
            "timeUnit":"DAYS",
            "scheduledSince":"2024-01-24T00:00:00.000+0300",
            "scheduledTill":"2024-02-24T00:00:00.000+0300"
        },
        "amount":100,
        "currency":643,
        "params":{
            "description":"desc",
            "phone":"576015555556"
        }
    }
}'

Пример за отговор

{
  "status": "SUCCESS",
  "task": {
    "created": "2024-01-24T10:23:35.434591+03:00",
    "merchantLogin": "testMerch",
    "taskUuid": "8a6a5350-1be3-456e-8e81-e5c7eafbd699",
    "nextPaymentDate": "2024-01-24T00:00:00+03:00",
    "state": "CREATED",
    "merchantTaskUuid": "c0fdc30e-0ba9-4d14-ac0b-44fe9d4d7c82"
  }
}

Промяна на задача

За промяна на съществуваща рекурентна задача се използва заявка https://uat.dskbank.bg/recurrent/v1/task/modify.


При изпълнение на заявката е необходимо да се използва заглавка: Content-Type: application/json

Параметри на заявката

ЗадължителностНаименованиеТипОписание
НезадължителноlocaleString [2]Ключ на език по ISO 639-1. Ако езикът не е указан, се използва езикът по подразбиране, указан в настройките на магазина.
ЗадължителноuserNameString [1..50]Потребителско име на API акаунта на продавача.
ЗадължителноpasswordString [1..30]Парола на API акаунта на продавача.
ЗадължителноtaskObjectИнформация за променяната рекурентна задача. Вж. вложени параметри.

По-долу са изброени параметрите на блока task (данни за променящата се рекурентна задача).

ЗадължителностИмеТипОписание
НезадължителноbindingIdString [1..255]Идентификатор на вече съществуваща връзка (идентификатор на карта, токенизирана от шлюза). Може да се използва само ако търговецът има разрешение за работа с връзки.
НезадължителноcardholderStringИме на притежателя на картата с латински букви.
НезадължителноclientIdString [0..255]Номер на клиента (ID) в системата на търговеца — до 255 символа. Използва се за реализиране на функционалността на връзките. Може да се връща в отговора, ако на търговеца е разрешено да създава връзки.
Указването на този параметър при обработка на плащания по връзка е задължително. В противен случай плащането ще бъде невъзможно.
НезадължителноexpiryString [6]Срок на валидност на картата във формат: YYYYMM.
НезадължителноpanString [1..19]Маскиран номер на картата, използвана за плащането.
НезадължителноattributesObjectНабор от атрибути на задачата, структура:
{name1:value1,…,nameN:valueN}. Точният набор от атрибути трябва да бъде съгласуван с Банката.
НезадължителноparamsObjectНабор от допълнителни параметри с произволна форма, структура:
{name1:value1,…,nameN:valueN}
ЗадължителноtaskIdentifierObjectУникален идентификатор или набор от идентификатори на задачата. Вж. вложени параметри.

По-долу са изброени параметрите на блока taskIdentifier (набор от идентификатори на рекурентната задача).

ЗадължителностНазваниеТипОписание
НезадължителноmerchantLoginStringLogin на търговеца. Трябва да бъде зададен при търсене по merchantTaskUuid.
НезадължителноmerchantTaskUuidStringУникален идентификатор на задачата в системата на търговеца. Задължителен, ако taskUuid не е зададен.
НезадължителноtaskUuidStringУникален идентификатор в службата за рекурентни списвания. Задължителен, ако merchantTaskUuid не е зададен.

Параметри на отговора

ЗадължителностНаименованиеТипОписание
ЗадължителноstatusStringСтатус на отговора. Допустими стойности: SUCCESS, FAIL.
ЗадължителноtaskObjectИнформация за променената рекурентна задача. Вж. вложени параметри.

По-долу са изброени параметрите на блока task (данни за променената рекурентна задача).

ЗадължителностНазваниеТипОписание
ЗадължителноupdatedStringДата и час на последната актуализация на задачата.
ЗадължителноmerchantLoginStringЛогин на търговеца.
ЗадължителноmerchantTaskUuidStringУникален идентификатор на задачата в системата на търговеца.
ЗадължителноtaskUuidStringУникален идентификатор в службата за рекурентни плащания.

Примери

Пример заявка

curl --request POST \
--url https://uat.dskbank.bg/recurrent/v1/task/modify \
--header 'Content-Type: application/json' \
--data '{
    "username":"test_user",
    "password":"test_user_password",
    "task":{
        "taskIdentifier": {
           "taskUuid":"9ae9f36d-0ba3-4686-87c4-a5ec77c562a4"
       },
        "bindingId":"5eb094e1-4a96-7b33-af5f-a29407a73a93",
        "clientId":"TestClient",
        "params":{
            "description":"new description",
            "phone":"+576015555558"
        }
}'

Пример отговор

{
  "status": "SUCCESS",
  "task": {
    "updated": "2024-01-23T14:10:03.730644+03:00",
    "merchantLogin": "testMerch",
    "taskUuid": "9ae9f36d-0ba3-4686-87c4-a5ec77c562a4",
    "merchantTaskUuid": "c0fdc30e-0ba9-4d14-ac0b-44fe9d4d7c80"
  }
}

Получаване на информация за задача

За получаване на информация за рекурентна задача се използва заявка https://uat.dskbank.bg/recurrent/v1/task/get.


При изпълнение на заявката е необходимо да се използва заглавка: Content-Type: application/json

Параметри на заявката

ЗадължителностНаименованиеТипОписание
НезадължителноlocaleString [2]Ключ на езика по ISO 639-1. Ако езикът не е указан, се използва езикът по подразбиране, указан в настройките на магазина.
ЗадължителноuserNameString [1..50]Потребителско име на API акаунта на продавача.
ЗадължителноpasswordString [1..30]Парола на API акаунта на продавача.
ЗадължителноtaskIdentifierObjectУникален идентификатор или набор от идентификатори на рекурентната задача. Вж. вложени параметри.

По-долу са изброени параметрите на блока taskIdentifier (набор от идентификатори на рекурентната задача).

ЗадължителностНазваниеТипОписание
НезадължителноmerchantLoginStringLogin на търговеца. Трябва да бъде зададен при търсене по merchantTaskUuid.
НезадължителноmerchantTaskUuidStringУникален идентификатор на задачата в системата на търговеца. Задължителен, ако taskUuid не е зададен.
НезадължителноtaskUuidStringУникален идентификатор в службата за рекурентни списвания. Задължителен, ако merchantTaskUuid не е зададен.

Параметри на отговора

ЗадължителностНаименованиеТипОписание
ЗадължителноstatusStringСтатус на отговора. Допустими стойности: SUCCESS, FAIL.
ЗадължителноtaskObjectИнформация за рекурентната задача. Вж. вложени параметри.

По-долу са изброени параметрите на блока task (данни за рекурентната задача).

ЗадължителностИмеТипОписание
MandatoryamountInteger [0..12]Сума на плащането в минимални единици валута (например, в стотинки).
OptionalattemptsHistoryArray of objectsВсички опити за плащане в хронологичен ред. Всеки опит за плащане е представен с обект attemptsHistory. Вж. вложени параметри.
OptionalbindingIdString [1..255]Идентификатор на вече съществуваща връзка (идентификатор на карта, токенизирана от шлюза). Може да се използва само ако търговецът има разрешение за работа с връзки.
OptionalcardHolderString [1..26]Име на притежателя на картата с латински букви.
OptionalclientIdString [0..255]Номер на клиента (ID) в системата на търговеца — до 255 символа. Използва се за реализиране на функционалността на връзките. Може да се връща в отговора, ако на търговеца е разрешено да създава връзки.
Указването на този параметър при обработка на плащания по връзка е задължително. В противен случай плащането ще бъде невъзможно.
MandatorycreatedStringДата и час на създаване на задачата.
MandatorycurrencyString [3]Код на валутата на плащането ISO 4217. Ако не е посочен, се използва стойността по подразбиране. Позволени са само цифри.
OptionalexpiryInteger [6]Срок на валидност на картата във формат: YYYYMM.
MandatorylastPaymentDateStringДата на последното плащане.
OptionalmaskedPanStringМаскиран номер на карта.
MandatorymerchantLoginString [1..30]Логин на търговеца.
MandatorymerchantTaskUuidStringУникален идентификатор на задачата в системата на търговеца.
MandatorynextPaymentDateStringДата на следващото плащане.
OptionalparamsObjectНабор от допълнителни параметри с произволна форма, структура:
{name1:value1,…,nameN:valueN}
MandatoryscheduleDataObjectНабор от данни за графика на задачата. Вж. вложени параметри.
MandatorystateStringСъстояние на задачата. Допустими стойности:
  • CREATED - създадена, но няма плащания
  • ACTIVE - създадена, извършено е поне едно плащане
  • FAILED - превишен е броят опити, задачата е деактивирана
  • COMPLETED - достигната е дата EOL, всички плащания са завършени
  • TERMINATED - прекратена или от клиента, или от търговеца
  • EXPIRED - срокът на валидност на картата е изтекъл
MandatorytaskUuidStringУникален идентификатор в службата за рекурентни списвания.
MandatoryupdatedStringДата и час на последното актуализиране на задачата.

По-долу са изброени параметрите на блока scheduleData (данни за разписанието на плащанията).

ЗадължителностНаименованиеТипОписание
MandatoryscheduledSinceString [26]Дата и време, когато задачата трябва да започне да се изпълнява. Формат: yyyy-MM-dd'T'HH:mm:ss.SSSZ
MandatoryscheduledTillString [26]Дата и време, до което задачата трябва да завърши. Формат: yyyy-MM-dd'T'HH:mm:ss.SSSZ
MandatorytimeUnitStringЕдиница време. Допустими стойности: Nanos, Micros, Millis, Seconds, Minutes, Hours, HalfDays, Days, Weeks, Months, Years, Decades, Centuries, Millennia, Eras, Forever
MandatoryvalueintegerСтойност на честотата

По-долу са изброени параметрите на блока attemptsHistory (данни за честотата на изпълнение на задачата).

ЗадължителностНаименованиеТипОписание
ЗадължителноexecutedStringДата и време на опит за плащане. Формат: yyyy-MM-dd'T'HH:mm:ss.SSSZ
НезадължителноorderIdStringУникален идентификатор на транзакцията в платежния gateway
НезадължителноorderNumberStringНомер на поръчката в платежния gateway
ЗадължителноpaymentAttemptUuidStringУникален идентификатор на опита за плащане
ЗадължителноpaymentUuidStringУникален идентификатор на плащането
ЗадължителноstateStringСъстояние на задачата. Допустими стойности:
  • CREATED - създадена, но няма плащания
  • ACTIVE - създадена, изпълнено е поне едно плащане
  • FAILED - превишен е броят на опитите, задачата е деактивирана
  • COMPLETED - достигната е датата EOL, всички плащания са завършени
  • TERMINATED - прекратена е или от клиента, или от търговеца
  • EXPIRED - срокът на валидност на картата е изтекъл
ЗадължителноtechnicalAttemptBooleanФлаг, указващ дали опитът е бил технически

Примери

Пример на заявка

curl --request POST \
--url https://uat.dskbank.bg/recurrent/v1/task/get \
--header 'Content-Type: application/json' \
--data '{
    "username":"test_user",
    "password":"test_user_password",
    "taskIdentifier": {
           "taskUuid":"8a6a5350-1be3-456e-8e81-e5c7eafbd699"
     }
}'

Пример на отговор

{
  "status": "SUCCESS",
  "task": {
    "taskUuid": "8a6a5350-1be3-456e-8e81-e5c7eafbd699",
    "state": "ACTIVE",
    "merchantLogin": "testMerch",
    "bindingId": "5eb094e1-4a96-7b33-af5f-a29407a73a93",
    "clientId": "TestClient",
    "created": "2024-01-24T10:23:35.434591+03:00",
    "updated": "2024-01-24T10:23:35.434591+03:00",
    "lastPaymentDate": "2024-01-24T00:00:00+03:00",
    "nextPaymentDate": "2024-01-25T00:00:00+03:00",
    "scheduleData": {
      "scheduledSince": "2024-01-24T00:00:00.000+0300",
      "scheduledTill": "2024-02-24T00:00:00.000+0300",
      "value": 1,
      "timeUnit": "DAYS"
    },
    "amount": 100,
    "currency": 643,
    "params": {
      "phone": "576015555556",
      "description": "description"
    },
    "attemptsHistory": [
      {
        "paymentAttemptUuid": "6873d7dc-4366-45c5-9de6-bc6e0aa05b3d",
        "paymentUuid": "1a450005-ad46-4474-8940-eb154822296c",
        "state": "SUCCEEDED",
        "executed": "2024-01-24T10:23:41.788436+03:00",
        "technicalAttempt": false,
        "orderId": "d2d56b04-124b-77ab-9034-9f2307a73a93",
        "orderNumber": "E5DFEDE990694FCFB5246AEC2612A355"
      }
    ],
    "merchantTaskUuid": "c0fdc30e-0ba9-4d14-ac0b-44fe9d4d7c82"
  }
}

Спиране изпълнението на задачата

За спиране изпълнението на рекурентна задача се използва заявка https://uat.dskbank.bg/recurrent/v1/task/terminate.


При изпълнение на заявката е необходимо да се използва заглавка: Content-Type: application/json

Параметри на заявката

ЗадължителностНаименованиеТипОписание
НезадължителноlocaleString [2]Ключ на езика по ISO 639-1. Ако езикът не е указан, се използва езикът по подразбиране, указан в настройките на магазина.
ЗадължителноuserNameString [1..50]Потребителско име на API акаунта на продавача.
ЗадължителноpasswordString [1..30]Парола на API акаунта на продавача.
ЗадължителноtaskIdentifierObjectУникален идентификатор или набор от идентификатори на рекурентната задача. Вж. вложени параметри.

По-долу са изброени параметрите на блока taskIdentifier (набор от идентификатори на рекурентната задача).

ЗадължителностНазваниеТипОписание
НезадължителноmerchantLoginStringLogin на търговеца. Трябва да бъде зададен при търсене по merchantTaskUuid.
НезадължителноmerchantTaskUuidStringУникален идентификатор на задачата в системата на търговеца. Задължителен, ако taskUuid не е зададен.
НезадължителноtaskUuidStringУникален идентификатор в службата за рекурентни списвания. Задължителен, ако merchantTaskUuid не е зададен.

Параметри на отговора

ЗадължителностНаименованиеТипОписание
ЗадължителноstatusStringСтатус на отговора. Допустими стойности: SUCCESS, FAIL.
ЗадължителноtaskObjectИнформация за рекурентната задача. Вж. вложени параметри.

По-долу са изброени параметрите на блока task (данни за прекратяваната задача).

ЗадължителностНаименованиеТипОписание
ЗадължителноupdatedStringДата и час на последната актуализация на задачата.
ЗадължителноmerchantLoginStringLogin на търговеца.
ЗадължителноmerchantTaskUuidStringУникален идентификатор на задачата в системата на търговеца.
ЗадължителноtaskUuidStringУникален идентификатор в службата за рекурентни събирания.
ЗадължителноstateStringСъстояние на задачата. Допустими стойности:
  • CREATED - създадена, но няма плащания
  • ACTIVE - създадена, извършено е поне едно плащане
  • FAILED - превишен е броят опити, задачата е деактивирана
  • COMPLETED - достигната е датата EOL, всички плащания са завършени
  • TERMINATED - прекратена или от клиента, или от търговеца
  • EXPIRED - срокът на валидност на картата е изтекъл

Примери

Пример заявка

curl --request POST \
--url https://uat.dskbank.bg/recurrent/v1/task/terminate \
--header 'Content-Type: application/json' \
--data '{
    "username":"test_user",
    "password":"test_user_password",
    "taskIdentifier": {
        "merchantTaskUuid": "c0fdc30e-0ba9-4d14-ac0b-44fe9d4d7c82",
        "merchantLogin": "testMerch"
    }
}'

Пример отговор

{
  "status": "SUCCESS",
  "task": {
    "updated": "2024-01-24T10:23:35.434591+03:00",
    "merchantLogin": "testMerch",
    "taskUuid": "8a6a5350-1be3-456e-8e81-e5c7eafbd699",
    "state": "TERMINATED",
    "merchantTaskUuid": "c0fdc30e-0ba9-4d14-ac0b-44fe9d4d7c82"
  }

Активиране на задача

За активиране на рекурентна задача се използва заявка https://uat.dskbank.bg/recurrent/v1/task/activate.


При изпълнение на заявката е необходимо да се използва заглавка: Content-Type: application/json

Параметри на заявката

ЗадължителностНаименованиеТипОписание
НезадължителноlocaleString [2]Ключ на езика по ISO 639-1. Ако езикът не е посочен, се използва езикът по подразбиране, посочен в настройките на магазина.
ЗадължителноuserNameString [1..50]Потребителско име на API акаунта на продавача.
ЗадължителноpasswordString [1..30]Парола на API акаунта на продавача.
ЗадължителноtaskIdentifierObjectУникален идентификатор или набор от идентификатори на рекурентната задача. Вж. вложени параметри.

По-долу са изброени параметрите на блока taskIdentifier (набор от идентификатори на рекурентната задача).

ЗадължителностНазваниеТипОписание
НезадължителноmerchantLoginStringLogin на търговеца. Трябва да бъде зададен при търсене по merchantTaskUuid.
НезадължителноmerchantTaskUuidStringУникален идентификатор на задачата в системата на търговеца. Задължителен, ако taskUuid не е зададен.
НезадължителноtaskUuidStringУникален идентификатор в службата за рекурентни списвания. Задължителен, ако merchantTaskUuid не е зададен.

Параметри на отговора

ЗадължителностНаименованиеТипОписание
ЗадължителноstatusStringСтатус на отговора. Допустими стойности: SUCCESS, FAIL.
ЗадължителноtaskObjectИнформация за рекурентната задача. Вж. вложени параметри.

По-долу са изброени параметрите на блока task (данни за активираната задача).

ЗадължителностИмеТипОписание
ЗадължителноupdatedStringДата и час на последната актуализация на задачата.
ЗадължителноmerchantLoginStringLogin на търговеца.
ЗадължителноmerchantTaskUuidStringУникален идентификатор на задачата в системата на търговеца.
ЗадължителноnextPaymentDateStringДата на следващото плащане.
ЗадължителноtaskUuidStringУникален идентификатор в службата за рекурентни списвания.
ЗадължителноstateStringСъстояние на задачата. Допустими стойности:
  • CREATED - създадена, но няма плащания
  • ACTIVE - създадена, извършено е поне едно плащане
  • FAILED - превишен е броят опити, задачата е деактивирана
  • COMPLETED - достигната е датата EOL, всички плащания са завършени
  • TERMINATED - прекратена е от клиента или от търговеца
  • EXPIRED - срокът на валидност на картата е изтекъл

Примери

Пример на заявка

curl --request POST \
--url https://uat.dskbank.bg/recurrent/v1/task/activate \
--header 'Content-Type: application/json' \
--data '{
    "username":"test_user",
    "password":"test_user_password",
    "taskIdentifier": {
        "merchantTaskUuid": "c0fdc30e-0ba9-4d14-ac0b-44fe9d4d7c82",
        "merchantLogin": "testMerch"
    }
}'

Пример на отговор

{
  "status": "SUCCESS",
  "task": {
    "updated": "2024-01-24T10:23:35.434591+03:00",
    "merchantLogin": "testMerch",
    "taskUuid": "8a6a5350-1be3-456e-8e81-e5c7eafbd699",
    "state": "ACTIVE",
    "nextPaymentDate": "2024-01-25T00:00:00+03:00",
    "merchantTaskUuid": "c0fdc30e-0ba9-4d14-ac0b-44fe9d4d7c82"
  }
}

Прекратяване на изпълнението на задачи

За прекратяване на изпълнението на няколко рекурентни задачи се използва заявка https://uat.dskbank.bg/recurrent/v1/task/batchTerminate.


При изпълнение на заявката е необходимо да се използва заглавие: Content-Type: application/json

Параметри на заявката

ЗадължителностНаименованиеТипОписание
НезадължителноlocaleString [2]Ключ на езика по ISO 639-1. Ако езикът не е посочен, се използва езикът по подразбиране, посочен в настройките на магазина.
ЗадължителноuserNameString [1..50]Потребителско име на API акаунта на продавача.
ЗадължителноpasswordString [1..30]Парола на API акаунта на продавача.
ЗадължителноtaskIdentifiersArray of ObjectsИдентификатори на прекратяваните задачи. Всеки идентификатор е представен с обект taskIdentifier. Вж. вложени параметри.

По-долу са изброени параметрите на блока taskIdentifier (набор от идентификатори на рекурентната задача).

ЗадължителностНазваниеТипОписание
НезадължителноmerchantLoginStringLogin на търговеца. Трябва да бъде зададен при търсене по merchantTaskUuid.
НезадължителноmerchantTaskUuidStringУникален идентификатор на задачата в системата на търговеца. Задължителен, ако taskUuid не е зададен.
НезадължителноtaskUuidStringУникален идентификатор в службата за рекурентни списвания. Задължителен, ако merchantTaskUuid не е зададен.

Параметри на отговора

ЗадължителностНаименованиеТипОписание
ЗадължителноstatusStringСтатус на отговора. Допустими стойности: SUCCESS, FAIL.

Примери

Ример за заявка

curl --request POST \
--url https://uat.dskbank.bg/recurrent/v1/task/batchTerminate \
--header 'Content-Type: application/json' \
--data '{
    "locale":"EN",
    "username":"testUser",
    "password":"testPwd",
    "tasksIdentifiers":[
        {
            "taskUuid":"0ba73819-65f8-43c4-9dc4-3870cb10416b"
        },
        {
            "taskUuid":"0ba73820-65f8-43c4-9dc4-3870cb10416b"
        }
    ]
}'

Ример за отговор

{
  "status": "SUCCESS"
}

Пропускане на плащане

За да пропуснете конкретно плащане от рекурентна задача, се използва заявка https://uat.dskbank.bg/recurrent/v1/payment/skip.


При изпълнение на заявката е необходимо да използвате заглавка: Content-Type: application/json

Параметри на заявката

ЗадължителностНаименованиеТипОписание
НезадължителноlocaleString [2]Ключ на език по ISO 639-1. Ако езикът не е посочен, се използва езикът по подразбиране, посочен в настройките на магазина.
ЗадължителноuserNameString [1..50]Потребителско име на API акаунта на продавача.
ЗадължителноpasswordString [1..30]Парола на API акаунта на продавача.
ЗадължителноtaskIdentifierObjectУникален идентификатор или набор от идентификатори на рекурентна задача. Вж. вложени параметри.
ЗадължителноpaymentNumberIntegerНомер на рекурентното плащане, което трябва да бъде пропуснато.

По-долу са изброени параметрите на блока taskIdentifier (набор от идентификатори на рекурентната задача).

ЗадължителностНазваниеТипОписание
НезадължителноmerchantLoginStringLogin на търговеца. Трябва да бъде зададен при търсене по merchantTaskUuid.
НезадължителноmerchantTaskUuidStringУникален идентификатор на задачата в системата на търговеца. Задължителен, ако taskUuid не е зададен.
НезадължителноtaskUuidStringУникален идентификатор в службата за рекурентни списвания. Задължителен, ако merchantTaskUuid не е зададен.

Параметри на отговора

ЗадължителностНаименованиеТипОписание
ЗадължителноstatusStringСтатус на отговора. Допустими стойности: SUCCESS, FAIL.
ЗадължителноtaskObjectИнформация за рекурентната задача. Вж. вложени параметри.

По-долу са изброени параметрите на блока task (данни за активираната задача).

ЗадължителностИмеТипОписание
ЗадължителноupdatedStringДата и час на последната актуализация на задачата.
ЗадължителноmerchantLoginStringLogin на търговеца.
ЗадължителноmerchantTaskUuidStringУникален идентификатор на задачата в системата на търговеца.
ЗадължителноnextPaymentDateStringДата на следващото плащане.
ЗадължителноtaskUuidStringУникален идентификатор в службата за рекурентни списвания.
ЗадължителноstateStringСъстояние на задачата. Допустими стойности:
  • CREATED - създадена, но няма плащания
  • ACTIVE - създадена, извършено е поне едно плащане
  • FAILED - превишен е броят опити, задачата е деактивирана
  • COMPLETED - достигната е датата EOL, всички плащания са завършени
  • TERMINATED - прекратена е от клиента или от търговеца
  • EXPIRED - срокът на валидност на картата е изтекъл

Примери

Пример за заявка

curl --request POST \
--url https://uat.dskbank.bg/recurrent/v1/payment/skip \
--header 'Content-Type: application/json' \
--data '{
    "locale":"EN",
    "username":"test_user",
    "password":"test_user_password",
    "taskIdentifier": {
           "taskUuid":"7ae881fb-aee0-4446-883c-8087512bd26a"
     },
    "paymentNumber": 2
}'

Пример за отговор

{
  "status": "SUCCESS",
  "task": {
    "updated": "2024-01-24T10:23:35.434591+03:00",
    "merchantLogin": "testMerch",
    "taskUuid": "8a6a5350-1be3-456e-8e81-e5c7eafbd699",
    "state": "ACTIVE",
    "nextPaymentDate": "2024-01-25T00:00:00+03:00",
    "merchantTaskUuid": "c0fdc30e-0ba9-4d14-ac0b-44fe9d4d7c82"
  }
}

Известия за обратно повикване

API на платежния шлюз позволява получаване на известия за обратно повикване (callback-известия) за промяна на статусите на плащанията.

Обща информация

Събития, за които могат да пристигат известия

Можете да получавате известия за промяна на статуса на плащането на поръчката и за други събития в платежния шлюз.

Най-разпространените известия описват промените на статуса на поръчката, например:

По-сложните интеграции могат да предполагат допълнителни тригери за обратно повикване, като:

Типът тригер се предава в параметъра operation на известието за обратно повикване (вж. подробности по-долу). За удобство известията за допълнителни тригери могат да бъдат насочени към друг URL-адрес с помощта на параметъра dynamicCallbackUrl в заявките за регистрация на поръчка.

Интеграция чрез известия за обратно повикване (callback)

Вместо последната стъпка интеграция чрез пренасочване можете да изберете един от следните подходи.

Използване на returnUrl

Когато кодът на вашия сайт, разположен на адрес returnUrl (например, https://mybestmerchantreturnurl.com/?back&amp;orderId=61c33664-85a0-7d6b-af26-09ee009c4000&amp;lang=en), идентифицира пренасочвания от шлюза притежател на карта след опит за плащане, можете да проверите статуса на поръчката чрез API-заявка getOrderStatusExtended.
Този вариант е най-простият, но не е напълно надежден, тъй като пренасочването на притежателя на карта може да завърши с грешка (например в резултат от прекъсване на връзката или затваряне на браузъра от притежателя на карта), а returnUrl може да не получи тригер за извикване на getOrderStatusExtended.

getOrderStatusExtended.do

curl --request POST \
  --url https://uat.dskbank.bg/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": "975",
  "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": "&ltUnknown&gt"
  }
}

Използване на подписан 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Тип събитие, предизвикало известието:
  • approved - холдиране (задържане) на средства по сметката на купувача;
  • deposited - операция завършване;
  • reversed - плащането е отменено;
  • refunded - парите за поръчката са върнати;
  • bindingCreated - картата на платеца е запазена (съхранени платежни данни са създадени);
  • bindingActivityChanged - съществуващи съхранени платежни данни са били изключени/включени.
  • declinedByTimeout - плащането е отхвърлено поради изтичане на времето за изчакване;
  • ``declinedCardPresent`` - отхвърлена транзакция с представяне на карта (плащане с физическа карта).
statusИндикатор за успешност на операцията, указана в параметъра operation:
  • 1 - успех;
  • 0 - грешка.

Потребителски заглавия на 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

Алгоритъм за обработка на известия за състоянието на поръчките

В разделите по-долу е представен алгоритъмът за обработка на известия за състоянието на поръчките в зависимост от типа на такива известия.

Известие без контролна сума

  1. Платежният шлюз изпраща на сървъра на продавача следната заявка.
    https://mybestmerchantreturnurl.com/callback/?mdOrder=1234567890-098776-234-522&amp;orderNumber=0987&amp;operation=deposited&amp;status=0
  2. Сървърът на продавача връща HTTP съобщение 200 OK на платежния шлюз.

Известие с контролна сума

  1. Платежният шлюз изпраща HTTPS заявка от следния вид към сървъра на търговеца, като при това:

    • при използване на симетрична криптография контролната сума се формира с помощта на ключ, общ за платежния шлюз и продавача;
    • при използване на асиметрична криптография контролната сума се формира с помощта на частен ключ, известен само на платежния шлюз.
      https://mybestmerchantreturnurl.com/path?amount=123456&amp;orderNumber=10747&amp;checksum=DBBE9E54D42072D8CAF32C7F660DEB82086A25C14FD813888E231A99E1220AB3&amp;mdOrder=3ff6962a-7dcc-4283-ab50-a6d7dd3386fe&amp;operation=deposited&amp;status=1
      Редът на параметрите в известието може да бъде произволен.
  2. От страна на продавача от низа на параметрите на известието се премахват параметрите checksum и sign_alias, а стойността на параметъра checksum (контролна сума) се запазва за проверка на автентичността на известието;

  3. Останалите параметри и техните стойности се използват за създаване на следния низ.
    име_на_параметър1;стойност_на_параметър1;име_на_параметър2;стойност_на_параметър2;…;име_на_параметърN;стойност_на_параметърN;
    В този случай двойките име_на_параметър;стойност_на_параметър трябва да бъдат сортирани в прав азбучен ред (във възходящ ред) по имената на параметрите.
    Пример на генериран низ от параметри:
    amount;123456;mdOrder;3ff6962a-7dcc-4283-ab50-a6d7dd3386fe;operation;deposited;orderNumber;10747;status;1;

  4. Контролната сума се изчислява от страна на търговеца, начинът на изчисляване зависи от начина на нейното формиране:

    • при използване на симетрична криптография - с помощта на алгоритъма HMAC-SHA256 и общия с платежния шлюз частен ключ;
    • при използване на асиметрична криптография - с помощта на алгоритъма за хеширане, който зависи от начина на създаване на ключовата двойка, и публичния ключ, който е свързан с частния ключ, намиращ се от страна на платежния шлюз.
  5. В получения низ от контролната сума всички малки букви се заменят с главни букви.

  6. Прави се сравнение на получената стойност с контролната сума, извлечена по-рано от параметъра checksum.

  7. Ако контролните суми съвпадат, сървърът изпраща в платежния шлюз HTTP код 200 OK.

Ако контролните суми съвпадат, това известие е автентично и е било изпратено от платежния шлюз. В противен случай е вероятно, че злонамерено лице се опитва да представи своето известие като известие на платежния шлюз.

Известие за статуса на плащането

За да определите дали плащането е преминало успешно или не, трябва да:

  1. Проверите подписа (параметър checksum в известието);
  2. Проверявате два параметъра на известието за обратно извикване: operation и status.

Ако стойността на параметъра operation се различава от approved или deposited, то известието за обратно извикване се отнася до статуса на плащането.

Неуспешни известия

Ако в платежния шлюз се върне отговор, различен от HTTP код 200 OK, изпращането на известието се счита за неуспешно. В този случай платежният шлюз повтаря известието с интервал от 30 секунди докато не бъде изпълнено едно от следните условия:

При достигане на едно от посочените по-горе условия опитите за изпращане на callback известия за операцията се прекратяват.

Допълнителни параметри за известията за обратно повикване

В известията за обратно повикване можете да използвате следните допълнителни параметри, ако са настроени в платежната шлюз. Ако искате даги използвате, свържете се с нашата служба за поддръжка.

ПараметърОписаниеТип събитие
bindingIdUUIID на създадените/обновените запазени удостоверения за самоличност (връзки).BINDING_CREATED, BINDING_ACTIVITY_CHANGED
emailЕлектронна поща на клиента.BINDING_CREATED
phoneТелефон на клиента.BINDING_CREATED
panMaskedМаскиран PAN на картата на клиента.BINDING_CREATED
panCountryCodeКод на страната на клиента.BINDING_CREATED
enabledАктивна ли е връзката (true/false).BINDING_ACTIVITY_CHANGED
currentDepositAmountFormattedФорматирана сума на операцията завършване.DEPOSITED
currentReverseAmountFormattedФорматирана сума на операцията отмяна.REVERSED
currentRefundAmountFormattedФорматирана сума на операцията възстановяване.REFUNDED
operationRefundedAmountFormattedФорматирана сума на операцията възстановяване.REFUNDED
operationRefundedAmountСума на възстановяването в минимални парични единици (например в центове).REFUNDED
externalRefundIdВъншен идентификатор на операцията възстановяване.REFUNDED
callbackCreationDateДата на създаване на известието за обратно повикване. Изисква се специална настройка на продавача.DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, BINDING_CREATED, BINDING_ACTIVITY_CHANGED, DECLINED_CARDPRESENT
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
finishCheckUrlURL за генериране на разписка 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Флаг, указващ тип операция.
  • 1 - покупка
  • 2 - предавторизация
DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
eciЕлектронен търговски индикатор. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
ipIP адрес на платеца. 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
paymentRefNumReference 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
refNumReference Retrieval Number - идентификатор на транзакцията, присвоен от банката-еквайър. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
refnumReference 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. Възможни стойности:
  • A - Превод от карта към карта на един собственик (от сметка към сметка)
  • B - Превод с цел придобиване на криптовалута
  • C - Превод за цели покупка на криптовалута
  • D - Изплащане на средства
  • ``E`` - Превод на пари без смяна на собственика на парите
  • F - Превод за залагания при хазартни игри
  • G - Изплащане в хазартни игри онлайн
  • L - Превод за цели погасяване на сметки по кредитна карта
  • O - Превод за цели плащане на задълженост
  • P - Превод от карта към карта на различни собственици
  • W - Превод към собствена сметка на етапен цифров портфейл за плащане
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
p2pDebitRrnRRN (Reference Retrieval Number) на операцията дебитиране P2P.DEPOSITED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT
aResTransStatusСъстояние на транзакцията от отговора на ACS на заявката за автентикация (ARes). Предава се при използване на 3DS2. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
aResTransStatusReasonПричина за статуса на транзакцията в ARes съобщението. Предава се при използване на 3DS2. Параметърът предоставя допълнителна информация за причината за конкретния статус на автентикацията. Приема стойности от 2 цифри, например, 01, 02. Вж. пълния списък със стойности по-долу. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
rreqTransStatusСтатус на транзакцията от заявката за предаване на резултатите от автентикацията на потребителя от ACS (RReq). Предава се при използване на 3DS2. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
rReqTransStatusReasonПричина за статуса на транзакцията в RReq съобщението. Предава се при използване на 3DS2. Параметърът предоставя допълнителна информация за причината за конкретния резултат от автентикацията на притежателя на картата. Приема стойности от 2 цифри, например, 01, 02. Вж. пълния списък със стойности по-долу. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
threeDSProtocolVersionВерсия на протокола 3DS. Възможни стойности: "2.1.0", "2.2.0" за 3DS2.
Ако в заявката не се предава threeDSProtocolVersion, то за авторизация 3D Secure ще се използва стойността по подразбиране (2.1.0 - за 3DS 2).
DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
rReqChallengeCancelИндикатор за отмяна на процеса Challenge в RReq съобщението. Предава се при използване на 3DS2. Параметърът показва кой е инициирал отмяната на автентикацията: притежателят на картата, търговецът или издателят. Приема стойности от 2 цифри, например, 01, 03. Вж. пълния списък със стойности по-долу. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
cvvResultCodeКод на резултата от проверката на CVV (Card Verification Value), който се връща в отговора на заявката за авторизация на плащането. Допустими стойности:
  • M - CVV съвпада;
  • N - CVV не съвпада;
  • P - Не е обработен;
  • S - CVV не трябва да присъства на картата;
  • U - Издателят не е сертифициран / не участва в проверката;
  • X - Няма отговор от мрежата.
DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
avsCodeКод на отговор на верификацията AVS (проверка на адреса и пощенския код на картодържателя). Възможни стойности:
  • -1 – пощенският код и адресът съвпадат.
  • 1 – адресът съвпада, пощенският код не съвпада.
  • 2 - пощенският код съвпада, адресът не съвпада.
  • 3 - пощенският код и адресът не съвпадат.
  • 50 - заявена е проверка на данните, но резултатът е неуспешен.
  • 51 - некоректен формат на заявката за AVS/AVV проверка.
DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT

Допустими стойности aResTransStatusReason и rreqTransStatusReason:

Допустими стойности rreqChallengeCancel:

Примери за код

Симетрична криптография

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("резултат от проверката на подписа: " + 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("резултат от проверката на подписа: " + 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]
";
?>
  1. Присвоете низова стойност на променливата data.
  2. Присвоете стойността на частния ключ на променливата key.
  3. Функцията hash_hmac ( 'sha256', $data, $key) изчислява контролна сума от подадения низ, с помощта на частния ключ по алгоритъма SHA-256.
  4. Запазете резултата от работата на функцията в променливата hmac.
  5. Изведете резултата от работата на функцията с командата echo.
  6. Сравнете тази стойност с тази, която е подадена в известието за състоянието на поръчката.

Асиметрична криптография

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
";
} elseif ($isVerify == 0) {
    echo "bad (there's something wrong)
";
} else {
    echo "error checking signature
";
}
?>
Categories:
eCommerceAPI V1
Beta
Categories
Search results