/

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

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

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

Изтегли колекция Postman

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

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

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

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

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

Задължителност Название Тип Описание
Условие

userName String [1..30] Логин на потребителския акаунт API на продавача. Ако за автентификация при регистрация вместо логин и парола се използва открит токен (параметър token), паролата не трябва да се предава.
Условие

password String [1..30] Парола на API акаунта на продавача. Ако за удостоверяване при регистрация вместо логин и парола се използва открит токен (параметър token), паролата не е необходимо да се предава.
Задължителност Название Тип Описание
Условие

token String [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 на тялото на заявката по следния начин:

    1. Използвайте тялото на заявката под формата на низ (в нашия пример това е amount=10000&password=gcjgcW1&returnUrl=http&userName=signature-api).
    2. Изчислете хеш SHA256 от този низ в необработени байтове.
    3. Преобразувайте необработените байтове в кодиране base64.

  2. Генерирайте подпис за изчисления хеш 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-----

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

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

Започнете работа с API Sandbox като създадете акаунт или влезете в системата.

 

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


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

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

Задължителност Наименование Тип Описание
Условие

userName String [1..30] Логин на потребителския акаунт API на продавача. Ако за автентификация при регистрация вместо логин и парола се използва открит токен (параметър token), паролата не трябва да се предава.
Условие

password String [1..30] Парола на API акаунта на продавача. Ако за удостоверяване при регистрация вместо логин и парола се използва открит токен (параметър token), паролата не е необходимо да се предава.
Условие

token String [1..256] Стойност, използвана за автентификация на продавача при изпращане на заявки към платежната шлюз. Ако предавате този параметър, то не предавайте userName и password.
Задължително

orderNumber String [1..36] Номер на поръчката (ID) в системата на търговеца; трябва да бъде уникален за всяка поръчка.
Задължително

amount Integer [0..12] Сума на плащането в минимални единици валута (например, в стотинки).
Задължително

currency String [3] Код на валутата на плащането ISO 4217. Ако не е посочен, се използва стойността по подразбиране. Позволени са само цифри.
Задължително

returnUrl String [1..512] Адрес, към който трябва да бъде пренасочен потребителят в случай на успешно плащане. Адресът трябва да бъде указан изцяло, включително използвания протокол (например, https://mybestmerchantreturnurl.com вместо mybestmerchantreturnurl.com). В противен случай потребителят ще бъде пренасочен на адрес от следния вид: https://uat.dskbank.bg/payment/<merchant_address>.
Незадължително

failUrl String [1..512] Адрес, на който трябва да се пренасочи потребителят в случай на неуспешно плащане. Адресът трябва да бъде посочен напълно, включително използвания протокол (например, https://mybestmerchantreturnurl.com вместо mybestmerchantreturnurl.com). В противен случай потребителят ще бъде пренасочен по адрес от следния вид: https://uat.dskbank.bg/payment/<merchant_address>.
Незадължително

dynamicCallbackUrl String [1..512] Параметър за предаване на динамичен адрес за получаване на "платежни" callback-уведомления за поръчката, активирани за търговеца (успешна авторизация, успешно списване, връщане, отказ, отхвърляне на плащане по таймаут, отхвърляне на card present плащане).
"Не платежни" callback-уведомления (включване/изключване на връзка, създаване на връзка), ще бъдат изпращани на статичен callback адрес.
Незадължително

description String [1..598] Описание на поръчката в произволен формат.
За да включите изпращането на това поле в процесинговата система, обърнете се към службата за техническа поддръжка.
В това поле е недопустимо да се предават лични данни или платежни данни (номера на карти и т.н.). Това изискване се дължи на факта, че описанието на поръчката никъде не се маскира.
Незадължително

language String [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.
Незадължително

ip String [1..39] IP адрес на платеца. IPv6 се поддържа във всички заявки (до 39 символа).
Незадължително

clientId String [0..255] Номер на клиента (ID) в системата на търговеца — до 255 символа. Използва се за реализиране на функционалността на връзките. Може да се връща в отговора, ако на търговеца е разрешено да създава връзки.
Указването на този параметър при обработка на плащания по връзка е задължително. В противен случай плащането ще бъде невъзможно.
Незадължително

merchantLogin String [1..255] За да регистрирате поръчка от името на друг търговец, посочете неговия логин (за API-акаунт) в този параметър.
Може да се използва само ако имате разрешение за преглед на транзакциите на други продавачи или ако посоченият продавач е ваш дъщерен продавач.
Незадължително

cardholderName String [1..150] Име на притежателя на картата с латински букви. При предаване на този параметър името на притежателя на картата ще бъде показано на страницата за плащане.
Незадължително

jsonParams Object Набор от допълнителни атрибути с произволна форма, структура:
jsonParams={"param_1_name":"param_1_value",...,"param_n_name":"param_n_value"}
Могат да бъдат предадени в Процесинговия Център, за последваща обработка (изисква се допълнителна настройка - обърнете се към поддръжката).
Някои предефинирани атрибути jsonParams:
  • backToShopUrl - добавя на страницата за плащане бутон, който ще върне държателя на картата на URL-адреса предаден в този параметър
  • backToShopName - настройва текстовия етикет на бутона Връщане към магазина по подразбиране, ако се използва заедно с backToShopUrl
  • installments - максимален брой разрешени авторизации за плащания на вноски. Изисква се за създаване на връзка за вноски
  • totalInstallmentAmount - крайна сума на всички плащания на вноски. Стойността е необходима за запазване на платежните данни за провеждане на вноски
  • recurringFrequency - минимален брой дни между авторизациите. Изисква се за създаване на рекурентна връзка, препоръчва се за създаване на връзка за вноски (ако се използва 3DS2, параметърът е задължителен).
  • recurringExpiry - дата, след която авторизациите не са разрешени, във формат ГГГГММДД. Изисква се за създаване на рекурентна връзка, препоръчва се за създаване на връзка за вноски (ако се използва 3DS2, параметърът е задължителен).
Незадължително

sessionTimeoutSecs Integer [1..9] Продължителност на живота на поръчката в секунди. В случай че параметърът не е зададен, ще бъде използвана стойността, указана в настройките на търговеца, или времето по подразбиране (1200 секунди = 20 минути). Ако в заявката присъства параметър expirationDate, то стойността на параметър sessionTimeoutSecs не се взема предвид.
Незадължително

expirationDate String [19] Дата и час на изтичане на срока на валидност на поръчката. Формат: yyyy-MM-ddTHH:mm:ss.
Ако този параметър не се предава в заявката, то за определяне на времето на изтичане на срока на валидност на поръчката се използва параметърът sessionTimeoutSecs.
Незадължително

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

features String Функции на поръчката. За да посочите няколко функции, използвайте този параметър няколко пъти в една заявка. По-долу са изброени възможните стойности.
  • 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, тогава поръчката ще бъде създадена САМО за създаване на връзка (без плащане).
Незадължително

postAddress String [1..255] Адрес за доставка.
Незадължително

orderBundle Object Обект, съдържащ кошницата с продукти. Описанието на вложените елементи е дадено по-долу.
Незадължително

feeInput Integer [0..8] Размер на комисионната в минимални единици валута. Функционалността трябва да бъде включена на ниво продавач в gateway-я.
Условие

email String [1..40] Електронна поща за показване на платежната страница. Ако за продавача са настроени известия на клиента, електронната поща трябва да бъде посочена. Пример: client_mail@email.com.
Адресът на електронната поща не се проверява при регистрация, той ще бъде проверен по-късно при плащане.
Незадължително

mcc Integer [4] Merchant Category Code (код на категория на търговеца). За предаване на този параметър е необходимо специално разрешение. Могат да се използват стойности само от разрешения списък MCC. За получаване на по-подробна информация се обърнете към техническата поддръжка.
Незадължително billingPayerData Object Блок с регистрационни данни на клиента (адрес, пощенски код), необходим за преминаване на проверка на адреса в рамките на услугите AVS/AVV. Задължително, ако функцията е включена за продавача от страната на Платежната шлюза. Виж вложени параметри.
Незадължително shippingPayerData Object Обект, съдържащ данни за доставка на клиента. Този параметър се използва за по-нататъшна 3DS-автентикация на клиента. Виж вложени параметри.
Незадължително preOrderPayerData Object Обект, съдържащ данни на предварителната поръчка. Този параметър се използва за по-нататъшна 3DS-автентикация на клиента. Виж вложени параметри.
Незадължително orderPayerData Object Обект, съдържащ данни за платеца на поръчката. Този параметър се използва за по-нататъшна 3DS-автентикация на клиента. Виж вложени параметри.
Незадължително

billingAndShippingAddressMatchIndicator String [1] Индикатор за съответствие на платежния адрес на притежателя на картата и адреса за доставка. Този параметър се използва за по-нататъшна 3DS-автентификация на клиента.
Възможни стойности:
  • Y - съвпадение на платежния адрес на притежателя на картата и адреса за доставка;
  • N - платежният адрес на притежателя на картата и адресът за доставка не съвпадат.

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

Задължителност Наименование Тип Описание
Условие

billingCity String [0..50] Град, регистриран за конкретната карта в Банката Емитент. Задължително за Visa.
Условие

billingCountry String [0..50] Държава, регистрирана по конкретната карта на банката-издател. Формат: ISO 3166-1 (Alpha 2 / Alpha 3 / Number-3) или наименование на държавата. Препоръчваме да предавате двух/трибуквен ISO код на държавата. Задължително за Visa.
Условие

billingAddressLine1 String [0..50] Адрес, регистриран за конкретната карта в Банката Емитент (адрес на платеца). Ред 1. Задължително за предаване при AVS-проверка. Задължително за Visa.
Незадължително

billingAddressLine2 String [0..50] Адрес, регистриран за конкретната карта в Банката Емитент. Ред 2.
Незадължително

billingAddressLine3 String [0..50] Адрес, регистриран за конкретната карта в Банката Емитент. Ред 3.
Незадължително

billingPostalCode String [0..9] Пощенски код, регистриран за конкретната карта в Банката Издател. Задължително за предаване за AVS-проверка.
Незадължително

billingState String [0..50] Щат, регистриран за конкретната карта в Банката Емитент. Формат: пълна стойност на кода ISO 3166-2, негова част или наименование на щата/региона. Може да съдържа букви само от латинската азбука. Препоръчваме да се предава двубуквен ISO код на щата/региона.
Задължително

payerAccount String [1..32] Номер на сметката на изпращача.
Условие

payerLastName String [1..64] Фамилия на изпращача. Задължително за Visa.
Условие

payerFirstName String [1..35] Име на изпращача. Задължително за Visa.
Незадължително

payerMiddleName String [1..35] Бащино име на изпращача.
Незадължително

payerCombinedName String [1..99] Пълно име на подателя.
Незадължително

payerIdType String [1..8] Тип на предоставения идентифициращ документ на подателя.
Възможни стойности:
  • IDTP1 - Паспорт
  • IDTP2 - Шофьорска книжка
  • IDTP3 - Социална карта
  • IDTP4 - ID карта на гражданин
  • IDTP5 - Сертификат за водене на бизнес
  • IDTP6 - Сертификат на бежанец
  • IDTP7 - Разрешително за пребиваване
  • IDTP8 - Чужд паспорт
  • IDTP9 - Служебен паспорт
  • IDTP10 - Временен паспорт
  • IDTP11 - Паспорт на моряк
Незадължително

payerIdNumber String [1..99] Номер на предоставения идентифициращ документ на изпращача.
Условие

payerBirthday String [1..20] Дата на раждане на подателя във формат YYYYMMDD. Задължително за Visa.

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

Задължителност Наименование Тип Описание
Незадължително shippingCity String [1..50] Град на поръчителя (от адреса за доставка)
Незадължително shippingCountry String [1..50] Страна на поръчителя
Незадължително shippingAddressLine1 String [1..50] Основен адрес на клиента (от адреса за доставка)
Незадължително shippingAddressLine2 String [1..50] Основен адрес на клиента (от адреса за доставка)
Незадължително shippingAddressLine3 String [1..50] Основен адрес на клиента (от адреса за доставка)
Незадължително shippingPostalCode String [1..16] Пощенски код на клиента за доставка
Незадължително shippingState String [1..50] Щат/регион на купувача (от адреса за доставка)
Незадължително shippingMethodIndicator Integer [2] Индикатор за начин на доставка.
Възможни стойности:
  • 01 - доставка на платежния адрес на притежателя на карта.
  • 02 - доставка на друг адрес, проверен от Търговеца.
  • 03 - доставка на адрес, различен от основния адрес на притежателя на карта.
  • 04 - изпращане в магазин/самовземане (адресът на магазина трябва да бъде указан в съответните параметри за доставка)
  • 05 - Цифрово разпространение (включва онлайн услуги и електронни подаръчни карти)
  • 06 - билети за пътувания и събития, които не могат да бъдат доставени.
  • 07 - Други (например игри, цифрови стоки, които не подлежат на доставка, цифрови абонаменти и т.н.)
Незадължително deliveryTimeframe Integer [2] Срок за доставка на стоката.
Възможни стойности:
  • 01 - цифрова дистрибуция
  • 02 - доставка в същия ден
  • 03 - доставка на следващия ден
  • 04 - доставка в рамките на 2 дни след плащането и по-късно.
Незадължително deliveryEmail String [1..254] Целеви адрес на електронна поща за доставка на цифрово разпространение. Препоръчително е да предавате електронната поща в самостоятелен параметър на заявката email (но ако я предадете в този блок, към нея ще се прилагат същите правила).

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

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

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

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

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

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

Задължителност Име Тип Описание
Незадължително

orderCreationDate String [19] Дата на създаване на поръчката във формат YYYY-MM-DDTHH:MM:SS.
Незадължително

customerDetails Object Блок, съдържащ атрибутите на клиента. Описанието на атрибутите на тага е дадено по-долу.
Задължително

cartItems Object Обект, съдържащ атрибутите на стоките в кошницата. Описанието на вложените елементи е дадено по-долу.

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

Задължителност Наименование Тип Описание
Незадължително

contact String [0..40] Предпочитан от клиента начин за връзка.
Незадължително fullName String [1..100] ФИО на платеца.
Незадължително

passport String [1..100] Серия и номер на паспорта на платеца в следния формат: 2222888888
Незадължително

deliveryInfo Object Обект, съдържащ атрибутите на адреса за доставка. Описанието на вложените елементи е приведено по-долу.

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

Задължителност Наименование Тип Описание
Незадължително

deliveryType String [1..20] Начин на доставка.
Задължително

country String [2] Двубуквен код на страната за доставка.
Задължително

city String [0..40] Град на назначение.
Задължително

postAddress String [1..255] Адрес за доставка.

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

Задължителност Наименование Тип Описание
Задължително

items Object Елемент на масив с атрибути на стокова позиция. Описанието на вложените елементи е дадено по-долу.

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

Задължителност Наименование Тип Описание
Задължително

positionId Integer [1..12] Уникален идентификатор на стоковата позиция в кошницата.
Задължително

name String [1..255] Наименование или описание на стокова позиция в свободна форма.
Незадължително

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

quantity Object Елемент, описващ общото количество стокови позиции на един positionId и неговите мерни единици. Описанието на вложените елементи е приведено по-долу.
Незадължително

itemAmount Integer [1..12] Сума на стойността на всички стокови позиции за един positionId в минимални единици валута. itemAmount е задължителен за предаване, само ако не е предаден параметърът itemPrice. В противен случай предаването на itemAmount не се изисква. Ако в заявката се предават и двата параметъра: itemPrice и itemAmount, то itemAmount трябва да се равнява на itemPrice * quantity, в противен случай заявката ще завърши с грешка.
Незадължително

itemPrice Integer [1..18] Сума на стойността на стоковата позиция на един positionId в пари в минимални единици валута.
Незадължително

depositedItemAmount String [1..18] Сума на списване за един positionId в минимални валутни единици (например, в стотинки).
Незадължително

itemCurrency Integer [3] Код на валута ISO 4217. Ако не е посочен, се счита равен на валутата на поръчката.
Задължително

itemCode String [1..100] Номер (идентификатор) на стокова позиция в системата на магазина.

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

Задължителност Име Тип Описание
Задължително

value Number [1..18] Количество на стокови позиции от дадения positionId. За указване на дробни числа използвайте десетична точка. Допуска се максимум 3 знака след точката.
Задължително

measure String [1..20] Мерна единица за количеството по позицията.

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

Задължителност Название Тип Описание
Незадължително

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

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

Задължителност Наименование Тип Описание
Задължително

value String [1..2000] Допълнителна информация за товарната позиция.
Задължително

name String [1..255] Наименование на параметъра за описанието на детайлизацията на стоковата позиция

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

Задължителност Наименование Тип Описание
Незадължително

errorCode String [1..2] Информационен параметър в случай на грешка, който може да има различни кодови стойности:
  • стойност 0 - указва успех при обработката на заявката;
  • друга числова стойност (1-99) - указва грешка, за получаване на по-подробна информация за която е необходимо да се провери параметърът errorMesage.__ HTML_5__
Може да отсъства, ако резултатът не е предизвикал грешки.
Незадължително

errorMessage String [1..512] Информационен параметър, който представлява описание на грешката в случай на възникване на грешка. Стойността на errorMessage може да варира, затова не трябва да се препраща изрично към неговите стойности в кода.
Езикът на описанието се задава в параметъра language на заявката.
Незадължително

formUrl String [1..512] URL на платежната форма, към която ще бъде пренасочен купувачът. URL не се връща, ако регистрацията на поръчката не е преминала поради грешка, посочена в errorCode.
Незадължително

orderId String [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 features=FORCE_TDS \
  --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

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

Задължителност Название Тип Описание
Условие

userName String [1..30] Логин на потребителския акаунт API на продавача. Ако за автентификация при регистрация вместо логин и парола се използва открит токен (параметър token), паролата не трябва да се предава.
Условие

password String [1..30] Парола на API акаунта на продавача. Ако за удостоверяване при регистрация вместо логин и парола се използва открит токен (параметър token), паролата не е необходимо да се предава.
Условие

token String [1..256] Стойност, използвана за автентификация на продавача при изпращане на заявки към платежната шлюз. Ако предавате този параметър, то не предавайте userName и password.
Задължително

orderNumber String [1..36] Номер на поръчката (ID) в системата на търговеца; трябва да бъде уникален за всяка поръчка.
Задължително

amount Integer [0..12] Сума на плащането в минимални единици валута (например, в стотинки).
Задължително

currency String [3] Код на валутата на плащането ISO 4217. Ако не е посочен, се използва стойността по подразбиране. Позволени са само цифри.
Задължително

returnUrl String [1..512] Адрес, към който трябва да бъде пренасочен потребителят в случай на успешно плащане. Адресът трябва да бъде указан изцяло, включително използвания протокол (например, https://mybestmerchantreturnurl.com вместо mybestmerchantreturnurl.com). В противен случай потребителят ще бъде пренасочен на адрес от следния вид: https://uat.dskbank.bg/payment/<merchant_address>.
Незадължително

failUrl String [1..512] Адрес, на който трябва да се пренасочи потребителят в случай на неуспешно плащане. Адресът трябва да бъде посочен напълно, включително използвания протокол (например, https://mybestmerchantreturnurl.com вместо mybestmerchantreturnurl.com). В противен случай потребителят ще бъде пренасочен по адрес от следния вид: https://uat.dskbank.bg/payment/<merchant_address>.
Незадължително

dynamicCallbackUrl String [1..512] Параметър за предаване на динамичен адрес за получаване на "платежни" callback-уведомления за поръчката, активирани за търговеца (успешна авторизация, успешно списване, връщане, отказ, отхвърляне на плащане по таймаут, отхвърляне на card present плащане).
"Не платежни" callback-уведомления (включване/изключване на връзка, създаване на връзка), ще бъдат изпращани на статичен callback адрес.
Незадължително

description String [1..598] Описание на поръчката в произволен формат.
За да включите изпращането на това поле в процесинговата система, обърнете се към службата за техническа поддръжка.
В това поле е недопустимо да се предават лични данни или платежни данни (номера на карти и т.н.). Това изискване се дължи на факта, че описанието на поръчката никъде не се маскира.
Незадължително

ip String [1..39] IP адрес на платеца. IPv6 се поддържа във всички заявки (до 39 символа).
Незадължително

language String [2] Ключ на езика по ISO 639-1. Ако езикът не е указан, се използва езикът по подразбиране, указан в настройките на магазина.
Поддържани езици: en,ru,el,ro,bg,pt,sw,hu,it,pl,de,fr,kh,cn,es,ka,da,et,fi,lt,lv,nl,sv.
Незадължително

clientId String [0..255] Номер на клиента (ID) в системата на търговеца — до 255 символа. Използва се за реализиране на функционалността на връзките. Може да се връща в отговора, ако на търговеца е разрешено да създава връзки.
Указването на този параметър при обработка на плащания по връзка е задължително. В противен случай плащането ще бъде невъзможно.
Незадължително

merchantLogin String [1..255] За да регистрирате поръчка от името на друг търговец, посочете неговия логин (за API-акаунт) в този параметър.
Може да се използва само ако имате разрешение за преглед на транзакциите на други продавачи или ако посоченият продавач е ваш дъщерен продавач.
Незадължително

cardholderName String [1..150] Име на притежателя на картата с латински букви. При предаване на този параметър името на притежателя на картата ще бъде показано на страницата за плащане.
Незадължително

jsonParams Object Набор от допълнителни атрибути с произволна форма, структура:
jsonParams={"param_1_name":"param_1_value",...,"param_n_name":"param_n_value"}
Могат да бъдат предадени в Процесинговия Център, за последваща обработка (изисква се допълнителна настройка - обърнете се към поддръжката).
Някои предефинирани атрибути jsonParams:
  • backToShopUrl - добавя на страницата за плащане бутон, който ще върне държателя на картата на URL-адреса предаден в този параметър
  • backToShopName - настройва текстовия етикет на бутона Връщане към магазина по подразбиране, ако се използва заедно с backToShopUrl
  • installments - максимален брой разрешени авторизации за плащания на вноски. Изисква се за създаване на връзка за вноски
  • totalInstallmentAmount - крайна сума на всички плащания на вноски. Стойността е необходима за запазване на платежните данни за провеждане на вноски
  • recurringFrequency - минимален брой дни между авторизациите. Изисква се за създаване на рекурентна връзка, препоръчва се за създаване на връзка за вноски (ако се използва 3DS2, параметърът е задължителен).
  • recurringExpiry - дата, след която авторизациите не са разрешени, във формат ГГГГММДД. Изисква се за създаване на рекурентна връзка, препоръчва се за създаване на връзка за вноски (ако се използва 3DS2, параметърът е задължителен).
Незадължително

sessionTimeoutSecs Integer [1..9] Продължителност на живота на поръчката в секунди. В случай че параметърът не е зададен, ще бъде използвана стойността, указана в настройките на търговеца, или времето по подразбиране (1200 секунди = 20 минути). Ако в заявката присъства параметър expirationDate, то стойността на параметър sessionTimeoutSecs не се взема предвид.
Незадължително

expirationDate String [19] Дата и час на изтичане на срока на валидност на поръчката. Формат: yyyy-MM-ddTHH:mm:ss.
Ако този параметър не се предава в заявката, то за определяне на времето на изтичане на срока на валидност на поръчката се използва параметърът sessionTimeoutSecs.
Незадължително

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

features String Функции на поръчката. За да посочите няколко функции, използвайте този параметър няколко пъти в една заявка. По-долу са изброени възможните стойности.
  • 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, тогава поръчката ще бъде създадена САМО за създаване на връзка (без плащане).
Незадължително

autocompletionDate String [19] Дата и време на автоматичното завършване на двуетапното плащане в следния формат: 2025-12-29T13:02:51. Използван часови пояс: UTC+0. За да включите изпращането на това поле в процесинговата система, обърнете се към службата за техническа поддръжка.
Незадължително

autoReverseDate String [19] Дата и час на автоматично анулиране на двуетапното плащане в следния формат: 2025-06-23T13:02:51. Използван часови пояс: UTC+0. За да включите изпращането на това поле в процесинговата система, обърнете се към службата за техническа поддръжка.
Незадължително

postAddress String [1..255] Адрес за доставка.
Незадължително

orderBundle Object Обект, съдържащ кошницата с продукти. Описанието на вложените елементи е дадено по-долу.
Незадължително

feeInput Integer [0..8] Размер на комисионната в минимални единици валута. Функционалността трябва да бъде включена на ниво продавач в gateway-я.
Условие

email String [1..40] Електронна поща за показване на платежната страница. Ако за продавача са настроени известия на клиента, електронната поща трябва да бъде посочена. Пример: client_mail@email.com.
Адресът на електронната поща не се проверява при регистрация, той ще бъде проверен по-късно при плащане.
Незадължително

mcc Integer [4] Merchant Category Code (код на категория на търговеца). За предаване на този параметър е необходимо специално разрешение. Могат да се използват стойности само от разрешения списък MCC. За получаване на по-подробна информация се обърнете към техническата поддръжка.
Незадължително billingPayerData Object Блок с регистрационни данни на клиента (адрес, пощенски код), необходим за преминаване на проверка на адреса в рамките на услугите AVS/AVV. Задължително, ако функцията е включена за продавача на страната на Платежния шлюз. Вж вложени параметри.
Незадължително shippingPayerData Object Обект, съдържащ данни за доставката на клиента. Този параметър се използва за по-нататъшна 3DS-автентификация на клиента. Вж. вложени параметри.
Незадължително preOrderPayerData Object Обект, съдържащ данни за предварителната поръчка. Този параметър се използва за по-нататъшна 3DS-автентификация на клиента. Вж. вложени параметри.
Незадължително orderPayerData Object Обект, съдържащ данни за платеца на поръчката. Този параметър се използва за по-нататъшна 3DS-автентификация на клиента. Вж. вложени параметри.
Незадължително

billingAndShippingAddressMatchIndicator String [1] Индикатор за съответствие на платежния адрес на притежателя на картата и адреса за доставка. Този параметър се използва за по-нататъшна 3DS-автентификация на клиента.
Възможни стойности:
  • Y - съвпадение на платежния адрес на притежателя на картата и адреса за доставка;
  • N - платежният адрес на притежателя на картата и адресът за доставка не съвпадат.

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

Задължителност Наименование Тип Описание
Условие

billingCity String [0..50] Град, регистриран за конкретната карта в Банката Емитент. Задължително за Visa.
Условие

billingCountry String [0..50] Държава, регистрирана по конкретната карта на банката-издател. Формат: ISO 3166-1 (Alpha 2 / Alpha 3 / Number-3) или наименование на държавата. Препоръчваме да предавате двух/трибуквен ISO код на държавата. Задължително за Visa.
Условие

billingAddressLine1 String [0..50] Адрес, регистриран за конкретната карта в Банката Емитент (адрес на платеца). Ред 1. Задължително за предаване при AVS-проверка. Задължително за Visa.
Незадължително

billingAddressLine2 String [0..50] Адрес, регистриран за конкретната карта в Банката Емитент. Ред 2.
Незадължително

billingAddressLine3 String [0..50] Адрес, регистриран за конкретната карта в Банката Емитент. Ред 3.
Незадължително

billingPostalCode String [0..9] Пощенски код, регистриран за конкретната карта в Банката Издател. Задължително за предаване за AVS-проверка.
Незадължително

billingState String [0..50] Щат, регистриран за конкретната карта в Банката Емитент. Формат: пълна стойност на кода ISO 3166-2, негова част или наименование на щата/региона. Може да съдържа букви само от латинската азбука. Препоръчваме да се предава двубуквен ISO код на щата/региона.
Задължително

payerAccount String [1..32] Номер на сметката на изпращача.
Условие

payerLastName String [1..64] Фамилия на изпращача. Задължително за Visa.
Условие

payerFirstName String [1..35] Име на изпращача. Задължително за Visa.
Незадължително

payerMiddleName String [1..35] Бащино име на изпращача.
Незадължително

payerCombinedName String [1..99] Пълно име на подателя.
Незадължително

payerIdType String [1..8] Тип на предоставения идентифициращ документ на подателя.
Възможни стойности:
  • IDTP1 - Паспорт
  • IDTP2 - Шофьорска книжка
  • IDTP3 - Социална карта
  • IDTP4 - ID карта на гражданин
  • IDTP5 - Сертификат за водене на бизнес
  • IDTP6 - Сертификат на бежанец
  • IDTP7 - Разрешително за пребиваване
  • IDTP8 - Чужд паспорт
  • IDTP9 - Служебен паспорт
  • IDTP10 - Временен паспорт
  • IDTP11 - Паспорт на моряк
Незадължително

payerIdNumber String [1..99] Номер на предоставения идентифициращ документ на изпращача.
Условие

payerBirthday String [1..20] Дата на раждане на подателя във формат YYYYMMDD. Задължително за Visa.

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

Задължителност Наименование Тип Описание
Незадължително shippingCity String [1..50] Град на поръчителя (от адреса за доставка)
Незадължително shippingCountry String [1..50] Страна на поръчителя
Незадължително shippingAddressLine1 String [1..50] Основен адрес на клиента (от адреса за доставка)
Незадължително shippingAddressLine2 String [1..50] Основен адрес на клиента (от адреса за доставка)
Незадължително shippingAddressLine3 String [1..50] Основен адрес на клиента (от адреса за доставка)
Незадължително shippingPostalCode String [1..16] Пощенски код на клиента за доставка
Незадължително shippingState String [1..50] Щат/регион на купувача (от адреса за доставка)
Незадължително shippingMethodIndicator Integer [2] Индикатор за начин на доставка.
Възможни стойности:
  • 01 - доставка на платежния адрес на притежателя на карта.
  • 02 - доставка на друг адрес, проверен от Търговеца.
  • 03 - доставка на адрес, различен от основния адрес на притежателя на карта.
  • 04 - изпращане в магазин/самовземане (адресът на магазина трябва да бъде указан в съответните параметри за доставка)
  • 05 - Цифрово разпространение (включва онлайн услуги и електронни подаръчни карти)
  • 06 - билети за пътувания и събития, които не могат да бъдат доставени.
  • 07 - Други (например игри, цифрови стоки, които не подлежат на доставка, цифрови абонаменти и т.н.)
Незадължително deliveryTimeframe Integer [2] Срок за доставка на стоката.
Възможни стойности:
  • 01 - цифрова дистрибуция
  • 02 - доставка в същия ден
  • 03 - доставка на следващия ден
  • 04 - доставка в рамките на 2 дни след плащането и по-късно.
Незадължително deliveryEmail String [1..254] Целеви адрес на електронна поща за доставка на цифрово разпространение. Препоръчително е да предавате електронната поща в самостоятелен параметър на заявката email (но ако я предадете в този блок, към нея ще се прилагат същите правила).

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

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

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

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

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

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

Задължителност Име Тип Описание
Незадължително

orderCreationDate String [19] Дата на създаване на поръчката във формат YYYY-MM-DDTHH:MM:SS.
Незадължително

customerDetails Object Блок, съдържащ атрибутите на клиента. Описанието на атрибутите на тага е дадено по-долу.
Задължително

cartItems Object Обект, съдържащ атрибутите на стоките в кошницата. Описанието на вложените елементи е дадено по-долу.

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

Задължителност Наименование Тип Описание
Незадължително

contact String [0..40] Предпочитан от клиента начин за връзка.
Незадължително fullName String [1..100] ФИО на платеца.
Незадължително

passport String [1..100] Серия и номер на паспорта на платеца в следния формат: 2222888888
Незадължително

deliveryInfo Object Обект, съдържащ атрибутите на адреса за доставка. Описанието на вложените елементи е приведено по-долу.

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

Задължителност Наименование Тип Описание
Незадължително

deliveryType String [1..20] Начин на доставка.
Задължително

country String [2] Двубуквен код на страната за доставка.
Задължително

city String [0..40] Град на назначение.
Задължително

postAddress String [1..255] Адрес за доставка.

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

Задължителност Наименование Тип Описание
Задължително

items Object Елемент на масив с атрибути на стокова позиция. Описанието на вложените елементи е дадено по-долу.

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

Задължителност Наименование Тип Описание
Задължително

positionId Integer [1..12] Уникален идентификатор на стоковата позиция в кошницата.
Задължително

name String [1..255] Наименование или описание на стокова позиция в свободна форма.
Незадължително

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

quantity Object Елемент, описващ общото количество стокови позиции на един positionId и неговите мерни единици. Описанието на вложените елементи е приведено по-долу.
Незадължително

itemAmount Integer [1..12] Сума на стойността на всички стокови позиции за един positionId в минимални единици валута. itemAmount е задължителен за предаване, само ако не е предаден параметърът itemPrice. В противен случай предаването на itemAmount не се изисква. Ако в заявката се предават и двата параметъра: itemPrice и itemAmount, то itemAmount трябва да се равнява на itemPrice * quantity, в противен случай заявката ще завърши с грешка.
Незадължително

itemPrice Integer [1..18] Сума на стойността на стоковата позиция на един positionId в пари в минимални единици валута.
Незадължително

depositedItemAmount String [1..18] Сума на списване за един positionId в минимални валутни единици (например, в стотинки).
Незадължително

itemCurrency Integer [3] Код на валута ISO 4217. Ако не е посочен, се счита равен на валутата на поръчката.
Задължително

itemCode String [1..100] Номер (идентификатор) на стокова позиция в системата на магазина.

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

Задължителност Име Тип Описание
Задължително

value Number [1..18] Количество на стокови позиции от дадения positionId. За указване на дробни числа използвайте десетична точка. Допуска се максимум 3 знака след точката.
Задължително

measure String [1..20] Мерна единица за количеството по позицията.

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

Задължителност Название Тип Описание
Незадължително

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

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

Задължителност Наименование Тип Описание
Задължително

value String [1..2000] Допълнителна информация за товарната позиция.
Задължително

name String [1..255] Наименование на параметъра за описанието на детайлизацията на стоковата позиция

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

Задължителност Название Тип Описание
Незадължително

errorCode String [1..2] Информационен параметър в случай на грешка, който може да има различни кодови стойности:
  • стойност 0 - указва успех при обработката на заявката;
  • друга числова стойност (1-99) - указва грешка, за получаване на по-подробна информация за която е необходимо да се провери параметърът errorMesage.__ HTML_5__
Може да отсъства, ако резултатът не е предизвикал грешки.
Незадължително

errorMessage String [1..512] Информационен параметър, който представлява описание на грешката в случай на възникване на грешка. Стойността на errorMessage може да варира, затова не трябва да се препраща изрично към неговите стойности в кода.
Езикът на описанието се задава в параметъра language на заявката.
Незадължително

orderId String [1..36] Номер на поръчката в платежния шлюз. Уникален в рамките на платежния шлюз.
Незадължително

formUrl String [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 (прилагането на автентификацията се регулира от настройки, контролирани от службата за поддръжка).

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

Задължителност Наименование Тип Описание
Задължително

userName String [1..100] Логин на профила API на продавача.
Задължително

password String [1..30] Парола на API акаунта на продавача. Ако за удостоверяване при регистрация вместо логин и парола се използва открит токен (параметър token), паролата не е необходимо да се предава.
Задължително

MDORDER String [1..36] Номер на поръчката в платежния шлюз.
Задължително

$PAN Integer [1..19] Номер на платежна карта. Задължителен, ако не е предаден seToken.
Задължително

$CVC String [3] Код CVC/CVV2 на обратната страна на картата. Задължителен, ако не е предаден seToken.
Позволени са само цифри.
Задължително

YYYY Integer [4] Година на изтичане на валидността на платежната карта. Ако seToken не е предаден, задължително е необходимо да се предаде или $EXPIRY, или YYYY и MM.
Задължително

MM Integer [2] Месец на изтичане на действието на платежната карта. Ако seToken не е предаден, задължително е необходимо да се предаде или $EXPIRY, или YYYY и MM.
Условие

$EXPIRY Integer [6] Срок на валидност на картата в следния формат: YYYYMM. Предефинира параметрите YYYY и MM. Ако seToken не е предаден, задължително е необходимо да се предаде или $EXPIRY, или YYYY и MM.
Условие

seToken String Криптирани данни на картата, които заменят параметрите $PAN, $CVC и $EXPIRY (или YYYY,MM). Задължително, ако се използва вместо данни на картата.
Задължителни параметри за низа seToken: timestamp, UUID, PAN, EXPDATE, MDORDER. Повече за генерирането на seToken вж. тук.
Ако seToken съдържа криптирани данни за връзката (bindingId), за плащането трябва да се използва заявката paymentOrderBinding.do.
Задължително

TEXT String [1..512] Име на притежателя на картата.
Задължително

language String [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.
Незадължително

ip String [1..39] IP адрес на платеца. IPv6 се поддържа във всички заявки (до 39 символа).
Незадължително

bindingNotNeeded Boolean Допустими стойности:
  • true- създаването на връзка след извършване на плащането е изключено (връзката – това е идентификатор на клиента, предаден в заявката за регистрация на поръчката, който след заявката за плащане ще бъде изтрит от детайлите на поръчката);
  • false – в случай на успешно плащане може да бъде създадена връзка (при спазване на необходимите условия). Това е стойността по подразбиране.
Незадължително

jsonParams Object Полета за допълнителна информация за последващо съхранение, предават се в следния вид: jsonParams={"param_1_name":"param_1_value",...,"param_n_name":"param_n_value"}.
Могат да бъдат предадени в Процесинговия Център, за последваща обработка (изисква се допълнителна настройка - обърнете се към поддръжката).
Ако използвате външен MPI/3DS Server, платежният шлюз очаква, че всяка заявка paymentOrder ще включва редица допълнителни параметри, като eci, xid, cavv и пр. По-подробна информация тук.
За да инициирате 3RI аутентификация, може да ви е необходимо да предадете редица допълнителни параметри (вж. 3RI аутентификация).
Някои предефинирани атрибути на jsonParams:
  • backToShopUrl - добавя на страницата за плащане бутон, който ще върне притежателя на картата на URL-адреса предаден в този параметър
  • backToShopName - настройва текстовия етикет на бутона Върни се в магазина по подразбиране, ако се използва заедно с backToShopUrl
  • installments - максимален брой разрешени авторизации за плащания на вноски. Изисква се за създаване на връзка за вноски
  • totalInstallmentAmount - обща сума на всички плащания на вноски. Стойността е необходима за съхраняване на платежните данни за провеждане на вноски
  • recurringFrequency - минимален брой дни между авторизациите. Изисква се за създаване на рекурентна връзка, препоръчва се за създаване на връзка за вноски (ако се използва 3DS2, параметърът е задължителен).
  • recurringExpiry - дата, след която авторизациите не са разрешени, във формат ГГГГММДД. Изисква се за създаване на рекурентна връзка, препоръчва се за създаване на връзка за вноски (ако се използва 3DS2, параметърът е задължителен).
Незадължително

threeDSSDK Boolean Възможни стойности: true или false Флаг, показващ, че плащането постъпва от 3DS SDK.
Незадължително

mcc Integer [4] Merchant Category Code (код на категория на търговеца). За предаване на този параметър е необходимо специално разрешение. Могат да се използват стойности само от разрешения списък MCC. За получаване на по-подробна информация се обърнете към техническата поддръжка.
Условие

email String [1..40] Електронна поща за показване на страницата за плащане. Ако за продавача са настроени уведомления на клиента, електронната поща трябва да бъде посочена. Пример: client_mail@email.com.
За плащания с VISA с 3DS оторизация е необходимо да се посочи електронната поща или номера на телефона на притежателя на картата.
Незадължително billingPayerData Object Блок с регистрационни данни на клиента (адрес, пощенски код), необходими за преминаване на проверката на адреса в рамките на услугите AVS/AVV. Задължително, ако функцията е включена за продавача от страна на Платежния шлюз. Вж. вложени параметри.
Незадължително shippingPayerData Object Обект, съдържащ данни за доставката до клиента. Този параметър се използва за по-нататъшна 3DS-автентификация на клиента. Вж. вложени параметри.
Незадължително preOrderPayerData Object Обект, съдържащ данни за предварителната поръчка. Този параметър се използва за по-нататъшна 3DS-автентификация на клиента. Вж. вложени параметри.
Незадължително orderPayerData Object Обект, съдържащ данни за платеца на поръчката. Този параметър се използва за по-нататъшна 3DS-автентификация на клиента. Вж. вложени параметри.
Незадължително

tii String Идентификатор на инициатора на транзакцията. Параметър, указващ какъв тип операция ще изпълнява инициаторът (Клиент или Мърчант). Възможни стойности
Незадължително

externalScaExemptionIndicator String Тип на изключение SCA (Strong Customer Authentication). Ако е посочен този параметър, транзакцията ще бъде обработена в зависимост от вашите настройки в платежния шлюз: или ще бъде изпълнена принудителна операция SSL, или банката-издател ще получи информация за изключението SCA и ще вземе решение за провеждане на операцията с 3DS-автентификация или без нея (за получаване на подробна информация се свържете с нашата служба за поддръжка). Допустими стойности:
  • LVP – транзакция от тип Low Value Payments. Транзакцията може да бъде отнесена към транзакции с ниско ниво на риск въз основа на сумата на транзакцията, броя на транзакциите на клиента в деня или общата дневна сума на плащанията на клиента.
  • TRA – транзакция от тип Transaction Risk Analysis, т.е. транзакция, преминала успешна антифрод-проверка.

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

clientBrowserInfo Object Блок данни за браузъра на клиента, който се изпраща на ACS по време на 3DS автентификация. Този блок може да се предава само ако е включена специална настройка (обърнете се към екипа за поддръжка). Вж. вложени параметри.
Условие

originalPaymentNetRefNum String Идентификатор на оригиналната или предишната успешна транзакция в платежната система по отношение на изпълняваната операция по връзката - TRN ID. Предава се, ако стойността на параметъра tii = R,U или F.
Задължителен при използване на връзките на търговеца в преводите по връзка.
Условие

originalPaymentDate String Дата на инициираща транзакция. Стойност във формат Unix timestamp в милисекунди. Предава се, ако стойността на параметъра tii = R,U или F.
Незадължително

acsInIFrame Boolean Флаг, показващ, че за финишния URL ще се връща iFrame версия. Възможни стойности true или false. За свързване на тази функционалност се обърнете към службата за поддръжка.

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

Задължителност Наименование Тип Описание
Условие

billingCity String [0..50] Град, регистриран за конкретната карта в Банката Емитент. Задължително за Visa.
Условие

billingCountry String [0..50] Държава, регистрирана по конкретната карта на банката-издател. Формат: ISO 3166-1 (Alpha 2 / Alpha 3 / Number-3) или наименование на държавата. Препоръчваме да предавате двух/трибуквен ISO код на държавата. Задължително за Visa.
Условие

billingAddressLine1 String [0..50] Адрес, регистриран за конкретната карта в Банката Емитент (адрес на платеца). Ред 1. Задължително за предаване при AVS-проверка. Задължително за Visa.
Незадължително

billingAddressLine2 String [0..50] Адрес, регистриран за конкретната карта в Банката Емитент. Ред 2.
Незадължително

billingAddressLine3 String [0..50] Адрес, регистриран за конкретната карта в Банката Емитент. Ред 3.
Незадължително

billingPostalCode String [0..9] Пощенски код, регистриран за конкретната карта в Банката Издател. Задължително за предаване за AVS-проверка.
Незадължително

billingState String [0..50] Щат, регистриран за конкретната карта в Банката Емитент. Формат: пълна стойност на кода ISO 3166-2, негова част или наименование на щата/региона. Може да съдържа букви само от латинската азбука. Препоръчваме да се предава двубуквен ISO код на щата/региона.
Задължително

payerAccount String [1..32] Номер на сметката на изпращача.
Условие

payerLastName String [1..64] Фамилия на изпращача. Задължително за Visa.
Условие

payerFirstName String [1..35] Име на изпращача. Задължително за Visa.
Незадължително

payerMiddleName String [1..35] Бащино име на изпращача.
Незадължително

payerCombinedName String [1..99] Пълно име на подателя.
Незадължително

payerIdType String [1..8] Тип на предоставения идентифициращ документ на подателя.
Възможни стойности:
  • IDTP1 - Паспорт
  • IDTP2 - Шофьорска книжка
  • IDTP3 - Социална карта
  • IDTP4 - ID карта на гражданин
  • IDTP5 - Сертификат за водене на бизнес
  • IDTP6 - Сертификат на бежанец
  • IDTP7 - Разрешително за пребиваване
  • IDTP8 - Чужд паспорт
  • IDTP9 - Служебен паспорт
  • IDTP10 - Временен паспорт
  • IDTP11 - Паспорт на моряк
Незадължително

payerIdNumber String [1..99] Номер на предоставения идентифициращ документ на изпращача.
Условие

payerBirthday String [1..20] Дата на раждане на подателя във формат YYYYMMDD. Задължително за Visa.

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

Задължителност Наименование Тип Описание
Незадължително shippingCity String [1..50] Град на поръчителя (от адреса за доставка)
Незадължително shippingCountry String [1..50] Страна на поръчителя
Незадължително shippingAddressLine1 String [1..50] Основен адрес на клиента (от адреса за доставка)
Незадължително shippingAddressLine2 String [1..50] Основен адрес на клиента (от адреса за доставка)
Незадължително shippingAddressLine3 String [1..50] Основен адрес на клиента (от адреса за доставка)
Незадължително shippingPostalCode String [1..16] Пощенски код на клиента за доставка
Незадължително shippingState String [1..50] Щат/регион на купувача (от адреса за доставка)
Незадължително shippingMethodIndicator Integer [2] Индикатор за начин на доставка.
Възможни стойности:
  • 01 - доставка на платежния адрес на притежателя на карта.
  • 02 - доставка на друг адрес, проверен от Търговеца.
  • 03 - доставка на адрес, различен от основния адрес на притежателя на карта.
  • 04 - изпращане в магазин/самовземане (адресът на магазина трябва да бъде указан в съответните параметри за доставка)
  • 05 - Цифрово разпространение (включва онлайн услуги и електронни подаръчни карти)
  • 06 - билети за пътувания и събития, които не могат да бъдат доставени.
  • 07 - Други (например игри, цифрови стоки, които не подлежат на доставка, цифрови абонаменти и т.н.)
Незадължително deliveryTimeframe Integer [2] Срок за доставка на стоката.
Възможни стойности:
  • 01 - цифрова дистрибуция
  • 02 - доставка в същия ден
  • 03 - доставка на следващия ден
  • 04 - доставка в рамките на 2 дни след плащането и по-късно.
Незадължително deliveryEmail String [1..254] Целеви адрес на електронна поща за доставка на цифрово разпространение. Препоръчително е да предавате електронната поща в самостоятелен параметър на заявката email (но ако я предадете в този блок, към нея ще се прилагат същите правила).

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

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

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

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

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

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

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

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

Задължителност Название Тип Описание
Незадължително userAgent String [1..2048] Агент на браузъра.
Незадължително OS String Операционна система.
Незадължително OSVersion String Версия на операционната система.
Незадължително browserAcceptHeader String [1..2048] Заглавка Accept, която съобщава на сървъра какви формати (или MIME-типове) поддържа браузъра.
Незадължително browserIpAddress String [1..45] IP-адрес на браузъра.
Незадължително browserLanguage String [1..8] Език на браузъра.
Незадължително browserTimeZone String Часова зона на браузъра.
Незадължително browserTimeZoneOffset String [1..5] Отместване на часовата зона в минути между локалното време на потребителя и UTC.
Незадължително colorDepth String [1..2] Дълбочина на цвета на екрана, в битове.
Незадължително fingerprint String Отпечатък на браузъра - уникален цифров идентификатор на браузъра.
Незадължително isMobile Boolean Възможни стойности: true или false. Флаг, указващ, че се използва мобилно устройство.
Незадължително javaEnabled Boolean Възможни стойности: true или false. Флаг, указващ, че в браузъра е включена поддръжка на java.
Незадължително javascriptEnabled Boolean Възможни стойности: true или false. Флаг, указващ, че в браузъра е включена поддръжка на javascript.
Незадължително plugins String Списък на плъгините, използвани в браузъра, разделени със запетая.
Незадължително screenHeight Integer [1..6] Височина на екрана в пиксели.
Незадължително screenWidth Integer [1..6] Ширина на екрана в пиксели.
Незадължително screenPrint String Данни за параметрите на печат на браузъра, включително резолюция, дълбочина на цвета, плътност на пикселите.

Пример на блока clientBrowserInfo:

"clientBrowserInfo":
    {
        "userAgent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/111.0.0.0 Safari/537.36 Edg/111.0.1661.41",
        "fingerprint":850891523,
        "OS":"Windows",
        "OSVersion":"10",
        "isMobile":false,
        "screenPrint":"Current Resolution: 1536x864, Available Resolution: 1536x824, Color Depth: 24, Device XDPI: undefined, Device YDPI: undefined",
        "colorDepth":24,
        "screenHeight":"864",
        "screenWidth":"1536",
        "plugins":"PDF Viewer, Chrome PDF Viewer, Chromium PDF Viewer, Microsoft Edge PDF Viewer, WebKit built-in PDF",
        "javaEnabled":false,
        "javascriptEnabled":true,
        "browserLanguage":"it-IT",
        "browserTimeZone":"Europe/Rome",
        "browserTimeZoneOffset":-120,
        "browserAcceptHeader":"gzip",
        "browserIpAddress":"x.x.x.x"
    }

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

Задължителност Наименование Тип Описание
Незадължително

threeDSServerTransId String [1..36] Идентификатор на транзакцията, създаден на 3DS сървъра. Задължителен за 3DS автентикация.
Незадължително

threeDSVer2FinishUrl String [1..512] URL-адрес, с който клиентът трябва да бъде пренасочен след автентификация на сървъра ACS.
Незадължително

threeDSMethodNotificationUrl String [1..512] URL-адрес за изпращане на уведомление за преминаване на проверката в ACS.

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

Задължителност Наименование Тип Описание
Задължително

errorCode String [1..2] Информационен параметър в случай на грешка, който може да има различни кодови стойности:
  • стойност 0 - указва успех при обработката на заявката;
  • друга числова стойност (1-99) - указва грешка, за получаване на по-подробна информация за която е необходимо да се провери параметърът errorMesage.__ HTML_5__
Може да отсъства, ако резултатът не е предизвикал грешки.
Незадължително

errorMessage String [1..512] Информационен параметър, който представлява описание на грешката в случай на възникване на грешка. Стойността на errorMessage може да варира, затова не трябва да се препраща изрично към неговите стойности в кода.
Езикът на описанието се задава в параметъра language на заявката.
Незадължително

info String В случай на успешен отговор. Резултат от опита за плащане. По-долу са приведени възможните стойности.
  • Вашето плащане е обработено, извършва се пренасочване...
  • Операцията е отхвърлена. Проверете въведените данни, достатъчността на средствата на картата и повторете операцията. Извършва се пренасочване...
  • Извинете, плащането не може да бъде извършено. Извършва се пренасочване...
  • Операцията е отхвърлена. Обърнете се към магазина. Извършва се пренасочване...
  • Операцията е отхвърлена. Обърнете се към банката, издала картата. Извършва се пренасочване...
  • Операцията е невъзможна. Удостоверяването на притежателя на картата завърши неуспешно. Извършва се пренасочване...
  • Няма връзка с банката. Повторете по-късно. Извършва се пренасочване...
  • Изтече срокът за изчакване на въвеждане на данни. Извършва се пренасочване...
  • Не е получен отговор от банката. Повторете по-късно. Извършва се пренасочване...
Незадължително

redirect String [1..512] Този параметър се връща, ако плащането е преминало успешно и за плащането не е извършвана проверка на картата за участие в 3-D Secure. Продавачите могат да го използват, ако искат да пренасочат потребителя към страницата на платежния шлюз. Ако продавачът използва собствена страница, тази стойност може да бъде игнорирана.
Незадължително

termUrl String [1..512] При успешен отговор в случай на плащане 3D-Secure. Това е URL-адрес, към който ACS пренасочва притежателя на картата след удостоверяване. Подробно вж. Пренасочване към ACS.
Незадължително

acsUrl String [1..512] При успешен отговор в случай на плащане 3D-Secure. URL-адрес за пренасочване към ACS. Задължителен, ако е необходимо пренасочване към ACS. За повече информация вижте Пренасочване към ACS.
Незадължително

paReq String [1..255] PAReq (Payment Authentication Request) — съобщение, което трябва да бъде изпратено в ACS заедно с пренасочването. Връща се при успешен отговор в случай на плащане 3D-Secure, ако е необходимо пренасочване към ACS. Това съобщение съдържа данни в кодировка Base64, необходими за автентификация на притежателя на картата. За повече подробности вижте Пренасочване към ACS.

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

Задължителност Наименование Тип Описание
Незадължително

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

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

Задължителност Наименование Тип Описание
Задължително

is3DSVer2 Boolean Възможни стойности: true или false Флаг, показващ, че плащането постъпва от 3DS2.
Задължително

threeDSServerTransId String [1..36] Идентификатор на транзакцията, създаден на 3DS сървъра. Задължителен за 3DS автентикация.
Незадължително

threeDSMethodUrl String [1..512] URL-адрес на ACS сървъра за събиране на данни от браузъра.
Задължително

threeDSMethodUrlServer String [1..512] URL-адрес на 3DS сървъра за събиране на данни от браузъра, които ще бъдат включени в AReq (Authentication Request) от 3DS сървъра към ACS сървъра.
Незадължително

threeDSMethodDataPacked String [1..1024] Данни CReq (Challenge Response) в кодировка Base-64 за изпращане на сървър ACS.
Незадължително

threeDSMethodURLServerDirect String [1..512] URL адрес 3dsmethod.do за изпълнение на 3DS метода на 3DS сървъра чрез платежния шлюз (при наличие на съответното разрешение на ниво продавач).

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

Задължителност Наименование Тип Описание
Условие

acsUrl String [1..512] При успешен отговор в случай на плащане 3D-Secure. URL-адрес за пренасочване към ACS. Задължителен, ако е необходимо пренасочване към ACS. За повече информация вижте Пренасочване към ACS.
Условие

packedCReq String Опаковани данни 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.
Също така ви е необходимо допълнително разрешение, назначавано от службата за поддръжка.

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

Задължителност Наименование Тип Описание
Задължително

userName String [1..100] Логин на профила API на продавача.
Задължително

password String [1..30] Парола на API акаунта на продавача.
Задължително

MDORDER String [1..36] Номер на поръчката в платежния шлюз.
Условие

$PAN Integer [1..19] Номер на платежна карта. Задължителен, ако не е предаден seToken.
Условие

$CVC String [3] Код CVC/CVV2 на обратната страна на картата. Задължителен, ако не е предаден seToken.
Позволени са само цифри.
Условие

YYYY Integer [4] Година на изтичане на валидността на платежната карта. Ако seToken не е предаден, задължително е необходимо да се предаде или $EXPIRY, или YYYY и MM.
Условие

MM Integer [2] Месец на изтичане на действието на платежната карта. Ако seToken не е предаден, задължително е необходимо да се предаде или $EXPIRY, или YYYY и MM.
Условие

$EXPIRY Integer [6] Срок на валидност на картата в следния формат: YYYYMM. Предефинира параметрите YYYY и MM. Ако seToken не е предаден, задължително е необходимо да се предаде или $EXPIRY, или YYYY и MM.
Условие

seToken String Криптирани данни на картата, които заменят параметрите $PAN, $CVC и $EXPIRY (или YYYY,MM). Задължително, ако се използва вместо данни на картата.
Задължителни параметри за низа seToken: timestamp, UUID, PAN, EXPDATE, MDORDER. Повече за генерирането на seToken вж. тук.
Ако seToken съдържа криптирани данни за връзката (bindingId), за плащането трябва да се използва заявката paymentOrderBinding.do.
Задължително

TEXT String [1..512] Име на притежателя на картата.
Задължително

language String [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.
Незадължително

ip String [1..39] IP адрес на платеца. IPv6 се поддържа във всички заявки (до 39 символа).
Незадължително

bindingNotNeeded Boolean Допустими стойности:
  • true- създаването на връзка след извършване на плащането е изключено (връзката – това е идентификатор на клиента, предаден в заявката за регистрация на поръчката, който след заявката за плащане ще бъде изтрит от детайлите на поръчката);
  • false – в случай на успешно плащане може да бъде създадена връзка (при спазване на необходимите условия). Това е стойността по подразбиране.
Незадължително

jsonParams Object Полета за допълнителна информация за последващо съхранение, предават се в следния вид: jsonParams={"param_1_name":"param_1_value",...,"param_n_name":"param_n_value"}.
Могат да бъдат предадени в Процесинговия Център, за последваща обработка (изисква се допълнителна настройка - обърнете се към поддръжката).
Ако използвате външен MPI/3DS Server, платежният шлюз очаква, че всяка заявка paymentOrder ще включва редица допълнителни параметри, като eci, xid, cavv и пр. По-подробна информация тук.
За да инициирате 3RI аутентификация, може да ви е необходимо да предадете редица допълнителни параметри (вж. 3RI аутентификация).
Някои предефинирани атрибути на jsonParams:
  • backToShopUrl - добавя на страницата за плащане бутон, който ще върне притежателя на картата на URL-адреса предаден в този параметър
  • backToShopName - настройва текстовия етикет на бутона Върни се в магазина по подразбиране, ако се използва заедно с backToShopUrl
  • installments - максимален брой разрешени авторизации за плащания на вноски. Изисква се за създаване на връзка за вноски
  • totalInstallmentAmount - обща сума на всички плащания на вноски. Стойността е необходима за съхраняване на платежните данни за провеждане на вноски
  • recurringFrequency - минимален брой дни между авторизациите. Изисква се за създаване на рекурентна връзка, препоръчва се за създаване на връзка за вноски (ако се използва 3DS2, параметърът е задължителен).
  • recurringExpiry - дата, след която авторизациите не са разрешени, във формат ГГГГММДД. Изисква се за създаване на рекурентна връзка, препоръчва се за създаване на връзка за вноски (ако се използва 3DS2, параметърът е задължителен).
Незадължително

tii String Идентификатор на инициатора на транзакцията. Параметър, указващ какъв тип операция ще изпълнява инициаторът (Клиент или Търговец). Възможни стойности
Незадължително

threeDSProtocolVersion String Версия на протокола 3DS. Възможни стойности: "2.1.0", "2.2.0" за 3DS2.
Ако в заявката не се предава threeDSProtocolVersion, то за оторизация 3D Secure ще се използва стойността по подразбиране (2.1.0 - за 3DS 2).
Условие

email String [1..40] Електронна поща за показване на страницата за плащане. Ако за продавача са настроени уведомления на клиента, електронната поща трябва да бъде посочена. Пример: client_mail@email.com.
За плащания с VISA с 3DS оторизация е необходимо да се посочи електронната поща или номера на телефона на притежателя на картата.
Незадължително

mcc Integer [4] Merchant Category Code (код на категория на търговеца). За предаване на този параметър е необходимо специално разрешение. Могат да се използват стойности само от разрешения списък MCC. За получаване на по-подробна информация се обърнете към техническата поддръжка.
Незадължително billingPayerData Object Блок с регистрационни данни на клиента (адрес, пощенски индекс), необходим за преминаване на проверка на адреса в рамките на услугите AVS/AVV. Задължително, ако функцията е включена за продавача от страна на Платежния шлюз. Вж вложени параметри.
Незадължително shippingPayerData Object Обект, съдържащ данни за доставката до клиента. Този параметър се използва за по-нататъшна 3DS-автентификация на клиента. Вж. вложени параметри.
Незадължително preOrderPayerData Object Обект, съдържащ данни за предварителна поръчка. Този параметър се използва за по-нататъшна 3DS-автентификация на клиента. Вж. вложени параметри.
Незадължително orderPayerData Object Обект, съдържащ данни за платеца на поръчката. Този параметър се използва за по-нататъшна 3DS-автентификация на клиента. Вж. вложени параметри.
Незадължително

billingAndShippingAddressMatchIndicator String [1] Индикатор за съответствие на платежния адрес на притежателя на картата и адреса за доставка. Този параметър се използва за по-нататъшна 3DS-автентификация на клиента.
Възможни стойности:
  • Y - съвпадение на платежния адрес на притежателя на картата и адреса за доставка;
  • N - платежният адрес на притежателя на картата и адресът за доставка не съвпадат.
Незадължително

clientBrowserInfo Object Блок данни за браузъра на клиента, който се изпраща към ACS по време на 3DS удостоверяване. Този блок може да се предава, само ако е включена специална настройка (обърнете се към екипа за поддръжка). Вж. вложени параметри.
Незадължително

acsInIFrame Boolean Флаг, показващ, че за финишния URL ще се връща iFrame версия. Възможни стойности true или false. За свързване на тази функционалност се обърнете към службата за поддръжка.

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

Задължителност Наименование Тип Описание
Условие

billingCity String [0..50] Град, регистриран за конкретната карта в Банката Емитент. Задължително за Visa.
Условие

billingCountry String [0..50] Държава, регистрирана по конкретната карта на банката-издател. Формат: ISO 3166-1 (Alpha 2 / Alpha 3 / Number-3) или наименование на държавата. Препоръчваме да предавате двух/трибуквен ISO код на държавата. Задължително за Visa.
Условие

billingAddressLine1 String [0..50] Адрес, регистриран за конкретната карта в Банката Емитент (адрес на платеца). Ред 1. Задължително за предаване при AVS-проверка. Задължително за Visa.
Незадължително

billingAddressLine2 String [0..50] Адрес, регистриран за конкретната карта в Банката Емитент. Ред 2.
Незадължително

billingAddressLine3 String [0..50] Адрес, регистриран за конкретната карта в Банката Емитент. Ред 3.
Незадължително

billingPostalCode String [0..9] Пощенски код, регистриран за конкретната карта в Банката Издател. Задължително за предаване за AVS-проверка.
Незадължително

billingState String [0..50] Щат, регистриран за конкретната карта в Банката Емитент. Формат: пълна стойност на кода ISO 3166-2, негова част или наименование на щата/региона. Може да съдържа букви само от латинската азбука. Препоръчваме да се предава двубуквен ISO код на щата/региона.
Задължително

payerAccount String [1..32] Номер на сметката на изпращача.
Условие

payerLastName String [1..64] Фамилия на изпращача. Задължително за Visa.
Условие

payerFirstName String [1..35] Име на изпращача. Задължително за Visa.
Незадължително

payerMiddleName String [1..35] Бащино име на изпращача.
Незадължително

payerCombinedName String [1..99] Пълно име на подателя.
Незадължително

payerIdType String [1..8] Тип на предоставения идентифициращ документ на подателя.
Възможни стойности:
  • IDTP1 - Паспорт
  • IDTP2 - Шофьорска книжка
  • IDTP3 - Социална карта
  • IDTP4 - ID карта на гражданин
  • IDTP5 - Сертификат за водене на бизнес
  • IDTP6 - Сертификат на бежанец
  • IDTP7 - Разрешително за пребиваване
  • IDTP8 - Чужд паспорт
  • IDTP9 - Служебен паспорт
  • IDTP10 - Временен паспорт
  • IDTP11 - Паспорт на моряк
Незадължително

payerIdNumber String [1..99] Номер на предоставения идентифициращ документ на изпращача.
Условие

payerBirthday String [1..20] Дата на раждане на подателя във формат YYYYMMDD. Задължително за Visa.

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

Задължителност Наименование Тип Описание
Незадължително shippingCity String [1..50] Град на поръчителя (от адреса за доставка)
Незадължително shippingCountry String [1..50] Страна на поръчителя
Незадължително shippingAddressLine1 String [1..50] Основен адрес на клиента (от адреса за доставка)
Незадължително shippingAddressLine2 String [1..50] Основен адрес на клиента (от адреса за доставка)
Незадължително shippingAddressLine3 String [1..50] Основен адрес на клиента (от адреса за доставка)
Незадължително shippingPostalCode String [1..16] Пощенски код на клиента за доставка
Незадължително shippingState String [1..50] Щат/регион на купувача (от адреса за доставка)
Незадължително shippingMethodIndicator Integer [2] Индикатор за начин на доставка.
Възможни стойности:
  • 01 - доставка на платежния адрес на притежателя на карта.
  • 02 - доставка на друг адрес, проверен от Търговеца.
  • 03 - доставка на адрес, различен от основния адрес на притежателя на карта.
  • 04 - изпращане в магазин/самовземане (адресът на магазина трябва да бъде указан в съответните параметри за доставка)
  • 05 - Цифрово разпространение (включва онлайн услуги и електронни подаръчни карти)
  • 06 - билети за пътувания и събития, които не могат да бъдат доставени.
  • 07 - Други (например игри, цифрови стоки, които не подлежат на доставка, цифрови абонаменти и т.н.)
Незадължително deliveryTimeframe Integer [2] Срок за доставка на стоката.
Възможни стойности:
  • 01 - цифрова дистрибуция
  • 02 - доставка в същия ден
  • 03 - доставка на следващия ден
  • 04 - доставка в рамките на 2 дни след плащането и по-късно.
Незадължително deliveryEmail String [1..254] Целеви адрес на електронна поща за доставка на цифрово разпространение. Препоръчително е да предавате електронната поща в самостоятелен параметър на заявката email (но ако я предадете в този блок, към нея ще се прилагат същите правила).

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

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

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

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

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

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

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

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

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

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

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

Задължителност Название Тип Описание
Незадължително userAgent String [1..2048] Агент на браузъра.
Незадължително OS String Операционна система.
Незадължително OSVersion String Версия на операционната система.
Незадължително browserAcceptHeader String [1..2048] Заглавка Accept, която съобщава на сървъра какви формати (или MIME-типове) поддържа браузъра.
Незадължително browserIpAddress String [1..45] IP-адрес на браузъра.
Незадължително browserLanguage String [1..8] Език на браузъра.
Незадължително browserTimeZone String Часова зона на браузъра.
Незадължително browserTimeZoneOffset String [1..5] Отместване на часовата зона в минути между локалното време на потребителя и UTC.
Незадължително colorDepth String [1..2] Дълбочина на цвета на екрана, в битове.
Незадължително fingerprint String Отпечатък на браузъра - уникален цифров идентификатор на браузъра.
Незадължително isMobile Boolean Възможни стойности: true или false. Флаг, указващ, че се използва мобилно устройство.
Незадължително javaEnabled Boolean Възможни стойности: true или false. Флаг, указващ, че в браузъра е включена поддръжка на java.
Незадължително javascriptEnabled Boolean Възможни стойности: true или false. Флаг, указващ, че в браузъра е включена поддръжка на javascript.
Незадължително plugins String Списък на плъгините, използвани в браузъра, разделени със запетая.
Незадължително screenHeight Integer [1..6] Височина на екрана в пиксели.
Незадължително screenWidth Integer [1..6] Ширина на екрана в пиксели.
Незадължително screenPrint String Данни за параметрите на печат на браузъра, включително резолюция, дълбочина на цвета, плътност на пикселите.

Пример на блока clientBrowserInfo:

"clientBrowserInfo":
    {
        "userAgent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/111.0.0.0 Safari/537.36 Edg/111.0.1661.41",
        "fingerprint":850891523,
        "OS":"Windows",
        "OSVersion":"10",
        "isMobile":false,
        "screenPrint":"Current Resolution: 1536x864, Available Resolution: 1536x824, Color Depth: 24, Device XDPI: undefined, Device YDPI: undefined",
        "colorDepth":24,
        "screenHeight":"864",
        "screenWidth":"1536",
        "plugins":"PDF Viewer, Chrome PDF Viewer, Chromium PDF Viewer, Microsoft Edge PDF Viewer, WebKit built-in PDF",
        "javaEnabled":false,
        "javascriptEnabled":true,
        "browserLanguage":"it-IT",
        "browserTimeZone":"Europe/Rome",
        "browserTimeZoneOffset":-120,
        "browserAcceptHeader":"gzip",
        "browserIpAddress":"x.x.x.x"
    }

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

Задължителност Име Тип Описание
Задължително

errorCode String [1..2] Информационен параметър в случай на грешка, който може да има различни кодови стойности:
  • стойност 0 - указва успех при обработката на заявката;
  • друга числова стойност (1-99) - указва грешка, за получаване на по-подробна информация за която е необходимо да се провери параметърът errorMesage.__ HTML_5__
Може да отсъства, ако резултатът не е предизвикал грешки.
Незадължително

errorMessage String [1..512] Информационен параметър, който представлява описание на грешката в случай на възникване на грешка. Стойността на errorMessage може да варира, затова не трябва да се препраща изрично към неговите стойности в кода.
Езикът на описанието се задава в параметъра language на заявката.
Незадължително

info String В случай на успешен отговор. Резултат от опита за плащане. По-долу са приведени възможните стойности.
  • Вашето плащане е обработено, извършва се пренасочване...
  • Операцията е отхвърлена. Проверете въведените данни, достатъчността на средствата на картата и повторете операцията. Извършва се пренасочване...
  • Извинете, плащането не може да бъде извършено. Извършва се пренасочване...
  • Операцията е отхвърлена. Обърнете се към магазина. Извършва се пренасочване...
  • Операцията е отхвърлена. Обърнете се към банката, издала картата. Извършва се пренасочване...
  • Операцията е невъзможна. Удостоверяването на притежателя на картата завърши неуспешно. Извършва се пренасочване...
  • Няма връзка с банката. Повторете по-късно. Извършва се пренасочване...
  • Изтече срокът за изчакване на въвеждане на данни. Извършва се пренасочване...
  • Не е получен отговор от банката. Повторете по-късно. Извършва се пренасочване...

Примери

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

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", "authenticationTypeIndicator": "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

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

Задължителност Име Тип Описание
Условие

userName String [1..30] Логин на потребителския акаунт API на продавача. Ако за автентификация при регистрация вместо логин и парола се използва открит токен (параметър token), паролата не трябва да се предава.
Условие

password String [1..30] Парола на API акаунта на продавача. Ако за удостоверяване при регистрация вместо логин и парола се използва открит токен (параметър token), паролата не е необходимо да се предава.
Условие

token String [1..256] Стойност, използвана за автентификация на продавача при изпращане на заявки към платежната шлюз. Ако предавате този параметър, то не предавайте userName и password.
Задължително

originalMdOrder String [1..36] Номер на първоначалния заказ в Платежния шлюз, за който се изпълнява Industry Practice плащане.
Задължително

orderNumber String [1..36] Номер на поръчката (ID) в системата на търговеца; трябва да бъде уникален за всяка поръчка.
Условие

amount Integer [0..12] Сума на плащането в минимални единици валута (например, в стотинки) на първоначалното плащане за операции Incremental, Delayed Charges, No show.
Параметърът е задължителен за предаване при операции Incremental, Delayed Charges, No show. Параметърът не трябва да се указва за Resubmission и Reauthorization.
Незадължително

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

tii String Идентификатор на инициатора (за) транзакцията. Параметър, указващ какъв тип операция ще изпълнява инициаторът (Клиент или Търговец).
Незадължително

features String Функции на поръчката. За да посочите няколко функции, използвайте този параметър няколко пъти в една заявка. По-долу са изброени възможните стойности.
  • 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 Описание Тип транзакция Инициатор на транзакцията Данни на картата за транзакцията Забележка
IPI Industry Practice Incremental (MIT) Последваща Продавач Не са въведени, заредени от съответния транзакционен запис или връзка на платежния шлюз Транзакция за увеличаване на сумата на плащането в рамките на вече платена поръчка.
IPS Industry Practice Resubmission (MIT) Последваща Продавач Не са въведени, заредени от съответния транзакционен запис или връзка на платежния шлюз Транзакция опит за повторно плащане, когато първоначалното плащане завърши с грешка.
IPD Industry Practice Delayed Charges (MIT) Последваща Продавач Не са въведени, заредени от съответния транзакционен запис или връзка на платежния шлюз Функционалност на отложени начисления.
IPA Industry Practice Reauthorization (MIT) Последваща Продавач Не са въведени, заредени от съответния транзакционен запис или връзка на платежния шлюз Повторен опит за оторизация, ако завършването или изпълнението на първоначалната поръчка/услуга излиза извън рамките на срока на действие на оторизацията, установен от Visa/MC.
IPN Industry Practice No Show (MIT) Последваща Продавач Не са въведени, заредени от съответния транзакционен запис или връзка на платежния шлюз Изпълнява се от търговците за начисляване на глоби на клиента за неявяване при резервация на хотели и Car Sharing автомобили.

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

Задължителност Име Тип Описание
Задължително

name String [1..255] Име на допълнителния параметър.
Задължително

value String [1..1024] Стойност на допълнителния параметър - до 1024 символа.

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

Задължителност Име Тип Описание
Незадължително

errorCode String [1..2] Информационен параметър в случай на грешка, който може да има различни кодови стойности:
  • стойност 0 - указва успех при обработката на заявката;
  • друга числова стойност (1-99) - указва грешка, за получаване на по-подробна информация за която е необходимо да се провери параметърът errorMesage.__ HTML_5__
Може да отсъства, ако резултатът не е предизвикал грешки.
Незадължително

errorMessage String [1..512] Информационен параметър, който представлява описание на грешката в случай на възникване на грешка. Стойността на errorMessage може да варира, затова не трябва да се препраща изрично към неговите стойности в кода.
Езикът на описанието се задава в параметъра language на заявката.
Незадължително

mdOrder String [1..36] Номер на поръчката в платежния шлюз с изпълнено Industry Practice плащане.
Незадължително

actionCode Integer Код за отговор от процесинга на банката. Виж списъка с кодове за отговор тук.
Незадължително

approvalCode String [6] Код за оторизация на МПС. Това поле има фиксирана дължина (шест символа) и може да съдържа цифри и латински букви.
Незадължително

rrn Integer [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

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

Задължителност Наименование Тип Описание
Условие

userName String [1..30] Логин на потребителския акаунт API на продавача. Ако за автентификация при регистрация вместо логин и парола се използва открит токен (параметър token), паролата не трябва да се предава.
Условие

password String [1..30] Парола на API акаунта на продавача. Ако за удостоверяване при регистрация вместо логин и парола се използва открит токен (параметър token), паролата не е необходимо да се предава.
Условие

token String [1..256] Стойност, използвана за автентификация на продавача при изпращане на заявки към платежната шлюз. Ако предавате този параметър, то не предавайте userName и password.
Задължително

amount Integer [0..12] Сума на плащането в минимални единици валута (например, в стотинки).
Задължително

currency String [3] Код на валутата на плащането ISO 4217. Ако не е посочен, се използва стойността по подразбиране. Позволени са само цифри.
Незадължително

clientId String [0..255] Номер на клиента (ID) в системата на търговеца — до 255 символа. Използва се за реализиране на функционалността на връзките. Може да се връща в отговора, ако на търговеца е разрешено да създава връзки.
Указването на този параметър при обработка на плащания по връзка е задължително. В противен случай плащането ще бъде невъзможно.
Незадължително

ip String [1..39] IP адрес на платеца. IPv6 се поддържа във всички заявки (до 39 символа).
Незадължително

bindingNotNeeded Boolean Допустими стойности:
  • true- създаването на връзка след извършване на плащането е изключено (връзката е идентификатор на клиента, предаден в заявката за регистрация на поръчката, който след заявката instantPayment.do ще бъде изтрит от детайлите на поръчката);
  • false – в случай на успешно плащане може да бъде създадена връзка (при спазване на необходимите условия). Това е стойността по подразбиране.
Условие

orderNumber String [1..36] Номер на поръчка (ID) в системата на търговеца, трябва да бъде уникален за всеки търговец, регистриран в платежния шлюз. Ако номерът на поръчката се генерира от страната на платежния шлюз, този параметър не е задължително да се предава.
Незадължително

description String [1..598] Описание на поръчката в произволен формат.
За да включите изпращането на това поле в процесинговата система, обърнете се към службата за техническа поддръжка.
В това поле е недопустимо да се предават лични данни или платежни данни (номера на карти и т.н.). Това изискване се дължи на факта, че описанието на поръчката никъде не се маскира.
Незадължително

language String [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.
Незадължително

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

preAuth Boolean Параметър, определящ необходимостта от предварителна оторизация (блокиране на средства по сметката на клиента преди тяхното списване). Достъпни са следните стойности:
  • true - включено е двуетапно плащане;
  • false - включено е едноетапно плащане (парите се списват веднага).
Ако параметърът липсва, извършва се едноетапно плащане.
Незадължително

pan String [1..19] Номер на платежна карта (задължително, ако bindinId не се предава). Стойността pan заменя стойността bindingId.
Незадължително

cvc String [3] Предаването на параметъра се определя от типа на плащането:
  • предаването на cvc не е предвидено за всички токенизирани плащания;
  • предаването на cvc не е предвидено за MIT плащания;
  • предаването на cvc е задължително по подразбиране за всички други типове плащания; но ако за търговеца е избрано разрешението Може да извършва плащане без потвърждение на CVC, то в такъв случай предаването на cvc става незадължително.
    Допускат се само цифри.
Незадължително

cardHolderName String [1..26] Име на притежателя на картата с латински букви. Този параметър се предава само след плащането на поръчката.
Незадължително

merchantLogin String [1..255] За да регистрирате поръчка от името на друг търговец, посочете неговия логин (за API-акаунт) в този параметър.
Може да се използва само ако имате разрешение за преглед на транзакциите на други продавачи или ако посоченият продавач е ваш дъщерен продавач.
Незадължително

sessionTimeoutSecs Integer [1..9] Продължителност на живота на поръчката в секунди. В случай че параметърът не е зададен, ще бъде използвана стойността, указана в настройките на търговеца, или времето по подразбиране (1200 секунди = 20 минути). Ако в заявката присъства параметър expirationDate, то стойността на параметър sessionTimeoutSecs не се взема предвид.
Незадължително

autocompletionDate String [19] Дата и време на автоматичното завършване на двуетапното плащане в следния формат: 2025-12-29T13:02:51. Използван часови пояс: UTC+0. За да включите изпращането на това поле в процесинговата система, обърнете се към службата за техническа поддръжка.
Незадължително

autoReverseDate String [19] Дата и час на автоматично анулиране на двуетапното плащане в следния формат: 2025-06-23T13:02:51. Използван часови пояс: UTC+0. За да включите изпращането на това поле в процесинговата система, обърнете се към службата за техническа поддръжка.
Незадължително

expirationDate String [19] Дата и час на изтичане на срока на валидност на поръчката. Формат: yyyy-MM-ddTHH:mm:ss.
Ако този параметър не се предава в заявката, то за определяне на времето на изтичане на срока на валидност на поръчката се използва параметърът sessionTimeoutSecs.
Условие

seToken String [1..8192] Шифровани данни за карта, които заменят параметрите $PAN, $CVC и $EXPIRY (или YYYY,MM). Задължително, ако се използва вместо данни за карта.
Задължителни параметри за низа seToken: timestamp, UUID, bindingId(или PAN,EXPDATE). Подробности за генерирането на seToken вж. тук.
Задължително

returnUrl String [1..512] Адрес, към който трябва да бъде пренасочен потребителят в случай на успешно плащане. Адресът трябва да бъде указан изцяло, включително използвания протокол (например, https://mybestmerchantreturnurl.com вместо mybestmerchantreturnurl.com). В противен случай потребителят ще бъде пренасочен на адрес от следния вид: https://uat.dskbank.bg/payment/<merchant_address>.
Незадължително

failUrl String [1..512] Адрес, на който трябва да се пренасочи потребителят в случай на неуспешно плащане. Адресът трябва да бъде посочен напълно, включително използвания протокол (например, https://mybestmerchantreturnurl.com вместо mybestmerchantreturnurl.com). В противен случай потребителят ще бъде пренасочен по адрес от следния вид: https://uat.dskbank.bg/payment/<merchant_address>.
Незадължително

jsonParams Object Полета за допълнителна информация за последващо съхранение, предават се в следния вид: jsonParams={"param_1_name":"param_1_value",...,"param_n_name":"param_n_value"}.
Могат да бъдат предадени в Процесинговия Център, за последваща обработка (изисква се допълнителна настройка - обърнете се към поддръжката).
Ако използвате външен MPI/3DS Server, платежният шлюз очаква, че всяка заявка paymentOrder ще включва редица допълнителни параметри, като eci, xid, cavv и пр. По-подробна информация тук.
За да инициирате 3RI аутентификация, може да ви е необходимо да предадете редица допълнителни параметри (вж. 3RI аутентификация).
Някои предефинирани атрибути на jsonParams:
  • backToShopUrl - добавя на страницата за плащане бутон, който ще върне притежателя на картата на URL-адреса предаден в този параметър
  • backToShopName - настройва текстовия етикет на бутона Върни се в магазина по подразбиране, ако се използва заедно с backToShopUrl
  • installments - максимален брой разрешени авторизации за плащания на вноски. Изисква се за създаване на връзка за вноски
  • totalInstallmentAmount - обща сума на всички плащания на вноски. Стойността е необходима за съхраняване на платежните данни за провеждане на вноски
  • recurringFrequency - минимален брой дни между авторизациите. Изисква се за създаване на рекурентна връзка, препоръчва се за създаване на връзка за вноски (ако се използва 3DS2, параметърът е задължителен).
  • recurringExpiry - дата, след която авторизациите не са разрешени, във формат ГГГГММДД. Изисква се за създаване на рекурентна връзка, препоръчва се за създаване на връзка за вноски (ако се използва 3DS2, параметърът е задължителен).
Незадължително

features String Функции на поръчката. За да посочите няколко функции, използвайте този параметър няколко пъти в една заявка. По-долу са изброени възможните стойности.
  • 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, тогава поръчката ще бъде създадена САМО за създаване на връзка (без плащане).
Незадължително

orderBundle Object Обект, съдържащ кошницата с продукти. Описанието на вложените елементи е дадено по-долу.
Незадължително

dynamicCallbackUrl String [1..512] Параметър за предаване на динамичен адрес за получаване на "платежни" callback-уведомления за поръчката, активирани за търговеца (успешна авторизация, успешно списване, връщане, отказ, отхвърляне на плащане по таймаут, отхвърляне на card present плащане).
"Не платежни" callback-уведомления (включване/изключване на връзка, създаване на връзка), ще бъдат изпращани на статичен callback адрес.
Незадължително

threeDSServerTransId String [1..36] Идентификатор на транзакцията, създаден на 3DS сървъра. Задължителен за 3DS автентикация.
Незадължително

threeDSVer2FinishUrl String [1..512] URL-адрес, с който клиентът трябва да бъде пренасочен след автентификация на сървъра ACS.
Незадължително

threeDSMethodNotificationUrl String [1..512] URL-адрес за изпращане на уведомление за преминаване на проверката в ACS.
Условие

threeDSVer2MdOrder String [1..36] Номер на поръчка, който е регистриран в първата част от заявката в рамките на 3DS2 операция. Задължителен за удостоверяване 3DS.
Ако този параметър присъства в заявката, тогава се използва mdOrder, който се предава в настоящия параметър. В такъв случай регистрацията на поръчката не се извършва, а се извършва веднага плащането на поръчката.
Този параметър се предава само при използване на методи за мгновено плащане, т.е., когато поръчката се регистрира и се заплаща в рамките на една заявка.
Незадължително

threeDSSDK Boolean Възможни стойности: true или false Флаг, показващ, че плащането постъпва от 3DS SDK.
Незадължително

threeDSProtocolVersion String Версия на протокола 3DS. Възможни стойности: "2.1.0", "2.2.0" за 3DS2.
Ако в заявката не се предава threeDSProtocolVersion, то за оторизация 3D Secure ще се използва стойността по подразбиране (2.1.0 - за 3DS 2).
Незадължително

expiry Integer [6] Срок на валидност на картата в следния формат: YYYYMM. Задължително, ако не са предадени нито seToken, нито bindingId.
Условие

email String [1..40] Електронна поща за показване на страницата за плащане. Ако за продавача са настроени уведомления на клиента, електронната поща трябва да бъде посочена. Пример: client_mail@email.com.
За плащания с VISA с 3DS оторизация е необходимо да се посочи електронната поща или номера на телефона на притежателя на картата.
Незадължително

mcc Integer [4] Merchant Category Code (код на категория на търговеца). За предаване на този параметър е необходимо специално разрешение. Могат да се използват стойности само от разрешения списък MCC. За получаване на по-подробна информация се обърнете към техническата поддръжка.
Незадължително

tii String Идентификатор на инициатора на транзакцията. Параметър, указващ какъв тип операция ще изпълнява инициаторът (Клиент или Търговец). Възможни стойности
Условие

originalPaymentNetRefNum String Идентификатор на оригиналната или предишната успешна транзакция в платежната система по отношение на изпълняваната операция по връзката - TRN ID. Предава се, ако стойността на параметъра tii = R,U или F.
Задължителен при използване на връзките на търговеца в преводите по връзка.
Условие

originalPaymentDate String Дата на инициираща транзакция. Стойност във формат Unix timestamp в милисекунди. Предава се, ако стойността на параметъра tii = R,U или F.
Незадължително

externalScaExemptionIndicator String Тип на изключение SCA (Strong Customer Authentication). Ако е посочен този параметър, транзакцията ще бъде обработена в зависимост от вашите настройки в платежния шлюз: или ще бъде изпълнена принудителна операция SSL, или банката-издател ще получи информация за изключението SCA и ще вземе решение за провеждане на операцията с 3DS-автентификация или без нея (за получаване на подробна информация се свържете с нашата служба за поддръжка). Допустими стойности:
  • LVP – транзакция от тип Low Value Payments. Транзакцията може да бъде отнесена към транзакции с ниско ниво на риск въз основа на сумата на транзакцията, броя на транзакциите на клиента в деня или общата дневна сума на плащанията на клиента.
  • TRA – транзакция от тип Transaction Risk Analysis, т.е. транзакция, преминала успешна антифрод-проверка.

За предаване на този параметър трябва да имате достатъчни права в платежния шлюз.
Незадължително billingPayerData Object Блок с регистрационни данни на клиента (адрес, пощенски индекс), необходим за преминаване на проверка на адреса в рамките на услугите AVS/AVV. Задължително, ако функцията е включена за продавача от страна на Платежната шлюза. Вж. вложени параметри.
Незадължително shippingPayerData Object Обект, съдържащ данни за доставката до клиента. Този параметър се използва за по-нататъшна 3DS-автентификация на клиента. Вж. вложени параметри.
Незадължително preOrderPayerData Object Обект, съдържащ данни за предварителната поръчка. Този параметър се използва за по-нататъшна 3DS-автентификация на клиента. Вж. вложени параметри.
Незадължително orderPayerData Object Обект, съдържащ данни за платеца на поръчката. Този параметър се използва за по-нататъшна 3DS-автентификация на клиента. Вж. вложени параметри.
Незадължително

billingAndShippingAddressMatchIndicator String [1] Индикатор за съответствие на платежния адрес на притежателя на картата и адреса за доставка. Този параметър се използва за по-нататъшна 3DS-автентификация на клиента.
Възможни стойности:
  • Y - съвпадение на платежния адрес на притежателя на картата и адреса за доставка;
  • N - платежният адрес на притежателя на картата и адресът за доставка не съвпадат.

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

Задължителност Име Тип Описание
Незадължително

orderCreationDate String [19] Дата на създаване на поръчката във формат YYYY-MM-DDTHH:MM:SS.
Незадължително

customerDetails Object Блок, съдържащ атрибутите на клиента. Описанието на атрибутите на тага е дадено по-долу.
Задължително

cartItems Object Обект, съдържащ атрибутите на стоките в кошницата. Описанието на вложените елементи е дадено по-долу.

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

Задължителност Наименование Тип Описание
Незадължително

contact String [0..40] Предпочитан от клиента начин за връзка.
Незадължително fullName String [1..100] ФИО на платеца.
Незадължително

passport String [1..100] Серия и номер на паспорта на платеца в следния формат: 2222888888
Незадължително

deliveryInfo Object Обект, съдържащ атрибутите на адреса за доставка. Описанието на вложените елементи е приведено по-долу.

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

Задължителност Наименование Тип Описание
Незадължително

deliveryType String [1..20] Начин на доставка.
Задължително

country String [2] Двубуквен код на страната за доставка.
Задължително

city String [0..40] Град на назначение.
Задължително

postAddress String [1..255] Адрес за доставка.

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

Задължителност Наименование Тип Описание
Задължително

items Object Елемент на масив с атрибути на стокова позиция. Описанието на вложените елементи е дадено по-долу.

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

Задължителност Наименование Тип Описание
Задължително

positionId Integer [1..12] Уникален идентификатор на стоковата позиция в кошницата.
Задължително

name String [1..255] Наименование или описание на стокова позиция в свободна форма.
Незадължително

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

quantity Object Елемент, описващ общото количество стокови позиции на един positionId и неговите мерни единици. Описанието на вложените елементи е приведено по-долу.
Незадължително

itemAmount Integer [1..12] Сума на стойността на всички стокови позиции за един positionId в минимални единици валута. itemAmount е задължителен за предаване, само ако не е предаден параметърът itemPrice. В противен случай предаването на itemAmount не се изисква. Ако в заявката се предават и двата параметъра: itemPrice и itemAmount, то itemAmount трябва да се равнява на itemPrice * quantity, в противен случай заявката ще завърши с грешка.
Незадължително

itemPrice Integer [1..18] Сума на стойността на стоковата позиция на един positionId в пари в минимални единици валута.
Незадължително

depositedItemAmount String [1..18] Сума на списване за един positionId в минимални валутни единици (например, в стотинки).
Незадължително

itemCurrency Integer [3] Код на валута ISO 4217. Ако не е посочен, се счита равен на валутата на поръчката.
Задължително

itemCode String [1..100] Номер (идентификатор) на стокова позиция в системата на магазина.

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

Задължителност Название Тип Описание
Незадължително

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

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

Задължителност Наименование Тип Описание
Задължително

value String [1..2000] Допълнителна информация за товарната позиция.
Задължително

name String [1..255] Наименование на параметъра за описанието на детайлизацията на стоковата позиция

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

Задължителност Име Тип Описание
Задължително

value Number [1..18] Количество на стокови позиции от дадения positionId. За указване на дробни числа използвайте десетична точка. Допуска се максимум 3 знака след точката.
Задължително

measure String [1..20] Мерна единица за количеството по позицията.

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

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

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

Задължителност Наименование Тип Описание
Условие

billingCity String [0..50] Град, регистриран за конкретната карта в Банката Емитент. Задължително за Visa.
Условие

billingCountry String [0..50] Държава, регистрирана по конкретната карта на банката-издател. Формат: ISO 3166-1 (Alpha 2 / Alpha 3 / Number-3) или наименование на държавата. Препоръчваме да предавате двух/трибуквен ISO код на държавата. Задължително за Visa.
Условие

billingAddressLine1 String [0..50] Адрес, регистриран за конкретната карта в Банката Емитент (адрес на платеца). Ред 1. Задължително за предаване при AVS-проверка. Задължително за Visa.
Незадължително

billingAddressLine2 String [0..50] Адрес, регистриран за конкретната карта в Банката Емитент. Ред 2.
Незадължително

billingAddressLine3 String [0..50] Адрес, регистриран за конкретната карта в Банката Емитент. Ред 3.
Незадължително

billingPostalCode String [0..9] Пощенски код, регистриран за конкретната карта в Банката Издател. Задължително за предаване за AVS-проверка.
Незадължително

billingState String [0..50] Щат, регистриран за конкретната карта в Банката Емитент. Формат: пълна стойност на кода ISO 3166-2, негова част или наименование на щата/региона. Може да съдържа букви само от латинската азбука. Препоръчваме да се предава двубуквен ISO код на щата/региона.
Задължително

payerAccount String [1..32] Номер на сметката на изпращача.
Условие

payerLastName String [1..64] Фамилия на изпращача. Задължително за Visa.
Условие

payerFirstName String [1..35] Име на изпращача. Задължително за Visa.
Незадължително

payerMiddleName String [1..35] Бащино име на изпращача.
Незадължително

payerCombinedName String [1..99] Пълно име на подателя.
Незадължително

payerIdType String [1..8] Тип на предоставения идентифициращ документ на подателя.
Възможни стойности:
  • IDTP1 - Паспорт
  • IDTP2 - Шофьорска книжка
  • IDTP3 - Социална карта
  • IDTP4 - ID карта на гражданин
  • IDTP5 - Сертификат за водене на бизнес
  • IDTP6 - Сертификат на бежанец
  • IDTP7 - Разрешително за пребиваване
  • IDTP8 - Чужд паспорт
  • IDTP9 - Служебен паспорт
  • IDTP10 - Временен паспорт
  • IDTP11 - Паспорт на моряк
Незадължително

payerIdNumber String [1..99] Номер на предоставения идентифициращ документ на изпращача.
Условие

payerBirthday String [1..20] Дата на раждане на подателя във формат YYYYMMDD. Задължително за Visa.

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

Задължителност Наименование Тип Описание
Незадължително shippingCity String [1..50] Град на поръчителя (от адреса за доставка)
Незадължително shippingCountry String [1..50] Страна на поръчителя
Незадължително shippingAddressLine1 String [1..50] Основен адрес на клиента (от адреса за доставка)
Незадължително shippingAddressLine2 String [1..50] Основен адрес на клиента (от адреса за доставка)
Незадължително shippingAddressLine3 String [1..50] Основен адрес на клиента (от адреса за доставка)
Незадължително shippingPostalCode String [1..16] Пощенски код на клиента за доставка
Незадължително shippingState String [1..50] Щат/регион на купувача (от адреса за доставка)
Незадължително shippingMethodIndicator Integer [2] Индикатор за начин на доставка.
Възможни стойности:
  • 01 - доставка на платежния адрес на притежателя на карта.
  • 02 - доставка на друг адрес, проверен от Търговеца.
  • 03 - доставка на адрес, различен от основния адрес на притежателя на карта.
  • 04 - изпращане в магазин/самовземане (адресът на магазина трябва да бъде указан в съответните параметри за доставка)
  • 05 - Цифрово разпространение (включва онлайн услуги и електронни подаръчни карти)
  • 06 - билети за пътувания и събития, които не могат да бъдат доставени.
  • 07 - Други (например игри, цифрови стоки, които не подлежат на доставка, цифрови абонаменти и т.н.)
Незадължително deliveryTimeframe Integer [2] Срок за доставка на стоката.
Възможни стойности:
  • 01 - цифрова дистрибуция
  • 02 - доставка в същия ден
  • 03 - доставка на следващия ден
  • 04 - доставка в рамките на 2 дни след плащането и по-късно.
Незадължително deliveryEmail String [1..254] Целеви адрес на електронна поща за доставка на цифрово разпространение. Препоръчително е да предавате електронната поща в самостоятелен параметър на заявката email (но ако я предадете в този блок, към нея ще се прилагат същите правила).

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

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

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

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

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

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

Задължителност Название Тип Описание
Незадължително userAgent String [1..2048] Агент на браузъра.
Незадължително OS String Операционна система.
Незадължително OSVersion String Версия на операционната система.
Незадължително browserAcceptHeader String [1..2048] Заглавка Accept, която съобщава на сървъра какви формати (или MIME-типове) поддържа браузъра.
Незадължително browserIpAddress String [1..45] IP-адрес на браузъра.
Незадължително browserLanguage String [1..8] Език на браузъра.
Незадължително browserTimeZone String Часова зона на браузъра.
Незадължително browserTimeZoneOffset String [1..5] Отместване на часовата зона в минути между локалното време на потребителя и UTC.
Незадължително colorDepth String [1..2] Дълбочина на цвета на екрана, в битове.
Незадължително fingerprint String Отпечатък на браузъра - уникален цифров идентификатор на браузъра.
Незадължително isMobile Boolean Възможни стойности: true или false. Флаг, указващ, че се използва мобилно устройство.
Незадължително javaEnabled Boolean Възможни стойности: true или false. Флаг, указващ, че в браузъра е включена поддръжка на java.
Незадължително javascriptEnabled Boolean Възможни стойности: true или false. Флаг, указващ, че в браузъра е включена поддръжка на javascript.
Незадължително plugins String Списък на плъгините, използвани в браузъра, разделени със запетая.
Незадължително screenHeight Integer [1..6] Височина на екрана в пиксели.
Незадължително screenWidth Integer [1..6] Ширина на екрана в пиксели.
Незадължително screenPrint String Данни за параметрите на печат на браузъра, включително резолюция, дълбочина на цвета, плътност на пикселите.

Пример на блока clientBrowserInfo:

"clientBrowserInfo":
    {
        "userAgent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/111.0.0.0 Safari/537.36 Edg/111.0.1661.41",
        "fingerprint":850891523,
        "OS":"Windows",
        "OSVersion":"10",
        "isMobile":false,
        "screenPrint":"Current Resolution: 1536x864, Available Resolution: 1536x824, Color Depth: 24, Device XDPI: undefined, Device YDPI: undefined",
        "colorDepth":24,
        "screenHeight":"864",
        "screenWidth":"1536",
        "plugins":"PDF Viewer, Chrome PDF Viewer, Chromium PDF Viewer, Microsoft Edge PDF Viewer, WebKit built-in PDF",
        "javaEnabled":false,
        "javascriptEnabled":true,
        "browserLanguage":"it-IT",
        "browserTimeZone":"Europe/Rome",
        "browserTimeZoneOffset":-120,
        "browserAcceptHeader":"gzip",
        "browserIpAddress":"x.x.x.x"
    }

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

Задължителност Название Тип Описание
Задължително

errorCode String [1..2] Информационен параметър в случай на грешка, който може да има различни кодови стойности:
  • стойност 0 - указва успех на обработката;
  • друга положителна числова стойност - указва грешка, за получаване на по-подробна информация за която е необходимо да се провери параметърът error.
Може да отсъства, ако резултатът не е предизвикал грешки.
Незадължително

error String [1..512] Съобщение за грешка (ако в отговора се върна грешка) на езика, предаден в заявката.
Незадължително

orderId String [1..36] Номер на поръчката в платежния шлюз. Уникален в рамките на платежния шлюз.
Незадължително

info String В случай на успешен отговор. Резултат от опита за плащане. По-долу са приведени възможните стойности.
  • Вашето плащане е обработено, извършва се пренасочване...
  • Операцията е отхвърлена. Проверете въведените данни, достатъчността на средствата на картата и повторете операцията. Извършва се пренасочване...
  • Извинете, плащането не може да бъде извършено. Извършва се пренасочване...
  • Операцията е отхвърлена. Обърнете се към магазина. Извършва се пренасочване...
  • Операцията е отхвърлена. Обърнете се към банката, издала картата. Извършва се пренасочване...
  • Операцията е невъзможна. Удостоверяването на притежателя на картата завърши неуспешно. Извършва се пренасочване...
  • Няма връзка с банката. Повторете по-късно. Извършва се пренасочване...
  • Изтече срокът за изчакване на въвеждане на данни. Извършва се пренасочване...
  • Не е получен отговор от банката. Повторете по-късно. Извършва се пренасочване...
Незадължително

redirect String [1..512] Този параметър се връща, ако плащането е преминало успешно и за плащането не е извършвана проверка на картата за участие в 3-D Secure. Продавачите могат да го използват, ако искат да пренасочат потребителя към страницата на платежния шлюз. Ако продавачът използва собствена страница, тази стойност може да бъде игнорирана.
Незадължително

termUrl String [1..512] При успешен отговор в случай на плащане 3D-Secure. Това е URL-адрес, към който ACS пренасочва притежателя на картата след удостоверяване. Подробно вж. Пренасочване към ACS.
Незадължително

acsUrl String [1..512] При успешен отговор в случай на плащане 3D-Secure. URL-адрес за пренасочване към ACS. Задължителен, ако е необходимо пренасочване към ACS. За повече информация вижте Пренасочване към ACS.
Незадължително

paReq String [1..255] PAReq (Payment Authentication Request) — съобщение, което трябва да бъде изпратено в ACS заедно с пренасочването. Връща се при успешен отговор в случай на плащане 3D-Secure, ако е необходимо пренасочване към ACS. Това съобщение съдържа данни в кодировка Base64, необходими за автентификация на притежателя на картата. За повече подробности вижте Пренасочване към ACS.
Условие orderStatus Object Съдържа параметри на статуса на поръчката и се връща само в случай, че платежният шлюз разпознае всички параметри на заявката като правилни. Вж. описанието по-долу.

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

Задължителност Название Тип Описание
Задължително

is3DSVer2 Boolean Възможни стойности: true или false Флаг, показващ, че плащането постъпва от 3DS2.
Задължително

threeDSServerTransId String [1..36] Идентификатор на транзакцията, създаден на 3DS сървъра. Задължителен за 3DS автентикация.
Незадължително

threeDSMethodUrl String [1..512] URL-адрес на ACS сървъра за събиране на данни от браузъра.
Задължително

threeDSMethodUrlServer String [1..512] URL-адрес на 3DS сървъра за събиране на данни от браузъра, които ще бъдат включени в AReq (Authentication Request) от 3DS сървъра към ACS сървъра.
Незадължително

threeDSMethodDataPacked String [1..1024] Данни CReq (Challenge Response) в кодировка Base-64 за изпращане на сървър ACS.
Незадължително

threeDSMethodURLServerDirect String [1..512] URL адрес 3dsmethod.do за изпълнение на 3DS метода на 3DS сървъра чрез платежния шлюз (при наличие на съответното разрешение на ниво продавач).

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

Задължителност Название Тип Описание
Незадължително

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

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

Задължителност Название Тип Описание
Незадължително

ErrorCode String [1..2] Информационен параметър в случай на грешка, който може да има различни кодови стойности:
  • стойност 0 - указва успех на обработката;
  • друга числова стойност (1-99) - указва грешка, за получаване на по-подробна информация за която е необходимо да се провери параметърът ErrorMesage.
Може да отсъства, ако резултатът не е предизвикал грешки.
Незадължително

ErrorMessage String [1..512] Информационен параметър, представляващ описание на грешката в случай на възникване на грешка. Стойността на ErrorMessage може да варира, затова не трябва да се препраща изрично към неговите стойности в кода.
Езикът на описанието се задава в параметъра language на заявката.
Незадължително

OrderNumber String [1..36] Номер на поръчка (ID) в системата на търговеца; трябва да бъде уникален за всяка поръчка.
Незадължително

OrderStatus Integer Стойността на този параметър указва статуса на поръчката в платежната шлюз. Отсъства, ако поръчката не е била намерена. По-долу е приведен списък на достъпните стойности:
  • 0 - поръчката е регистрирана, но не е платена;
  • 1 - Предавторизираната сума е задържана (за двуетапни плащания);
  • 2 - проведена е пълна авторизация на сумата на поръчката;
  • 3 - авторизацията е отменена;
  • 4 - по транзакцията е била проведена операция връщане;
  • 5 - инициирана е авторизация чрез ACS на банката-емитент;
  • 6 - авторизацията е отхвърлена;
  • 7 - очакване на плащане на поръчката;
  • 8 - междинно завършване за многократно частично завършване.
Незадължително

expiration Integer [6] Срок на валидност на картата в следния формат: YYYYMM.
Незадължително

cardholderName String [1..26] Име на притежателя на картата (при наличие).
Незадължително

approvedAmount Integer [0..12] Сума в минимални единици валута (например, в центове), която е била блокирана на сметката на купувача. Използва се само в двуетапни плащания.
Незадължително

depositAmount Integer [1..12] Сума на списване в минимални единици валута (например, в стотинки).
Незадължително

currency String [3] Код на валутата на плащането ISO 4217. Ако не е посочен, се използва стойността по подразбиране. Позволени са само цифри.
Незадължително

approvalCode String [6] Код за оторизация на МПС. Това поле има фиксирана дължина (шест символа) и може да съдържа цифри и латински букви.
Незадължително

authCode Integer [6] Остарял параметър (не се използва). Неговата стойност винаги е 2 независимо от статуса на поръчката и кода за оторизация на процесинговата система.
Незадължително

Pan String [1..19] Маскиран номер на картата, която е използвана за плащане. Указва се само след плащането на поръчката. При плащане с Apple Pay се използва DPAN. Това е номер, свързан с мобилното устройство на купувача и изпълняващ функциите на номера на платежната карта в системата Apple Pay.
Незадължително

amount Integer [0..12] Сума на плащането в минимални единици валута (например, в стотинки).
Незадължително

Ip String [1..39] IP адрес на платеца. IPv6 се поддържа във всички заявки (до 39 символа).
Незадължително

originalActionCode String [1..15] Код на отговор, получен от процесинга. За да включите получаването на това поле, обърнете се към службата за техническа поддръжка.
Незадължително

rrn Integer [1..12] Reference Retrieval Number - идентификатор на транзакцията, присвоен от банката-акуайър.
Незадължително

paymentNetRefNum String [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={Номер на поръчка в платежния шлюз}

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

Задължителност Наименование Тип Описание
Задължително

orderId String [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

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

Задължителност Наименование Тип Описание
Задължително

merchant String [1..255] За да регистрирате и платите поръчка от името на друг търговец, посочете неговия логин (за API-акаунт) в този параметър.
Може да се използва само ако имате разрешение за преглед на транзакции на други продавачи или ако посоченият продавач е ваш дъщерен продавач.
Задължително

orderNumber String [1..36] Номер на поръчката (ID) в системата на търговеца; трябва да бъде уникален за всяка поръчка.
Незадължително

description String [1..598] Описание на поръчката в произволен формат.
За да включите изпращането на това поле в процесинговата система, обърнете се към службата за техническа поддръжка.
В това поле е недопустимо да се предават лични данни или платежни данни (номера на карти и т.н.). Това изискване се дължи на факта, че описанието на поръчката никъде не се маскира.
Незадължително

language String [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.
Незадължително

additionalParameters Object Допълнителни параметри на поръчката, които се съхраняват в личния кабинет на продавача за последващ преглед. Всяка нова двойка име на параметър и неговата стойност трябва да бъде разделена със запетая. По-долу е даден пример за използване.
{ "firstParamName": "firstParamValue", "secondParamName": "secondParamValue"}
При създаване на връзка в този таг могат да бъдат предадени параметри, определящи типа на създаваната връзка. Вж. списък на параметрите.
Незадължително

preAuth Boolean Параметър, определящ необходимостта от предварителна оторизация (блокиране на средства по сметката на клиента преди тяхното списване). Достъпни са следните стойности:
  • true - включено е двуетапно плащане;
  • false - включено е едноетапно плащане (парите се списват веднага).
Ако параметърът липсва, извършва се едноетапно плащане.
Незадължително

autocompletionDate String [19] Дата и време на автоматичното завършване на двуетапното плащане в следния формат: 2025-12-29T13:02:51. Използван часови пояс: UTC+0. За да включите изпращането на това поле в процесинговата система, обърнете се към службата за техническа поддръжка.
Незадължително

autoReverseDate String [19] Дата и час на автоматично анулиране на двуетапното плащане в следния формат: 2025-06-23T13:02:51. Използван часови пояс: UTC+0. За да включите изпращането на това поле в процесинговата система, обърнете се към службата за техническа поддръжка.
Задължително

paymentToken String [1..8192] Параметърът paymentToken трябва да съдържа разшифрованата и кодирана в Base64 стойност на свойството paymentData, получено от обекта PKPaymentToken Object от системата Apple Pay (за повече подробности вижте документацията на Apple Pay). По този начин, за да направи заявка за плащане към платежния шлюз, продавачът трябва да:
  1. получи PKPaymentToken Object, съдържащ paymentData от Apple Pay;
  2. извлече стойността на paymentData и я кодира в Base64;
  3. включи кодираната стойност на свойството paymentData като стойност на параметъра paymentToken в заявката за плащане, която продавачът ще изпрати към платежния шлюз.
Незадължително

tii String Идентификатор на инициатора на транзакцията. Параметър, указващ какъв тип операция ще изпълнява инициаторът (Клиент или Търговец). Възможни стойности.
Условие

clientId String [0..255] Номер на клиента (ID) в системата на търговеца — до 255 символа. Използва се за реализиране на функционалността на връзките. Може да се връща в отговора, ако на търговеца е разрешено да създава връзки.
Указването на този параметър при обработка на плащания по връзка е задължително. В противен случай плащането ще бъде невъзможно.
Условие

email String [1..40] Електронна поща за показване на страницата за плащане. Ако за продавача са настроени уведомления на клиента, електронната поща трябва да бъде посочена. Пример: client_mail@email.com.
За плащания с VISA с 3DS оторизация е необходимо да се посочи електронната поща или номера на телефона на притежателя на картата.
Незадължително

mcc Integer [4] Merchant Category Code (код на категория на търговеца). За предаване на този параметър е необходимо специално разрешение. Могат да се използват стойности само от разрешения списък MCC. За получаване на по-подробна информация се обърнете към техническата поддръжка.
Условие

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

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

threeDSProtocolVersion String Версия на протокола 3DS. Възможни стойности: "2.1.0", "2.2.0" за 3DS2.
Ако в заявката не се предава threeDSProtocolVersion, то за оторизация 3D Secure ще се използва стойността по подразбиране (2.1.0 - за 3DS 2).
Незадължително

externalScaExemptionIndicator String Тип на изключение SCA (Strong Customer Authentication). Ако е посочен този параметър, транзакцията ще бъде обработена в зависимост от вашите настройки в платежния шлюз: или ще бъде изпълнена принудителна операция SSL, или банката-издател ще получи информация за изключението SCA и ще вземе решение за провеждане на операцията с 3DS-автентификация или без нея (за получаване на подробна информация се свържете с нашата служба за поддръжка). Допустими стойности:
  • LVP – транзакция от тип Low Value Payments. Транзакцията може да бъде отнесена към транзакции с ниско ниво на риск въз основа на сумата на транзакцията, броя на транзакциите на клиента в деня или общата дневна сума на плащанията на клиента.
  • TRA – транзакция от тип Transaction Risk Analysis, т.е. транзакция, преминала успешна антифрод-проверка.

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

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

Задължителност Наименование Тип Описание
Условие

installments Integer [3] Максимален брой разрешени упълномощавания за плащания на вноски.
Посочва се в случай на създаване на връзка за извършване на плащания на вноски.
Условие

recurringFrequency Integer [2] Минимален брой дни между авторизациите. Цяло положително число от 1 до 28 включително.
Указва се в случай на създаване на връзка за изпълнение на рекурентни плащания.
Задължително за предаване в случай на създаване на връзка за изпълнение на плащания на вноски при включен 3DS2.
Условие

recurringExpiry String [8] Дата, след която по-нататъшни оторизации не трябва да се изпълняват. Формат: YYYYMMDD.
Указва се в случай на създаване на връзка за изпълнение на рекурентни плащания.
Задължително за предаване в случай на създаване на връзка за изпълнение на плащания на вноски при включен 3DS2.

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

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

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

Задължителност Наименование Тип Описание
Задължително

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

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

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

Задължителност Наименование Тип Описание
Задължително

orderId String [1..36] Номер на поръчката в платежния шлюз. Уникален в рамките на платежния шлюз.

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

Задължителност Наименование Тип Описание

code String [1..3] Код като информационен параметър, съобщаващ за грешка.

description String [1..598] Подробно техническо обяснение на грешката - съдържанието на този параметър не е предназначено за показване на потребителя.

message String [1..512] Информационен параметър, който представлява описание на грешката за показване на потребителя. Параметърът може да варира, затова не трябва да се прави експлицитна препратка към неговите стойности в кода.

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

Задължителност Наименование Тип Описание
Незадължително

errorCode String [1..2] Информационен параметър в случай на грешка, който може да има различни кодови стойности:
  • стойност 0 - указва успех при обработката на заявката;
  • друга числова стойност (1-99) - указва грешка, за получаване на по-подробна информация за която е необходимо да се провери параметърът errorMesage.__ HTML_5__
Може да отсъства, ако резултатът не е предизвикал грешки.
Незадължително

errorMessage String [1..512] Информационен параметър, който представлява описание на грешката в случай на възникване на грешка. Стойността на errorMessage може да варира, затова не трябва да се препраща изрично към неговите стойности в кода.
Езикът на описанието се задава в параметъра language на заявката.
Незадължително

orderNumber String [1..36] Номер на поръчката (ID) в системата на търговеца; трябва да бъде уникален за всяка поръчка.
Незадължително

orderStatus Integer Стойността на този параметър указва статуса на поръчката в платежния шлюз. Отсъства, ако поръчката не е била намерена. По-долу е приведен списък на наличните стойности:
  • 0 - поръчката е регистрирана, но не е платена;
  • 1 - поръчката е само авторизирана и още не е завършена (за двуетапните плащания);
  • 2 - поръчката е авторизирана и завършена;
  • 3 - авторизацията е отменена;
  • 4 - по транзакцията е била проведена операция възстановяване;
  • 5 - инициирана е авторизация чрез ACS на банката-емитент;
  • 6 - авторизацията е отхвърлена;
  • 7 - очакване на плащане на поръчки;
  • 8 - междинно завършване за многократно частично завършване.
Незадължително

actionCode Integer Код за отговор от процесинга на банката. Виж списъка с кодове за отговор тук.
Незадължително

actionCodeDescription String [1..512] Описание на actionCode, връщано от процесинга на банката.
Незадължително

amount Integer [0..12] Сума на плащането в минимални единици валута (например, в стотинки).
Незадължително

currency String [3] Код на валутата на плащането ISO 4217. Ако не е посочен, се използва стойността по подразбиране. Позволени са само цифри.
Незадължително

date Integer Дата на регистрация на поръчката като брой милисекунди, изминали от 00:00 GMT 1 януари 1970 година (Unix време). Пример: 1740392720718 (съответства на времето 24 февруари 2025 година, 10:25:20 (UTC)).
Незадължително

ip String [1..39] IP адрес на платеца. IPv6 се поддържа във всички заявки (до 39 символа).
Условие merchantOrderParams Object Обект с атрибути, в които се предават допълнителни параметри на търговеца. Вижте описанието по-долу.
Условие attributes Object Атрибути на поръчката в платежната система (номер на поръчката). Вижте описанието по-долу.
Условие cardAuthInfo Object Информация за платежната карта на купувача. Вижте описанието по-долу.
Незадължително

authDateTime Integer Дата и час на оторизация, показани като брой милисекунди, изминали от 00:00 GMT 1 януари 1970 година (Unix време). Пример: 1740392720718 (съответства на време 24 февруари 2025 година, 10:25:20 (UTC)).
Незадължително

terminalId String [1..10] Идентификатор на терминала в системата, обработваща плащането.
Незадължително

authRefNum String [1..24] Номер на авторизация на плащането, присвоен му при регистрация на плащането.
Условие paymentAmountInfo Object Параметър, съдържащ вложени параметри с информация за сумите на потвърждение, списване и възстановяване. Вижте описанието по-долу.
Условие bankInfo Object Съдържа вложения параметър bankCountryName. Вижте описанието по-долу.

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

Задължителност Наименование Тип Описание
Незадължително

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

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

Задължителност Наименование Тип Описание
Задължително

name String [1..255] Име на допълнителния параметър на търговеца.
Задължително

value String [1..1024] Стойност на допълнителния параметър на продавача - до 1024 символа.

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

Задължителност Наименование Тип Описание
Задължително

name String [1..255] Име на допълнителния параметър.
Задължително

value String [1..1024] Стойност на допълнителния параметър - до 1024 символа.

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

Задължителност Наименование Тип Описание
Задължително

expiration Integer [6] Срок на валидност на картата в следния формат: YYYYMM.
Задължително

cardholderName String [1..26] Име на притежателя на картата с латински букви. Допустими символи: латински букви, точка, интервал.
Задължително

approvalCode String [6] Код за оторизация на МПС. Това поле има фиксирана дължина (шест символа) и може да съдържа цифри и латински букви.
Задължително

pan String [1..19] Маскиран DPAN: номер, свързан с мобилното устройство на купувача и изпълняващ функциите на номер на платежна карта в системата Apple Pay.
Незадължително

detokenizedPanRepresentation String [1..19] Детокенизиран номер на карта (последните 4 цифри или в маскиран вид).
Незадължително

detokenizedPanExpiryDate String Детокенизиран срок на валидност на картата в следния формат: YYYYMM.

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

Задължителност Наименование Тип Описание
Задължително

paymentState String Състояние на поръчката, параметърът може да приема следните стойности:
  • CREATED - поръчката е създадена (но не е платена);
  • APPROVED - поръчката е одобрена (средствата по сметката на купувача са блокирани);
  • DEPOSITED - поръчката е завършена (парите са отписани от сметката на купувача);
  • DECLINED - поръчката е отхвърлена;
  • REVERSED - поръчката е отхвърлена;
  • REFUNDED - възстановяване на средства.
Задължително

approvedAmount Integer [0..12] Сума в минимални единици валута (например, в центове), която е била блокирана на сметката на купувача. Използва се само в двуетапни плащания.
Задължително

depositedAmount Integer [1..12] Сума на списване в минимални единици валута (например, в стотинки).
Задължително

refundedAmount Integer [1..12] Сума на възстановяване в минимални единици валута.

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

Задължителност Наименование Тип Описание
Задължително

bankCountryName String [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" : "eyJkYXRhIjoiYPhK3M1bEtm...YjM2NWMzZWNmYjE5fIkVDX3YxIn0=",
  "preAuth" : false
}'

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

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

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

Задължителност Наименование Тип Описание
Задължително

merchant String [1..255] За да регистрирате и платите поръчка от името на друг търговец, посочете неговия логин (за API-акаунт) в този параметър.
Може да се използва само ако имате разрешение за преглед на транзакции на други продавачи или ако посоченият продавач е ваш дъщерен продавач.
Задължително

orderNumber String [1..36] Номер на поръчката (ID) в системата на търговеца; трябва да бъде уникален за всяка поръчка.
Незадължително

description String [1..598] Описание на поръчката в произволен формат.
За да включите изпращането на това поле в процесинговата система, обърнете се към службата за техническа поддръжка.
В това поле е недопустимо да се предават лични данни или платежни данни (номера на карти и т.н.). Това изискване се дължи на факта, че описанието на поръчката никъде не се маскира.
Незадължително

language String [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.
Незадължително

additionalParameters Object Допълнителни параметри на поръчката, които се съхраняват в личния кабинет на продавача за последващ преглед. Всяка нова двойка от име на параметър и неговата стойност трябва да бъде разделена със запетая. По-долу е приведен пример за използване.
{ "firstParamName": "firstParamValue", "secondParamName": "secondParamValue"}
При създаване на връзка в този таг могат да бъдат предадени параметри, определящи типа на създаваната връзка. Вж. списък на параметрите.
Незадължително

preAuth Boolean Параметър, определящ необходимостта от предварителна оторизация (блокиране на средства по сметката на клиента преди тяхното списване). Достъпни са следните стойности:
  • true - включено е двуетапно плащане;
  • false - включено е едноетапно плащане (парите се списват веднага).
Ако параметърът липсва, извършва се едноетапно плащане.
Незадължително

autocompletionDate String [19] Дата и време на автоматичното завършване на двуетапното плащане в следния формат: 2025-12-29T13:02:51. Използван часови пояс: UTC+0. За да включите изпращането на това поле в процесинговата система, обърнете се към службата за техническа поддръжка.
Незадължително

autoReverseDate String [19] Дата и час на автоматично анулиране на двуетапното плащане в следния формат: 2025-06-23T13:02:51. Използван часови пояс: UTC+0. За да включите изпращането на това поле в процесинговата система, обърнете се към службата за техническа поддръжка.
Задължително

clientId String [0..255] Номер на клиента (ID) в системата на търговеца — до 255 символа. Използва се за реализиране на функционалността на връзките. Може да се връща в отговора, ако на търговеца е разрешено да създава връзки.
Указването на този параметър при обработка на плащания по връзка е задължително. В противен случай плащането ще бъде невъзможно.
Незадължително

tii String Идентификатор на инициатора на транзакцията. Параметър, указващ какъв тип операция ще изпълнява инициаторът (Клиент или Търговец). Възможни стойности.
Задължително

paymentToken String [1..8192] Токен, получен от Google Pay и кодиран в Base64.
Задължително

ip String [1..39] IP адрес на платеца. IPv6 се поддържа във всички заявки (до 39 символа).
Задължително

amount Integer [0..12] Сума на плащането в минимални единици валута (например, в стотинки).
Незадължително

currencyCode String [3] Цифров код на валутата за плащане ISO 4217.
Задължително

returnUrl String [1..512] Адрес, към който трябва да бъде пренасочен потребителят в случай на успешно плащане. Адресът трябва да бъде указан изцяло, включително използвания протокол (например, https://mybestmerchantreturnurl.com вместо mybestmerchantreturnurl.com). В противен случай потребителят ще бъде пренасочен на адрес от следния вид: https://uat.dskbank.bg/payment/<merchant_address>.
Незадължително

failUrl String [1..512] Адрес, на който трябва да се пренасочи потребителят в случай на неуспешно плащане. Адресът трябва да бъде посочен напълно, включително използвания протокол (например, https://mybestmerchantreturnurl.com вместо mybestmerchantreturnurl.com). В противен случай потребителят ще бъде пренасочен по адрес от следния вид: https://uat.dskbank.bg/payment/<merchant_address>.
Незадължително

dynamicCallbackUrl String [1..512] Параметър за предаване на динамичен адрес за получаване на "платежни" callback-уведомления за поръчката, активирани за търговеца (успешна авторизация, успешно списване, връщане, отказ, отхвърляне на плащане по таймаут, отхвърляне на card present плащане).
"Не платежни" callback-уведомления (включване/изключване на връзка, създаване на връзка), ще бъдат изпращани на статичен callback адрес.
Условие

email String [1..40] Електронна поща за показване на страницата за плащане. Ако за продавача са настроени уведомления на клиента, електронната поща трябва да бъде посочена. Пример: client_mail@email.com.
За плащания с VISA с 3DS оторизация е необходимо да се посочи електронната поща или номера на телефона на притежателя на картата.
Незадължително

mcc Integer [4] Merchant Category Code (код на категория на търговеца). За предаване на този параметър е необходимо специално разрешение. Могат да се използват стойности само от разрешения списък MCC. За получаване на по-подробна информация се обърнете към техническата поддръжка.
Незадължително billingPayerData Object Блок с регистрационни данни на клиента (адрес, пощенски индекс), необходим за преминаване на проверка на адреса в рамките на услугите AVS/AVV. Задължително, ако функцията е включена за търговеца от страна на Платежната шлюз. Вж. вложени параметри.
Незадължително shippingPayerData Object Обект, съдържащ данни за доставка до клиента. Този параметър се използва за по-нататъшна 3DS-автентификация на клиента. Вж. вложени параметри.
Незадължително preOrderPayerData Object Обект, съдържащ данни за предварителна поръчка. Този параметър се използва за по-нататъшна 3DS-автентификация на клиента. Вж. вложени параметри.
Незадължително orderPayerData Object Обект, съдържащ данни за платеца на поръчката. Този параметър се използва за по-нататъшна 3DS-автентификация на клиента. Вж. вложени параметри.
Незадължително

billingAndShippingAddressMatchIndicator String [1] Индикатор за съответствие на платежния адрес на притежателя на картата и адреса за доставка. Този параметър се използва за по-нататъшна 3DS-автентификация на клиента.
Възможни стойности:
  • Y - съвпадение на платежния адрес на притежателя на картата и адреса за доставка;
  • N - платежният адрес на притежателя на картата и адресът за доставка не съвпадат.
Незадължително

clientBrowserInfo Object Блок данни за браузъра на клиента, който се изпраща на ACS по време на 3DS удостоверяване. Този блок може да се предава, само ако е включена специална настройка (обърнете се към екипа за поддръжка). Вж. вложени параметри.

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

Задължителност Наименование Тип Описание
Условие

threeDSServerTransId String [1..36] Идентификатор на транзакцията, създаден на 3DS сървъра. Задължителен за 3DS автентикация.
Незадължително

threeDSVer2FinishUrl String [1..512] URL-адрес, с който клиентът трябва да бъде пренасочен след автентификация на сървъра ACS.
Незадължително

threeDSMethodNotificationUrl String [1..512] URL-адрес за изпращане на уведомление за преминаване на проверката в ACS.

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

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

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

Задължителност Наименование Тип Описание
Условие

installments Integer [3] Максимален брой разрешени упълномощавания за плащания на вноски.
Посочва се в случай на създаване на връзка за извършване на плащания на вноски.
Условие

recurringFrequency Integer [2] Минимален брой дни между авторизациите. Цяло положително число от 1 до 28 включително.
Указва се в случай на създаване на връзка за изпълнение на рекурентни плащания.
Задължително за предаване в случай на създаване на връзка за изпълнение на плащания на вноски при включен 3DS2.
Условие

recurringExpiry String [8] Дата, след която по-нататъшни оторизации не трябва да се изпълняват. Формат: YYYYMMDD.
Указва се в случай на създаване на връзка за изпълнение на рекурентни плащания.
Задължително за предаване в случай на създаване на връзка за изпълнение на плащания на вноски при включен 3DS2.

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

Задължителност Наименование Тип Описание
Условие

billingCity String [0..50] Град, регистриран за конкретната карта в Банката Емитент. Задължително за Visa.
Условие

billingCountry String [0..50] Държава, регистрирана по конкретната карта на банката-издател. Формат: ISO 3166-1 (Alpha 2 / Alpha 3 / Number-3) или наименование на държавата. Препоръчваме да предавате двух/трибуквен ISO код на държавата. Задължително за Visa.
Условие

billingAddressLine1 String [0..50] Адрес, регистриран за конкретната карта в Банката Емитент (адрес на платеца). Ред 1. Задължително за предаване при AVS-проверка. Задължително за Visa.
Незадължително

billingAddressLine2 String [0..50] Адрес, регистриран за конкретната карта в Банката Емитент. Ред 2.
Незадължително

billingAddressLine3 String [0..50] Адрес, регистриран за конкретната карта в Банката Емитент. Ред 3.
Незадължително

billingPostalCode String [0..9] Пощенски код, регистриран за конкретната карта в Банката Издател. Задължително за предаване за AVS-проверка.
Незадължително

billingState String [0..50] Щат, регистриран за конкретната карта в Банката Емитент. Формат: пълна стойност на кода ISO 3166-2, негова част или наименование на щата/региона. Може да съдържа букви само от латинската азбука. Препоръчваме да се предава двубуквен ISO код на щата/региона.
Задължително

payerAccount String [1..32] Номер на сметката на изпращача.
Условие

payerLastName String [1..64] Фамилия на изпращача. Задължително за Visa.
Условие

payerFirstName String [1..35] Име на изпращача. Задължително за Visa.
Незадължително

payerMiddleName String [1..35] Бащино име на изпращача.
Незадължително

payerCombinedName String [1..99] Пълно име на подателя.
Незадължително

payerIdType String [1..8] Тип на предоставения идентифициращ документ на подателя.
Възможни стойности:
  • IDTP1 - Паспорт
  • IDTP2 - Шофьорска книжка
  • IDTP3 - Социална карта
  • IDTP4 - ID карта на гражданин
  • IDTP5 - Сертификат за водене на бизнес
  • IDTP6 - Сертификат на бежанец
  • IDTP7 - Разрешително за пребиваване
  • IDTP8 - Чужд паспорт
  • IDTP9 - Служебен паспорт
  • IDTP10 - Временен паспорт
  • IDTP11 - Паспорт на моряк
Незадължително

payerIdNumber String [1..99] Номер на предоставения идентифициращ документ на изпращача.
Условие

payerBirthday String [1..20] Дата на раждане на подателя във формат YYYYMMDD. Задължително за Visa.

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

Задължителност Наименование Тип Описание
Незадължително shippingCity String [1..50] Град на поръчителя (от адреса за доставка)
Незадължително shippingCountry String [1..50] Страна на поръчителя
Незадължително shippingAddressLine1 String [1..50] Основен адрес на клиента (от адреса за доставка)
Незадължително shippingAddressLine2 String [1..50] Основен адрес на клиента (от адреса за доставка)
Незадължително shippingAddressLine3 String [1..50] Основен адрес на клиента (от адреса за доставка)
Незадължително shippingPostalCode String [1..16] Пощенски код на клиента за доставка
Незадължително shippingState String [1..50] Щат/регион на купувача (от адреса за доставка)
Незадължително shippingMethodIndicator Integer [2] Индикатор за начин на доставка.
Възможни стойности:
  • 01 - доставка на платежния адрес на притежателя на карта.
  • 02 - доставка на друг адрес, проверен от Търговеца.
  • 03 - доставка на адрес, различен от основния адрес на притежателя на карта.
  • 04 - изпращане в магазин/самовземане (адресът на магазина трябва да бъде указан в съответните параметри за доставка)
  • 05 - Цифрово разпространение (включва онлайн услуги и електронни подаръчни карти)
  • 06 - билети за пътувания и събития, които не могат да бъдат доставени.
  • 07 - Други (например игри, цифрови стоки, които не подлежат на доставка, цифрови абонаменти и т.н.)
Незадължително deliveryTimeframe Integer [2] Срок за доставка на стоката.
Възможни стойности:
  • 01 - цифрова дистрибуция
  • 02 - доставка в същия ден
  • 03 - доставка на следващия ден
  • 04 - доставка в рамките на 2 дни след плащането и по-късно.
Незадължително deliveryEmail String [1..254] Целеви адрес на електронна поща за доставка на цифрово разпространение. Препоръчително е да предавате електронната поща в самостоятелен параметър на заявката email (но ако я предадете в този блок, към нея ще се прилагат същите правила).

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

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

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

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

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

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

Задължителност Название Тип Описание
Незадължително userAgent String [1..2048] Агент на браузъра.
Незадължително OS String Операционна система.
Незадължително OSVersion String Версия на операционната система.
Незадължително browserAcceptHeader String [1..2048] Заглавка Accept, която съобщава на сървъра какви формати (или MIME-типове) поддържа браузъра.
Незадължително browserIpAddress String [1..45] IP-адрес на браузъра.
Незадължително browserLanguage String [1..8] Език на браузъра.
Незадължително browserTimeZone String Часова зона на браузъра.
Незадължително browserTimeZoneOffset String [1..5] Отместване на часовата зона в минути между локалното време на потребителя и UTC.
Незадължително colorDepth String [1..2] Дълбочина на цвета на екрана, в битове.
Незадължително fingerprint String Отпечатък на браузъра - уникален цифров идентификатор на браузъра.
Незадължително isMobile Boolean Възможни стойности: true или false. Флаг, указващ, че се използва мобилно устройство.
Незадължително javaEnabled Boolean Възможни стойности: true или false. Флаг, указващ, че в браузъра е включена поддръжка на java.
Незадължително javascriptEnabled Boolean Възможни стойности: true или false. Флаг, указващ, че в браузъра е включена поддръжка на javascript.
Незадължително plugins String Списък на плъгините, използвани в браузъра, разделени със запетая.
Незадължително screenHeight Integer [1..6] Височина на екрана в пиксели.
Незадължително screenWidth Integer [1..6] Ширина на екрана в пиксели.
Незадължително screenPrint String Данни за параметрите на печат на браузъра, включително резолюция, дълбочина на цвета, плътност на пикселите.

Пример на блока clientBrowserInfo:

"clientBrowserInfo":
    {
        "userAgent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/111.0.0.0 Safari/537.36 Edg/111.0.1661.41",
        "fingerprint":850891523,
        "OS":"Windows",
        "OSVersion":"10",
        "isMobile":false,
        "screenPrint":"Current Resolution: 1536x864, Available Resolution: 1536x824, Color Depth: 24, Device XDPI: undefined, Device YDPI: undefined",
        "colorDepth":24,
        "screenHeight":"864",
        "screenWidth":"1536",
        "plugins":"PDF Viewer, Chrome PDF Viewer, Chromium PDF Viewer, Microsoft Edge PDF Viewer, WebKit built-in PDF",
        "javaEnabled":false,
        "javascriptEnabled":true,
        "browserLanguage":"it-IT",
        "browserTimeZone":"Europe/Rome",
        "browserTimeZoneOffset":-120,
        "browserAcceptHeader":"gzip",
        "browserIpAddress":"x.x.x.x"
    }

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

Задължителност Наименование Тип Описание
Задължително

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

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

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

Задължителност Наименование Тип Описание
Задължително

orderId String [1..36] Номер на поръчката в платежния шлюз. Уникален в рамките на платежния шлюз.
Незадължително

termUrl String [1..512] При успешен отговор в случай на плащане 3D-Secure. Това е URL-адрес, към който ACS пренасочва притежателя на картата след удостоверяване. Подробно вж. Пренасочване към ACS.
Незадължително

acsUrl String [1..512] При успешен отговор в случай на плащане 3D-Secure. URL-адрес за пренасочване към ACS. Задължителен, ако е необходимо пренасочване към ACS. За повече информация вижте Пренасочване към ACS.
Незадължително

paReq String [1..255] PAReq (Payment Authentication Request) — съобщение, което трябва да бъде изпратено в ACS заедно с пренасочването. Връща се при успешен отговор в случай на плащане 3D-Secure, ако е необходимо пренасочване към ACS. Това съобщение съдържа данни в кодировка Base64, необходими за автентификация на притежателя на картата. За повече подробности вижте Пренасочване към ACS.
Незадължително

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

detokenizedPanRepresentation String [1..19] Детокенизиран номер на карта (последните 4 цифри или в маскиран вид).
Незадължително

detokenizedPanExpiryDate String Детокенизиран срок на валидност на картата в следния формат: YYYYMM.

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

Задължителност Наименование Тип Описание
Незадължително

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

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

Задължителност Наименование Тип Описание
Задължително

is3DSVer2 Boolean Възможни стойности: true или false Флаг, показващ, че плащането постъпва от 3DS2.
Задължително

threeDSServerTransId String [1..36] Идентификатор на транзакцията, създаден на 3DS сървъра. Задължителен за 3DS автентикация.
Незадължително

threeDSMethodUrl String [1..512] URL-адрес на ACS сървъра за събиране на данни от браузъра.
Задължително

threeDSMethodUrlServer String [1..512] URL-адрес на 3DS сървъра за събиране на данни от браузъра, които ще бъдат включени в AReq (Authentication Request) от 3DS сървъра към ACS сървъра.
Незадължително

threeDSMethodDataPacked String [1..1024] Данни CReq (Challenge Response) в кодировка Base-64 за изпращане на сървър ACS.
Незадължително

threeDSMethodURLServerDirect String [1..512] URL адрес 3dsmethod.do за изпълнение на 3DS метода на 3DS сървъра чрез платежния шлюз (при наличие на съответното разрешение на ниво продавач).

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

Задължителност Наименование Тип Описание
Задължително

code String [1..3] Код като информационен параметър, съобщаващ за грешка.
Задължително

message String [1..512] Информационен параметър, който представлява описание на грешката за показване на потребителя. Параметърът може да варира, затова не трябва да се прави експлицитна препратка към неговите стойности в кода.
Задължително

description String [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": "eyJtZXJjaGFudCI6ICJrdXBpdmlwIiwib3JkZXJOdW1iZXIiOiAyMDUxOTIzMzkxLCJwYXltZW50VG9rZW4iOiAie1wiZXBoZW1lcmFsUHVibGljS2V5XCI6XCJrZXlcIixcImVuY3J5cHRlZE1lc3NhZ2VcIjpcIm1lc3NhZ2VcIixcInRhZ1wiOlwidGFnXCJ9In0=",
  "ip" : "127.0.0.1",
  "amount" : "230000",
  "currencyCode" : 643,
  "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

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

Задължителност Наименование Тип Описание
Да

userName String [1..100] Логин на профила API на продавача.
Да

password String [1..30] Парола на API акаунта на продавача.
Да

orderId String [1..36] Номер на поръчката в платежния шлюз. Уникален в рамките на платежния шлюз.
Не

language String [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.

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

Задължителност Наименование Тип Описание
Не

ErrorCode String [1..2] Информационен параметър в случай на грешка, който може да има различни кодови стойности:
  • стойност 0 - указва успех на обработката;
  • друга числова стойност (1-99) - указва грешка, за получаване на по-подробна информация за която е необходимо да се провери параметърът errorMesage.
Може да отсъства, ако резултатът не е предизвикал грешки.
Не

ErrorMessage String [1..512] Информационен параметър, който представлява описание на грешката в случай на възникване на грешка. Стойността на errorMessage може да варира, поради което не следва да се позовавате изрично на нейните стойности в кода.
Езикът на описанието се задава в параметъра language на заявката.
Да

orderNumber String [1..36] Номер на поръчката (ID) в системата на търговеца; трябва да бъде уникален за всеки търговец.
Не

orderStatus Integer Стойността на този параметър указва статуса на поръчката в платежния gateway. Отсъства, ако поръчката не е била намерена. По-долу е приведен списък на наличните стойности:
  • 0 - поръчката е регистрирана, но не е платена;
  • 1 - Предавторизираната сума е задържана (за двуетапни плащания);
  • 2 - проведена е пълна авторизация на сумата на поръчката;
  • 3 - авторизацията е отменена;
  • 4 - по транзакцията е проведена операция възстановяване;
  • 5 - инициирана е авторизация чрез ACS на банката-издател;
  • 6 - авторизацията е отхвърлена.
Да

amount Integer [0..12] Сума на плащането в минимални единици валута (например, в стотинки).
Не

currency String [3] Код на валутата на плащането ISO 4217. Ако не е посочен, се използва стойността по подразбиране. Позволени са само цифри.
Не

Ip String [1..39] IP адрес на платеца. IPv6 се поддържа във всички заявки (до 39 символа).
Не

Pan String [1..19] Маскиран номер на картата, която е използвана за плащане. Указва се само след плащането на поръчката. При плащане с Apple Pay се използва DPAN. Това е номер, свързан с мобилното устройство на купувача и изпълняващ функциите на номера на платежната карта в системата Apple Pay.
Не

expiration Integer [6] Срок на валидност на картата в следния формат: YYYYMM.
Не

cardholderName String [1..26] Име на притежателя на картата с латински букви. Допустими символи: латински букви, точка, интервал.
Не

approvalCode String [6] Код за оторизация на МПС. Това поле има фиксирана дължина (шест символа) и може да съдържа цифри и латински букви.
Не

depositedAmount Integer [1..12] Сума на списване в минимални единици валута (например, в стотинки).
Не

clientId String [0..255] Номер на клиента (ID) в системата на търговеца — до 255 символа. Използва се за реализиране на функционалността на връзките. Може да се връща в отговора, ако на търговеца е разрешено да създава връзки.
Указването на този параметър при обработка на плащания по връзка е задължително. В противен случай плащането ще бъде невъзможно.
Не

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

paymentNetRefNum String [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

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

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

Задължителност Наименование Тип Описание
Условие

userName String [1..30] Логин на потребителския акаунт API на продавача. Ако за автентификация при регистрация вместо логин и парола се използва открит токен (параметър token), паролата не трябва да се предава.
Условие

password String [1..30] Парола на API акаунта на продавача. Ако за удостоверяване при регистрация вместо логин и парола се използва открит токен (параметър token), паролата не е необходимо да се предава.
Условие

token String [1..256] Стойност, използвана за автентификация на продавача при изпращане на заявки към платежната шлюз. Ако предавате този параметър, то не предавайте userName и password.
Условие

orderId String [1..36] Номер на поръчка в платежния шлюз. Уникален в рамките на платежния шлюз.
Условие

orderNumber String [1..36] Номер на поръчката (ID) в системата на търговеца; трябва да бъде уникален за всеки търговец.
Незадължително

language String [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.
Незадължително

merchantLogin String [1..255] За да получите статуса на поръчката на определен търговец вместо текущия потребител, посочете логина на търговеца (за API-акаунт).
Може да се използва само ако имате разрешение за преглед на транзакциите на други продавачи или ако посоченият продавач е ваш дъщерен продавач.

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

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

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

Версия Добавени параметри
1 orderBundle
2
  • authDateTime
  • terminalId
  • authRefNum
3
  • paymentAmountInfo->approvedAmount, depositedAmount, paymentState, refundedAmount
  • bankInfo->bankCountryCode, bankCountryName, bankName
4 Няма промени
5 refunds
6 chargeback
7 cardAuthInfo->secureAuthInfo->paResStatus, veResStatus, paResCheckStatus
8 cardAuthInfo->paymentSystem, product
9 paymentWay
10 depositedDate
11 Няма промени
12
  • refundedDate
  • reversedDate
13 payerData->email,phone,postAddress
14 transactionAttributes
15
  • prepaymentMdOrder
  • partpaymentMdOrders
16 feUtrnno
17 cardAuthInfo->productCategory
18 totalAmount
19 avsCode
20 bindingInfo->externalCreated
21 refunds->externalRefundId
22 Няма промени
23 efectyOrderInfo
24 ofdOrderBundle
25 Няма промени
26 refunds->approvalCode
27 authRefNum
28 pluginInfo
29 Няма промени
30 cardAuthInfo->secureAuthInfo->aResTransStatus, rReqTransStatus, threeDsProtocolVersion
31 Няма промени
32 Няма промени
33 displayErrorMessage
34 orderBundle->cartItems->items->depostedItemAmount,itemPrice
35 cardAuthInfo->corporateCard
36 Няма промени
37
  • tii
  • usedPsdIndicatorValue
38 payerData ->paymentAccountReference
39 cardAuthInfo -> detokenizedPanRepresentation, detokenizedPanExpiryDate
40 Няма промени
41 Няма промени
42 cardAuthInfo->secureAuthInfo->threeDsType
43 Не са добавени нови параметри. Изтрити: cardAuthInfo->secureAuthInfo-> authTypeIndicator
Версия Задължителност Название Тип Описание
Всички Незадължително

errorCode String [1..2] Информационен параметър в случай на грешка, който може да има различни кодови стойности:
  • стойност 0 - указва успех на обработката;
  • друга числова стойност (1-99) - указва грешка, за получаване на по-подробна информация за която е необходимо да се провери параметърът errorMesage.
Може да отсъства, ако резултатът не е предизвикал грешки.
Всички Незадължително

errorMessage String [1..512] Информационен параметър, който представлява описание на грешката в случай на възникване на грешка. Стойността на errorMessage може да варира, затова не трябва да се препраща изрично към неговите стойности в кода.
Езикът на описанието се задава в параметъра language на заявката.
Всички Условие

orderNumber String [1..36] Номер на поръчка (ID) в системата на търговеца, трябва да бъде уникален за всеки търговец, регистриран в платежния шлюз. Ако номерът на поръчката се генерира от страната на платежния шлюз, този параметър не е задължително да се предава.
Всички Незадължително

orderStatus Integer Стойността на този параметър указва статуса на поръчката в платежния шлюз. Отсъства, ако поръчката не е била намерена. По-долу е приведен списък на наличните стойности:
  • 0 - поръчката е регистрирана, но не е платена;
  • 1 - поръчката е само авторизирана и още не е завършена (за двуетапните плащания);
  • 2 - поръчката е авторизирана и завършена;
  • 3 - авторизацията е отменена;
  • 4 - по транзакцията е била проведена операция възстановяване;
  • 5 - инициирана е авторизация чрез ACS на банката-емитент;
  • 6 - авторизацията е отхвърлена;
  • 7 - очакване на плащане на поръчки;
  • 8 - междинно завършване за многократно частично завършване.
Всички Задължително

actionCode Integer Код за отговор от процесинга на банката. Виж списъка с кодове за отговор тук.
Всички Задължително

actionCodeDescription String [1..512] Описание на actionCode, връщано от процесинга на банката.
Всички Задължително

amount Integer [0..12] Сума на плащането в минимални единици валута (например, в стотинки).
Всички Незадължително

currency String [3] Код на валутата на плащането ISO 4217. Ако не е посочено, се използва стойността по подразбиране.
Всички Задължително

date Integer Дата на регистрация на поръчката като брой милисекунди, изминали от 00:00 GMT 1 януари 1970 година (Unix време). Пример: 1740392720718 (съответства на времето 24 февруари 2025 година, 10:25:20 (UTC)).
10+ Незадължително

depositedDate Integer Дата на плащане на поръчката като брой милисекунди, изминали от 00:00 GMT 1 януари 1970 година (Unix време). Пример: 1740392720718 (съответства на времето 24 февруари 2025 година, 10:25:20 (UTC)).
Всички Незадължително

orderDescription String [1..600] Описание на поръчката, предавано на платежния шлюз при регистрация.
В това поле не е допустимо да се предават персонални данни или платежни данни (номера на карти и т.н.). Това изискване е свързано с факта, че описанието на поръчката никъде не се маскира.
Всички Задължително

ip String [1..39] IP адрес на платеца. IPv6 се поддържа във всички заявки (до 39 символа).
27+ Незадължително

authRefNum String [1..24] Номер на авторизация на плащането, присвоен му при регистрация на плащането.
12+, задължително от 27 Незадължително

refundedDate Integer Дата и час на възстановяването, показани като брой милисекунди, изминали от 00:00 GMT 1 януари 1970 година (Unix време). Пример: 1740392720718 (съответства на времето 24 февруари 2025 година, 10:25:20 (UTC)).
12+ Незадължително

reversedDate Integer Дата и час на отмяната на плащането, показани като брой милисекунди, изминали от 00:00 GMT 1 януари 1970 година (Unix време). Пример: 1740392720718 (съответства на време 24 февруари 2025 година, 10:25:20 (UTC)).
09+ Задължително

paymentWay String Начин на извършване на плащане (плащане с въвеждане на данни от карта, плащане чрез връзка и т.н.). Допълнителни възможни стойности на параметъра са посочени по-долу
19+ Незадължително

avsCode String Код на отговор за верификация AVS (проверка на адрес и пощенски код на притежателя на карта). Възможни стойности:
  • A – пощенският код и адресът съвпадат.
  • B – адресът съвпада, пощенският код не съвпада.
  • C - пощенският код съвпада, адресът не съвпада.
  • D - пощенският код и адресът не съвпадат.
  • E - заявена е проверка на данни, но резултатът е неуспешен.
  • F - некоректен формат на заявка за AVS/AVV проверка.
06+ Незадължително

chargeback Boolean Дали средствата са били принудително върнати на купувача от банката. Възможни стойности:
  • true - средствата са били върнати;
  • false - средствата не са били върнати.
02+ Незадължително

authDateTime Integer Дата и час на оторизация, показани като брой милисекунди, изминали от 00:00 GMT 1 януари 1970 година (Unix време). Пример: 1740392720718 (съответства на време 24 февруари 2025 година, 10:25:20 (UTC)).
02+ Незадължително

terminalId String [1..10] Идентификатор на терминала в системата, обработваща плащането.
01+ Незадължително

orderBundle Object Обект, съдържащ кошницата с продукти. Описанието на вложените елементи е дадено по-долу.
03+ Незадължително

paymentAmountInfo Object Обект с информация за сумите на потвърждение, списване, възстановяване. Списък на вложените параметри вж. по-долу.
05+ Незадължително

refunds Object Обект, съдържащ информация за възстановяване на средства. Присъства само при наличие на възстановявания в поръчката. Описанието на вложените елементи е дадено по-долу.
Всички Незадължително

cardAuthInfo Object Блок с данни за картата на платеца. Описанието на вложените елементи е приведено по-долу.
14+ Незадължително

transactionAttributes Object Набор от допълнителни атрибути на транзакцията. Списък на вложените параметри вж. по-долу.
15+ Незадължително

prepaymentMdOrder String Номер на предхождащата поръчка за предплащане в платежната шлюза.
15+ Незадължително

partpaymentMdOrders Array of String Масив от последващи поръчки за частично плащане.
16+ Незадължително

feUtrnno Integer [1..18] Номер на транзакция FE.
Всички Незадължително

bindingInfo Object Обект, съдържащ информация за връзката, по която се осъществява плащането. Вж. таблицата с описанието на bindingInfo.
23+ Незадължително

efectyOrderInfo Object Блок параметри, свързани с платежния метод EFECTY. Описанието на вложените елементи е дадено по-долу.
28+ Незадължително

pluginInfo Object Присъства в отговора, ако плащането е било извършено чрез платежен plugin. Вж. вложените параметри по-долу.
33+ Незадължително

displayErrorMessage String Показвано съобщение за грешка.
37+ Незадължително

tii String Идентификатор на инициатора на транзакцията. Параметър, указващ какъв тип операция ще изпълнява инициаторът (Клиент или Търговец). Описанието на вложените елементи е дадено по-долу.
37+ Незадължително

usedPsdIndicatorValue String Тип изключение SCA (Strong Customer Authentication). Съдържа стойност, предадена при плащане на поръчката в параметъра externalScaExemptionIndicator.
Допустими стойности:
  • LVP – транзакция тип Low Value Payments. Транзакцията може да бъде отнесена към транзакции с ниско ниво на риск въз основа на сумата на транзакцията, броя транзакции на клиента в ден или общата дневна сума на плащанията на клиента.
  • TRA – транзакция тип Transaction Risk Analysis, т.е. транзакция, преминала успешна антифрод-проверка.

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

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

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

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

Версия Задължителност Название Тип Описание
05+ Незадължително

date String Дата за връщане на поръчката
21+ Незадължително

externalRefundId String [1..32] Идентификатор на възстановяването. При опит за възстановяване се проверява externalRefundId: ако съществува, се връща успешен отговор с данни за възстановяването, ако не — се осъществява възстановяване.
26+ за всички платежни методи Незадължително

approvalCode String [6] Код за оторизация на МПС. Това поле има фиксирана дължина (шест символа) и може да съдържа цифри и латински букви.
05+ Незадължително

actionCode Integer Код за отговор от процесинга на банката. Виж списъка с кодове за отговор тук.
05+ Незадължително

referenceNumber String [12] Уникален идентификационен номер, който се присвоява на операцията при нейното завършване.
05+ Незадължително

amount Integer [0..12] Сума на плащането в минимални единици валута (например, в стотинки).

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

Версия Задължителност Название Тип Описание
Всички Незадължително

name String [1..255] Име на допълнителния параметър.
Всички Незадължително

value String [1..1024] Стойност на допълнителния параметър - до 1024 символа.

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

Версия Задължителност Название Тип Описание
14+ Незадължително

name String [1..255] Име на допълнителния параметър.
14+ Незадължително

value String [1..1024] Стойност на допълнителния параметър - до 1024 символа.
блок merchantOrderParams се предава в отговора, ако в поръчката има допълнителни параметри на търговеца. Всеки допълнителен параметър се предава в отделен елемент merchantOrderParams.
Версия Задължителност Название Тип Описание
Всички Незадължително

name String [1..255] Име на допълнителния параметър.
Всички Незадължително

value String [1..1024] Стойност на допълнителния параметър - до 1024 символа.

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

Версия Задължителност Название Тип Описание
01+ Незадължително

maskedPan String [1..19] Маскиран номер на карта, използвана за плащането. Съдържа реалните първи 6 и последни 4 цифри от номера на картата във формат XXXXXX**XXXX.
01+ Незадължително

expiration Integer [6] Срок на валидност на картата в следния формат: YYYYMM.
01+ Незадължително

cardholderName String [1..26] Име на притежателя на картата с латински букви. Допустими символи: латински букви, точка, интервал.
01+ Незадължително

approvalCode String [6] Код за оторизация на МПС. Това поле има фиксирана дължина (шест символа) и може да съдържа цифри и латински букви.
08+ Задължително

paymentSystem String Наименование на платежната система. Възможни са следните стойности:
  • VISA;
  • MASTERCARD;
  • AMEX;
  • JCB;
  • CUP;
    08+ Задължително

    		product String [1..255] Допълнителна информация за корпоративните карти. Тази информация се попълва от службата за техническа поддръжка. Ако такава информация липсва, се връща празна стойност.
    17+ Задължително

    		productCategory String Допълнителна информация за категорията на корпоративните карти. Тази информация се попълва от службата за техническа поддръжка. Ако такава информация липсва, се връща празна стойност. Възможни стойности: DEBIT, CREDIT, PREPAID, NON_MASTERCARD, CHARGE, DIFFERED_DEBIT.
    35+ Незадължително

    		corporateCard String [1..5] Указва дали тази карта е корпоративна. Възможни стойности: false - не е корпоративна карта, true - е корпоративна карта. Може да връща празна стойност, което означава, че стойността не е намерена.
    39+ Незадължително

    		detokenizedPanRepresentation String [1..19] Детокенизиран номер на карта (последните 4 цифри или в маскиран вид).
    39+ Незадължително

    		detokenizedPanExpiryDate String Детокенизиран срок на валидност на картата в следния формат: YYYYMM.

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

    Версия Задължителност Название Тип Описание
    01+ Незадължително

    		eci Integer [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 Незадължително

    		authTypeIndicator String Тип на удостоверяване 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+ Незадължително

    		threeDsType String Тип на удостоверяването 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+ Незадължително

    		cavv String [0..200] Стойност за проверка на автентификацията на притежателя на картата. Посочва се само след плащането на поръчката и в случай на наличие на съответното разрешение.
    01+ Незадължително

    		xid String [1..80] Електронен търговски идентификатор на транзакцията. Посочен само след плащане на поръчката и при наличие на съответното разрешение.
    30+ Незадължително

    		threeDSProtocolVersion String Версия на протокола 3DS. Възможни стойности: "2.1.0", "2.2.0" за 3DS2.
    Ако в заявката не се предава threeDSProtocolVersion, то за оторизация 3D Secure ще се използва стойността по подразбиране (2.1.0 - за 3DS 2).
    30+ Незадължително

    		rreqTransStatus String [1] Статус на транзакцията от заявката за предаване на резултатите от автентификацията на потребителя от ACS (RReq). Предава се при използване на 3DS2.
    30+ Незадължително

    		aresTransStatus String Състояние на транзакцията от отговора на ACS към заявката за удостоверяване (ARes). Предава се при използване на 3DS2.

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

    Версия Задължително Название Тип Описание
    Всички Незадължително

    		clientId String [0..255] Номер на клиента (ID) в системата на търговеца — до 255 символа. Използва се за реализиране на функционалността на връзките. Може да се връща в отговора, ако на търговеца е разрешено да създава връзки.
    Указването на този параметър при обработка на плащания по връзка е задължително. В противен случай плащането ще бъде невъзможно.
    Всички Незадължително

    		bindingId String [1..255] Идентификатор на вече съществуваща връзка (идентификатор на карта, токенизирана от gateway). Може да се използва само ако търговецът има разрешение за работа с връзки. Ако този параметър се предава в тази заявка, това означава, че:
    • Тази поръчка може да бъде платена само чрез връзка;
    • Платецът ще бъде пренасочен към страница за плащане, където се изисква само въвеждане на CVC.
    02+ Незадължително

    		authDateTime Integer Дата и час на оторизация, показани като брой милисекунди, изминали от 00:00 GMT 1 януари 1970 година (Unix време). Пример: 1740392720718 (съответства на време 24 февруари 2025 година, 10:25:20 (UTC)).
    02+ Незадължително

    		authRefNum String [1..24] Номер на авторизация на плащането, присвоен му при регистрация на плащането.
    02+ Незадължително

    		terminalId String [1..10] Идентификатор на терминала в системата, обработваща плащането.
    20+ Незадължително

    		externalCreated Boolean Признак, показващ дали връзката е създадена във външна услуга.

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

    Версия Задължително Название Тип Описание
    03+ Незадължително

    		approvedAmount Integer [0..12] Сума в минимални единици валута (например, в центове), която е била блокирана на сметката на купувача. Използва се само в двуетапни плащания.
    03+ Незадължително

    		depositedAmount Integer [1..12] Сума на списване в минимални единици валута (например, в стотинки).
    03+ Незадължително

    		refundedAmount Integer [1..12] Сума на възстановяване в минимални единици валута.
    03+ Незадължително

    		paymentState String Състояние на поръчката, параметърът може да приема следните стойности:
    • CREATED - поръчката е създадена (но не е платена);
    • APPROVED - поръчката е одобрена (средствата по сметката на купувача са блокирани);
    • DEPOSITED - поръчката е завършена (парите са отписани от сметката на купувача);
    • DECLINED - поръчката е отхвърлена;
    • REVERSED - поръчката е отхвърлена;
    • REFUNDED - възстановяване на средства.
    18+ Незадължително

    		totalAmount Integer [1..20] Сума на поръчката плюс комисионна, ако такава има.

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

    Версия Задължителност Название Тип Описание
    03+ Незадължително

    		bankName String [1..50] Наименование на банката-емитент.
    03+ Незадължително

    		bankCountryCode String [1..4] Код на страната на банката-издател.
    03+ Незадължително

    		bankCountryName String [1..160] Държава на банката-издател.

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

    Версия Задължителност Название Тип Описание
    13+ Незадължително

    		email String [1..40] Електронна поща на платеца.
    13+ Незадължително

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

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

    		postAddress String [1..255] Адрес за доставка.
    38+ Незадължително

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

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

    Версия Задължителност Название Тип Описание
    23+ Незадължително referenceNumber Integer Номер на препратка Efecty на поръчката, генериран от страната на Efecty
    23+ Незадължително referenceDate Integer Дата/време на създаване на препратката
    23+ Незадължително referenceStatus String Състояние на Efecty поръчката
    23+ Незадължително referenceTerm Integer Време на живот на Efecty поръчката (в часове)
    23+ Незадължително networkID Integer Идентификатор на мрежата за прием на брой плащане (за Efecty постоянна стойност - 1)
    23+ Незадължително networkName String Наименование на мрежата за прием на брой плащане (за Efecty постоянна стойност - efecty)

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

    Версия Задължителност Название Тип Описание
    28+ Незадължително

    		name String [1..32] Уникално наименование на плащащия плъгин.
    28+ Незадължително

    		params Object Параметрите за конкретния начин на плащане трябва да се предават по следния начин {"param":"value","param2":"value2"}.

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

    Задължителност Име Тип Описание
    Незадължително

    		orderCreationDate String [19] Дата на създаване на поръчката във формат YYYY-MM-DDTHH:MM:SS.
    Незадължително

    		customerDetails Object Блок, съдържащ атрибутите на клиента. Описанието на атрибутите на тага е дадено по-долу.
    Задължително

    		cartItems Object Обект, съдържащ атрибутите на стоките в кошницата. Описанието на вложените елементи е дадено по-долу.

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

    Задължителност Название Тип Описание
    Незадължително

    		bonusAmountForCredit String [0..18] Общата сума бонуси за всички стоки от дадения positionId за зачисляване в бонусната сметка на клиента в минимални валутни единици.
    Незадължително

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

    		bonusAmountRefunded String [0..18] Обща сума на възстановените бонуси за дадения positionId в минимални единици валута.

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

    Задължителност Наименование Тип Описание
    Незадължително

    		contact String [0..40] Предпочитан от клиента начин за връзка.
    Незадължително fullName String [1..100] ФИО на платеца.
    Незадължително

    		passport String [1..100] Серия и номер на паспорта на платеца в следния формат: 2222888888
    Незадължително

    		deliveryInfo Object Обект, съдържащ атрибутите на адреса за доставка. Описанието на вложените елементи е приведено по-долу.

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

    Задължителност Наименование Тип Описание
    Незадължително

    		deliveryType String [1..20] Начин на доставка.
    Задължително

    		country String [2] Двубуквен код на страната за доставка.
    Задължително

    		city String [0..40] Град на назначение.
    Задължително

    		postAddress String [1..255] Адрес за доставка.

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

    Задължителност Наименование Тип Описание
    Задължително

    		items Object Елемент на масив с атрибути на стокова позиция. Описанието на вложените елементи е дадено по-долу.

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

    Задължителност Наименование Тип Описание
    Задължително

    		positionId Integer [1..12] Уникален идентификатор на стоковата позиция в кошницата.
    Задължително

    		name String [1..255] Наименование или описание на стокова позиция в свободна форма.
    Незадължително

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

    		quantity Object Елемент, описващ общото количество стокови позиции на един positionId и неговите мерни единици. Описанието на вложените елементи е приведено по-долу.
    Незадължително

    		itemAmount Integer [1..12] Сума на стойността на всички стокови позиции за един positionId в минимални единици валута. itemAmount е задължителен за предаване, само ако не е предаден параметърът itemPrice. В противен случай предаването на itemAmount не се изисква. Ако в заявката се предават и двата параметъра: itemPrice и itemAmount, то itemAmount трябва да се равнява на itemPrice * quantity, в противен случай заявката ще завърши с грешка.
    Незадължително

    		itemPrice Integer [1..18] Сума на стойността на стоковата позиция на един positionId в пари в минимални единици валута.
    Незадължително

    		depositedItemAmount String [1..18] Сума на списване за един positionId в минимални валутни единици (например, в стотинки).
    Незадължително

    		itemCurrency Integer [3] Код на валута ISO 4217. Ако не е посочен, се счита равен на валутата на поръчката.
    Задължително

    		itemCode String [1..100] Номер (идентификатор) на стокова позиция в системата на магазина.

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

    Задължителност Име Тип Описание
    Задължително

    		value Number [1..18] Количество на стокови позиции от дадения positionId. За указване на дробни числа използвайте десетична точка. Допуска се максимум 3 знака след точката.
    Задължително

    		measure String [1..20] Мерна единица за количеството по позицията.

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

    Задължителност Название Тип Описание
    Незадължително

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

    Примери

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

    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

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

    Задължителност Наименование Тип Описание
    Задължително

    		userName String [1..100] Логин на профила API на продавача.
    Задължително

    		password String [1..30] Парола на API акаунта на продавача.
    Условие

    		orderId String [1..36] Номер на поръчката в платежния шлюз. Уникален в рамките на платежния шлюз.

    Необходимо е да се предаде orderId или orderNumber+merchantLogin.
    Условие

    		orderNumber String [1..36] Номер на поръчката (ID) в системата на търговеца; трябва да бъде уникален за всяка поръчка.

    Необходимо е да се предаде orderId или orderNumber+merchantLogin.
    Условие

    		merchantLogin String [1..255] За да извършвате определени действия с плащането на поръчката от името на друг търговец, посочете неговия логин (за API-акаунта) в този параметър.
    Може да се използва само ако имате разрешение за преглед на транзакциите на други продавачи или ако посоченият продавач е ваш дъщерен продавач.

    Необходимо е да се предаде orderId или orderNumber+merchantLogin.
    Задължително

    		amount String [0..12] Сума на завършване в минимални единици валута (например, в стотинки). Сумата на завършване трябва да съответства на общата сума на всички стоки, за които се извършва завършване. Ако в заявката се посочи amount=0, ще се формира завършване на цялата сума на поръчката.
    Незадължително

    		depositItems Object Обект, съдържащ атрибутите на стоките в кошницата. По-долу е приведено описание на включените атрибути.
    Незадължително

    		language String [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.
    Незадължително

    		currency String [3] Код на валутата на плащането ISO 4217. Ако не е посочен, се използва стойността по подразбиране. Позволени са само цифри.
    Незадължително

    		jsonParams Object Набор от допълнителни атрибути с произволна форма, структура:
    jsonParams={"param_1_name":"param_1_value",...,"param_n_name":"param_n_value"}
    Могат да бъдат предадени в Процесинговия Център, за последваща обработка (изисква се допълнителна настройка - обърнете се към поддръжката).
    Някои предефинирани атрибути jsonParams:
    • backToShopUrl - добавя на страницата за плащане бутон, който ще върне държателя на картата на URL-адреса предаден в този параметър
    • backToShopName - настройва текстовия етикет на бутона Връщане към магазина по подразбиране, ако се използва заедно с backToShopUrl
    • installments - максимален брой разрешени авторизации за плащания на вноски. Изисква се за създаване на връзка за вноски
    • totalInstallmentAmount - крайна сума на всички плащания на вноски. Стойността е необходима за запазване на платежните данни за провеждане на вноски
    • recurringFrequency - минимален брой дни между авторизациите. Изисква се за създаване на рекурентна връзка, препоръчва се за създаване на връзка за вноски (ако се използва 3DS2, параметърът е задължителен).
    • recurringExpiry - дата, след която авторизациите не са разрешени, във формат ГГГГММДД. Изисква се за създаване на рекурентна връзка, препоръчва се за създаване на връзка за вноски (ако се използва 3DS2, параметърът е задължителен).

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

    Задължителност Наименование Тип Описание
    Задължително

    		items Object Елемент на масив с атрибути на стокова позиция. Описанието на вложените елементи е дадено по-долу.

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

    Задължителност Наименование Тип Описание
    Задължително

    		positionId Integer [1..12] Уникален идентификатор на стоковата позиция в кошницата.
    Задължително

    		name String [1..255] Наименование или описание на стокова позиция в свободна форма.
    Незадължително

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

    		quantity Object Елемент, описващ общото количество стокови позиции на един positionId и неговите мерни единици. Описанието на вложените елементи е приведено по-долу.
    Незадължително

    		itemAmount Integer [1..12] Сума на стойността на всички стокови позиции за един positionId в минимални единици валута. itemAmount е задължителен за предаване, само ако не е предаден параметърът itemPrice. В противен случай предаването на itemAmount не се изисква. Ако в заявката се предават и двата параметъра: itemPrice и itemAmount, то itemAmount трябва да се равнява на itemPrice * quantity, в противен случай заявката ще завърши с грешка.
    Незадължително

    		itemPrice Integer [1..18] Сума на стойността на стоковата позиция на един positionId в пари в минимални единици валута.
    Незадължително

    		depositedItemAmount String [1..18] Сума на списване за един positionId в минимални валутни единици (например, в стотинки).
    Незадължително

    		itemCurrency Integer [3] Код на валута ISO 4217. Ако не е посочен, се счита равен на валутата на поръчката.
    Задължително

    		itemCode String [1..100] Номер (идентификатор) на стокова позиция в системата на магазина.

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

    Задължителност Название Тип Описание
    Незадължително

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

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

    Задължителност Име Тип Описание
    Задължително

    		value Number [1..18] Количество на стокови позиции от дадения positionId. За указване на дробни числа използвайте десетична точка. Допуска се максимум 3 знака след точката.
    Задължително

    		measure String [1..20] Мерна единица за количеството по позицията.

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

    Задължителност Наименование Тип Описание
    Незадължително

    		errorCode String [1..2] Информационен параметър в случай на грешка, който може да има различни кодови стойности:
    • стойност 0 - указва успех при обработката на заявката;
    • друга числова стойност (1-99) - указва грешка, за получаване на по-подробна информация за която е необходимо да се провери параметърът errorMesage.__ HTML_5__
    Може да отсъства, ако резултатът не е предизвикал грешки.
    Незадължително

    		errorMessage String [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=978\
  --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

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

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

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

    Задължителност Название Тип Описание
    Задължително

    		userName String [1..30] Логин на потребителския акаунт API на продавача. Ако за автентификация при регистрация вместо логин и парола се използва открит токен (параметър token), паролата не трябва да се предава.
    Задължително

    		password String [1..30] Парола на API акаунта на продавача.
    Условие

    		orderId String [1..36] Номер на поръчката в платежния шлюз. Уникален в рамките на платежния шлюз.

    Необходимо е да се предаде orderId или orderNumber+merchantLogin.
    Условие

    		orderNumber String [1..36] Номер на поръчката (ID) в системата на търговеца; трябва да бъде уникален за всяка поръчка.

    Необходимо е да се предаде orderId или orderNumber+merchantLogin.
    Условие

    		merchantLogin String [1..255] За да отмените поръчка от името на друг търговец, посочете неговия login (за API-акаунт) в този параметър.
    Може да се използва само ако имате разрешение за преглед на транзакциите на други продавачи или ако посоченият продавач е ваш дъщерен продавач.

    Необходимо е да се предаде orderId или orderNumber+merchantLogin.
    Незадължително

    		language String [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.
    Незадължително

    		jsonParams String Полета за съхранение на допълнителни данни трябва да се предават по следния начин: {"param":"value","param2":"value2"}.
    Незадължително

    		amount String [0..12] Сума на отмяна в минимални единици валута (например, в стотинки). Сумата на отмяна трябва да бъде по-малка или равна на оторизираната сума на поръчката (за двуетапни поръчки - общата предварително оторизирана сума на поръчката).
    Незадължително

    		currency String [3] Код на валутата на плащането ISO 4217. Ако не е посочен, се използва стойността по подразбиране. Позволени са само цифри.

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

    Задължителност Название Тип Описание
    Незадължително

    		errorCode String [1..2] Информационен параметър в случай на грешка, който може да има различни кодови стойности:
    • стойност 0 - указва успех при обработката на заявката;
    • друга числова стойност (1-99) - указва грешка, за получаване на по-подробна информация за която е необходимо да се провери параметърът errorMesage.__ HTML_5__
    Може да отсъства, ако резултатът не е предизвикал грешки.
    Незадължително

    		errorMessage String [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=978\
  --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

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

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

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

    Задължителност Наименование Тип Описание
    Задължително

    		userName String [1..100] Логин на профила API на продавача.
    Задължително

    		password String [1..30] Парола на API акаунта на продавача.
    Условие

    		orderId String [1..36] Номер на поръчката в платежния шлюз. Уникален в рамките на платежния шлюз.

    Необходимо е да се предаде orderId или orderNumber+merchantLogin.
    Условие

    		orderNumber String [1..36] Номер на поръчката (ID) в системата на търговеца; трябва да бъде уникален за всяка поръчка.

    Необходимо е да се предаде orderId или orderNumber+merchantLogin.
    Условие

    		merchantLogin String [1..255] За да извършвате определени действия с плащането на поръчката от името на друг търговец, посочете неговия логин (за API-акаунта) в този параметър.
    Може да се използва само ако имате разрешение за преглед на транзакциите на други продавачи или ако посоченият продавач е ваш дъщерен продавач.

    Необходимо е да се предаде orderId или orderNumber+merchantLogin.
    Задължително

    		amount String [0..12] Сума за възстановяване в минимални единици валута (например, в стотинки). Сумата за възстановяване трябва да бъде по-малка или равна на сумата на поръчката (за двуетапни поръчки - общата сума на завършване по поръчката). Ако в заявката се посочи amount=0, то ще бъде възстановена цялата сума на поръчката.
    Незадължително

    		language String [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.
    Незадължително

    		jsonParams String Полета за съхранение на допълнителни данни трябва да се предават по следния начин: {"param":"value","param2":"value2"}.
    Незадължително

    		expectedDepositedAmount Integer [1..12] Параметърът служи за определяне, че заявката е повторна. Ако параметърът е предаден, неговата стойност се сравнява с текущата стойност на depositedAmount в поръчката. Операцията ще бъде изпълнена само в случай, че стойностите съвпадат. Ако два връщания пристигат с еднакъв expectedDepositedAmount, ще бъде изпълнено само едно връщане. Това връщане ще промени стойността на depositedAmount, а след това второто връщане ще бъде отхвърлено.
    Незадължително

    		externalRefundId String [1..32] Идентификатор на възстановяването. При опит за възстановяване се проверява externalRefundId: ако съществува, се връща успешен отговор с данни за възстановяването, ако не — се осъществява възстановяване.
    Незадължително

    		currency String [3] Код на валутата на плащането ISO 4217. Ако не е посочен, се използва стойността по подразбиране. Позволени са само цифри.
    Незадължително

    		refundItems Object Обект за предаване на информация за възвръщаните стоки - номер на позицията на стоката в заявката, наименование, детайли, мерна единица, количество, валута, код на стоката, печалба на агента.

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

    Задължителност Наименование Тип Описание
    Незадължително

    		items Object Елемент на масив с атрибути на стокова позиция. Описанието на вложените елементи е дадено по-долу.

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

    Задължителност Наименование Тип Описание
    Задължително

    		positionId Integer [1..12] Уникален идентификатор на стоковата позиция в кошницата.
    Задължително

    		name String [1..255] Наименование или описание на стокова позиция в свободна форма.
    Незадължително

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

    		quantity Object Елемент, описващ общото количество стокови позиции на един positionId и неговите мерни единици. Описанието на вложените елементи е приведено по-долу.
    Незадължително

    		itemAmount Integer [1..12] Сума на стойността на всички стокови позиции за един positionId в минимални единици валута. itemAmount е задължителен за предаване, само ако не е предаден параметърът itemPrice. В противен случай предаването на itemAmount не се изисква. Ако в заявката се предават и двата параметъра: itemPrice и itemAmount, то itemAmount трябва да се равнява на itemPrice * quantity, в противен случай заявката ще завърши с грешка.
    Незадължително

    		itemPrice Integer [1..18] Сума на стойността на стоковата позиция на един positionId в пари в минимални единици валута.
    Незадължително

    		depositedItemAmount String [1..18] Сума на списване за един positionId в минимални валутни единици (например, в стотинки).
    Незадължително

    		itemCurrency Integer [3] Код на валута ISO 4217. Ако не е посочен, се счита равен на валутата на поръчката.
    Задължително

    		itemCode String [1..100] Номер (идентификатор) на стокова позиция в системата на магазина.

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

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

    "itemAttributes":{"attributes":[{"name":"paymentMethod","value":"1"},{"name":"paymentObject","value":"1"}]}
    Задължителност Название Тип Описание
    Задължително

    		paymentMethod Integer [1..2] Тип плащане, достъпни стойности:
    • 1 - пълна предплата;
    • 2 - частична предплата;
    • 3 - аванс;
    • 4 - пълно плащане;
    • 5 - частично плащане с последващо плащане на кредит;
    • 6 - без плащане с последващо плащане на кредит;
    • 7 - плащане с последващо плащане на кредит.
    Задължително
    Условие

    		nomenclature String [1..95] Код на стоковата номенклатура в шестнадесетично представяне с интервали. Максимална дължина – 32 байта. Задължително, ако е предадено markQuantity.
    Незадължително

    		markQuantity Object Дробно количество на маркирания стока.
    Незадължително

    		userData String [1..64] Стойност на реквизита на потребителя. Може да се предава само след съгласуване с ФНС.
    Незадължително

    		agent_info Object Обект с данни за платежния агент за стоковата позиция. Описанието на вложените елементи е дадено по-долу.
    Незадължително

    		supplier_info Object Обект с данни за доставчика за стоковата позиция. Описанието на вложените елементи е дадено по-долу.

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

    Задължителност Название Тип Описание
    Задължително

    		type Integer Тип на агента, достъпни стойности:
    • 1 - банков платежен агент;
    • 2 - банков платежен субагент;
    • 3 - платежен агент;
    • 4 - платежен субагент;
    • 5 - пълномощник;
    • 6 - комисионер;
    • 7 - друг агент.
    Незадължително

    		paying Object Обект с данни за платежния агент. Описанието на вложените елементи е дадено по-долу.
    Незадължително

    		paymentsOperator Object Обект с информация за оператора за приемане на плащания. Описанието на вложените елементи е дадено по-долу.
    Незадължително

    		MTOperator Object Обект с данни за Оператора на превода. Описанието на вложените елементи е дадено по-долу.

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

    Задължителност Название Тип Описание
    Незадължително

    		operation String [1..24] Име на транзакцията на платежния агент.
    Незадължително

    		phones Array of strings Масив от телефонни номера на платежния агент във формат +N.

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

    Задължителност Име Тип Описание
    Незадължително

    		phones Array of strings Масив от телефонни номера на платежния агент във формат +N.

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

    Задължителност Име Тип Описание
    Незадължително

    		phones Array of strings Масив от телефонни номера на оператора за превод в формат +N.
    Незадължително

    		name String [1..256] Име на оператора за превод.
    Незадължително

    		address String [1..256] Адрес на оператора за превод.
    Незадължително

    		inn String [10..12] ИНН на оператора на превода.

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

    Задължителност Название Тип Описание
    Незадължително

    		phones Array of strings Масив от телефонни номера на доставчика във формат +N.
    Незадължително

    		name String [1..256] Наименование на доставчика.
    Незадължително

    		inn Integer [10..12] ИНН на доставчика

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

    Задължителност Наименование Тип Описание
    Задължително

    		numerator Integer [1..12] Числител на дробната част на обекта на плащане.
    Задължително

    		denominator Integer [1..12] Знаменател на дробната част на обекта за плащане.

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

    Задължителност Име Тип Описание
    Задължително

    		value Number [1..18] Количество на стокови позиции от дадения positionId. За указване на дробни числа използвайте десетична точка. Допуска се максимум 3 знака след точката.
    Задължително

    		measure String [1..20] Мерна единица за количеството по позицията.

    Възможни стойности на параметъра measure:

    Стойност Описание
    0 Прилага се към позиции, които могат да бъдат реализирани индивидуално или в отделни единици, както и ако обектът на плащане е предмет, подлежащ на задължително идентификационно маркиране.
    10 Грам
    11 Килограм
    12 Тон
    20 Сантиметър
    21 Дециметър
    22 Метър
    30 Квадратен сантиметър
    31 Квадратен дециметър
    32 Квадратен метър
    40 Милилитър
    41 Литър
    42 Кубичен метър
    50 Киловат час
    51 Гигакалория
    70 Ден
    71 Час
    72 Минута
    73 Секунда
    80 Килобайт
    81 Мегабайт
    82 Гигабайт
    83 Терабайт
    255 Прилага се към други мерни единици

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

    Задължителност Название Тип Описание
    Незадължително

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

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

    Задължителност Наименование Тип Описание
    Задължително

    		value String [1..2000] Допълнителна информация за товарната позиция.
    Задължително

    		name String [1..255] Наименование на параметъра за описанието на детайлизацията на стоковата позиция

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

    Задължителност Наименование Тип Описание
    Незадължително

    		errorCode String [1..2] Информационен параметър в случай на грешка, който може да има различни кодови стойности:
    • стойност 0 - указва успех при обработката на заявката;
    • друга числова стойност (1-99) - указва грешка, за получаване на по-подробна информация за която е необходимо да се провери параметърът errorMesage.__ HTML_5__
    Може да отсъства, ако резултатът не е предизвикал грешки.
    Незадължително

    		errorMessage String [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=978\
  --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

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

    Задължителност Име Тип Описание
    Задължително

    		userName String [1..100] Логин на профила API на продавача.
    Задължително

    		password String [1..30] Парола на API акаунта на продавача.
    Незадължително

    		merchantLogin String [1..255] За да регистрирате поръчка от името на друг търговец, посочете неговия логин (за API-акаунта) в този параметър.
    Може да се използва само ако имате разрешение за преглед на транзакциите на други продавачи или ако посоченият продавач е ваш дъщерен продавач.
    Незадължително

    		language String [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.
    Задължително

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

    		orderNumber String [1..36] Номер на поръчката (ID) в системата на търговеца; трябва да бъде уникален за всяка поръчка.

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

    Задължителност Име Тип Описание
    Задължително

    		errorCode String [1..2] Информационен параметър в случай на грешка, който може да има различни кодови стойности:
    • стойност 0 - указва успех при обработката на заявката;
    • друга числова стойност (1-99) - указва грешка, за получаване на по-подробна информация за която е необходимо да се провери параметърът errorMesage.__ HTML_5__
    Може да отсъства, ако резултатът не е предизвикал грешки.
    Задължително

    		errorMessage String [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

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

    Задължителност Наименование Тип Описание
    Задължително

    		userName String [1..100] Логин на профила API на продавача.
    Задължително

    		password String [1..30] Парола на API акаунта на продавача.
    Задължително

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

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

    		language String [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.
    Незадължително

    		ip String [1..39] IP адрес на платеца. IPv6 се поддържа във всички заявки (до 39 символа).
    Незадължително

    		cvc String [3] Предаването на параметъра се определя от типа на плащането:
    • предаването на cvc не е предвидено за всички токенизирани плащания;
    • предаването на cvc не е предвидено за MIT плащания;
    • предаването на cvc е задължително по подразбиране за всички други типове плащания; но ако за търговеца е избрано разрешението Може да извършва плащане без потвърждение на CVC, то в такъв случай предаването на cvc става незадължително.
      Допускат се само цифри.
    Незадължително

    		threeDSSDK Boolean Възможни стойности: true или false Флаг, показващ, че плащането постъпва от 3DS SDK.
    Задължително

    		tii String Идентификатор на инициатора на транзакцията. Параметър, указващ какъв тип операция ще изпълнява инициаторът (Клиент или Мерчант). Възможни стойности: F, U. Вижте описанието на стойностите.
    Условие

    		email String [1..40] Електронна поща за показване на страницата за плащане. Ако за продавача са настроени уведомления на клиента, електронната поща трябва да бъде посочена. Пример: client_mail@email.com.
    За плащания с VISA с 3DS оторизация е необходимо да се посочи електронната поща или номера на телефона на притежателя на картата.
    Незадължително

    		mcc Integer [4] Merchant Category Code (код на категория на търговеца). За предаване на този параметър е необходимо специално разрешение. Могат да се използват стойности само от разрешения списък MCC. За получаване на по-подробна информация се обърнете към техническата поддръжка.
    Незадължително

    		threeDSProtocolVersion String Версия на протокола 3DS. Възможни стойности: "2.1.0", "2.2.0" за 3DS2.
    Ако в заявката не се предава threeDSProtocolVersion, то за оторизация 3D Secure ще се използва стойността по подразбиране (2.1.0 - за 3DS 2).
    Незадължително

    		externalScaExemptionIndicator String Тип на изключение SCA (Strong Customer Authentication). Ако е посочен този параметър, транзакцията ще бъде обработена в зависимост от вашите настройки в платежния шлюз: или ще бъде изпълнена принудителна операция SSL, или банката-издател ще получи информация за изключението SCA и ще вземе решение за провеждане на операцията с 3DS-автентификация или без нея (за получаване на подробна информация се свържете с нашата служба за поддръжка). Допустими стойности:
    • LVP – транзакция от тип Low Value Payments. Транзакцията може да бъде отнесена към транзакции с ниско ниво на риск въз основа на сумата на транзакцията, броя на транзакциите на клиента в деня или общата дневна сума на плащанията на клиента.
    • TRA – транзакция от тип Transaction Risk Analysis, т.е. транзакция, преминала успешна антифрод-проверка.

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

    		seToken String [1..8192] Криптирани данни на картата. Задължително, ако се използва вместо данни на картата.
    Задължителни параметри за низа seToken: timestamp, UUID, bindingId, MDORDER. Подробно за генериране на seToken вижте тук.

    Необходимо е да предадете един от следните набори параметри: bindingId, pan+expirationYear+expirationMonth или seToken.
    Optional

    		clientBrowserInfo Object Блок данни за браузъра на клиента, който се изпраща към ACS по време на 3DS автентикация. Този блок може да се предава само ако е включена специална настройка (обърнете се към екипа за поддръжка). Вж. вложени параметри.
    Незадължително

    		acsInIFrame Boolean Флаг, показващ, че за финишния URL ще се връща iFrame версия. Възможни стойности true или false. За свързване на тази функционалност се обърнете към службата за поддръжка.

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

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

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

    Задължителност Название Тип Описание
    Незадължително userAgent String [1..2048] Агент на браузъра.
    Незадължително OS String Операционна система.
    Незадължително OSVersion String Версия на операционната система.
    Незадължително browserAcceptHeader String [1..2048] Заглавка Accept, която съобщава на сървъра какви формати (или MIME-типове) поддържа браузъра.
    Незадължително browserIpAddress String [1..45] IP-адрес на браузъра.
    Незадължително browserLanguage String [1..8] Език на браузъра.
    Незадължително browserTimeZone String Часова зона на браузъра.
    Незадължително browserTimeZoneOffset String [1..5] Отместване на часовата зона в минути между локалното време на потребителя и UTC.
    Незадължително colorDepth String [1..2] Дълбочина на цвета на екрана, в битове.
    Незадължително fingerprint String Отпечатък на браузъра - уникален цифров идентификатор на браузъра.
    Незадължително isMobile Boolean Възможни стойности: true или false. Флаг, указващ, че се използва мобилно устройство.
    Незадължително javaEnabled Boolean Възможни стойности: true или false. Флаг, указващ, че в браузъра е включена поддръжка на java.
    Незадължително javascriptEnabled Boolean Възможни стойности: true или false. Флаг, указващ, че в браузъра е включена поддръжка на javascript.
    Незадължително plugins String Списък на плъгините, използвани в браузъра, разделени със запетая.
    Незадължително screenHeight Integer [1..6] Височина на екрана в пиксели.
    Незадължително screenWidth Integer [1..6] Ширина на екрана в пиксели.
    Незадължително screenPrint String Данни за параметрите на печат на браузъра, включително резолюция, дълбочина на цвета, плътност на пикселите.

    Пример на блока clientBrowserInfo:

    "clientBrowserInfo":
    {
        "userAgent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/111.0.0.0 Safari/537.36 Edg/111.0.1661.41",
        "fingerprint":850891523,
        "OS":"Windows",
        "OSVersion":"10",
        "isMobile":false,
        "screenPrint":"Current Resolution: 1536x864, Available Resolution: 1536x824, Color Depth: 24, Device XDPI: undefined, Device YDPI: undefined",
        "colorDepth":24,
        "screenHeight":"864",
        "screenWidth":"1536",
        "plugins":"PDF Viewer, Chrome PDF Viewer, Chromium PDF Viewer, Microsoft Edge PDF Viewer, WebKit built-in PDF",
        "javaEnabled":false,
        "javascriptEnabled":true,
        "browserLanguage":"it-IT",
        "browserTimeZone":"Europe/Rome",
        "browserTimeZoneOffset":-120,
        "browserAcceptHeader":"gzip",
        "browserIpAddress":"x.x.x.x"
    }

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

    Задължителност Наименование Тип Описание
    Задължително

    		errorCode String [1..2] Информационен параметър в случай на грешка, който може да има различни кодови стойности:
    • стойност 0 - указва успех при обработката на заявката;
    • друга числова стойност (1-99) - указва грешка, за получаване на по-подробна информация за която е необходимо да се провери параметърът errorMesage.__ HTML_5__
    Може да отсъства, ако резултатът не е предизвикал грешки.
    Незадължително

    		errorMessage String [1..512] Информационен параметър, който представлява описание на грешката в случай на възникване на грешка. Стойността на errorMessage може да варира, затова не трябва да се препраща изрично към неговите стойности в кода.
    Езикът на описанието се задава в параметъра language на заявката.
    Незадължително

    		redirect String [1..512] Този параметър се връща, ако плащането е преминало успешно и за плащането не е извършвана проверка на картата за участие в 3-D Secure. Продавачите могат да го използват, ако искат да пренасочат потребителя към страницата на платежния шлюз. Ако продавачът използва собствена страница, тази стойност може да бъде игнорирана.
    Незадължително

    		info String В случай на успешен отговор. Резултат от опита за плащане. По-долу са приведени възможните стойности.
    • Вашето плащане е обработено, извършва се пренасочване...
    • Операцията е отхвърлена. Проверете въведените данни, достатъчността на средствата на картата и повторете операцията. Извършва се пренасочване...
    • Извинете, плащането не може да бъде извършено. Извършва се пренасочване...
    • Операцията е отхвърлена. Обърнете се към магазина. Извършва се пренасочване...
    • Операцията е отхвърлена. Обърнете се към банката, издала картата. Извършва се пренасочване...
    • Операцията е невъзможна. Удостоверяването на притежателя на картата завърши неуспешно. Извършва се пренасочване...
    • Няма връзка с банката. Повторете по-късно. Извършва се пренасочване...
    • Изтече срокът за изчакване на въвеждане на данни. Извършва се пренасочване...
    • Не е получен отговор от банката. Повторете по-късно. Извършва се пренасочване...
    Незадължително

    		error String [1..512] Съобщение за грешка (ако в отговора се върна грешка) на езика, предаден в заявката.
    Незадължително

    		processingErrorType String Тип на грешка при обработката. Предава се, ако грешката възниква от страна на обработката, а не в платежния шлюз, при това броят на опитите за плащане не е превишен и все още не е имало пренасочване към финалната страница.
    Незадължително

    		displayErrorMessage String Показвано съобщение за грешка.
    Незадължително*

    		errorTypeName String Параметър, необходим за frontend страницата за определяне на типа грешка. Задължителен за неуспешни плащания.
    Незадължително

    		acsUrl String [1..512] При успешен отговор в случай на плащане 3D-Secure. URL-адрес за пренасочване към ACS. Задължителен, ако е необходимо пренасочване към ACS. За повече информация вижте Пренасочване към ACS.
    Незадължително

    		paReq String [1..255] PAReq (Payment Authentication Request) — съобщение, което трябва да бъде изпратено в ACS заедно с пренасочването. Връща се при успешен отговор в случай на плащане 3D-Secure, ако е необходимо пренасочване към ACS. Това съобщение съдържа данни в кодировка Base64, необходими за автентификация на притежателя на картата. За повече подробности вижте Пренасочване към ACS.
    Незадължително

    		termUrl String [1..512] При успешен отговор в случай на плащане 3D-Secure. Това е URL-адрес, към който ACS пренасочва притежателя на картата след удостоверяване. Подробно вж. Пренасочване към ACS.
    Незадължително

    		bindingId String [1..255] Идентификатор на връзката, създадена по-рано или използвана за плащане. Присъства само ако търговецът има разрешение за работа със връзки.

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

    Задължителност Наименование Тип Описание
    Незадължително

    		paymentAccountReference String [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

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

    Задължителност Наименование Тип Описание
    Задължително

    		clientId String [0..255] Номер на клиента (ID) в системата на търговеца — до 255 символа. Използва се за реализиране на функционалността на връзките. Може да се връща в отговора, ако на търговеца е разрешено да създава връзки.
    Указването на този параметър при обработка на плащания по връзка е задължително. В противен случай плащането ще бъде невъзможно.
    Незадължително

    		language String [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.
    Задължително

    		userName String [1..30] Логин на потребителския акаунт API на продавача. Ако за автентификация при регистрация вместо логин и парола се използва открит токен (параметър token), паролата не трябва да се предава.
    Задължително

    		password String [1..30] Парола на API акаунта на продавача. Ако за удостоверяване при регистрация вместо логин и парола се използва открит токен (параметър token), паролата не е необходимо да се предава.
    Незадължително

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

    		bindingType String Тип на връзката, който се очаква в отговора (ако не е посочен, се връщат всички типове). Възможни стойности:
    • C – обичайна връзка.
    • R – рекурентна връзка.
    • I - връзка за разсрочване.
    Незадължително

    		showExpired Boolean true/false параметър, определящ дали да се показват връзки с изтекли карти. Стойност по подразбиране: false.
    Незадължително

    		merchantLogin String [1..255] За да получите списък със запазените от клиента удостоверения за самоличност на друг търговец, посочете в този параметър логина на търговеца (за API-акаунта).
    Може да се използва само ако имате разрешение за преглед на транзакциите на други продавачи или ако посоченият продавач е ваш дъщерен продавач. И вие, и посоченият продавач трябва да имате разрешение за работа със запазени удостоверения за самоличност (връзки).

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

    Задължителност Наименование Тип Описание
    Задължително

    		errorCode String [1..2] Информационен параметър в случай на грешка, който може да има различни кодови стойности:
    • стойност 0 - указва успех при обработката на заявката;
    • друга числова стойност (1-99) - указва грешка, за получаване на по-подробна информация за която е необходимо да се провери параметърът errorMesage.__ HTML_5__
    Може да отсъства, ако резултатът не е предизвикал грешки.
    Незадължително

    		errorMessage String [1..512] Информационен параметър, който представлява описание на грешката в случай на възникване на грешка. Стойността на errorMessage може да варира, затова не трябва да се препраща изрично към неговите стойности в кода.
    Езикът на описанието се задава в параметъра language на заявката.
    Незадължително

    		bindings Object Елемент с блокове, съдържащи параметри на връзките. Вж. описанието по-долу.

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

    Задължителност Наименование Тип Описание
    Незадължително

    		maskedPan String [1..19] Маскиран номер на карта, използвана за плащането. Съдържа реалните първи 6 и последни 4 цифри от номера на картата във формат XXXXXX**XXXX.
    Незадължително

    		paymentWay String Начин на извършване на плащане (плащане с въвеждане на данни от карта, плащане чрез връзка и т.н.). Допълнителни възможни стойности на параметъра са посочени по-долу
    Задължително

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

    		expiryDate Integer [6] Срок на валидност на картата в следния формат: YYYYMM.
    Незадължително

    		bindingCategory String Предназначение на връзката, очаквана в отговора. Възможни стойности: COMMON, INSTALLMENT, RECURRENT.
    Незадължително

    		clientId String [0..255] Номер на клиента (ID) в системата на търговеца — до 255 символа. Използва се за реализиране на функционалността на връзките. Може да се връща в отговора, ако на търговеца е разрешено да създава връзки.
    Указването на този параметър при обработка на плащания по връзка е задължително. В противен случай плащането ще бъде невъзможно.
    Незадължително

    		displayLabel Integer [1..16] Последните 4 цифри от оригиналния PAN преди токенизация.
    Незадължително

    		paymentSystem String Наименование на платежната система. Възможни са следните стойности:
    • 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

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

      Задължителност Наименование Тип Описание
      Задължително

      		userName String [1..100] Логин на профила API на продавача.
      Задължително

      		password String [1..30] Парола на API акаунта на продавача.
      Условие

      		pan String [1..19] Номер на платежна карта (задължително, ако bindinId не се предава). Стойността pan заменя стойността bindingId.
      Условие

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

      		showExpired Boolean true/false параметър, определящ дали да се показват връзки с изтекли карти. Стойност по подразбиране: false.

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

      Задължителност Наименование Тип Описание
      Задължително

      		errorCode String [1..2] Информационен параметър в случай на грешка, който може да има различни кодови стойности:
      • стойност 0 - указва успех при обработката на заявката;
      • друга числова стойност (1-99) - указва грешка, за получаване на по-подробна информация за която е необходимо да се провери параметърът errorMesage.__ HTML_5__
      Може да отсъства, ако резултатът не е предизвикал грешки.
      Незадължително

      		errorMessage String [1..512] Информационен параметър, който представлява описание на грешката в случай на възникване на грешка. Стойността на errorMessage може да варира, затова не трябва да се препраща изрично към неговите стойности в кода.
      Езикът на описанието се задава в параметъра language на заявката.
      Незадължително

      		bindings Object Елемент с блокове, съдържащи параметри на връзки: bindingId, maskedPan, expiryDate, clientId
      Незадължително

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

      		maskedPan String [1..19] Маскиран номер на карта, използвана за плащането. Съдържа реалните първи 6 и последни 4 цифри от номера на картата във формат XXXXXX**XXXX.
      Незадължително

      		expiryDate Integer [6] Срок на валидност на картата в следния формат: YYYYMM.
      Незадължително

      		clientId String [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

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

      Задължителност Наименование Тип Описание
      Задължително

      		userName String [1..100] Логин на профила API на продавача.
      Задължително

      		password String [1..30] Парола на API акаунта на продавача.
      Задължително

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

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

      Задължителност Наименование Тип Описание
      Незадължително

      		errorCode String [1..2] Информационен параметър в случай на грешка, който може да има различни кодови стойности:
      • стойност 0 - указва успех при обработката на заявката;
      • друга числова стойност (1-99) - указва грешка, за получаване на по-подробна информация за която е необходимо да се провери параметърът errorMesage.__ HTML_5__
      Може да отсъства, ако резултатът не е предизвикал грешки.
      Незадължително

      		errorMessage String [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

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

      Задължителност Наименование Тип Описание
      Задължително

      		userName String [1..100] Логин на профила API на продавача.
      Задължително

      		password String [1..30] Парола на API акаунта на продавача.
      Задължително

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

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

      Задължителност Наименование Тип Описание
      Незадължително

      		errorCode String [1..2] Информационен параметър в случай на грешка, който може да има различни кодови стойности:
      • стойност 0 - указва успех при обработката на заявката;
      • друга числова стойност (1-99) - указва грешка, за получаване на по-подробна информация за която е необходимо да се провери параметърът errorMesage.__ HTML_5__
      Може да отсъства, ако резултатът не е предизвикал грешки.
      Незадължително

      		errorMessage String [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

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

      Задължителност Название Тип Описание
      Задължително

      		userName String [1..100] Логин на профила API на продавача.
      Задължително

      		password String [1..30] Парола на API акаунта на продавача.
      Задължително

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

      		newExpiry Integer [6] Нова дата (година и месец) на изтичане на срока на валидност във формат YYYYMM.
      Задължително

      		language String [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.

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

      Задължителност Название Тип Описание
      Незадължително

      		errorCode String [1..2] Информационен параметър в случай на грешка, който може да има различни кодови стойности:
      • стойност 0 - указва успех при обработката на заявката;
      • друга числова стойност (1-99) - указва грешка, за получаване на по-подробна информация за която е необходимо да се провери параметърът errorMesage.__ HTML_5__
      Може да отсъства, ако резултатът не е предизвикал грешки.
      Незадължително

      		errorMessage String [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

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

      Задължителност Наименование Тип Описание
      Задължително

      		userName String [1..100] Логин на профила API на продавача.
      Задължително

      		password String [1..30] Парола на API акаунта на продавача.
      Задължително

      		orderNumber String [1..36] Номер на поръчката (ID) в системата на търговеца; трябва да бъде уникален за всяка поръчка.
      Незадължително

      		language String [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.
      Незадължително

      		feeInput Integer [0..8] Размер на комисионната в минимални единици валута. Функционалността трябва да бъде включена на ниво продавач в gateway-я.
      Задължително

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

      		amount Integer [0..12] Сума на плащането в минимални единици валута (например, в стотинки).
      Незадължително

      		currency String [3] Код на валутата на плащането ISO 4217. Ако не е посочен, се използва стойността по подразбиране. Позволени са само цифри.
      Незадължително

      		description String [1..598] Описание на поръчката в произволен формат.
      За да включите изпращането на това поле в процесинговата система, обърнете се към службата за техническа поддръжка.
      В това поле е недопустимо да се предават лични данни или платежни данни (номера на карти и т.н.). Това изискване се дължи на факта, че описанието на поръчката никъде не се маскира.
      Незадължително

      		preAuth Boolean Параметър, определящ необходимостта от предварителна оторизация (блокиране на средства по сметката на клиента преди тяхното списване). Достъпни са следните стойности:
      • true - включено е двуетапно плащане;
      • false - включено е едноетапно плащане (парите се списват веднага).
      Ако параметърът липсва, извършва се едноетапно плащане.
      Незадължително

      		autocompletionDate String [19] Дата и време на автоматичното завършване на двуетапното плащане в следния формат: 2025-12-29T13:02:51. Използван часови пояс: UTC+0. За да включите изпращането на това поле в процесинговата система, обърнете се към службата за техническа поддръжка.
      Незадължително

      		autoReverseDate String [19] Дата и час на автоматично анулиране на двуетапното плащане в следния формат: 2025-06-23T13:02:51. Използван часови пояс: UTC+0. За да включите изпращането на това поле в процесинговата система, обърнете се към службата за техническа поддръжка.
      Незадължително

      		features String Функции на поръчката. За да посочите няколко функции, използвайте този параметър няколко пъти в една заявка. По-долу са изброени възможните стойности.
      • 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, тогава поръчката ще бъде създадена САМО за създаване на връзка (без плащане).
      Незадължително

      		additionalParameters Object Допълнителни параметри на поръчката, които се съхраняват в личния кабинет на продавача за последващ преглед. Всяка нова двойка от име на параметър и неговата стойност трябва да бъде разделена със запетая. По-долу е даден пример за използване.
      { "firstParamName": "firstParamValue", "secondParamName": "secondParamValue"}
      Незадължително billingPayerData Object Блок с регистрационни данни на клиента (адрес, пощенски код), необходим за преминаване на проверка на адреса в рамките на услугите AVS/AVV. Задължително, ако функцията е включена за продавача от страна на Платежния шлюз. Виж вложени параметри.
      Незадължително shippingPayerData Object Обект, съдържащ данни за доставка до клиента. Този параметър се използва за по-нататъшна 3DS-автентификация на клиента. Виж вложени параметри.
      Незадължително preOrderPayerData Object Обект, съдържащ данни за предварителна поръчка. Този параметър се използва за по-нататъшна 3DS-автентификация на клиента. Виж вложени параметри.
      Незадължително orderPayerData Object Обект, съдържащ данни за платеца на поръчката. Този параметър се използва за по-нататъшна 3DS-автентификация на клиента. Виж вложени параметри.
      Незадължително

      		billingAndShippingAddressMatchIndicator String [1] Индикатор за съответствие на платежния адрес на притежателя на картата и адреса за доставка. Този параметър се използва за по-нататъшна 3DS-автентификация на клиента.
      Възможни стойности:
      • Y - съвпадение на платежния адрес на притежателя на картата и адреса за доставка;
      • N - платежният адрес на притежателя на картата и адресът за доставка не съвпадат.

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

      Задължителност Наименование Тип Описание
      Условие

      		billingCity String [0..50] Град, регистриран за конкретната карта в Банката Емитент. Задължително за Visa.
      Условие

      		billingCountry String [0..50] Държава, регистрирана по конкретната карта на банката-издател. Формат: ISO 3166-1 (Alpha 2 / Alpha 3 / Number-3) или наименование на държавата. Препоръчваме да предавате двух/трибуквен ISO код на държавата. Задължително за Visa.
      Условие

      		billingAddressLine1 String [0..50] Адрес, регистриран за конкретната карта в Банката Емитент (адрес на платеца). Ред 1. Задължително за предаване при AVS-проверка. Задължително за Visa.
      Незадължително

      		billingAddressLine2 String [0..50] Адрес, регистриран за конкретната карта в Банката Емитент. Ред 2.
      Незадължително

      		billingAddressLine3 String [0..50] Адрес, регистриран за конкретната карта в Банката Емитент. Ред 3.
      Незадължително

      		billingPostalCode String [0..9] Пощенски код, регистриран за конкретната карта в Банката Издател. Задължително за предаване за AVS-проверка.
      Незадължително

      		billingState String [0..50] Щат, регистриран за конкретната карта в Банката Емитент. Формат: пълна стойност на кода ISO 3166-2, негова част или наименование на щата/региона. Може да съдържа букви само от латинската азбука. Препоръчваме да се предава двубуквен ISO код на щата/региона.
      Задължително

      		payerAccount String [1..32] Номер на сметката на изпращача.
      Условие

      		payerLastName String [1..64] Фамилия на изпращача. Задължително за Visa.
      Условие

      		payerFirstName String [1..35] Име на изпращача. Задължително за Visa.
      Незадължително

      		payerMiddleName String [1..35] Бащино име на изпращача.
      Незадължително

      		payerCombinedName String [1..99] Пълно име на подателя.
      Незадължително

      		payerIdType String [1..8] Тип на предоставения идентифициращ документ на подателя.
      Възможни стойности:
      • IDTP1 - Паспорт
      • IDTP2 - Шофьорска книжка
      • IDTP3 - Социална карта
      • IDTP4 - ID карта на гражданин
      • IDTP5 - Сертификат за водене на бизнес
      • IDTP6 - Сертификат на бежанец
      • IDTP7 - Разрешително за пребиваване
      • IDTP8 - Чужд паспорт
      • IDTP9 - Служебен паспорт
      • IDTP10 - Временен паспорт
      • IDTP11 - Паспорт на моряк
      Незадължително

      		payerIdNumber String [1..99] Номер на предоставения идентифициращ документ на изпращача.
      Условие

      		payerBirthday String [1..20] Дата на раждане на подателя във формат YYYYMMDD. Задължително за Visa.

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

      Задължителност Наименование Тип Описание
      Незадължително shippingCity String [1..50] Град на поръчителя (от адреса за доставка)
      Незадължително shippingCountry String [1..50] Страна на поръчителя
      Незадължително shippingAddressLine1 String [1..50] Основен адрес на клиента (от адреса за доставка)
      Незадължително shippingAddressLine2 String [1..50] Основен адрес на клиента (от адреса за доставка)
      Незадължително shippingAddressLine3 String [1..50] Основен адрес на клиента (от адреса за доставка)
      Незадължително shippingPostalCode String [1..16] Пощенски код на клиента за доставка
      Незадължително shippingState String [1..50] Щат/регион на купувача (от адреса за доставка)
      Незадължително shippingMethodIndicator Integer [2] Индикатор за начин на доставка.
      Възможни стойности:
      • 01 - доставка на платежния адрес на притежателя на карта.
      • 02 - доставка на друг адрес, проверен от Търговеца.
      • 03 - доставка на адрес, различен от основния адрес на притежателя на карта.
      • 04 - изпращане в магазин/самовземане (адресът на магазина трябва да бъде указан в съответните параметри за доставка)
      • 05 - Цифрово разпространение (включва онлайн услуги и електронни подаръчни карти)
      • 06 - билети за пътувания и събития, които не могат да бъдат доставени.
      • 07 - Други (например игри, цифрови стоки, които не подлежат на доставка, цифрови абонаменти и т.н.)
      Незадължително deliveryTimeframe Integer [2] Срок за доставка на стоката.
      Възможни стойности:
      • 01 - цифрова дистрибуция
      • 02 - доставка в същия ден
      • 03 - доставка на следващия ден
      • 04 - доставка в рамките на 2 дни след плащането и по-късно.
      Незадължително deliveryEmail String [1..254] Целеви адрес на електронна поща за доставка на цифрово разпространение. Препоръчително е да предавате електронната поща в самостоятелен параметър на заявката email (но ако я предадете в този блок, към нея ще се прилагат същите правила).

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

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

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

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

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

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

      Задължителност Наименование Тип Описание
      Задължително

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

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

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

      Задължителност Наименование Тип Описание
      Незадължително

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

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

      Задължителност Наименование Тип Описание
      Задължително

      		orderId String [1..36] Номер на поръчката в платежния шлюз. Уникален в рамките на платежния шлюз.

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

      Задължителност Наименование Тип Описание
      Задължително

      		code String [1..3] Код като информационен параметър, съобщаващ за грешка.
      Задължително

      		description String [1..598] Подробно техническо обяснение на грешката - съдържанието на този параметър не е предназначено за показване на потребителя.
      Задължително

      		message String [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>"
        },
        "chargeback": false,
        "operations": [
            {
                "amount": 12300,
                "cardHolder": "TEST CARDHOLDER",
                "authCode": "123456"
            }
        ]
    }
}

      Грешка

      {
  "error": {
    "code": "10",
    "description": "Order with this number is already registered in the system.",
    "message": "Order with this number is already registered in the system."
  },
  "success": false
}

      Плащане на вноски

      За извършване на плащане на вноски се използва заявка https://uat.dskbank.bg/payment/installmentPayment.do.


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

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

      Задължителност Название Тип Описание
      Условие

      		userName String [1..30] Логин на потребителския акаунт API на продавача. Ако за автентификация при регистрация вместо логин и парола се използва открит токен (параметър token), паролата не трябва да се предава.
      Условие

      		password String [1..30] Парола на API акаунта на продавача. Ако за удостоверяване при регистрация вместо логин и парола се използва открит токен (параметър token), паролата не е необходимо да се предава.
      Задължително

      		orderNumber String [1..36] Номер на поръчката (ID) в системата на търговеца; трябва да бъде уникален за всяка поръчка.
      Незадължително

      		language String [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.
      Задължително

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

      		amount Integer [0..12] Сума на плащането в минимални единици валута (например, в стотинки).
      Незадължително

      		currency String [3] Код на валутата на плащането ISO 4217. Ако не е посочен, се използва стойността по подразбиране. Позволени са само цифри.
      Незадължително

      		description String [1..598] Описание на поръчката в произволен формат.
      За да включите изпращането на това поле в процесинговата система, обърнете се към службата за техническа поддръжка.
      В това поле е недопустимо да се предават лични данни или платежни данни (номера на карти и т.н.). Това изискване се дължи на факта, че описанието на поръчката никъде не се маскира.
      Незадължително

      		additionalParameters Object Допълнителни параметри на поръчката, които се съхраняват в личния кабинет на продавача за последващ преглед. Всяка нова двойка от име на параметър и неговата стойност трябва да бъде разделена със запетая. По-долу е даден пример за използване.
      { "firstParamName": "firstParamValue", "secondParamName": "secondParamValue"}
      Задължително

      		preAuth Boolean Параметър, определящ необходимостта от предварителна оторизация (блокиране на средства по сметката на клиента преди тяхното списване). Достъпни са следните стойности:
      • true - включено е двуетапно плащане;
      • false - включено е едноетапно плащане (парите се списват веднага).
      Ако параметърът липсва, извършва се едноетапно плащане.
      Незадължително

      		autocompletionDate String [19] Дата и време на автоматичното завършване на двуетапното плащане в следния формат: 2025-12-29T13:02:51. Използван часови пояс: UTC+0. За да включите изпращането на това поле в процесинговата система, обърнете се към службата за техническа поддръжка.
      Незадължително

      		autoReverseDate String [19] Дата и час на автоматично анулиране на двуетапното плащане в следния формат: 2025-06-23T13:02:51. Използван часови пояс: UTC+0. За да включите изпращането на това поле в процесинговата система, обърнете се към службата за техническа поддръжка.
      Незадължително

      		features String Функции на поръчката. За да посочите няколко функции, използвайте този параметър няколко пъти в една заявка. По-долу са изброени възможните стойности.
      • 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, тогава поръчката ще бъде създадена САМО за създаване на връзка (без плащане).
      Условие

      		token String [1..256] Стойност, използвана за автентификация на продавача при изпращане на заявки към платежната шлюз. Ако предавате този параметър, то не предавайте userName и password.
      Незадължително billingPayerData Object Блок с регистрационни данни на клиента (адрес, пощенски код), необходим за преминаване на проверка на адреса в рамките на услугите AVS/AVV. Задължително, ако функцията е включена за продавача от страна на Платежната шлюз. Вж. вложени параметри.
      Незадължително shippingPayerData Object Обект, съдържащ данни за доставката до клиента. Този параметър се използва за по-нататъшна 3DS-автентификация на клиента. Вж. вложени параметри.
      Незадължително preOrderPayerData Object Обект, съдържащ данни за предварителната поръчка. Този параметър се използва за по-нататъшна 3DS-автентификация на клиента. Вж. вложени параметри.
      Незадължително orderPayerData Object Обект, съдържащ данни за платеца на поръчката. Този параметър се използва за по-нататъшна 3DS-автентификация на клиента. Вж. вложени параметри.
      Незадължително

      		billingAndShippingAddressMatchIndicator String [1] Индикатор за съответствие на платежния адрес на притежателя на картата и адреса за доставка. Този параметър се използва за по-нататъшна 3DS-автентификация на клиента.
      Възможни стойности:
      • Y - съвпадение на платежния адрес на притежателя на картата и адреса за доставка;
      • N - платежният адрес на притежателя на картата и адресът за доставка не съвпадат.

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

      Задължителност Наименование Тип Описание
      Условие

      		billingCity String [0..50] Град, регистриран за конкретната карта в Банката Емитент. Задължително за Visa.
      Условие

      		billingCountry String [0..50] Държава, регистрирана по конкретната карта на банката-издател. Формат: ISO 3166-1 (Alpha 2 / Alpha 3 / Number-3) или наименование на държавата. Препоръчваме да предавате двух/трибуквен ISO код на държавата. Задължително за Visa.
      Условие

      		billingAddressLine1 String [0..50] Адрес, регистриран за конкретната карта в Банката Емитент (адрес на платеца). Ред 1. Задължително за предаване при AVS-проверка. Задължително за Visa.
      Незадължително

      		billingAddressLine2 String [0..50] Адрес, регистриран за конкретната карта в Банката Емитент. Ред 2.
      Незадължително

      		billingAddressLine3 String [0..50] Адрес, регистриран за конкретната карта в Банката Емитент. Ред 3.
      Незадължително

      		billingPostalCode String [0..9] Пощенски код, регистриран за конкретната карта в Банката Издател. Задължително за предаване за AVS-проверка.
      Незадължително

      		billingState String [0..50] Щат, регистриран за конкретната карта в Банката Емитент. Формат: пълна стойност на кода ISO 3166-2, негова част или наименование на щата/региона. Може да съдържа букви само от латинската азбука. Препоръчваме да се предава двубуквен ISO код на щата/региона.
      Задължително

      		payerAccount String [1..32] Номер на сметката на изпращача.
      Условие

      		payerLastName String [1..64] Фамилия на изпращача. Задължително за Visa.
      Условие

      		payerFirstName String [1..35] Име на изпращача. Задължително за Visa.
      Незадължително

      		payerMiddleName String [1..35] Бащино име на изпращача.
      Незадължително

      		payerCombinedName String [1..99] Пълно име на подателя.
      Незадължително

      		payerIdType String [1..8] Тип на предоставения идентифициращ документ на подателя.
      Възможни стойности:
      • IDTP1 - Паспорт
      • IDTP2 - Шофьорска книжка
      • IDTP3 - Социална карта
      • IDTP4 - ID карта на гражданин
      • IDTP5 - Сертификат за водене на бизнес
      • IDTP6 - Сертификат на бежанец
      • IDTP7 - Разрешително за пребиваване
      • IDTP8 - Чужд паспорт
      • IDTP9 - Служебен паспорт
      • IDTP10 - Временен паспорт
      • IDTP11 - Паспорт на моряк
      Незадължително

      		payerIdNumber String [1..99] Номер на предоставения идентифициращ документ на изпращача.
      Условие

      		payerBirthday String [1..20] Дата на раждане на подателя във формат YYYYMMDD. Задължително за Visa.

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

      Задължителност Наименование Тип Описание
      Незадължително shippingCity String [1..50] Град на поръчителя (от адреса за доставка)
      Незадължително shippingCountry String [1..50] Страна на поръчителя
      Незадължително shippingAddressLine1 String [1..50] Основен адрес на клиента (от адреса за доставка)
      Незадължително shippingAddressLine2 String [1..50] Основен адрес на клиента (от адреса за доставка)
      Незадължително shippingAddressLine3 String [1..50] Основен адрес на клиента (от адреса за доставка)
      Незадължително shippingPostalCode String [1..16] Пощенски код на клиента за доставка
      Незадължително shippingState String [1..50] Щат/регион на купувача (от адреса за доставка)
      Незадължително shippingMethodIndicator Integer [2] Индикатор за начин на доставка.
      Възможни стойности:
      • 01 - доставка на платежния адрес на притежателя на карта.
      • 02 - доставка на друг адрес, проверен от Търговеца.
      • 03 - доставка на адрес, различен от основния адрес на притежателя на карта.
      • 04 - изпращане в магазин/самовземане (адресът на магазина трябва да бъде указан в съответните параметри за доставка)
      • 05 - Цифрово разпространение (включва онлайн услуги и електронни подаръчни карти)
      • 06 - билети за пътувания и събития, които не могат да бъдат доставени.
      • 07 - Други (например игри, цифрови стоки, които не подлежат на доставка, цифрови абонаменти и т.н.)
      Незадължително deliveryTimeframe Integer [2] Срок за доставка на стоката.
      Възможни стойности:
      • 01 - цифрова дистрибуция
      • 02 - доставка в същия ден
      • 03 - доставка на следващия ден
      • 04 - доставка в рамките на 2 дни след плащането и по-късно.
      Незадължително deliveryEmail String [1..254] Целеви адрес на електронна поща за доставка на цифрово разпространение. Препоръчително е да предавате електронната поща в самостоятелен параметър на заявката email (но ако я предадете в този блок, към нея ще се прилагат същите правила).

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

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

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

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

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

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

      Задължителност Название Тип Описание
      Незадължително

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

      		errorCode String [1..2] Информационен параметър в случай на грешка, който може да има различни кодови стойности:
      • стойност 0 - указва успех при обработката на заявката;
      • друга числова стойност (1-99) - указва грешка, за получаване на по-подробна информация за която е необходимо да се провери параметърът errorMesage.__ HTML_5__
      Може да отсъства, ако резултатът не е предизвикал грешки.
      Задължително

      		errorMessage String [1..512] Информационен параметър, който представлява описание на грешката в случай на възникване на грешка. Стойността на errorMessage може да варира, затова не трябва да се препраща изрично към неговите стойности в кода.
      Езикът на описанието се задава в параметъра language на заявката.
      Условие orderStatus Object Съдържа параметри на статуса на поръчката и се връща само в случай, че платежната шлюз е разпознала всички параметри на заявката като правилни. Вж. описанието по-долу.

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

      Задължителност Название Тип Описание
      Незадължително

      		errorCode String [1..2] Информационен параметър в случай на грешка, който може да има различни кодови стойности:
      • стойност 0 - указва успех при обработката на заявката;
      • друга числова стойност (1-99) - указва грешка, за получаване на по-подробна информация за която е необходимо да се провери параметърът errorMesage.__ HTML_5__
      Може да отсъства, ако резултатът не е предизвикал грешки.
      Незадължително

      		errorMessage String [1..512] Информационен параметър, който представлява описание на грешката в случай на възникване на грешка. Стойността на errorMessage може да варира, затова не трябва да се препраща изрично към неговите стойности в кода.
      Езикът на описанието се задава в параметъра language на заявката.
      Незадължително

      		orderNumber String [1..36] Номер на поръчката (ID) в системата на търговеца; трябва да бъде уникален за всяка поръчка.
      Незадължително

      		orderStatus Integer Стойността на този параметър указва статуса на поръчката в платежния шлюз. Отсъства, ако поръчката не е била намерена. По-долу е приведен списък на наличните стойности:
      • 0 - поръчката е регистрирана, но не е платена;
      • 1 - поръчката е само авторизирана и още не е завършена (за двуетапните плащания);
      • 2 - поръчката е авторизирана и завършена;
      • 3 - авторизацията е отменена;
      • 4 - по транзакцията е била проведена операция възстановяване;
      • 5 - инициирана е авторизация чрез ACS на банката-емитент;
      • 6 - авторизацията е отхвърлена;
      • 7 - очакване на плащане на поръчки;
      • 8 - междинно завършване за многократно частично завършване.
      Незадължително

      		actionCode Integer Код за отговор от процесинга на банката. Виж списъка с кодове за отговор тук.
      Незадължително

      		actionCodeDescription String [1..512] Описание на actionCode, връщано от процесинга на банката.
      Незадължително

      		amount Integer [0..12] Сума на плащането в минимални единици валута (например, в стотинки).
      Незадължително

      		currency String [3] Код на валутата на плащането ISO 4217. Ако не е посочен, се използва стойността по подразбиране. Позволени са само цифри.
      Незадължително

      		date Integer Дата на регистрация на поръчката като брой милисекунди, изминали от 00:00 GMT 1 януари 1970 година (Unix време). Пример: 1740392720718 (съответства на времето 24 февруари 2025 година, 10:25:20 (UTC)).
      Незадължително

      		ip String [1..39] IP адрес на платеца. IPv6 се поддържа във всички заявки (до 39 символа).
      Незадължително

      		chargeback Boolean Дали средствата са принудително върнати на купувача от банката. Възможни стойности: true, false.
      Незадължително merchantOrderParams N/A Раздел с атрибути, в който се предават допълнителни параметри на търговеца. Вж. описанието по-долу.
      Незадължително attributes Object Атрибути на поръчката в платежната система (номер на поръчката). Вж. описанието по-долу.
      Незадължително cardAuthInfo Object Информация за платежната карта на купувача. Вж. описанието по-долу.
      Незадължително

      		authDateTime Integer Дата и час на оторизация, показани като брой милисекунди, изминали от 00:00 GMT 1 януари 1970 година (Unix време). Пример: 1740392720718 (съответства на време 24 февруари 2025 година, 10:25:20 (UTC)).
      Незадължително

      		terminalId String [1..10] Идентификатор на терминала в системата, обработваща плащането.
      Незадължително

      		authRefNum String [1..24] Номер на авторизация на плащането, присвоен му при регистрация на плащането.
      Незадължително paymentAmountInfo Object Параметър, съдържащ вложени параметри с информация за сумите на потвърждаване, списване и връщане. Вж. описанието по-долу.
      Незадължително bankInfo Object Съдържа вложения параметър bankCountryName. Вж. описанието по-долу.
      Незадължително bindingInfo Object Обект, съдържащ информация за връзката, по която се осъществява плащането. Вж. описанието по-долу.
      Незадължително operations Object Обект, съдържащ информация за операциите. Вж. описанието по-долу.

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

      Задължителност Име Тип Описание
      Незадължително

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

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

      Задължителност Име Тип Описание
      Задължително

      		name String [1..255] Име на допълнителния параметър на търговеца.
      Задължително

      		value String [1..1024] Стойност на допълнителния параметър на продавача - до 1024 символа.

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

      Задължителност Име Тип Описание
      Задължително

      		name String [1..255] Име на допълнителния параметър.
      Задължително

      		value String [1..1024] Стойност на допълнителния параметър - до 1024 символа.

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

      Задължителност Име Тип Описание
      Задължително

      		expiration Integer [6] Срок на валидност на картата в следния формат: YYYYMM.
      Задължително

      		cardholderName String [1..26] Име на притежателя на картата с латински букви. Допустими символи: латински букви, точка, интервал.
      Задължително

      		approvalCode String [6] Код за оторизация на МПС. Това поле има фиксирана дължина (шест символа) и може да съдържа цифри и латински букви.
      Задължително

      		pan String [1..19] Маскиран DPAN: номер, свързан с мобилното устройство на купувача и изпълняващ функциите на номер на платежна карта в системата Apple Pay.
      Задължително

      		maskedPan String [1..19] Маскиран номер на карта, използвана за плащането. Съдържа реалните първи 6 и последни 4 цифри от номера на картата във формат XXXXXX**XXXX.
      Задължително

      		paymentSystem String Наименование на платежната система. Възможни са следните стойности:
      • VISA;
      • MASTERCARD;
      • AMEX;
      • JCB;
      • CUP;

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

        Задължителност Име Тип Описание
        Задължително

        		paymentState String Състояние на поръчката, параметърът може да приема следните стойности:
        • CREATED - поръчката е създадена (но не е платена);
        • APPROVED - поръчката е одобрена (средствата по сметката на купувача са блокирани);
        • DEPOSITED - поръчката е завършена (парите са отписани от сметката на купувача);
        • DECLINED - поръчката е отхвърлена;
        • REVERSED - поръчката е отхвърлена;
        • REFUNDED - възстановяване на средства.
        Задължително

        		approvedAmount Integer [0..12] Сума в минимални единици валута (например, в центове), която е била блокирана на сметката на купувача. Използва се само в двуетапни плащания.
        Задължително

        		depositedAmount Integer [1..12] Сума на списване в минимални единици валута (например, в стотинки).
        Задължително

        		refundedAmount Integer [1..12] Сума на възстановяване в минимални единици валута.
        Задължително

        		totalAmount Integer [1..20] Сума на поръчката плюс комисионна, ако такава има.

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

        Задължителност Име Тип Описание
        Задължително

        		bankCountryName String [1..160] Държава на банката-издател.

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

        Име Тип Задължително Описание
        Незадължително

        		clientId String [0..255] Номер на клиента (ID) в системата на търговеца — до 255 символа. Използва се за реализиране на функционалността на връзките. Може да се връща в отговора, ако на търговеца е разрешено да създава връзки.
        Указването на този параметър при обработка на плащания по връзка е задължително. В противен случай плащането ще бъде невъзможно.
        Незадължително

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

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

        Име Тип Задължително Описание
        Незадължително

        		amount Integer [0..12] Сума на плащането в минимални единици валута (например, в стотинки).
        Незадължително

        		cardHolder String [1..26] Име на притежателя на картата с латински букви. Този параметър се предава само след плащането на поръчката.
        Незадължително

        		authCode Integer [6] Остарял параметър (не се използва). Неговата стойност винаги е 2 независимо от статуса на поръчката и кода за оторизация на процесинговата система.

        Примери

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

        curl --request POST \
  --url https://uat.dskbank.bg/payment/installmentPayment.do \
  --header 'Content-Type: application/json' \
  --data '{
  "userName": "test_user",
  "password": "test_user_password",
  "orderNumber": "UAF-203974-DE-12",
  "language": "EN",
  "bindingId": "8aa4fa8b-4d8a-76ca-b314-7bcc00b4f820",
  "amount": 12300,
  "currency": "975",
  "description" : "Test description",
  "additionalParameters": {
    "firstParamName": "firstParamValue",
    "secondParamName": "secondParamValue"
  }
 }'

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

        {
  "errorCode": 0,
  "errorMessage": "Success",
  "orderId": "0e441115-f3bc-711c-8827-2fdc00b4f820",
  "orderStatus": {
    "errorCode": "0",
    "orderNumber": "7033",
    "orderStatus": 2,
    "actionCode": 0,
    "actionCodeDescription": "",
    "amount": 12300,
    "currency": "975",
    "date": 1618340470944,
    "orderDescription": "Test description",
    "merchantOrderParams": [
      {
        "name": "firstParamName",
        "value": "firstParamValue"
      },
      {
        "name": "secondParamName",
        "value": "secondParamValue"
      }
    ],
    "transactionAttributes": [],
    "attributes": [
      {
        "name": "mdOrder",
        "value": "0e441115-f3bc-711c-8827-2fdc00b4f820"
      }
    ],
    "cardAuthInfo": {
      "maskedPan": "400000**1118",
      "expiration": "203012",
      "cardholderName": "TEST CARDHOLDER",
      "approvalCode": "123456",
      "paymentSystem": "VISA",
      "product": "visa-product",
      "secureAuthInfo": {
        "eci": 7
      },
      "pan": "400000**1118"
    },
    "bindingInfo": {
      "clientId": "TEST CARDHOLDER",
      "bindingId": "8aa4fa8b-4d8a-76ca-b314-7bcc00b4f820"
    },
    "authDateTime": 1618340471076,
    "authRefNum": "111111111111",
    "paymentAmountInfo": {
      "paymentState": "DEPOSITED",
      "approvedAmount": 12300,
      "depositedAmount": 12300,
      "refundedAmount": 0,
      "totalAmount": 12300
    },
    "bankInfo": {
      "bankName": "ES TEST BANK",
      "bankCountryCode": "ES",
      "bankCountryName": "Spain"
    },
    "chargeback": false,
    "operations": [
      {
        "amount": 12300,
        "cardHolder": "TEST CARDHOLDER",
        "authCode": "123456"
      }
    ]
  },
  "error": false
}

        Създаване на връзка без плащане

        За създаване на връзка без извършване на плащане се използва заявка https://uat.dskbank.bg/payment/rest/createBindingNoPayment.do.


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

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

        Задължителност Наименование Тип Описание
        Задължително

        		userName String [1..100] Логин на профила API на продавача.
        Задължително

        		password String [1..30] Парола на API акаунта на продавача.
        Задължително

        		clientId String [0..255] Номер на клиента (ID) в системата на търговеца. Използва се за реализиране на функционалността на връзките.
        Задължително

        		cardholderName String [1..26] Име на притежателя на картата с латински букви. Допустими символи: латински букви, точка, интервал.
        Задължително

        		expiryDate Integer [6] Срок на валидност на картата в следния формат: YYYYMM.
        Задължително

        		pan String [1..19] Номер на платежна карта
        Незадължително

        		additionalParameters Object Допълнителни параметри на поръчката, които се съхраняват в личния кабинет на продавача за последващ преглед. Всяка нова двойка от име на параметър и неговата стойност трябва да бъде разделена със запетая. По-долу е даден пример за използване.
        { "firstParamName": "firstParamValue", "secondParamName": "secondParamValue"}
        Незадължително

        		merchantLogin String [1..255] За да регистрирате поръчка от името на друг търговец, посочете неговия логин (за API-акаунт) в този параметър.
        Може да се използва само ако имате разрешение за преглед на транзакциите на други продавачи или ако посоченият продавач е ваш дъщерен продавач.

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

        Задължителност Наименование Тип Описание
        Задължително

        		errorCode String [1..2] Информационен параметър в случай на грешка, който може да има различни кодови стойности:
        • стойност 0 - указва успех при обработката на заявката;
        • друга числова стойност (1-99) - указва грешка, за получаване на по-подробна информация за която е необходимо да се провери параметърът errorMesage.__ HTML_5__
        Може да отсъства, ако резултатът не е предизвикал грешки.
        Незадължително

        		errorMessage String [1..512] Информационен параметър, който представлява описание на грешката в случай на възникване на грешка. Стойността на errorMessage може да варира, затова не трябва да се препраща изрично към неговите стойности в кода.
        Езикът на описанието се задава в параметъра language на заявката.
        Незадължително

        		error Boolean Флаг, показващ, че в отговора е върната грешка. Допустими стойности: true или false. Приема стойност true, ако errorCode съдържа стойност, различна от 0.
        Незадължително

        		bindingId String [1..255] Идентификатор на връзката, създадена по-рано или използвана за плащане. Присъства само ако търговецът има разрешение за работа със връзки.
        Незадължително

        		clientId String [0..255] Номер на клиента (ID) в системата на търговеца — до 255 символа. Използва се за реализиране на функционалността на връзките. Може да се връща в отговора, ако на търговеца е разрешено да създава връзки.
        Указването на този параметър при обработка на плащания по връзка е задължително. В противен случай плащането ще бъде невъзможно.
        Незадължително

        		cardholderName String [1..26] Име на притежателя на картата с латински букви. Допустими символи: латински букви, точка, интервал.
        Незадължително

        		expiryDate Integer [6] Срок на валидност на картата в следния формат: YYYYMM.
        Незадължително

        		maskedPan String [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 pan=5555555555555599
  --data cardholderName=TEST CARDHOLDER

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

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

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

        Задължителност Наименование Тип Описание
        Задължително

        		userName String [1..100] Логин на профила API на продавача.
        Задължително

        		password String [1..30] Парола на API акаунта на продавача.
        Задължително

        		threeDSServerTransId String [1..36] Идентификатор на транзакцията, създаден на 3DS сървъра. Задължителен за 3DS автентикация.
        Незадължително

        		threeDSVer2MdOrder String [1..36] Номер на поръчка, който е регистриран в първата част от заявката в рамките на 3DS2 операция. Задължителен за удостоверяване 3DS.
        Ако този параметър присъства в заявката, тогава се използва mdOrder, който се предава в настоящия параметър. В такъв случай регистрацията на поръчката не се извършва, а се извършва веднага плащането на поръчката.
        Този параметър се предава само при използване на методи за мгновено плащане, т.е., когато поръчката се регистрира и се заплаща в рамките на една заявка.

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

        Задължителност Наименование Тип Описание
        Задължително

        		errorCode String [1..2] Информационен параметър в случай на грешка, който може да има различни кодови стойности:
        • стойност 0 - указва успех при обработката на заявката;
        • друга числова стойност (1-99) - указва грешка, за получаване на по-подробна информация за която е необходимо да се провери параметърът errorMesage.__ HTML_5__
        Може да отсъства, ако резултатът не е предизвикал грешки.
        Задължително

        		errorMessage String [1..512] Информационен параметър, който представлява описание на грешката в случай на възникване на грешка. Стойността на errorMessage може да варира, затова не трябва да се препраща изрично към неговите стойности в кода.
        Езикът на описанието се задава в параметъра language на заявката.
        Незадължително

        		redirect String [1..512] Този параметър се връща, ако плащането е преминало успешно и за плащането не е извършвана проверка на картата за участие в 3-D Secure. Продавачите могат да го използват, ако искат да пренасочат потребителя към страницата на платежния шлюз. Ако продавачът използва собствена страница, тази стойност може да бъде игнорирана.
        Незадължително

        		is3DSVer2 Boolean Възможни стойности: 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

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

        Задължителност Наименование Тип Описание
        Незадължително

        		userName String [1..30] Логин на потребителския акаунт API на продавача. Ако за автентификация при регистрация вместо логин и парола се използва открит токен (параметър token), паролата не трябва да се предава.
        Незадължително

        		password String [1..30] Парола на API акаунта на продавача. Ако за удостоверяване при регистрация вместо логин и парола се използва открит токен (параметър token), паролата не е необходимо да се предава.
        Незадължително

        		token String [1..256] Стойност, използвана за автентификация на продавача при изпращане на заявки към платежната шлюз. Ако предавате този параметър, то не предавайте userName и password.
        Задължително

        		amount Integer [0..12] Сума на плащането в минимални единици валута (например, в стотинки).
        Незадължително

        		currency String [3] Код на валутата на плащането ISO 4217. Ако не е посочен, се използва стойността по подразбиране. Позволени са само цифри.
        Незадължително

        		pan String [1..19] Номер на платежна карта
        Незадължително

        		cvc String [3] Предаването на параметъра се определя от типа на плащането:
        • предаването на cvc не е предвидено за всички токенизирани плащания;
        • предаването на cvc не е предвидено за MIT плащания;
        • предаването на cvc е задължително по подразбиране за всички други типове плащания; но ако за търговеца е избрано разрешението Може да извършва плащане без потвърждение на CVC, то в такъв случай предаването на cvc става незадължително.
          Допускат се само цифри.
        Незадължително

        		expiry Integer [6] Срок на валидност на картата в следния формат: YYYYMM. Задължително, ако не са предадени нито seToken, нито bindingId.
        Незадължително

        		cardholderName String [1..26] Име на притежателя на картата с латински букви. Допустими символи: латински букви, точка, интервал.
        Незадължително

        		backUrl String [1..512] URL-адрес, на който потребителят ще бъде пренасочен в случай на успешно плащане.
        Използвайте пълен път с указване на протокола, например https://test.com (а не test.com).
        В противен случай потребителят ще бъде пренасочен към URL-адрес от следния вид: http://paymentGatewayURL/merchantURL
        Незадължително

        		failUrl String [1..512] Адрес, на който трябва да се пренасочи потребителят в случай на неуспешно плащане. Адресът трябва да бъде посочен напълно, включително използвания протокол (например, https://mybestmerchantreturnurl.com вместо mybestmerchantreturnurl.com). В противен случай потребителят ще бъде пренасочен по адрес от следния вид: https://uat.dskbank.bg/payment/<merchant_address>.
        Незадължително

        		description String [1..598] Описание на поръчката в произволен формат.
        За да включите изпращането на това поле в процесинговата система, обърнете се към службата за техническа поддръжка.
        В това поле е недопустимо да се предават лични данни или платежни данни (номера на карти и т.н.). Това изискване се дължи на факта, че описанието на поръчката никъде не се маскира.
        Незадължително

        		language String [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.
        Незадължително

        		returnUrl String [1..512] Адрес, към който трябва да бъде пренасочен потребителят в случай на успешно плащане. Адресът трябва да бъде указан изцяло, включително използвания протокол (например, https://mybestmerchantreturnurl.com вместо mybestmerchantreturnurl.com). В противен случай потребителят ще бъде пренасочен на адрес от следния вид: https://uat.dskbank.bg/payment/<merchant_address>.
        Незадължително

        		threeDSServerTransId String [1..36] Идентификатор на транзакцията, създаден на 3DS сървъра. Задължителен за 3DS автентикация.
        Незадължително

        		threeDSVer2FinishUrl String [1..512] URL-адрес, с който клиентът трябва да бъде пренасочен след автентификация на сървъра ACS.
        Условие

        		threeDSVer2MdOrder String [1..36] Номер на поръчка, който е регистриран в първата част от заявката в рамките на 3DS2 операция. Задължителен за удостоверяване 3DS.
        Ако този параметър присъства в заявката, тогава се използва mdOrder, който се предава в настоящия параметър. В такъв случай регистрацията на поръчката не се извършва, а се извършва веднага плащането на поръчката.
        Този параметър се предава само при използване на методи за мгновено плащане, т.е., когато поръчката се регистрира и се заплаща в рамките на една заявка.
        Незадължително

        		threeDSSDK Boolean Възможни стойности: true или false Флаг, показващ, че плащането постъпва от 3DS SDK.
        Незадължително billingPayerData Object Блок с регистрационни данни на клиента (адрес, пощенски индекс), необходим за преминаване на проверката на адреса в рамките на услугите AVS/AVV. Задължително, ако функцията е включена за продавача от страна на Платежния шлюз. Вж. вложени параметри.
        Незадължително shippingPayerData Object Обект, съдържащ данни за доставката до клиента. Този параметър се използва за по-нататъшна 3DS-удостоверяване на клиента. Вж. вложени параметри.
        Незадължително preOrderPayerData Object Обект, съдържащ данни за предварителната поръчка. Този параметър се използва за по-нататъшна 3DS-удостоверяване на клиента. Вж. вложени параметри.
        Незадължително orderPayerData Object Обект, съдържащ данни за платеца на поръчката. Този параметър се използва за по-нататъшна 3DS-удостоверяване на клиента. Вж. вложени параметри.
        Незадължително

        		billingAndShippingAddressMatchIndicator String [1] Индикатор за съответствие на платежния адрес на притежателя на картата и адреса за доставка. Този параметър се използва за по-нататъшна 3DS-автентификация на клиента.
        Възможни стойности:
        • Y - съвпадение на платежния адрес на притежателя на картата и адреса за доставка;
        • N - платежният адрес на притежателя на картата и адресът за доставка не съвпадат.

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

        Задължителност Наименование Тип Описание
        Условие

        		billingCity String [0..50] Град, регистриран за конкретната карта в Банката Емитент. Задължително за Visa.
        Условие

        		billingCountry String [0..50] Държава, регистрирана по конкретната карта на банката-издател. Формат: ISO 3166-1 (Alpha 2 / Alpha 3 / Number-3) или наименование на държавата. Препоръчваме да предавате двух/трибуквен ISO код на държавата. Задължително за Visa.
        Условие

        		billingAddressLine1 String [0..50] Адрес, регистриран за конкретната карта в Банката Емитент (адрес на платеца). Ред 1. Задължително за предаване при AVS-проверка. Задължително за Visa.
        Незадължително

        		billingAddressLine2 String [0..50] Адрес, регистриран за конкретната карта в Банката Емитент. Ред 2.
        Незадължително

        		billingAddressLine3 String [0..50] Адрес, регистриран за конкретната карта в Банката Емитент. Ред 3.
        Незадължително

        		billingPostalCode String [0..9] Пощенски код, регистриран за конкретната карта в Банката Издател. Задължително за предаване за AVS-проверка.
        Незадължително

        		billingState String [0..50] Щат, регистриран за конкретната карта в Банката Емитент. Формат: пълна стойност на кода ISO 3166-2, негова част или наименование на щата/региона. Може да съдържа букви само от латинската азбука. Препоръчваме да се предава двубуквен ISO код на щата/региона.
        Задължително

        		payerAccount String [1..32] Номер на сметката на изпращача.
        Условие

        		payerLastName String [1..64] Фамилия на изпращача. Задължително за Visa.
        Условие

        		payerFirstName String [1..35] Име на изпращача. Задължително за Visa.
        Незадължително

        		payerMiddleName String [1..35] Бащино име на изпращача.
        Незадължително

        		payerCombinedName String [1..99] Пълно име на подателя.
        Незадължително

        		payerIdType String [1..8] Тип на предоставения идентифициращ документ на подателя.
        Възможни стойности:
        • IDTP1 - Паспорт
        • IDTP2 - Шофьорска книжка
        • IDTP3 - Социална карта
        • IDTP4 - ID карта на гражданин
        • IDTP5 - Сертификат за водене на бизнес
        • IDTP6 - Сертификат на бежанец
        • IDTP7 - Разрешително за пребиваване
        • IDTP8 - Чужд паспорт
        • IDTP9 - Служебен паспорт
        • IDTP10 - Временен паспорт
        • IDTP11 - Паспорт на моряк
        Незадължително

        		payerIdNumber String [1..99] Номер на предоставения идентифициращ документ на изпращача.
        Условие

        		payerBirthday String [1..20] Дата на раждане на подателя във формат YYYYMMDD. Задължително за Visa.

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

        Задължителност Наименование Тип Описание
        Незадължително shippingCity String [1..50] Град на поръчителя (от адреса за доставка)
        Незадължително shippingCountry String [1..50] Страна на поръчителя
        Незадължително shippingAddressLine1 String [1..50] Основен адрес на клиента (от адреса за доставка)
        Незадължително shippingAddressLine2 String [1..50] Основен адрес на клиента (от адреса за доставка)
        Незадължително shippingAddressLine3 String [1..50] Основен адрес на клиента (от адреса за доставка)
        Незадължително shippingPostalCode String [1..16] Пощенски код на клиента за доставка
        Незадължително shippingState String [1..50] Щат/регион на купувача (от адреса за доставка)
        Незадължително shippingMethodIndicator Integer [2] Индикатор за начин на доставка.
        Възможни стойности:
        • 01 - доставка на платежния адрес на притежателя на карта.
        • 02 - доставка на друг адрес, проверен от Търговеца.
        • 03 - доставка на адрес, различен от основния адрес на притежателя на карта.
        • 04 - изпращане в магазин/самовземане (адресът на магазина трябва да бъде указан в съответните параметри за доставка)
        • 05 - Цифрово разпространение (включва онлайн услуги и електронни подаръчни карти)
        • 06 - билети за пътувания и събития, които не могат да бъдат доставени.
        • 07 - Други (например игри, цифрови стоки, които не подлежат на доставка, цифрови абонаменти и т.н.)
        Незадължително deliveryTimeframe Integer [2] Срок за доставка на стоката.
        Възможни стойности:
        • 01 - цифрова дистрибуция
        • 02 - доставка в същия ден
        • 03 - доставка на следващия ден
        • 04 - доставка в рамките на 2 дни след плащането и по-късно.
        Незадължително deliveryEmail String [1..254] Целеви адрес на електронна поща за доставка на цифрово разпространение. Препоръчително е да предавате електронната поща в самостоятелен параметър на заявката email (но ако я предадете в този блок, към нея ще се прилагат същите правила).

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

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

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

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

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

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

        Задължителност Наименование Тип Описание
        Незадължително

        		errorCode String [1..2] Информационен параметър в случай на грешка, който може да има различни кодови стойности:
        • стойност 0 - указва успех при обработката на заявката;
        • друга числова стойност (1-99) - указва грешка, за получаване на по-подробна информация за която е необходимо да се провери параметърът errorMesage.__ HTML_5__
        Може да отсъства, ако резултатът не е предизвикал грешки.
        Незадължително

        		errorMessage String [1..512] Информационен параметър, който представлява описание на грешката в случай на възникване на грешка. Стойността на errorMessage може да варира, затова не трябва да се препраща изрично към неговите стойности в кода.
        Езикът на описанието се задава в параметъра language на заявката.
        Незадължително

        		orderId String [1..36] Номер на поръчката в платежния шлюз. Уникален в рамките на платежния шлюз.
        Незадължително

        		orderNumber String [1..36] Номер на поръчката (ID) в системата на търговеца; трябва да бъде уникален за всяка поръчка.
        Незадължително

        		authCode Integer [6] Остарял параметър (не се използва). Неговата стойност винаги е 2 независимо от статуса на поръчката и кода за оторизация на процесинговата система.
        Незадължително

        		actionCode Integer Код за отговор от процесинга на банката. Виж списъка с кодове за отговор тук.
        Незадължително

        		actionCodeDescription String [1..512] Описание на actionCode, връщано от процесинга на банката.
        Незадължително

        		time Integer Време на извършване на транзакцията като брой милисекунди, изминали от 00:00 GMT 1 януари 1970 година (време Unix). Пример: 1740392720718 (съответства на време 24 февруари 2025 година, 10:25:20 (UTC)).
        Незадължително

        		eci Integer [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.
        Незадължително

        		amount Integer [0..12] Сума на плащането в минимални единици валута (например, в стотинки).
        Незадължително

        		currency String [3] Код на валутата на плащането ISO 4217. Ако не е посочен, се използва стойността по подразбиране. Позволени са само цифри.
        Незадължително

        		rrn Integer [1..12] Reference Retrieval Number - идентификатор на транзакцията, присвоен от банката-акуайър.
        Незадължително

        		acsUrl String [1..512] При успешен отговор в случай на плащане 3D-Secure. URL-адрес за пренасочване към ACS. Задължителен, ако е необходимо пренасочване към ACS. За повече информация вижте Пренасочване към ACS.
        Незадължително

        		termUrl String [1..512] При успешен отговор в случай на плащане 3D-Secure. Това е URL-адрес, към който ACS пренасочва притежателя на картата след удостоверяване. Подробно вж. Пренасочване към ACS.
        Незадължително

        		paReq String [1..255] 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

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

        Задължителност Наименование Тип Описание
        Незадължително locale String [2] Ключ на езика по ISO 639-1. Ако езикът не е посочен, се използва езикът по подразбиране, посочен в настройките на магазина.
        Незадължително merchantLogin String [1..30] За да създадете задача от името на друг търговец, посочете неговия логин (за API-акаунта) в този параметър.
        Може да се използва, само ако имате разрешение за преглед на транзакциите на други продавачи или ако посоченият продавач е ваш дъщерен продавач.
        Задължително

        		userName String [1..100] Логин на профила API на продавача.
        Задължително

        		password String [1..30] Парола на API акаунта на продавача.
        Задължително task Object Информация за създаваната рекурентна задача. Вж. вложени параметри.

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

        Задължителност Наименование Тип Описание
        Задължително

        		amount Integer [0..12] Сума на плащането в минимални единици валута (например, в стотинки).
        Незадължително bindingId String [1..255] Идентификатор на вече съществуваща връзка (идентификатор на карта, токенизирана от gateway). Може да се използва само ако търговецът има разрешение за работа с връзки.
        Незадължително cardHolder String [1..26] Име на притежателя на картата с латински букви.
        Незадължително

        		clientId String [0..255] Номер на клиента (ID) в системата на търговеца — до 255 символа. Използва се за реализиране на функционалността на връзките. Може да се връща в отговора, ако на търговеца е разрешено да създава връзки.
        Указването на този параметър при обработка на плащания по връзка е задължително. В противен случай плащането ще бъде невъзможно.
        Задължително

        		currency String [3] Код на валутата на плащането ISO 4217. Ако не е посочен, се използва стойността по подразбиране. Позволени са само цифри.
        Незадължително expiry Integer Срок на валидност на картата в следния формат: YYYYMM.
        Задължително merchantTaskUuid String Уникален идентификатор на задачата в системата на търговеца.
        Незадължително pan String [1..19] Маскиран номер на картата, която е използвана за плащане.
        Незадължително attributes Object Набор от атрибути на задачата, структура:
        {name1:value1,…,nameN:valueN}. Точният набор от атрибути трябва да бъде съгласуван с Банката.
        Незадължително params Object Набор от допълнителни параметри с произволна форма, структура:
        {name1:value1,…,nameN:valueN}
        Задължително scheduleData Object Набор от данни за разписанието на задачата. Вж. вложени параметри.

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

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

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

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

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

        Задължителност Наименование Тип Описание
        Задължително created String Дата и час на създаване на задачата.
        Задължително merchantLogin String Login на търговеца.
        Задължително merchantTaskUuid String Уникален идентификатор на задачата в системата на търговеца.
        Задължително nextPaymentDate String Дата на следващото плащане.
        Задължително state String Състояние на задачата. Допустими стойности:
        • CREATED - създадена, но няма плащания
        • ACTIVE - създадена, изпълнено е поне едно плащане
        • FAILED - превишен е броят опити, задачата е деактивирана
        • COMPLETED - достигната е датата EOL, всички плащания са завършени
        • TERMINATED - прекратена или от клиента, или от търговеца
        • EXPIRED - срокът на валидност на картата е изтекъл
        Задължително taskUuid String Уникален идентификатор в службата за рекурентни списвания.

        Примери

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

        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

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

        Задължителност Наименование Тип Описание
        Незадължително locale String [2] Ключ на език по ISO 639-1. Ако езикът не е указан, се използва езикът по подразбиране, указан в настройките на магазина.
        Задължително

        		userName String [1..100] Логин на профила API на продавача.
        Задължително

        		password String [1..30] Парола на API акаунта на продавача.
        Задължително task Object Информация за променяната рекурентна задача. Вж. вложени параметри.

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

        Задължителност Име Тип Описание
        Незадължително bindingId String [1..255] Идентификатор на вече съществуваща връзка (идентификатор на карта, токенизирана от шлюза). Може да се използва само ако търговецът има разрешение за работа с връзки.
        Незадължително

        		cardholder String Име на притежателя на картата с латински букви.
        Незадължително

        		clientId String [0..255] Номер на клиента (ID) в системата на търговеца — до 255 символа. Използва се за реализиране на функционалността на връзките. Може да се връща в отговора, ако на търговеца е разрешено да създава връзки.
        Указването на този параметър при обработка на плащания по връзка е задължително. В противен случай плащането ще бъде невъзможно.
        Незадължително expiry String [6] Срок на валидност на картата във формат: YYYYMM.
        Незадължително pan String [1..19] Маскиран номер на картата, използвана за плащането.
        Незадължително attributes Object Набор от атрибути на задачата, структура:
        {name1:value1,…,nameN:valueN}. Точният набор от атрибути трябва да бъде съгласуван с Банката.
        Незадължително params Object Набор от допълнителни параметри с произволна форма, структура:
        {name1:value1,…,nameN:valueN}
        Задължително taskIdentifier Object Уникален идентификатор или набор от идентификатори на задачата. Вж. вложени параметри.

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

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

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

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

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

        Задължителност Название Тип Описание
        Задължително updated String Дата и час на последната актуализация на задачата.
        Задължително merchantLogin String Логин на търговеца.
        Задължително merchantTaskUuid String Уникален идентификатор на задачата в системата на търговеца.
        Задължително taskUuid String Уникален идентификатор в службата за рекурентни плащания.

        Примери

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

        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

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

        Задължителност Наименование Тип Описание
        Незадължително locale String [2] Ключ на езика по ISO 639-1. Ако езикът не е указан, се използва езикът по подразбиране, указан в настройките на магазина.
        Задължително

        		userName String [1..100] Логин на профила API на продавача.
        Задължително

        		password String [1..30] Парола на API акаунта на продавача.
        Задължително taskIdentifier Object Уникален идентификатор или набор от идентификатори на рекурентната задача. Вж. вложени параметри.

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

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

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

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

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

        Задължителност Име Тип Описание
        Mandatory

        		amount Integer [0..12] Сума на плащането в минимални единици валута (например, в стотинки).
        Optional attemptsHistory Array of objects Всички опити за плащане в хронологичен ред. Всеки опит за плащане е представен с обект attemptsHistory. Вж. вложени параметри.
        Optional bindingId String [1..255] Идентификатор на вече съществуваща връзка (идентификатор на карта, токенизирана от шлюза). Може да се използва само ако търговецът има разрешение за работа с връзки.
        Optional cardHolder String [1..26] Име на притежателя на картата с латински букви.
        Optional

        		clientId String [0..255] Номер на клиента (ID) в системата на търговеца — до 255 символа. Използва се за реализиране на функционалността на връзките. Може да се връща в отговора, ако на търговеца е разрешено да създава връзки.
        Указването на този параметър при обработка на плащания по връзка е задължително. В противен случай плащането ще бъде невъзможно.
        Mandatory created String Дата и час на създаване на задачата.
        Mandatory

        		currency String [3] Код на валутата на плащането ISO 4217. Ако не е посочен, се използва стойността по подразбиране. Позволени са само цифри.
        Optional expiry Integer [6] Срок на валидност на картата във формат: YYYYMM.
        Mandatory lastPaymentDate String Дата на последното плащане.
        Optional maskedPan String Маскиран номер на карта.
        Mandatory merchantLogin String [1..30] Логин на търговеца.
        Mandatory merchantTaskUuid String Уникален идентификатор на задачата в системата на търговеца.
        Mandatory nextPaymentDate String Дата на следващото плащане.
        Optional params Object Набор от допълнителни параметри с произволна форма, структура:
        {name1:value1,…,nameN:valueN}
        Mandatory scheduleData Object Набор от данни за графика на задачата. Вж. вложени параметри.
        Mandatory state String Състояние на задачата. Допустими стойности:
        • CREATED - създадена, но няма плащания
        • ACTIVE - създадена, извършено е поне едно плащане
        • FAILED - превишен е броят опити, задачата е деактивирана
        • COMPLETED - достигната е дата EOL, всички плащания са завършени
        • TERMINATED - прекратена или от клиента, или от търговеца
        • EXPIRED - срокът на валидност на картата е изтекъл
        Mandatory taskUuid String Уникален идентификатор в службата за рекурентни списвания.
        Mandatory updated String Дата и час на последното актуализиране на задачата.

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

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

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

        Задължителност Наименование Тип Описание
        Задължително executed String Дата и време на опит за плащане. Формат: yyyy-MM-dd'T'HH:mm:ss.SSSZ
        Незадължително orderId String Уникален идентификатор на транзакцията в платежния gateway
        Незадължително orderNumber String Номер на поръчката в платежния gateway
        Задължително paymentAttemptUuid String Уникален идентификатор на опита за плащане
        Задължително paymentUuid String Уникален идентификатор на плащането
        Задължително state String Състояние на задачата. Допустими стойности:
        • CREATED - създадена, но няма плащания
        • ACTIVE - създадена, изпълнено е поне едно плащане
        • FAILED - превишен е броят на опитите, задачата е деактивирана
        • COMPLETED - достигната е датата EOL, всички плащания са завършени
        • TERMINATED - прекратена е или от клиента, или от търговеца
        • EXPIRED - срокът на валидност на картата е изтекъл
        Задължително technicalAttempt Boolean Флаг, указващ дали опитът е бил технически

        Примери

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

        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

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

        Задължителност Наименование Тип Описание
        Незадължително locale String [2] Ключ на езика по ISO 639-1. Ако езикът не е указан, се използва езикът по подразбиране, указан в настройките на магазина.
        Задължително

        		userName String [1..100] Логин на профила API на продавача.
        Задължително

        		password String [1..30] Парола на API акаунта на продавача.
        Задължително taskIdentifier Object Уникален идентификатор или набор от идентификатори на рекурентната задача. Вж. вложени параметри.

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

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

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

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

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

        Задължителност Наименование Тип Описание
        Задължително updated String Дата и час на последната актуализация на задачата.
        Задължително merchantLogin String Login на търговеца.
        Задължително merchantTaskUuid String Уникален идентификатор на задачата в системата на търговеца.
        Задължително taskUuid String Уникален идентификатор в службата за рекурентни събирания.
        Задължително state String Състояние на задачата. Допустими стойности:
        • 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

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

        Задължителност Наименование Тип Описание
        Незадължително locale String [2] Ключ на езика по ISO 639-1. Ако езикът не е посочен, се използва езикът по подразбиране, посочен в настройките на магазина.
        Задължително

        		userName String [1..100] Логин на профила API на продавача.
        Задължително

        		password String [1..30] Парола на API акаунта на продавача.
        Задължително taskIdentifier Object Уникален идентификатор или набор от идентификатори на рекурентната задача. Вж. вложени параметри.

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

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

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

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

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

        Задължителност Име Тип Описание
        Задължително updated String Дата и час на последната актуализация на задачата.
        Задължително merchantLogin String Login на търговеца.
        Задължително merchantTaskUuid String Уникален идентификатор на задачата в системата на търговеца.
        Задължително nextPaymentDate String Дата на следващото плащане.
        Задължително taskUuid String Уникален идентификатор в службата за рекурентни списвания.
        Задължително state String Състояние на задачата. Допустими стойности:
        • 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

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

        Задължителност Наименование Тип Описание
        Незадължително locale String [2] Ключ на езика по ISO 639-1. Ако езикът не е посочен, се използва езикът по подразбиране, посочен в настройките на магазина.
        Задължително

        		userName String [1..100] Логин на профила API на продавача.
        Задължително

        		password String [1..30] Парола на API акаунта на продавача.
        Задължително taskIdentifiers Array of Objects Идентификатори на прекратяваните задачи. Всеки идентификатор е представен с обект taskIdentifier. Вж. вложени параметри.

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

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

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

        Задължителност Наименование Тип Описание
        Задължително status String Статус на отговора. Допустими стойности: 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

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

        Задължителност Наименование Тип Описание
        Незадължително locale String [2] Ключ на език по ISO 639-1. Ако езикът не е посочен, се използва езикът по подразбиране, посочен в настройките на магазина.
        Задължително

        		userName String [1..100] Логин на профила API на продавача.
        Задължително

        		password String [1..30] Парола на API акаунта на продавача.
        Задължително taskIdentifier Object Уникален идентификатор или набор от идентификатори на рекурентна задача. Вж. вложени параметри.
        Задължително paymentNumber Integer Номер на рекурентното плащане, което трябва да бъде пропуснато.

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

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

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

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

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

        Задължителност Име Тип Описание
        Задължително updated String Дата и час на последната актуализация на задачата.
        Задължително merchantLogin String Login на търговеца.
        Задължително merchantTaskUuid String Уникален идентификатор на задачата в системата на търговеца.
        Задължително nextPaymentDate String Дата на следващото плащане.
        Задължително taskUuid String Уникален идентификатор в службата за рекурентни списвания.
        Задължително state String Състояние на задачата. Допустими стойности:
        • 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-callback-ите ще получите същите параметри в 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. Проверявате два параметъра на callback уведомлението: operation и status.

        Ако стойността на параметъра operation се различава от approved или deposited, то callback уведомлението се отнася към статуса на плащането.

        Неуспешни уведомления

        Ако към платежния шлюз се върне отговор, различен от HTTP-код 200 OK, изпращането на уведомлението се счита за неуспешно. В този случай платежният шлюз повтаря уведомлението с интервал от 30 секунди, докато не бъде изпълнено едно от следните условия:

        При достигане на едно от посочените по-горе условия опитите за изпращане на callback-уведомления за операцията се прекратяват.

        Допълнителни параметри на уведомленията за обратно повикване

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

        Параметър Описание Тип събитие
        bindingId UUIID на създадените/актуализираните запазени идентификационни данни (връзки). BINDING_CREATED, BINDING_ACTIVITY_CHANGED
        email Електронна поща на клиента. BINDING_CREATED
        phone Телефон на клиента. BINDING_CREATED
        panMasked Маскиран PAN на картата на клиента. BINDING_CREATED
        panCountryCode Код на страната на клиента. BINDING_CREATED
        enabled Активна ли е връзката (true/false). BINDING_ACTIVITY_CHANGED
        currentReverseAmountFormatted Форматирана сума на операцията за отмяна. REVERSED
        currentRefundAmountFormatted Форматирана сума на операцията за възстановяване. REFUNDED
        operationRefundedAmountFormatted Форматирана сума на операцията за възстановяване. REFUNDED
        operationRefundedAmount Сума за възстановяване в минимални парични единици (например в центове). REFUNDED
        externalRefundId Външен идентификатор на операцията за възстановяване. REFUNDED
        callbackCreationDate Дата на създаване на уведомлението за обратно повикване. Изисква се специална конфигурация на продавача. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, 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
        finishCheckUrl URL за генериране на разписка DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
        sign_alias Име на ключа, използван за подпис. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT, BINDING_CREATED, BINDING_ACTIVITY_CHANGED
        checksum Контролна сума на уведомлението за обратно повикване (използва се за уведомления за обратно повикване с контролна сума). DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT, BINDING_CREATED, BINDING_ACTIVITY_CHANGED
        cardholderName Име на притежателя на картата. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
        amount Сума на регистрираната поръчка в минимални парични единици. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
        paymentAmount Сума на регистрираната поръчка в минимални парични единици. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
        amountFormatted Форматирана сума на регистрираната поръчка. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
        feeAmount Сума на комисията в минимални единици валута. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
        approvedAmount Предварително оторизирана сума в минимални парични единици. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
        depositedAmount Сума на завършване в минимални парични единици. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
        refundedAmount Сума на възстановяването в минимални единици валута. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
        approvedAmountFormatted Форматирана предварително оторизирана сума. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
        depositedAmountFormatted Форматирана сума на зачисляване. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
        refundedAmountFormatted Форматирана сума на връщане. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
        totalAmountFormatted Форматирана обща сума на поръчката (регистрирана сума + комисия). DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
        depositedTotalAmountFormatted Форматирана обща сума на завършване (всички суми на завършване + всички суми на възстановяване + комисионна). DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
        approvalCode Код за авторизация на плащането, получен от процесинга. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
        authCode Код за авторизация DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
        bankName Наименование на банката, издала картата на клиента. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
        currency Валута на поръчката. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
        depositFlag Флаг, указващ типа на операцията.
        • 1 - покупка
        • 2 - предавторизация
        		 DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
        eci Електронен търговски индикатор. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
        ip IP адрес на платеца. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
        ipCountryCode Код на страната на банката-емитент. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
        maskedPan Маскиран номер на картата на клиента. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
        mdOrder Номер на поръчката в платежния шлюз. Уникален в рамките на платежния шлюз. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
        mdorder Номер на поръчката в платежния шлюз. Уникален в рамките на платежния шлюз. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
        merchantFullName Пълно име на търговеца. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
        merchantLogin Логин на търговеца. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
        orderDescription Описание на поръчката. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
        orderNumber Номер на поръчката (ID) в системата на търговеца. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
        threeDSType Вид транзакция (3DS). Възможни стойности: SSL, THREE_DS1_FULL, THREE_DS1_ATTEMPT, THREE_DS2_FULL, THREE_DS2_FRICTIONLESS, THREE_DS2_ATTEMPT, THREE_DS2_EXEMPTION_GRANTED, THREE_DS2_3RI, THREE_DS2_3RI_ATTEMPT DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
        date Дата на създаване на поръчката. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
        clientId Номер на клиента (ID) в системата на търговеца. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT,BINDING_CREATED, BINDING_ACTIVITY_CHANGED
        actionCode Код на резултата от изпълнение на операцията. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
        actionCodeDescription Описание на кода на резултата от изпълнение на операцията. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
        paymentRefNum Reference Retrieval Number - идентификатор на транзакцията, присвоен от банката-акуайер. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
        paymentState Статус на поръчката. Possible values: started, payment_approved, payment_declined, payment_void, payment_deposited, refunded, pending, partly_deposited DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
        paymentWay Начин на плащане на поръчката. Допълнителни възможни стойности на параметъра са приведени тук. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
        processingId Идентификатор на клиента в процесинга. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
        refNum Reference Retrieval Number - идентификатор на транзакцията, присвоен от банката-акуайер. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
        refnum Reference Retrieval Number - идентификатор на транзакцията, присвоен от банката-акуайер. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
        terminalId Идентификатор на терминала в системата, обработваща плащането. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
        paymentSystem Наименование на платежната система. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
        currencyName Трибуквен ISO-код на валутата. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
        transactionAttributes Атрибути на поръчката. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
        paymentDate Дата на плащане на поръчката. DEPOSITED, APPROVED, REVERSED, REFUNDED
        depositedDate Дата на операцията завършване по поръчката. DEPOSITED, APPROVED, REVERSED, REFUNDED
        refundedDate Дата на операцията възстановяване по поръчката. REFUNDED
        reversedDate Дата на операцията отмяна на поръчката. DEPOSITED, REVERSED, REFUNDED
        declineDate Дата на отмяна на поръчката. DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
        xid Индикатор на електронната търговия на транзакцията, определян от продавача. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
        cavv Стойност на проверката за автентификация на притежателя на картата. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
        authValue Стойност на проверката за автентификация на притежателя на картата. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
        sessionExpiredDate Дата и време на изтичане на срока на действие на поръчката. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
        tokenizeCryptogram Токенизирана криптограма. DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
        creditBankName Име на банката, издала картата за кредитиране (в P2P). DEPOSITED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT
        creditPanCountryCode Код на страната на картата получател (в P2P). DEPOSITED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT
        isInternationalP2P Дали P2P-транзакцията е междустранова. DEPOSITED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT
        recipientData Информация за получателя P2P. DEPOSITED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT
        transactionTypeIndicator

        		Информация за получателя P2P. Възможни стойности:
        • 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
        p2pDebitRrn RRN (Reference Retrieval Number) на операцията дебитиране P2P. DEPOSITED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT
        avsCode Код на отговора за верификация AVS (проверка на адреса и пощенския код на притежателя на картата). Възможни стойности:
        • -1 – пощенският код и адресът съвпадат.
        • 1 – адресът съвпада, пощенският код не съвпада.
        • 2 - пощенският код съвпада, адресът не съвпада.
        • 3 - пощенският код и адресът не съвпадат.
        • 50 - поискана е проверка на данните, но резултатът е неуспешен.
        • 51 - некоректен формат на заявката за AVS/AVV проверка.
        		 DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT

        Примери за код

        Симетрична криптография

        Java
        package net.payrdr.test;

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.util.Comparator;
import java.util.Map;
import java.util.stream.Collector;

public class SymmetricCryptographyExample {

    private static final String secretToken = "ooc7slpvc61k7sf7ma7p4hrefr";
    private static final Map<String, String> callbackParams = Map.of(
            "checksum", "EAF2FB72CAB99FD5067F4BA493DD84F4D79C1589FDE8ED29622F0F07215AA972",
            "mdOrder", "06cf5599-3f17-7c86-bdbc-bd7d00a8b38b",
            "operation", "approved",
            "orderNumber", "2003",
            "status", "1"
    );

    public static void main(String[] args) throws Exception {
        String signedString = callbackParams.entrySet().stream()
                .filter(entry -> !entry.getKey().equals("checksum"))
                .sorted(Map.Entry.comparingByKey(Comparator.naturalOrder()))
                .collect(Collector.of(
                        StringBuilder::new,
                        (accumulator, element) -> accumulator
                                .append(element.getKey()).append(";")
                                .append(element.getValue()).append(";"),
                        StringBuilder::append,
                        StringBuilder::toString
                ));

        byte[] mac = generateHMacSHA256(secretToken.getBytes(), signedString.getBytes());
        String signature = callbackParams.get("checksum");

        boolean verified = verifyMac(signature, mac);
        System.out.println("резултат от проверката на подписа: " + 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
";
}
?>
        :
        eCommerce API V1