NAV
Example

Сводка изменений

Версия 1.0.1 от 01.03.2024

В этом разделе отражены изменения документа, внесенные с 12.02.2024 года.

Номер версии Раздел Описание Дата изменения
1.0.1 Уведомления (Pay, Fail, Confirm, Refund, Cancel) Добавлен новый параметр Rrn 01.03.2024
1.0.0 Публикация Публикация документации TipTop Pay Kazakhstan 12.02.2024

Общая информация

Термины и определения

Виды операций

Система предполагает два вида операций: оплата и возврат.

Схемы проведения платежа

Существует два варианта проведения операции оплаты: одностадийная и двухстадийная, их также называют single message system (SMS) и dual message system (DMS).

Одностадийная оплата выполняется одной командой, по результатам которой проходит авторизация и последующее списание средств в пользу ТСП.

Двухстадийная оплата использует две команды: отдельно на авторизацию и списание. После успешной авторизации сумма операции будет блокирована на счету держателя, то есть он не сможет ей воспользоваться. Далее у ТСП есть до 7 дней, в зависимости от типа карты, для подтверждения операции, после чего произойдет списание денег. Если операцию не подтвердить в течение этого времени — она будет автоматически отменена. Подтверждать можно как всю сумму авторизации, так и ее часть.
Как правило, двухстадийная схема используется для получения депозита с плательщика, например, в прокатных компаниях или отелях.

В зависимости от настройки, система может автоматически выполнять подтверждение двухстадийных платежей через указанное количество дней.

Способы оплаты

Оплату можно проводить следующими способами:

3-D Secure

3-D Secure — общее название программ Verified By Visa и Mastercard Secure Code от платежных систем Visa и MasterCard. Суть программы - в проверке подлинности держателя защита от несанкционированного использования карты эмитентом перед оплатой. На практике это выглядит так: держатель указывает реквизиты карты, далее открывается сайт эмитента, где держателю предлагается ввести пароль или секретный код. Как правило, код отправляется в СМС-сообщении. Если код указан правильно, оплата будет проведена. Если нет — отклонена.

3-D Secure в процессе оплаты появляется не на всех картах, а только тех, банки-эмитенты которых поддерживают данную технологию. Проведение оплаты без 3-D Secure является менее безопасным вариантом.

Платежный виджет

Платежный виджет — всплывающая форма для ввода реквизитов карты и e-mail адреса плательщика. Виджет автоматически определяет тип платежной системы: Visa, MasterCard или Maestro, а также банк-эмитент карты и показывает соответствующие логотипы. Форма оптимизирована для использования в любых браузерах и мобильных устройствах. Внутри виджета открывается iframe, который гарантирует безопасность передачи карточных данных и не требует от ТСП сертификации для использования.

Demo widget

Демонстрация работы виджета Widget представлена в нашем демо-магазине.
Для тестирования можно использовать как тестовые карточные данные, так и реальные. Списания денежных средств не произойдет.

Установка виджета

Для установки виджета необходимо прописать на сайте скрипт в раздел head:

<script src="https://widget.tiptoppay.kz/bundles/widget.js"></script>

Для появления платежной формы необходимо зарегистрировать функцию для вызова метода pay, передав в него параметр auth или charge:

this.pay = function () {
 var widget = new tiptop.Widget();
    widget.pay('auth', // или 'charge'
        { //options
            publicId: 'test_api_00000000000000000000002', //id из личного кабинета
            description: 'Оплата товаров в example.com', //назначение
            amount: 100, //сумма
            currency: 'KZT', //валюта
            accountId: '[email protected]', //идентификатор плательщика (необязательно)
            invoiceId: '1234567', //номер заказа  (необязательно)
            email: '[email protected]', //email плательщика (необязательно)
            skin: "mini", //дизайн виджета (необязательно)
            autoClose: 3, //время в секундах до авто-закрытия виджета (необязательный)
            data: {
                myProp: 'myProp value'
            },
            payer: { 
                firstName: 'Тест',
                lastName: 'Тестов',
                middleName: 'Тестович',
                birth: '1955-02-24',
                address: 'тестовый проезд дом тест',
                street: 'Lenina',
                city: 'MO',
                country: 'KZ',
                phone: '123',
                postcode: '345'
            }
        },
        {
            onSuccess: function (options) { // success
                //действие при успешной оплате
            },
            onFail: function (reason, options) { // fail
                //действие при неуспешной оплате
            },
            onComplete: function (paymentResult, options) { //Вызывается как только виджет получает от api.tiptoppay ответ с результатом транзакции.
                //например вызов вашей аналитики
            }
        }
    )
};

И прописать вызов функции на событие, например, нажатие кнопки «Оплатить»:

$('#checkout').click(pay);

Демонстрация работы виджета представлена в нашем демо-магазине.

Пример реализации запуска виджета без библиотеки jquery:

document.querySelector('#checkout').onclick = pay

Для тестирования можно использовать как тестовые карточные данные, так и реальные. Списания денежных средств не произойдет.

Параметры

Вызов функции pay c аргументом auth или charge определяет схему проведения оплаты:

Параметр Формат Применение Описание
publicId String Обязательный Идентификатор сайта, который находится в ЛК
amount Float Обязательный Сумма оплаты
currency String Обязательный Валюта: RUB/USD/EUR/GBP (см. справочник)
accountId String Обязательный для создания подписки Идентификатор пользователя
description String Необязательный Описание назначения оплаты в произвольном формате
invoiceId String Необязательный Номер заказа или счета
email String Необязательный E-mail адрес пользователя
requireEmail bool Необязательный Требование указать e-mail адрес пользователя в виджете
data Json Необязательный Любые другие данные, которые будут связаны с транзакцией, в том числе инструкции для создания подписки или формирования онлайн-чека должны обёртываться в объект PaymentData. Мы зарезервировали названия следующих параметров и отображаем их содержимое в транзакционной выгрузке в Личном Кабинете: name, firstName, middleName, lastName, nick, phone, address, comment, birthDate
skin String Необязательный Выбор дизайна виджета. Возможные варианты: classic, modern, mini. По умолчанию стоит — classic
retryPayment bool Необязательный Появление кнопки «Повторить платеж» при неудачном платеже. По умолчанию стоит true
autoClose number Необязательный Автоматическое закрытие виджета после успешной оплаты через указанное количество секунд (минимум 3 секунды, максимум 10 секунд). Дальнейшее поведение задается параметром onSuccess. Если параметр не передан, значение не определено - виджет автоматически не будет закрыт.
payer Object Необязательный Доп. поле, куда передается информация о плательщике. Используйте следующие параметры: firstName, lastName, middleName, birth, street, address, city, country, phone, postcode

В случае успешной или неуспешной оплаты, можно определить поведение формы следующими параметрами:

Параметр Формат Применение Описание
onSuccess Function или String Необязательный Указывается либо функция, либо адрес страницы сайта. В случае указания функции — она будет вызвана после успешного завершения оплаты и закрытия пользователем окна виджета. В случае указания адреса — пользователь будет направлен на указанную страницу.
onFail Function или String Необязательный Указывается либо функция, либо адрес страницы сайта. В случае указания функции — она будет вызвана после неуспешного завершения платежа. В случае указания адреса — пользователь будет направлен на указанную страницу.
onComplete Function Необязательный Указывается функция, которая будет вызвана, как только виджет получит ответ с результатом транзакции. Редиректы в этом методе делать нельзя.

Локализация виджета

По умолчанию мы отображаем виджет на русском языке. Для вызова виджета на других языках передайте в параметрах инициализации виджета параметр language.

var widget = new tiptop.Widget({language: "en-US"});

Список поддерживаемых языков:

Язык Часовой пояс Код
Русский MSK ru-RU
Английский CET en-US
Немецкий CET de-DE
Латышский CET lv
Азербайджанский AZT az
Русский ALMT kk
Казахский ALMT kk-KZ
Украинский EET uk
Польский CET pl
Португальский CET pt
Чешский CET cs-CZ
Вьетнамский ICT vi-VN
Турецкий TRT tr-TR
Испанский CET es-ES
Итальянский CET it
Узбекский UZT uz

Рекуррентные платежи (подписка)

После успешного завершения оплаты виджет может автоматически создавать подписку на рекуррентные платежи. Для это нужно добавить несколько параметров запуска:

Параметр Формат Применение Описание
Interval String Обязательный Интервал. Возможные значения: Day, Week, Month
Period Int Обязательный Период. В комбинации с интервалом, 1 Month значит раз в месяц, а 2 Week — раз в две недели. Должен быть больше 0
MaxPeriods Int Необязательный Максимальное количество платежей в подписке. По умолчанию стоит без ограничений. Если задаете количество, проверьте, чтобы оно было больше 0
Amount Number Необязательный Сумма регулярного платежа. По умолчанию совпадает с суммой первого, установочного платежа. Если указываете другую сумму, проверьте, чтобы она была больше 0
StartDate DateTime Необязательный Дата и время первого регулярного платежа. По умолчанию запуск произойдет через указанный интервал и период, например через месяц. Если указываете другую дату, то она должна стоять в будущем времени
CustomerReceipt String Необязательный Данные для формирования онлайн-чека в регулярных платежах

Параметры для запуска регулярных платежей необходимо добавить в объект data.PaymentData.recurrent как в примере ниже::

this.pay = function () {
    var widget = new tiptop.Widget();
    var receipt = {
        Items: [//товарные позиции
            {
                label: 'Наименование товара 3', //наименование товара
                price: 300.00, //цена
                quantity: 3.00, //количество
                amount: 900.00, //сумма
                vat: 20, //ставка НДС
                method: 0, // признак способа расчета
                object: 0, // признак предмета товара, работы, услуги, платежа, выплаты, иного предмета расчета
            }
        ],
        taxationSystem: 0, //система налогообложения; необязательный, если у вас одна система налогообложения
        email: '[email protected]', //e-mail покупателя, если нужно отправить письмо с чеком
        phone: '', //телефон покупателя в любом формате, если нужно отправить сообщение со ссылкой на чек
        isBso: false, //чек является бланком строгой отчетности
        amounts:
            {
                electronic: 900.00, // Сумма оплаты электронными деньгами
                advancePayment: 0.00, // Сумма из предоплаты (зачетом аванса) (2 знака после точки)
                credit: 0.00, // Сумма постоплатой(в кредит) (2 знака после точки)
                provision: 0.00 // Сумма оплаты встречным предоставлением (сертификаты, др. мат.ценности) (2 знака после точки)
            }
    };

    var data = {};
    data.PaymentData = {
        CustomerReceipt: receipt, //чек для первого платежа
        recurrent: {
            interval: 'Month',
            period: 1,
            customerReceipt: receipt //чек для регулярных платежей
        }
    }; //создание ежемесячной подписки

    widget.charge({ // options
            publicId: 'test_api_00000000000000000000001', //id из личного кабинета
            description: 'Подписка на ежемесячный доступ к сайту example.com', //назначение
            amount: 1000, //сумма
            currency: 'KZT', //валюта
            invoiceId: '1234567', //номер заказа  (необязательно)
            accountId: '[email protected]', //идентификатор плательщика (обязательно для создания подписки)
            data: data
        },
        function (options) { // success
            //действие при успешной оплате
        },
        function (reason, options) { // fail
            //действие при неуспешной оплате
        }
    );
};

Обратите внимание, что создать подписку можно, указав параметр accountId, который может быть e-mail адресом, номером телефона или любым другим идентификатором плательщика.

Больше примеров создания рекуррентных платежей из виджета — в разделе "Сценарии интеграции".

Для отмены рекуррентных платежей используйте возможности личного кабинета, API или предоставьте покупателю ссылку на сайт системы — https://my.tiptoppay.kz/, где он самостоятельно сможет найти и отменить свои подписки.

Мобильный виджет

Скрипт автоматически определяет устройство пользователя и запускает наиболее подходящий вариант виджета: обычный либо оптимизированный для мобильных устройств. Для удобства покупателей мобильная версия виджета занимает весь экран и предлагает провести оплату либо картой, либо по технологии Apple Pay или Google Pay.

mobile-widget

Возможность оплаты в виджете через Apple Pay и Google Pay появляется при соблюдении следующих условий:

  1. Сайт работает по схеме HTTPS и поддерживает протокол TLS версии 1.2.
  2. На сайте отсутствует "mixed content", когда часть ресурсов загружается по HTTPS, а часть — по HTTP.
  3. Проведена упрощенная (только для веб-сайтов) или классическая интеграция функции Apple Pay.
  4. Клиент открыл страницу оплаты на сайте в браузере, который поддерживает Apple или Google Pay. Для Apple Pay это Apple Safari, для Google Pay — Google Chrome, Mozilla Firefox, Apple Safari, Microsoft Edge, Opera или UCWeb UC. Другие браузеры не поддерживают возможность оплаты с помощью Apple или Google Pay.

Платежный конструктор

PaymentBlocks — конструктор блоков, из которых можно собрать кастомную платежную форму.

Первый блок - содержит форму для ввода реквизитов карты и электронной почты плательщика со всеми доступными способами оплаты, интегрируемая в DOM элемент. Блок автоматически определяет тип платежной системы Visa, MasterCard или Maestro), банк-эмитент карты, а также показывает соответствующие логотипы.

Форма оптимизирована для использования в любых браузерах и мобильных устройствах. Внутри блока открывается iframe, который гарантирует безопасность передачи карточных данных и не требует от ТСП сертификации для использования.

Демо конструктора.

payment-blocks

Скрипт checkout

Checkout — скрипт, который прописывается на вашем сайте, собирает из указанной формы карточные данные и составляет из них криптограмму для оплаты через наш API.

Криптограмма формируется алгоритмом RSA с длиной ключа в 2048 бит и удовлетворяет стандарту по защите карточных данных. При соблюдении описанных ниже требований карточные данные к вам не попадают, но ваш сервер всё равно влияет на их безопасность.

Demo checkout

Демонстрация работы скрипта Checkout представлена в нашем демо-магазине.
Для тестирования можно использовать как тестовые карточные данные, так и реальные. Списания денежных средств не произойдет.

Требования

Требования к форме:

Требования к криптограмме:

Требования к безопасности по PCI DSS:

С точки зрения PCI DSS, подобный способ подключения классифицируется как "E-commerce merchants who outsource all payment processing to PCI DSS validated third parties, and who have a website(s) that doesn’t directly receive cardholder data but that can impact the security of the payment transaction. No electronic storage, processing, or transmission of any cardholder data on the merchant’s systems or premises.", то есть обработка платежных данных выполняется третьей стороной, но сайт влияет на безопасность карточных данных.

Для соблюдения требований стандарта, необходимо заполнять лист самооценки SAQ-EP и ежеквартально проходить ASV-тестирование.

Подробнее про соответствие требованиям PCI читайте в разделе PCI DSS.

Установка

Для создания криптограммы необходимо прописать на странице с платежной формой скрипт checkout:

<script src="https://checkout.tiptoppay.kz/checkout.js"></script>

Выбрать удобный для вас вариант передачи карточных данных:

Далее созданную криптограмму карты необходимо отправить на сервер и вызывать метод оплаты через API.

Вариант с передачей карточных данных напрямую в скрипт

1) Инициализировать скрипт checkout

const checkout = new tiptop.Checkout({
    publicId: 'test_api_000000000000000002',
});

2) Вызвать метод генерации криптограммы, передав в него карточные данные

const fieldValues = {
    cvv: '911',
    cardNumber: '4242 4242 4242 4242',
    expDateMonth: '12',
    expDateYear: '24',
}

checkout.createPaymentCryptogram(fieldValues)
    .then((cryptogram) => {
        console.log(cryptogram);
    }).catch((errors) => {
        console.log(errors)
    });

Вариант с использованием формы:

1) Создать форму для ввода карточных данных:

<form id="paymentFormSample" autocomplete="off">
    <input type="text" data-cp="cardNumber">
    <input type="text" data-cp="expDateMonth">
    <input type="text" data-cp="expDateYear">
    <input type="text" data-cp="cvv">
    <input type="text" data-cp="name">
    <button type="submit">Оплатить 100 р.</button>
</form>

Поля ввода карточных данных должны быть помечены атрибутами:

2) Инициализировать скрипт checkout

const checkout = new tiptop.Checkout({
    publicId: 'test_api_000000000000000002',
    container: document.getElementById("paymentFormSample")
});

3) Вызвать метод генерации криптограммы

checkout.createPaymentCryptogram()
    .then((cryptogram) => {
        console.log(cryptogram); // криптограмма
    }).catch((errors) => {
        console.log(errors)
    });

При разработке собственной формы или передачи данных в скрипт обратите внимание на следующие моменты:

Методы

Асинхронный метод для генерации криптограммы.

В данном методе при ошибке валидации карточных данных - вместо локализованного сообщения будет выдан код ошибки пример см. ниже.

async createPaymentCryptogram(fieldValues: CardData): Promise<string>

Метод возвращает Promise содержащий криптограмму. В случае если переданы некорректные данные Promise будет отклонен с ошибкой содержащей объект со списком ошибок.

const checkout = new tiptop.Checkout({
    publicId: 'test_api_000000000000000002'
});

const fieldValues = {
    cvv: '911',
    cardNumber: '4242 4242 4242 4242',
    expDateMonth: '12',
    expDateYear: '24',
}

checkout.createPaymentCryptogram(fieldValues)
    .then((cryptogram) => {
        console.log(cryptogram);
    });

Описание объекта CardData:

export interface CardData {
    cvv?:  string; // CVV/CVC код
    cardNumber?: string; // Номер карты, наличие пробелов не имеет значения
    expDateMonth?: string; // Срок действия карты - месяц
    expDateYear?: string; // Срок дейcтвия карты - год
    expDateMonthYear?: string; // Срок действия карты, все символы за исключением цифр игнорируются, 
    //Если длина строки 2,3 или 5 символов то первая цифра воспринимается как месяц, оставшиеся как год. 
    //Если длина строки 4 или 6 символов то первые два трактуются как месяц, а оставшиеся как год.
}
Параметр Описание Тип Обязательный *
cvv CVV/CVC код string Нет *
cardNumber Номер карты, наличие пробелов не имеет значения string Не обязательный, если поле привязано в форме
expDateMonth Срок действия карты - месяц string Не обязательный, если поле привязано в форме или передано поле expDateMonthYear
expDateYear Срок дейcтвия карты - год string Не обязательный, если поле привязано в форме или переданы поля expDateMonth и expDateYear
expDateMonthYear Срок действия карты, все символы за исключением цифр игнорируются. Если длина строки 2, 3 или 5 символов то первая цифра воспринимается как месяц, оставшиеся как год. Если длина строки 4 или 6 символов то первые два трактуются как месяц, а оставшиеся как год. string Не обязательный, если поле привязано в форме или переданы поля expDateMonth и expDateYear
name Имя владельца карты string Нет

Обработка ошибок валидации карточных данных:

const fieldValues = {
    cvv: '91', // Невалидный CVV
    cardNumber: '4242 4242 4242 424', // Невалидный номер карты
    expDateMonth: '12',
    expDateYear: '24',
}

checkout.createPaymentCryptogram(fieldValues)
    .then((cryptogram) => {
        console.log(cryptogram);
    })
        .catch((errors) => {
                console.log(errors);
             /* Выведет
                {
            cardNumber: "CardNumber_Invalid",
            cvv: "Cvv_Invalid"
                }
                */
});
Код ошибки Описание
CardNumber_Empty Пустой номер карты
CardNumber_Invalid Некорректный номер карты
Cvv_Empty Пустой CVV
Cvv_Invalid Некорректный CVV
ExpDateMonthYear_Empty Пустой год и месяц
ExpDateMonthYear_Invalid Некорректный год и месяц
ExpDateMonth_Empty Пустой месяц
ExpDateMonth_Invalid Некорректный месяц
ExpDateYear_Empty Пустой год
ExpDateYear_Invalid Некорректный год
Name_Empty Пустое имя *
Name_Invalid Некорректное имя *
Name_TooLong Слишком длинное имя *
Name_TooShort Слишком короткое имя *

Метод для генерации криптограммы

Метод возвращает криптограмму в случае успешной генерации и объект со списком ошибок в случае наличия ошибок в карточных данных - в отличие от метода createPaymentCryptogram, объект со списком ошибок содержит не коды ошибок, а локализованные на русский язык описания ошибок.

createCryptogramPacket(fieldValues: CardData):string|object - устаревший.

Метод может принимать на вход объект с карточными данными и может использоваться в устаревшей схеме с привязкой к HTML-форме. В случае если используется и привязка формы и этот же параметр найден в объекте CardData при попытке сформировать криптограмму будет выброшена ошибка.

Cкрипт для создания криптограммы:

this.createCryptogram = function () {
    var result = checkout.createCryptogramPacket();

    if (result.success) {
        // сформирована криптограмма
        alert(result.packet);
    }
    else {
        // найдены ошибки в введённых данных, объект `result.messages` формата: 
        // { name: "В имени держателя карты слишком много символов", cardNumber: "Неправильный номер карты" }
        // где `name`, `cardNumber` соответствуют значениям атрибутов `<input ... data-cp="cardNumber">`
       for (var msgName in result.messages) {
           alert(result.messages[msgName]);
       }
    }
};

$(function () {
    /* Создание checkout */
    checkout = new tiptop.Checkout(
    // public id из личного кабинета
    "test_api_00000000000000000000001",
    // тег, содержащий поля данных карты
    document.getElementById("paymentFormSample"));
});

Рекуррентные платежи

Рекуррентные платежи, также известные как платежи по подписке или «автоплатежи» — возможность выполнять регулярные списания денег с банковской карты покупателя без повторного ввода реквизитов карты и без участия плательщика для инициации очередного платежа.

Рекуррентные платежи всегда начинаются с первого, установочного платежа, для выполнения которого плательщик должен ввести реквизиты своей карты. Для последующих регулярных платежей обязательно нужно ознакомить держателя карты с графиком и получить его согласие на безакцептное списание.

Есть распространенное мнение, что задача рекуррентного биллинга сводится к тому, чтобы установить сумму, которая будет каждый месяц списываться с карты клиента. Выбор системы регулярных платежей при этом основан только на стоимости предоставляемых услуг. В действительности — ситуация более сложная, потому как для качественного сервиса требуется намного больше функций и возможностей. Мы сделали все, чтобы в системе TipTop Pay процедура запуска и обработки рекуррентных платежей стала максимально простой и гибкой.

Запуск и остановка регулярных платежей

Запуск рекуррентных платежей возможен в любое время после выполнения установочного платежа: в тот же момент, через неделю или через месяц. Ограничение только одно - интервал между регулярными платежами, а также между установочным и первым регулярным платежом не может превышать один год.

Пример: покупатель оплачивает первый месяц предоставления услуг через установочный платеж и дает согласие на ежемесячное списание с его карты начиная со второго месяца.
Запуск регулярных платежей может быть выполнен через API или платежный виджет.

Если покупатель отказывается от дальнейших платежей, вы можете отменить подписку в любой момент:

Также плательщик может самостоятельно найти и отменить свои регулярные платежи на сайте системы TipTop Pay.

Возможность настройки графика платежей

Выбор периода и интервала списания

Система может выполнять регулярные платежи каждые 2 недели, 1 раз в месяц, каждые 3 месяца и так далее: вы можете указать любой период.

Выбор даты начала списаний

Рекуррентные платежи могут быть запущены сразу при создании подписки, либо с отсрочкой.

Пример: покупатель подписывается на вашу услугу в середине месяца, вы создаете план ежемесячных рекуррентных платежей начиная со следующего месяца по 15-м числам.

Ограничение на количество платежей

Можно указать максимальное количество платежей в подписке или создать план без ограничений. В первом случае рекуррентные платежи будут автоматически остановлены после исполнения всех платежей в графике.

Пример: покупатель приобретает товар стоимостью 12 000 тенге в рассрочку на год — оплачивает 1000 тенге установочным платежом и подписывается на план рекуррентных платежей по 1000 тенге ежемесячно, но не более 11 списаний.

Заморозка плана

Подписку на регулярные платежи можно приостановить на любой срок из личного кабинета или с помощью API.

Пример: покупатель просит приостановить предоставление услуг на пару месяцев, вы сдвигаете дату следующего платежа на соответствующий срок.

Возможность смены суммы платежа

Сумма установочного платежа

Сумма первого установочного платежа может быть произвольной и отличаться от суммы последующих рекуррентных платежей.

Пример: покупатель регистрируется в вашем сервисе, вы просите его выполнить установочный платеж на 1 Тенге для проверки карты. Далее, с согласия пользователя, запускаете рекуррентные платежи на любую сумму.

Сумма рекуррентных платежей

Сумму рекуррентных платежей можно изменять в любой момент действия плана из личного кабинета или с помощью API.

Пример: вы предоставляете покупателю скидку на первые 2 месяца использования сервиса, далее повышаете сумму подписки.

Автоматическая коррекция ошибок

Ошибки, которые возникают при выполнении рекуррентных платежей, можно разделить на: поправимые и непоправимые.

В первую категорию относятся ошибки, связанные с недостатком средств на карте покупателя, с временными техническими проблемами или недоступностью банка-эмитента карты. Как правило, данные проблемы может исправить держатель карты.

Во вторую категорию попадают ошибки, исправление которых невозможно: истек срок действия карты, карта утеряна, у банка-эмитента отозвана лицензия.

В зависимости от категории система по-разному реагирует и обрабатывает ошибки рекуррентных платежей.

Взаимодействие с держателем карты

В случае отказа по причине недостатка средств на карте, система сообщает держателю, что очередной платеж не прошел, рекомендует пополнить счет карты и информирует, что повторная попытка списания будет произведена на следующий день.

Повторные попытки

Система повторяет попытки списаний с карты несколько дней подряд, если очередной платеж не проходит из-за поправимой ошибки.

Обновление карты

Система предлагает через свою форму ввести новые данные карты для продолжения рекуррентных платежей. Если покупатель соглашается, система проводит новый установочный платеж по реквизитам полученной карты, засчитывает платеж в подписку и продолжает выполнять регулярные платежи по обновленной карте.

Оповещение покупателя

Важная функция рекуррентных платежей — это своевременное информирование держателя карты о наступлении даты очередного платежа. Некоторым покупателям свойственна забывчивость, поэтому предупреждение о предстоящем списании убирает эффект внезапности и существенно снижает вероятность отсутствия денег на карте. Система TipTop Pay всегда напоминает плательщикам дату очередного платежа с указанием суммы, назначения и получателя оплаты.

SDK для iOS

SDK позволяет интегрировать прием платежей в мобильные приложение для платформы iOS.
Основная версия находится на GitHub.

Из приложения вы узнаете как получить карточные данные, сформировать криптограмму, провести 3-D Secure авторизацию и выполнить платеж на iPhone или iPad.

Условия использования:

SDK для Android

SDK позволяет интегрировать прием платежей в мобильные приложение для платформы Android.
Основная версия находится на GitHub.

Из приложения вы узнаете, как получить карточные данные, сформировать криптограмму, провести 3-D Secure авторизацию и выполнить платеж на Android.

Условия использования:

API

API — программный интерфейс системы для взаимодействия с системами ТСП.

Интерфейс работает по адресу api.tiptoppay.kz и поддерживает функции для выполнения платежа, отмены оплаты, возврата денег, завершения платежей, выполненных по двухстадийной схеме, создания и отмены подписок на рекуррентные платежи, а также отправки счетов по почте.

Принцип работы

Выбор формата передачи параметров определяется на стороне клиента и управляется через заголовок запроса Content-Type.

Ответ система выдает в JSON-формате, который как минимум включает в себя два параметра: Success и Message:

{ "Success": false, "Message": "Invalid Amount value" }

Аутентификация запросов

Для аутентификации запроса используется HTTP Basic Auth — отправка логина и пароля в заголовке HTTP-запроса. В качестве логина используется Public ID, в качестве пароля — API Secret. Оба этих значения можно получить в личном кабинете.

Идемпотентность API

Идемпотентность — свойство API при повторном запросе выдавать тот же результат, что на первичный запрос без повторной обработки. Это значит, что вы можете отправить несколько запросов к системе с одинаковым идентификатором, при этом обработан будет только один успешный запрос, а все ответы будут идентичными. Таким образом реализуется защита от сетевых ошибок, которые приводят к созданию дублированных записей и действий.
Для включения идемпотентности необходимо в запросе к API передавать заголовок с ключом X-Request-ID, содержащий уникальный идентификатор. Формирование идентификатора запроса остается на вашей стороне — это может быть guid, комбинация из номера заказа, даты и суммы или любое другое значение на ваше усмотрение.
Каждый новый запрос, который необходимо обработать, должен включать новое значение X-Request-ID. Обработанный результат хранится в системе в течение 1 часа.

Тестовый метод

Для проверки взаимодействия с API можно вызвать тестовый метод.

Адрес метода:
https://api.tiptoppay.kz/test

Параметры запроса:
Отсутствуют.

Пример ответа:
В ответ метод возвращает статус запроса.

{"Success":true,"Message":"bd6353c3-0ed6-4a65-946f-083664bf8dbd"}

Оплата по криптограмме

Метод для оплаты по криптограмме платежных данных результат алгоритма шифрования. Для формирования криптограммы воспользуйтесь скриптом Checkout, Apple Pay или Google Pay.

Адреса метода:
https://api.tiptoppay.kz/payments/cards/charge — для одностадийного платежа
https://api.tiptoppay.kz/payments/cards/auth — для двухстадийного

Параметры запроса:

Параметр Формат Применение Описание
Amount Number Обязательный Cумма платежа в валюте, разделитель точка. Количество не нулевых знаков после точки – 2.
Currency String Необязательный Валюта: KZT/USD/EUR/GBP (см. справочник). Если параметр не передан, то по умолчанию принимает значение KZT
IpAddress String Обязательный IP-адрес плательщика
CardCryptogramPacket String Обязательный Криптограмма платежных данных
Name String Необязательный Имя держателя карты латиницей
PaymentUrl String Необязательный Адрес сайта, с которого совершается вызов скрипта checkout
InvoiceId String Необязательный Номер счета или заказа
Description String Необязательный Описание оплаты в свободной форме
CultureName String Необязательный Язык уведомлений. Возможные значения: "ru-RU", "en-US". (см. справочник)
AccountId String Необязательный Обязательный идентификатор пользователя для создания подписки и получения токена
Email String Необязательный E-mail плательщика, на который будет отправлена квитанция об оплате
Payer Object Необязательный Доп. поле, куда передается информация о плательщике. Используйте следующие параметры: FirstName, LastName, MiddleName, Birth, Street, Address, City, Country, Phone, Postcode
JsonData Json Необязательный Любые другие данные, которые будут связаны с транзакцией, в том числе инструкции для создания подписки или формирования онлайн-чека должны обёртываться в объект PaymentData. Мы зарезервировали названия следующих параметров и отображаем их содержимое в реестре операций, выгружаемом в Личном Кабинете: name, firstName, middleName, lastName, nick, phone, address, comment, birthDate.

В ответ сервер возвращает JSON с тремя составляющими:

Возможные варианты ответа:

Пример запроса на оплату по криптограмме:

{
    "Amount":10,
    "Currency":"KZT",
    "InvoiceId":"1234567",
    "IpAddress": "123.123.123.123",
    "Description":"Оплата товаров в example.com",
    "AccountId":"user_x",
    "Name":"CARDHOLDER NAME", // CardCryptogramPacket Обязательный параметр
    "CardCryptogramPacket":"01492500008719030128SMfLeYdKp5dSQVIiO5l6ZCJiPdel4uDjdFTTz1UnXY+3QaZcNOW8lmXg0H670MclS4lI+qLkujKF4pR5Ri+T/E04Ufq3t5ntMUVLuZ998DLm+OVHV7FxIGR7snckpg47A73v7/y88Q5dxxvVZtDVi0qCcJAiZrgKLyLCqypnMfhjsgCEPF6d4OMzkgNQiynZvKysI2q+xc9cL0+CMmQTUPytnxX52k9qLNZ55cnE8kuLvqSK+TOG7Fz03moGcVvbb9XTg1oTDL4pl9rgkG3XvvTJOwol3JDxL1i6x+VpaRxpLJg0Zd9/9xRJOBMGmwAxo8/xyvGuAj85sxLJL6fA=="
    "Payer":
      { 
        "FirstName":"Тест",
        "LastName":"Тестов",
        "MiddleName":"Тестович",
        "Birth":"1955-02-24",
        "Address":"тестовый проезд дом тест",
        "Street":"Lenina",
        "City":"Almaty",
        "Country":"KZ",
        "Phone":"123",
        "Postcode":"345"
    }
}

Пример ответа: некорректный запрос:

{"Success":false,"Message":"Amount is required"}

Пример ответа: требуется 3-D Secure аутентификация:

{
    "Model": {
        "TransactionId": 891463508,
        "PaReq": "+/eyJNZXJjaGFudE5hbWUiOm51bGwsIkZpcnN0U2l4IjoiNDI0MjQyIiwiTGFzdEZvdXIiOiI0MjQyIiwiQW1vdW50IjoxMDAuMCwiQ3VycmVuY3lDb2RlIjoiUlVCIiwiRGF0ZSI6IjIwMjEtMTAtMjVUMDA6MDA6MDArMDM6MDAiLCJDdXN0b21lck5hbWUiOm51bGwsIkN1bHR1cmVOYW1lIjoicnUtUlUifQ==",
        "GoReq": null,
        "AcsUrl": "https://demo.tiptoppay.kz/acs",
        "ThreeDsSessionData": null,
        "IFrameIsAllowed": true,
        "FrameWidth": null,
        "FrameHeight": null,
        "ThreeDsCallbackId": "7be4d37f0a434c0a8a7fc0e328368d7d",
        "EscrowAccumulationId": null
    },
    "Success": false,
    "Message": null
}

Пример ответа: транзакция отклонена. В поле ReasonCode код ошибки (см. справочник):

{
    "Model": {
        "ReasonCode": 5051,
        "PublicId": "pk_**********************************",
        "TerminalUrl": "http://test.test",
        "TransactionId": 891583633,
        "Amount": 10,
        "Currency": "KZT",
        "CurrencyCode": 0,
        "PaymentAmount": 10,
        "PaymentCurrency": "KZT",
        "PaymentCurrencyCode": 0,
        "InvoiceId": "1234567",
        "AccountId": "user_x",
        "Email": null,
        "Description": "Оплата товаров в example.com",
        "JsonData": null,
        "CreatedDate": "/Date(1635154784619)/",
        "PayoutDate": null,
        "PayoutDateIso": null,
        "PayoutAmount": null,
        "CreatedDateIso": "2021-10-25T09:39:44",
        "AuthDate": null,
        "AuthDateIso": null,
        "ConfirmDate": null,
        "ConfirmDateIso": null,
        "AuthCode": null,
        "TestMode": true,
        "Rrn": null,
        "OriginalTransactionId": null,
        "FallBackScenarioDeclinedTransactionId": null,
        "IpAddress": "123.123.123.123",
        "IpCountry": "CN",
        "IpCity": "Beijing",
        "IpRegion": "Beijing",
        "IpDistrict": "Beijing",
        "IpLatitude": 39.9289,
        "IpLongitude": 116.3883,
        "CardFirstSix": "400005",
        "CardLastFour": "5556",
        "CardExpDate": "12/25",
        "CardType": "Visa",
        "CardProduct": null,
        "CardCategory": null,
        "EscrowAccumulationId": null,
        "IssuerBankCountry": "US",
        "Issuer": "ITS Bank",
        "CardTypeCode": 0,
        "Status": "Declined",
        "StatusCode": 5,
        "CultureName": "kk",
        "Reason": "InsufficientFunds",
        "CardHolderMessage": "Недостаточно средств на карте",
        "Type": 0,
        "Refunded": false,
        "Name": "CARDHOLDER NAME",
        "Token": "tk_255c42192323f2e09ea17635302c3",
        "SubscriptionId": null,
        "GatewayName": "Test",
        "ApplePay": false,
        "AndroidPay": false,
        "WalletType": "",
        "TotalFee": 0
    },
    "Success": false,
    "Message": null
}

Пример ответа: транзакция принята:

{
    "Model": {
        "ReasonCode": 0,
        "PublicId": "pk_********************************",
        "TerminalUrl": "http://test.test",
        "TransactionId": 891510444,
        "Amount": 10,
        "Currency": "KZT",
        "CurrencyCode": 0,
        "PaymentAmount": 10,
        "PaymentCurrency": "KZT",
        "PaymentCurrencyCode": 0,
        "InvoiceId": "1234567",
        "AccountId": "user_x",
        "Email": null,
        "Description": "Оплата товаров в example.com",
        "JsonData": null,
        "CreatedDate": "/Date(1635150224630)/",
        "PayoutDate": null,
        "PayoutDateIso": null,
        "PayoutAmount": null,
        "CreatedDateIso": "2021-10-25T08:23:44",
        "AuthDate": "/Date(1635150224739)/",
        "AuthDateIso": "2021-10-25T08:23:44",
        "ConfirmDate": null,
        "ConfirmDateIso": null,
        "AuthCode": "A1B2C3",
        "TestMode": true,
        "Rrn": null,
        "OriginalTransactionId": null,
        "FallBackScenarioDeclinedTransactionId": null,
        "IpAddress": "123.123.123.123",
        "IpCountry": "CN",
        "IpCity": "Beijing",
        "IpRegion": "Beijing",
        "IpDistrict": "Beijing",
        "IpLatitude": 39.9289,
        "IpLongitude": 116.3883,
        "CardFirstSix": "411111",
        "CardLastFour": "1111",
        "CardExpDate": "11/25",
        "CardType": "Visa",
        "CardProduct": "C",
        "CardCategory": "Visa Signature (Signature)",
        "EscrowAccumulationId": null,
        "IssuerBankCountry": "KZ",
        "Issuer": "TipTop Pay",
        "CardTypeCode": 0,
        "Status": "Authorized",
        "StatusCode": 2,
        "CultureName": "kk",
        "Reason": "Approved",
        "CardHolderMessage": "Оплата успешно проведена",
        "Type": 0,
        "Refunded": false,
        "Name": "CARDHOLDER NAME",
        "Token": "0a0afb77-8f41-4de2-9524-1057f9695303",
        "SubscriptionId": null,
        "GatewayName": "Test",
        "ApplePay": false,
        "AndroidPay": false,
        "WalletType": "",
        "TotalFee": 0
    },
    "Success": true,
    "Message": null
}

Обработка 3-D Secure

Для проведения 3-D Secure аутентификации нужно отправить плательщика на адрес, указанный в параметре AcsUrl ответа сервера с передачей следующих параметров:

Пример формы:

<form name="downloadForm" action="AcsUrl" method="POST">
    <input type="hidden" name="PaReq" value="eJxVUdtugkAQ/RXDe9mLgo0Z1nhpU9PQasWmPhLYAKksuEChfn13uVR9mGTO7MzZM2dg3qSn0Q+X\nRZIJxyAmNkZcBFmYiMgxDt7zw6MxZ+DFkvP1ngeV5AxcXhR+xEdJ6BhpEZnEYLBdfPAzg56JKSKT\nAhqgGpFB7IuSgR+cl5s3NqFTG2NAPYSUy82aETqeWPYUUAdB+ClnwSmrwtz/TbkoC0BtDYKsEqX8\nZfZkDGgAUMkTi8synyFU17V5N2nKCpBuAHRVs610VijCJgmZu17UXTxhFWP34l7evYPlegsHkO6A\n0C85o5hMsI3piNIZHc+IBaitg59qJYzgdrUOQK7/WNy+3FZAeSqV5cMqAwLe5JlQwpny8T8HdFW8\netFuBqUyahV+Hjf27vWCaSx22fe+KY6kXKZfJLK1x22TZkyUS8QiHaUGgDQN6s+H+tOq7O7kf8hd\nt30=">
    <input type="hidden" name="MD" value="504">
    <input type="hidden" name="TermUrl" value="https://example.com/post3ds?order=1234567">
</form>
<script>
    window.onload = submitForm;
    function submitForm() { downloadForm.submit(); }
</script>


Для завершения оплаты выполните следующий метод Post3ds.

Адрес метода:
https://api.tiptoppay.kz/payments/cards/post3ds

Параметры запроса:

Параметр Формат Применение Описание
TransactionId Long Обязательный Значение параметра MD
PaRes String Обязательный Значение одноименного параметра

В ответ на корректно сформированный запрос сервер вернет либо информацию об успешной транзакции, либо — об отклоненной.

Оплата по токену (рекарринг)

Метод для оплаты по токену, полученному при оплате по криптограмме, либо через Pay-уведомление.

Адреса метода:
https://api.tiptoppay.kz/payments/tokens/charge — для одностадийного платежа
https://api.tiptoppay.kz/payments/tokens/auth — для двухстадийного

Параметры запроса:

Параметр Формат Применение Описание
Amount Number Обязательный Cумма платежа в валюте, разделитель точка. Количество не нулевых знаков после точки – 2.
Currency String Необязательный Валюта: KZT/USD/EUR/GBP (см. справочник). Если параметр не передан, то по умолчанию принимает значение KZT
AccountId String Обязательный Идентификатор пользователя
TrInitiatorCode Int Необязательный Признак инициатора списания денежных средств.Возможные значения:
0 - транзакция инициирована ТСП на основе ранее сохраненных учетных данных;
1 - транзакция инициирована держателем карты (клиентом) на основе ранее сохраненных учетных данных.
Token String Обязательный Токен
InvoiceId String Необязательный Номер счета или заказа
Description String Необязательный Назначение платежа в свободной форме
IpAddress String Необязательный IP-адрес плательщика
Email String Необязательный E-mail плательщика, на который будет отправлена квитанция об оплате
Payer Object Необязательный Доп. поле, куда передается информация о плательщике. Используйте следующие параметры: FirstName, LastName, MiddleName, Birth, Street, Address, City, Country, Phone, Postcode
JsonData Json Необязательный Любые другие данные, которые будут связаны с транзакцией, в том числе инструкции для создания подписки или формирования онлайн-чека должны обёртываться в объект PaymentData. Мы зарезервировали названия следующих параметров и отображаем их содержимое в реестре операций, выгружаемом в Личном Кабинете: name, firstName, middleName, lastName, nick, phone, address, comment, birthDate.

В ответ сервер возвращает JSON с тремя составляющими: поле success — результат запроса, поле message — описание ошибки, объект model — расширенная информация.

Возможные варианты

Пример запроса на оплату по токену:

{
    "Amount":59,
    "Currency":"KZT",
    "InvoiceId":"1234567",
    "Description":"Оплата товаров в example.com",
    "AccountId":"user_x",
    "Token":"success_1111a3e0-2428-48fb-a530-12815d90d0e8",
    "Payer":
      { 
        "FirstName":"Тест",
        "LastName":"Тестов",
        "MiddleName":"Тестович",
        "Birth":"1955-02-24",
        "Address":"тестовый проезд дом тест",
        "Street":"Lenina",
        "City":"Almaty",
        "Country":"KZ",
        "Phone":"123",
        "Postcode":"345"
    }
}

Пример ответа: некорректный запрос

{"Success":false,"Message":"Amount is required"}

Пример ответа: транзакция отклонена. В поле ReasonCode код ошибки (см. справочник)

{
    "Model": {
        "ReasonCode": 5051,
        "PublicId": "pk_**********************************",
        "TerminalUrl": "http://test.test",
        "TransactionId": 891583633,
        "Amount": 100,
        "Currency": "KZT",
        "CurrencyCode": 0,
        "PaymentAmount": 100,
        "PaymentCurrency": "KZT",
        "PaymentCurrencyCode": 0,
        "InvoiceId": "1234567",
        "AccountId": "user_x",
        "Email": null,
        "Description": "Оплата товаров в example.com",
        "JsonData": null,
        "CreatedDate": "/Date(1635154784619)/",
        "PayoutDate": null,
        "PayoutDateIso": null,
        "PayoutAmount": null,
        "CreatedDateIso": "2021-10-25T09:39:44",
        "AuthDate": null,
        "AuthDateIso": null,
        "ConfirmDate": null,
        "ConfirmDateIso": null,
        "AuthCode": null,
        "TestMode": true,
        "Rrn": null,
        "OriginalTransactionId": null,
        "FallBackScenarioDeclinedTransactionId": null,
        "IpAddress": "123.123.123.123",
        "IpCountry": "CN",
        "IpCity": "Beijing",
        "IpRegion": "Beijing",
        "IpDistrict": "Beijing",
        "IpLatitude": 39.9289,
        "IpLongitude": 116.3883,
        "CardFirstSix": "400005",
        "CardLastFour": "5556",
        "CardExpDate": "12/25",
        "CardType": "Visa",
        "CardProduct": null,
        "CardCategory": null,
        "EscrowAccumulationId": null,
        "IssuerBankCountry": "US",
        "Issuer": "ITS Bank",
        "CardTypeCode": 0,
        "Status": "Declined",
        "StatusCode": 5,
        "CultureName": "kk",
        "Reason": "InsufficientFunds",
        "CardHolderMessage": "Недостаточно средств на карте",
        "Type": 0,
        "Refunded": false,
        "Name": "CARDHOLDER NAME",
        "Token": "tk_255c42192323f2e09ea17635302c3",
        "SubscriptionId": null,
        "GatewayName": "Test",
        "ApplePay": false,
        "AndroidPay": false,
        "WalletType": "",
        "TotalFee": 0
    },
    "Success": false,
    "Message": null
}

Пример ответа: транзакция принята

 {
    "Model": {
        "ReasonCode": 0,
        "PublicId": "pk_**************************",
        "TerminalUrl": "http://test.test",
        "TransactionId": 897728064,
        "Amount": 59,
        "Currency": "KZT",
        "CurrencyCode": 0,
        "PaymentAmount": 59,
        "PaymentCurrency": "KZT",
        "PaymentCurrencyCode": 0,
        "InvoiceId": 1234567,
        "AccountId": "user_x",
        "Email": null,
        "Description": "Оплата товаров в example.com",
        "JsonData": null,
        "CreatedDate": "/Date(1635562705992)/",
        "PayoutDate": null,
        "PayoutDateIso": null,
        "PayoutAmount": null,
        "CreatedDateIso": "2021-10-30T02:58:25",
        "AuthDate": "/Date(1635562706070)/",
        "AuthDateIso": "2021-10-30T02:58:26",
        "ConfirmDate": "/Date(1635562706070)/",
        "ConfirmDateIso": "2021-10-30T02:58:26",
        "AuthCode": "A1B2C3",
        "TestMode": true,
        "Rrn": null,
        "OriginalTransactionId": null,
        "FallBackScenarioDeclinedTransactionId": null,
        "IpAddress": "87.251.91.164",
        "IpCountry": "KZ",
        "IpCity": "Алматы",
        "IpRegion": "Алматы",
        "IpDistrict": "Алматы",
        "IpLatitude": 55.03923,
        "IpLongitude": 82.927818,
        "CardFirstSix": "424242",
        "CardLastFour": "4242",
        "CardExpDate": "12/25",
        "CardType": "Visa",
        "CardProduct": "I",
        "CardCategory": "Visa Infinite Infinite",
        "EscrowAccumulationId": null,
        "IssuerBankCountry": "KZ",
        "Issuer": "TipTop Pay",
        "CardTypeCode": 0,
        "Status": "Completed",
        "StatusCode": 3,
        "CultureName": "kk",
        "Reason": "Approved",
        "CardHolderMessage": "Оплата успешно проведена",
        "Type": 0,
        "Refunded": false,
        "Name": "SER",
        "Token": "success_1111a3e0-2428-48fb-a530-12815d90d0e8",
        "SubscriptionId": null,
        "GatewayName": "Test",
        "ApplePay": false,
        "AndroidPay": false,
        "WalletType": "",
        "TotalFee": 0
    },
    "Success": true,
    "Message": null
}

Подтверждение оплаты

Для платежей, проведенных по двухстадийной схеме, необходимо подтверждение оплаты, которое можно выполнить через личный кабинет, либо через вызов метода API.

Адрес метода:
https://api.tiptoppay.kz/payments/confirm

Параметры запроса:

Параметр Формат Применение Описание
TransactionId Long Обязательный Номер транзакции в системе
Amount Number Обязательный Сумма подтверждения в валюте транзакции, разделитель точка. Количество не нулевых знаков после точки – 2.
JsonData Json Необязательный Любые другие данные, которые будут связаны с транзакцией, в том числе инструкции для формирования онлайн-чека

Пример запроса:

{"TransactionId":455,"Amount":65.98}

Пример ответа:

{"Success":true,"Message":null}

Отмена оплаты

Отмену оплаты можно выполнить через личный кабинет либо через вызов метода API.

Адрес метода:
https://api.tiptoppay.kz/payments/void

Параметры запроса:

Параметр Формат Применение Описание
TransactionId Long Обязательный Номер транзакции в системе

Пример запроса:

{"TransactionId":455}

Пример ответа:

{"Success":true,"Message":null}

Возврат денег

Возврат денег можно выполнить через личный кабинет или через вызов метода API.

Адрес метода:
https://api.tiptoppay.kz/payments/refund

Параметры запроса:

Параметр Формат Применение Описание
TransactionId Long Обязательный Номер транзакции оплаты
Amount Number Обязательный Сумма возврата в валюте транзакции, разделитель точка. Количество не нулевых знаков после точки – 2.
JsonData Json Необязательный Любые другие данные, которые будут связаны с транзакцией, в том числе инструкции для формирования онлайн-чека

Пример запроса:

{"TransactionId":455, "Amount": 100}

Пример ответа:

{
    "Model": {
        "TransactionId": 568
    },
    "Success": true,
    "Message": null
}

Выплата по криптограмме

Выплату по криптограмме можно осуществить через вызов метода API.

Адрес метода:
https://api.tiptoppay.kz/payments/cards/topup

Параметры запроса:

Параметр Формат Применение Описание
CardCryptogramPacket String Обязательный Криптограмма платежных данных
Amount Number Обязательный Cумма платежа в валюте, разделитель точка. Количество не нулевых знаков после точки – 2.
Currency String Обязательный Валюта: KZT
Name String Необязательный Имя держателя карты латиницей
AccountId String Необязательный Идентификатор пользователя
Email String Необязательный E-mail плательщика, на который будет отправлена квитанция об оплате
JsonData Json Необязательный Любые другие данные, которые будут связаны с транзакцией. Мы зарезервировали названия следующих параметров и отображаем их содержимое в реестре операций, выгружаемом в Личном Кабинете: name, firstName, middleName, lastName, nick, phone, address, comment, birthDate.
InvoiceId String Необязательный Номер заказа в вашей системе
Description String Необязательный Описание оплаты в свободной форме
Payer Object Необязательный Доп. поле, куда передается информация о плательщике
Receiver Object Необязательный Доп. поле, куда передается информация о получателе

Пример запроса:

{
    "Name":"CARDHOLDER NAME",
    "CardCryptogramPacket":"01492500008719030128SMfLeYdKp5dSQVIiO5l6ZCJiPdel4uDjdFTTz1UnXY+3QaZcNOW8lmXg0H670MclS4lI+qLkujKF4pR5Ri+T/E04Ufq3t5ntMUVLuZ998DLm+OVHV7FxIGR7snckpg47A73v7/y88Q5dxxvVZtDVi0qCcJAiZrgKLyLCqypnMfhjsgCEPF6d4OMzkgNQiynZvKysI2q+xc9cL0+CMmQTUPytnxX52k9qLNZ55cnE8kuLvqSK+TOG7Fz03moGcVvbb9XTg1oTDL4pl9rgkG3XvvTJOwol3JDxL1i6x+VpaRxpLJg0Zd9/9xRJOBMGmwAxo8/xyvGuAj85sxLJL6fA==",
    "Amount":1,
    "AccountId":"[email protected]",
    "Currency":"KZT",
    "InvoiceId":"1234567",
    "Payer":
      //Набор полей аналогичен и для параметра Receiver
      { 
        "FirstName":"Тест",
        "LastName":"Тестов",
        "MiddleName":"Тестович",
        "Address":"тестовый проезд дом тест",
        "Birth":"1955-02-24",
        "City":"Almaty",
        "Street":"Lenina",
        "Country":"KZ",
        "Phone":"123",
        "Postcode":"345"
    }
}

Пример ответа:

{
    "Model": {
        "ReasonCode": 0,
        "PublicId": "pk_*******************************",
        "TerminalUrl": "http://test.test",
        "TransactionId": 897739551,
        "Amount": 399,
        "Currency": "KZT",
        "CurrencyCode": 0,
        "PaymentAmount": 399,
        "PaymentCurrency": "KZT",
        "PaymentCurrencyCode": 0,
        "InvoiceId": null,
        "AccountId": "[email protected]",
        "Email": null,
        "Description": null,
        "JsonData": null,
        "CreatedDate": "/Date(1635564719715)/",
        "PayoutDate": null,
        "PayoutDateIso": null,
        "PayoutAmount": null,
        "CreatedDateIso": "2021-10-30T03:31:59",
        "AuthDate": "/Date(1635564719858)/",
        "AuthDateIso": "2021-10-30T03:31:59",
        "ConfirmDate": "/Date(1635564719858)/",
        "ConfirmDateIso": "2021-10-30T03:31:59",
        "AuthCode": "A1B2C3",
        "TestMode": true,
        "Rrn": null,
        "OriginalTransactionId": null,
        "FallBackScenarioDeclinedTransactionId": null,
        "IpAddress": "172.18.200.124",
        "IpCountry": "",
        "IpCity": null,
        "IpRegion": null,
        "IpDistrict": null,
        "IpLatitude": null,
        "IpLongitude": null,
        "CardFirstSix": "424242",
        "CardLastFour": "4242",
        "CardExpDate": "12/25",
        "CardType": "Visa",
        "CardProduct": "I",
        "CardCategory": "Visa Infinite (Infinite)",
        "EscrowAccumulationId": null,
        "IssuerBankCountry": "KZ",
        "Issuer": "TipTop Pay",
        "CardTypeCode": 0,
        "Status": "Completed",
        "StatusCode": 3,
        "CultureName": "kk",
        "Reason": "Approved",
        "CardHolderMessage": "Оплата успешно проведена",
        "Type": 2,
        "Refunded": false,
        "Name": "CARDHOLDER NAME",
        "Token": null,
        "SubscriptionId": null,
        "GatewayName": "Test",
        "ApplePay": false,
        "AndroidPay": false,
        "WalletType": "",
        "TotalFee": 0
    },
    "Success": true,
    "Message": null
}

Выплата по токену

Выплату по токену можно осуществить через вызов метода API.

Адрес метода:
https://api.tiptoppay.kz/payments/token/topup

Параметры запроса:

Параметр Формат Применение Описание
Token String Обязательный Токен карты, выданный системой после первого платежа
Amount Number Обязательный Cумма платежа в валюте, разделитель точка. Количество не нулевых знаков после точки – 2.
AccountId String Обязательный Идентификатор пользователя
Currency String Обязательный Валюта: KZT
InvoiceId String Необязательный Номер заказа в вашей системе
Payer Object Необязательный Доп. поле, куда передается информация о плательщике
Receiver Object Необязательный Доп. поле, куда передается информация о получателе

Пример запроса:

{
    "Token":"0a0afb77-8f41-4de2-9524-1057f9695303",
    "Amount":59,
    "AccountId":"user_x",
    "Currency":"KZT",
    "Payer":
    //Набор полей аналогичен и для параметра Receiver
      { 
        "FirstName":"Тест",
        "LastName":"Тестов",
        "MiddleName":"Тестович",
        "Address":"тестовый проезд дом тест",
        "Birth":"1955-02-24",
        "City":"Almaty",
        "Country":"KZ",
        "Phone":"123",
        "Postcode":"345"
    }
}

Пример ответа:

 {
    "Model": {
        "ReasonCode": 0,
        "PublicId": "pk_******************************",
        "TerminalUrl": "http://test.test",
        "TransactionId": 897747761,
        "Amount": 59,
        "Currency": "KZT",
        "CurrencyCode": 0,
        "PaymentAmount": 59,
        "PaymentCurrency": "KZT",
        "PaymentCurrencyCode": 0,
        "InvoiceId": null,
        "AccountId": "user_x",
        "Email": null,
        "Description": null,
        "JsonData": null,
        "CreatedDate": "/Date(1635566071122)/",
        "PayoutDate": null,
        "PayoutDateIso": null,
        "PayoutAmount": null,
        "CreatedDateIso": "2021-10-30T03:54:31",
        "AuthDate": "/Date(1635566071232)/",
        "AuthDateIso": "2021-10-30T03:54:31",
        "ConfirmDate": "/Date(1635566071232)/",
        "ConfirmDateIso": "2021-10-30T03:54:31",
        "AuthCode": "A1B2C3",
        "TestMode": true,
        "Rrn": null,
        "OriginalTransactionId": null,
        "FallBackScenarioDeclinedTransactionId": null,
        "IpAddress": "172.18.200.124",
        "IpCountry": "",
        "IpCity": null,
        "IpRegion": null,
        "IpDistrict": null,
        "IpLatitude": null,
        "IpLongitude": null,
        "CardFirstSix": "411111",
        "CardLastFour": "1111",
        "CardExpDate": "11/25",
        "CardType": "Visa",
        "CardProduct": "C",
        "CardCategory": "Visa Signature Signature",
        "EscrowAccumulationId": null,
        "IssuerBankCountry": "KZ",
        "Issuer": "TipTop Pay",
        "CardTypeCode": 0,
        "Status": "Completed",
        "StatusCode": 3,
        "CultureName": "kk",
        "Reason": "Approved",
        "CardHolderMessage": "Оплата успешно проведена",
        "Type": 2,
        "Refunded": false,
        "Name": "CARDHOLDER NAME",
        "Token": "0a0afb77-8f41-4de2-9524-1057f9695303",
        "SubscriptionId": null,
        "GatewayName": "Test",
        "ApplePay": false,
        "AndroidPay": false,
        "WalletType": "",
        "TotalFee": 0
    },
    "Success": true,
    "Message": null
}

Просмотр транзакции

Метод получения детализации по транзакции.

Адрес метода:
https://api.tiptoppay.kz/payments/get

Параметры запроса:

Параметр Формат Применение Описание
TransactionId Long Обязательный Номер транзакции

Если транзакция с указанным номером была найдена, система отобразит информацию о ней.

Пример запроса:

{"TransactionId":897749645}

Пример ответа:

{
    "Model": {
        "ReasonCode": 0,
        "PublicId": "pk_*****************************************",
        "TerminalUrl": "http://test.test",
        "TransactionId": 897749645,
        "Amount": 159,
        "Currency": "KZT",
        "CurrencyCode": 0,
        "PaymentAmount": 159,
        "PaymentCurrency": "KZT",
        "PaymentCurrencyCode": 0,
        "InvoiceId": "12345",
        "AccountId": "usex_x",
        "Email": null,
        "Description": "test",
        "JsonData": "",
        "CreatedDate": "/Date(1635566398686)/",
        "PayoutDate": null,
        "PayoutDateIso": null,
        "PayoutAmount": null,
        "CreatedDateIso": "2021-10-30T03:59:58",
        "AuthDate": "/Date(1635566402780)/",
        "AuthDateIso": "2021-10-30T04:00:02",
        "ConfirmDate": "/Date(1635566406382)/",
        "ConfirmDateIso": "2021-10-30T04:00:06",
        "AuthCode": "A1B2C3",
        "TestMode": true,
        "Rrn": null,
        "OriginalTransactionId": null,
        "FallBackScenarioDeclinedTransactionId": null,
        "IpAddress": "87.251.91.164",
        "IpCountry": "KZ",
        "IpCity": "Алматы",
        "IpRegion": "Алматы",
        "IpDistrict": "Алматы",
        "IpLatitude": 55.03923,
        "IpLongitude": 82.927818,
        "CardFirstSix": "424242",
        "CardLastFour": "4242",
        "CardExpDate": "12/25",
        "CardType": "Visa",
        "CardProduct": "I",
        "CardCategory": "Visa Infinite (Infinite)",
        "EscrowAccumulationId": null,
        "IssuerBankCountry": "KZ",
        "Issuer": "TipTop Pay",
        "CardTypeCode": 0,
        "Status": "Completed",
        "StatusCode": 3,
        "CultureName": "kk",
        "Reason": "Approved",
        "CardHolderMessage": "Оплата успешно проведена",
        "Type": 0,
        "Refunded": false,
        "Name": "TEST",
        "Token": "success_eb250528-bd9e-4de7-bb49-9e0b546351d3",
        "SubscriptionId": null,
        "GatewayName": "Test",
        "ApplePay": false,
        "AndroidPay": false,
        "WalletType": "",
        "TotalFee": 0
    },
    "Success": true,
    "Message": null
}

Проверка статуса платежа

Метод поиска платежа и проверки статуса (см. справочник).

Адрес старого метода:
https://api.tiptoppay.kz/payments/find

Адрес нового метода:
https://api.tiptoppay.kz/v2/payments/find

Параметры запроса:

Параметр Формат Применение Описание
InvoiceId String Обязательный Номер заказа

Если платеж по указанному номеру заказа был найден, система отобразит либо информацию об успешной транзакции, либо — об отклоненной. Если будет найдено несколько платежей с указанным номером заказа, то система вернет информацию только о последней операции. Отличие нового метода в том, что он ищет по всем платежам, включая возвраты и выплаты на карту.

Пример запроса:

{"InvoiceId":"123456789"}

Пример ответа:

{"Success":false,"Message":"Not found"}

Выгрузка списка транзакций

Метод выгрузки списка транзакций за день.

Адрес метода:
https://api.tiptoppay.kz/payments/list

Параметры запроса:

Параметр Формат Применение Описание
Date Date Обязательный Дата создания операций
TimeZone String Необязательный Код временной зоны, по умолчанию — UTC

В выгрузку транзакций попадают все операции, зарегистрированные за указанный день. Для удобства учета вы можете указать код временной зоны (см. справочник).

Пример запроса:

{"Date":"2014-08-09", "TimeZone": "MSK"}

Пример ответа:

{
   "Model":[
      {
         "PublicId":"test_api_00000000000000000000001",
         "TerminalUrl":"https://tiptoppay.kz",
         "TransactionId":54,
         "Amount":12.34,
         "Currency":"KZT",
         "CurrencyCode":0,
         "PaymentAmount":12.34,
         "PaymentCurrency":"KZT",
         "PaymentCurrencyCode":0,
         "InvoiceId":"1234567",
         "AccountId":"[email protected]",
         "Email":null,
         "Description":"Оплата товаров в example.com",
         "JsonData":"{\"some\": \"value\"}",
         "CreatedDate":"\/Date(1615288374632)\/",
         "PayoutDate":null,
         "PayoutDateIso":null,
         "PayoutAmount":null,
         "CreatedDateIso":"2021-03-09T11:12:54",
         "AuthDate":null,
         "AuthDateIso":null,
         "ConfirmDate":null,
         "ConfirmDateIso":null,
         "AuthCode":null,
         "TestMode":true,
         "Rrn":null,
         "OriginalTransactionId":null,
         "FallBackScenarioDeclinedTransactionId":null,
         "IpAddress":"127.0.0.1",
         "IpCountry":"",
         "IpCity":null,
         "IpRegion":null,
         "IpDistrict":null,
         "IpLatitude":null,
         "IpLongitude":null,
         "CardFirstSix":"424242",
         "CardLastFour":"4242",
         "CardExpDate":"05/22",
         "CardType":"Visa",
         "CardProduct":null,
         "CardCategory":null,
         "IssuerBankCountry":"FF",
         "Issuer":null,
         "CardTypeCode":0,
         "Status":"Declined",
         "StatusCode":5,
         "CultureName":"kk",
         "Reason":"SystemError",
         "CardHolderMessage":"Повторите попытку позже",
         "Type":0,
         "Refunded":false,
         "Name":"CARD HOLDER",
         "Token":null,
         "SubscriptionId":null,
         "IsLocalOrder":false,
         "HideInvoiceId":false,
         "Gateway":0,
         "GatewayName":"Test",
         "ApplePay":false,
         "AndroidPay":false,
         "MasterPass":false,
         "TotalFee":0,
         "EscrowAccumulationId":null,
         "ReasonCode":5096
      }
   ],
   "Success":true,
   "Message":null
}

Выгрузка списка транзакций за произвольный период

Метод выгрузки списка транзакций за произвольный период.

Адрес метода:
https://api.tiptoppay.kz/v2/payments/list

Параметры запроса:

Параметр Формат Применение Описание
CreatedDateGte Date Обязательный Начальная дата создания операций
CreatedDateLte Date Обязательный Конечная дата создания операций
PageNumber Number Обязательный порядковый номер страницы, должно быть больше или равно 1
TimeZone String Необязательный Код временной зоны, по умолчанию — UTC
Statuses String Array Необязательный Статус операция. Может иметь значения [ "Authorized", "Completed", "Cancelled", "Declined" ]. По умолчанию выбраны все

В выгрузку транзакций попадают все операции, зарегистрированные за указанный день. Результат сортируется по CreatedDate, от старых к новым с лимитом - 100 на одну страницу. Для удобства учета вы можете указать код временной зоны (см. справочник).

Пример запроса:

{
    "PageNumber": 1,
    "CreatedDateGte":"2021-03-09T00:00:00+03:00", 
    "CreatedDateLte":"2021-03-10T00:00:00+03:00",
    "TimeZone": "MSK",
    "Statuses": [
        "Authorized", 
        "Completed", 
        "Cancelled", 
        "Declined"
    ]
    }

Пример ответа:

{
   "Model":[
      {
         "PublicId":"test_api_00000000000000000000001",
         "TerminalUrl":"https://tiptoppay.kz",
         "TransactionId":54,
         "Amount":12.34,
         "Currency":"KZT",
         "CurrencyCode":0,
         "PaymentAmount":12.34,
         "PaymentCurrency":"KZT",
         "PaymentCurrencyCode":0,
         "InvoiceId":"1234567",
         "AccountId":"[email protected]",
         "Email":null,
         "Description":"Оплата товаров в example.com",
         "JsonData":"{\"some\": \"value\"}",
         "CreatedDate":"\/Date(1615288374632)\/",
         "PayoutDate":null,
         "PayoutDateIso":null,
         "PayoutAmount":null,
         "CreatedDateIso":"2021-03-09T11:12:54",
         "AuthDate":null,
         "AuthDateIso":null,
         "ConfirmDate":null,
         "ConfirmDateIso":null,
         "AuthCode":null,
         "TestMode":true,
         "Rrn":null,
         "OriginalTransactionId":null,
         "FallBackScenarioDeclinedTransactionId":null,
         "IpAddress":"127.0.0.1",
         "IpCountry":"",
         "IpCity":null,
         "IpRegion":null,
         "IpDistrict":null,
         "IpLatitude":null,
         "IpLongitude":null,
         "CardFirstSix":"424242",
         "CardLastFour":"4242",
         "CardExpDate":"05/22",
         "CardType":"Visa",
         "CardProduct":null,
         "CardCategory":null,
         "IssuerBankCountry":"FF",
         "Issuer":null,
         "CardTypeCode":0,
         "Status":"Declined",
         "StatusCode":5,
         "CultureName":"kk",
         "Reason":"SystemError",
         "CardHolderMessage":"Повторите попытку позже",
         "Type":0,
         "Refunded":false,
         "Name":"CARD HOLDER",
         "Token":null,
         "SubscriptionId":null,
         "IsLocalOrder":false,
         "HideInvoiceId":false,
         "Gateway":0,
         "GatewayName":"Test",
         "ApplePay":false,
         "AndroidPay":false,
         "MasterPass":false,
         "TotalFee":0,
         "EscrowAccumulationId":null,
         "ReasonCode":5096
      }
   ],
   "Success":true,
   "Message":null
}

Выгрузка токенов

Метод выгрузки списка всех платежных токенов TipTop Pay.

Адрес метода:
https://api.tiptoppay.kz/payments/tokens/list

Параметры запроса:

Параметр Формат Применение Описание
PageNumber Int Обязательный Порядковый номер страницы, должно быть больше или равно 1

Пример запроса:

{
    "PageNumber": 1
}

Пример ответа:

{
    "Model": [
        {
            "Token": "tk_020a924486aa4df254331afa33f2a",
            "AccountId": "user_x",
            "CardMask": "4242 42****** 4242",
            "ExpirationDateMonth": 12,
            "ExpirationDateYear": 2020
        },
        {
            "Token": "tk_1a9f2f10253a30a7c5692a3fc4c17",
            "AccountId": "user_x",
            "CardMask": "5555 55****** 4444",
            "ExpirationDateMonth": 12,
            "ExpirationDateYear": 2021
        },
        {
            "Token": "tk_b91062f0f2875909233ab66d0fc7b",
            "AccountId": "user_x",
            "CardMask": "4012 88****** 1881",
            "ExpirationDateMonth": 12,
            "ExpirationDateYear": 2022
        }
    ],
    "Success": true,
    "Message": null
}

Создание подписки на рекуррентные платежи

Метод создания подписки на рекуррентные платежи.

Адрес метода:
https://api.tiptoppay.kz/subscriptions/create

Параметры запроса:

Параметр Формат Применение Описание
Token String Обязательный Токен карты, выданный системой после первого платежа
AccountId String Обязательный Идентификатор пользователя
Description String Обязательный Назначение платежа в свободной форме
Email String Необязательный E-mail плательщика
Amount Number Обязательный Cумма платежа в валюте, разделитель точка. Количество не нулевых знаков после точки – 2.
Currency String Обязательный Валюта: KZT/USD/EUR/GBP (см. справочник)
RequireConfirmation Bool Обязательный Если значение true — платежи будут выполняться по двухстадийной схеме
StartDate DateTime Обязательный Дата и время первого платежа по плану во временной зоне UTC. Значение должно быть в будущем
Interval String Обязательный Интервал. Возможные значения: Day, Week, Month
Period Int Обязательный Период. В комбинации с интервалом, 1 Month значит раз в месяц, а 2 Week — раз в две недели. Должен быть больше 0
MaxPeriods Int Необязательный Максимальное количество платежей в подписке. Если указан, должен быть больше 0
CustomerReceipt json Необязательный Для изменения состава онлайн-чека

В ответ на корректно сформированный запрос система возвращает сообщение об успешно выполненной операции и идентификатор подписки.

Пример запроса:

{  
   "token": "477BBA133C182267FE5F086924ABDC5DB71F77BFC27F01F2843F2CDC69D89F05",
   "accountId": "user_x",
   "description": "Ежемесячная подписка на сервис example.com",
   "email": "[email protected]",
   "amount": 399,
   "Currency": "KZT",
   "requireConfirmation": false,
   "startDate": "2021-11-02T21:00:00",
   "interval": "Day",
   "period": 5
}

Пример ответа:

 {
    "Model": {
        "Id": "sc_221da6421dc44dbd2cc3464f6f083",
        "AccountId": "user_x",
        "Description": "Ежемесячная подписка на сервис example.com",
        "Email": "[email protected]",
        "Amount": 399,
        "CurrencyCode": 0,
        "Currency": "KZT",
        "RequireConfirmation": false,
        "StartDate": "/Date(1635886800000)/",
        "StartDateIso": "2021-11-02T21:00:00",
        "IntervalCode": 2,
        "Interval": "Day",
        "Period": 5,
        "MaxPeriods": null,
        "CultureName": "ru-RU",
        "StatusCode": 0,
        "Status": "Active",
        "SuccessfulTransactionsNumber": 0,
        "FailedTransactionsNumber": 0,
        "LastTransactionDate": null,
        "LastTransactionDateIso": null,
        "NextTransactionDate": "/Date(1635886800000)/",
        "NextTransactionDateIso": "2021-11-02T21:00:00",
        "Receipt": null,
        "FailoverSchemeId": null
    },
    "Success": true,
    "Message": null
}

Запрос информации о подписке

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

Адрес метода:
https://api.tiptoppay.kz/subscriptions/get

Параметры запроса:

Параметр Формат Применение Описание
Id String Обязательный Идентификатор подписки

Пример запроса:

{"Id":"sc_8cf8a9338fb8ebf7202b08d09c938"}

Пример ответа:

{
    "Model": {
        "Id": "sc_8cf8a9338fb8ebf7202b08d09c938",
        "AccountId": "user_x",
        "Description": null,
        "Email": "[email protected]",
        "Amount": 399,
        "CurrencyCode": 0,
        "Currency": "KZT",
        "RequireConfirmation": false,
        "StartDate": "/Date(1635886800000)/",
        "StartDateIso": "2021-11-02T21:00:00",
        "IntervalCode": 2,
        "Interval": "Day",
        "Period": 5,
        "MaxPeriods": null,
        "CultureName": "ru-RU",
        "StatusCode": 3,
        "Status": "Cancelled",
        "SuccessfulTransactionsNumber": 0,
        "FailedTransactionsNumber": 0,
        "LastTransactionDate": null,
        "LastTransactionDateIso": null,
        "NextTransactionDate": null,
        "NextTransactionDateIso": null,
        "Receipt": null,
        "FailoverSchemeId": null
    },
    "Success": true,
    "Message": null
}

Поиск подписок

Метод получения списка подписок для определенного аккаунта.

Адрес метода:
https://api.tiptoppay.kz/subscriptions/find

Параметры запроса:

Параметр Формат Применение Описание
accountId String Обязательный Идентификатор пользователя

Пример запроса:

{"accountId":"[email protected]"}

Пример ответа:

{
    "Model": [
{
            "Id": "sc_221da6421dc44dbd2cc3464f6f083",
            "AccountId": "user_x",
            "Description": null,
            "Email": "[email protected]",
            "Amount": 399,
            "CurrencyCode": 0,
            "Currency": "KZT",
            "RequireConfirmation": false,
            "StartDate": "/Date(1635886800000)/",
            "StartDateIso": "2021-11-02T21:00:00",
            "IntervalCode": 2,
            "Interval": "Day",
            "Period": 5,
            "MaxPeriods": null,
            "CultureName": "ru-RU",
            "StatusCode": 3,
            "Status": "Cancelled",
            "SuccessfulTransactionsNumber": 0,
            "FailedTransactionsNumber": 0,
            "LastTransactionDate": null,
            "LastTransactionDateIso": null,
            "NextTransactionDate": null,
            "NextTransactionDateIso": null,
            "Receipt": null,
            "FailoverSchemeId": null
        },
        {
            "Id": "sc_3ffc96c001e152b341817341b075a",
            "AccountId": "user_x",
            "Description": null,
            "Email": "[email protected]",
            "Amount": 999,
            "CurrencyCode": 0,
            "Currency": "KZT",
            "RequireConfirmation": false,
            "StartDate": "/Date(1635973200000)/",
            "StartDateIso": "2021-11-03T21:00:00",
            "IntervalCode": 2,
            "Interval": "Day",
            "Period": 5,
            "MaxPeriods": null,
            "CultureName": "ru-RU",
            "StatusCode": 0,
            "Status": "Active",
            "SuccessfulTransactionsNumber": 0,
            "FailedTransactionsNumber": 0,
            "LastTransactionDate": null,
            "LastTransactionDateIso": null,
            "NextTransactionDate": "/Date(1635973200000)/",
            "NextTransactionDateIso": "2021-11-03T21:00:00",
            "Receipt": null,
            "FailoverSchemeId": null
        }
    ],
    "Success": true,
    "Message": null
}

Изменение подписки на рекуррентные платежи

Метод изменения ранее созданной подписки.

Адрес метода:
https://api.tiptoppay.kz/subscriptions/update

Параметры запроса:

Параметр Формат Применение Описание
Id String Обязательный Идентификатор подписки
Description String Необязательный Для изменения назначения платежа
Amount Number Необязательный Для изменения суммы платежа в валюте, разделитель точка. Количество не нулевых знаков после точки – 2.
Currency String Необязательный Для изменения валюты: KZT/USD/EUR/GBP (см. справочник)
RequireConfirmation Bool Необязательный Для изменения схемы проведения платежей
StartDate DateTime Необязательный Для изменения даты и времени первого или следующего платежа во временной зоне UTC
Interval String Необязательный Для изменения интервала. Возможные значения: Day, Week, Month
Period Int Необязательный Для изменения периода. В комбинации с интервалом, 1 Month значит раз в месяц, а 2 Week — раз в две недели
MaxPeriods Int Необязательный Для изменения максимального количества платежей в подписке
CustomerReceipt json Необязательный Для изменения состава онлайн-чека
CultureName String Необязательный Язык уведомлений. Возможные значения: "ru-RU", "en-US". (см. справочник)

В ответ на корректно сформированный запрос система возвращает сообщение об успешно выполненной операции и параметры подписки.

Пример запроса:

{  
   "Id":"sc_3ffc96c001e152b341817341b075a",
   "description":"изменение рекуррента",
   "amount":499,
   "Currency":"KZT"
}

Пример ответа:

{
    "Model": {
        "Id": "sc_3ffc96c001e152b341817341b075a",
        "AccountId": "user_x",
        "Description": "изменение рекуррента",
        "Email": "[email protected]",
        "Amount": 499,
        "CurrencyCode": 0,
        "Currency": "KZT",
        "RequireConfirmation": false,
        "StartDate": "/Date(1635973200000)/",
        "StartDateIso": "2021-11-03T21:00:00",
        "IntervalCode": 2,
        "Interval": "Day",
        "Period": 2,
        "MaxPeriods": null,
        "CultureName": "ru-RU",
        "StatusCode": 0,
        "Status": "Active",
        "SuccessfulTransactionsNumber": 0,
        "FailedTransactionsNumber": 0,
        "LastTransactionDate": null,
        "LastTransactionDateIso": null,
        "NextTransactionDate": "/Date(1635973200000)/",
        "NextTransactionDateIso": "2021-11-03T21:00:00",
        "Receipt": null,
        "FailoverSchemeId": null
    },
    "Success": true,
    "Message": null
}

Отмена подписки на рекуррентные платежи

Метод отмены подписки на рекуррентные платежи.

Адрес метода:

https://api.tiptoppay.kz/subscriptions/cancel
Параметры запроса:

Параметр Формат Применение Описание
Id String Обязательный Идентификатор подписки

В ответ на корректно сформированный запрос система возвращает сообщение об успешно выполненной операции.

Пример запроса:

{"Id":"sc_cc673fdc50b3577e60eee9081e440"}

Пример ответа:

{"Success":true,"Message":null}

Вы также можете предоставить покупателю ссылку на сайт системы — https://my.tiptoppay.kz/, где он самостоятельно сможет найти и отменить свои регулярные платежи.

Создание счета для отправки по почте

Метод формирования ссылки на оплату и последующей отправки уведомления на e-mail адрес плательщика.

Адрес метода:
https://api.tiptoppay.kz/orders/create

Параметры запроса:

Параметр Формат Применение Описание
Amount Number Обязательный Cумма платежа в валюте, разделитель точка. Количество не нулевых знаков после точки – 2.
Currency String Необязательный Валюта KZT/USD/EUR/GBP (см. справочник). Если параметр не передан, то по умолчанию принимает значение KZT
Description String Обязательный Назначение платежа в свободной форме
Email String Необязательный E-mail плательщика
RequireConfirmation Bool Необязательный Есть значение true — платеж будет выполнен по двухстадийной схеме
SendEmail Bool Необязательный Если значение true — плательщик получит письмо со ссылкой на оплату
InvoiceId String Необязательный Номер заказа в вашей системе
AccountId String Необязательный Идентификатор пользователя в вашей системе
OfferUri String Необязательный Ссылка на оферту, которая будет показываться на странице заказа
Phone String Необязательный Номер телефона плательщика в произвольном формате
SendSms Bool Необязательный Если значение true — плательщик получит СМС со ссылкой на оплату
SendViber Bool Необязательный Если значение true — плательщик получит сообщение в Viber со ссылкой на оплату
CultureName String Необязательный Язык уведомлений. Возможные значения: "ru-RU", "en-US". (см. справочник)
SubscriptionBehavior String Необязательный Для создания платежа с подпиской. Возможные значения: CreateWeekly, CreateMonthly
SuccessRedirectUrl String Необязательный Адрес страницы для редиректа при успешной оплате
FailRedirectUrl String Необязательный Адрес страницы для редиректа при неуспешной оплате
JsonData Json Необязательный Любые другие данные, которые будут связаны с транзакцией, в том числе инструкции для формирования онлайн-чека должны обёртываться в объект PaymentData

Пример запроса:

{
    "Amount":10.0,
    "Currency":"KZT",
    "Description":"Оплата на сайте example.com",
    "Email":"[email protected]",
    "RequireConfirmation":true,
    "SendEmail":false
}

Пример ответа:

{
    "Model": {
        "Id": "gASGZVgUN21hcpPF",
        "Number": 2130,
        "Amount": 10.0,
        "Currency": "KZT",
        "CurrencyCode": 0,
        "Email": "[email protected]",
        "Phone": "",
        "Description": "Оплата на сайте example.com",
        "RequireConfirmation": true,
        "Url": "https://orders.tiptoppay.kz/d/gASGZVgUN21hcpPF",
        "CultureName": "ru-RU",
        "CreatedDate": "/Date(1635835930555)/",
        "CreatedDateIso": "2021-11-02T09:52:10",
        "PaymentDate": null,
        "PaymentDateIso": null,
        "StatusCode": 0,
        "Status": "Created",
        "InternalId": 12272915
    },
    "Success": true,
    "Message": null
}

Отмена созданного счета

Метод отмены созданного счета:

Адрес метода:
https://api.tiptoppay.kz/orders/cancel

Параметры запроса:

Параметр Формат Применение Описание
Id String Обязательный Идентификатор счета

В ответ на корректно сформированный запрос система возвращает сообщение об успешно выполненной операции.

Пример запроса:

{"Id":"f2K8LV6reGE9WBFn"}

Пример ответа:

{
    "Success": true,
    "Message": null
}

Просмотр настроек уведомлений

Метод просмотра настроек уведомлений с указанием типа уведомления.

Адрес метода:
https://api.tiptoppay.kz/site/notifications/{Type}/get

Параметры запроса:

Параметр Формат Применение Описание
Type String Обязательный Тип уведомления: Check/Pay/Fail и т.д. (см. справочник)

Пример ответа на запрос для Pay-уведомления на адрес:
https://api.tiptoppayy.kz/site/notifications/pay/get

{
    "Model": {
        "IsEnabled": true,
        "Address": "http://example.com",
        "HttpMethod": "POST",
        "Encoding": "UTF8",
        "Format": "TipTop Pay"
    },
    "Success": true,
    "Message": null
}

Изменение настроек уведомлений

Метод изменения настроек уведомлений.

Адрес метода:
https://api.tiptoppay.kz/site/notifications/{Type}/update

Параметры запроса:

Параметр Формат Применение Описание
Type String Обязательный Тип уведомления: Pay/Fail и т.д., кроме Check-уведомления (см. справочник)
IsEnabled Bool Необязательный Если значение true — то уведомление включено. Значение по умолчанию — false
Address String Необязательный, если IsEnabled=false, в противном случае обязательный Адрес для отправки уведомлений (для HTTPS-схемы необходим валидный SSL-сертификат)
HttpMethod String Необязательный HTTP-метод для отправки уведомлений. Возможные значения: GET, POST. Значение по умолчанию — GET
Encoding String Необязательный Кодировка уведомлений. Возможные значения: UTF8, Windows1251. Значение по умолчанию — UTF8
Format String Необязательный Формат уведомлений. Возможные значения: TipTop Pay, QIWI, RT. Значение по умолчанию — TipTop Pay

Пример запроса для Pay-уведомления на адрес:
https://api.tiptoppay.kz/site/notifications/pay/update:

{
    "IsEnabled": true,
    "Address": "http://example.com",
    "HttpMethod": "GET",
    "Encoding": "UTF8",
    "Format": "TipTop Pay"
}

Пример ответа:

{"Success":true,"Message":null}

Запуск сессии для оплаты через Apple Pay

Запуск сессии необходим для приема платежей Apple Pay на сайтах. Для оплаты в мобильных приложениях его использование не требуется.

Адрес метода:
https://api.tiptoppay.kz/applepay/startsession

Параметры запроса:

Параметр Формат Применение Описание
ValidationUrl Строка Обязательный Адрес, полученный из Apple JS
paymentUrl Строка Необязательный Адрес для старта сессии в Apple

В ответ на корректно сформированный запрос система возвращает ответ, где в объекте Model содержится сессия для оплаты Apple Pay в формате JSON.

Пример запроса:

{"ValidationUrl":"https://apple-pay-gateway.apple.com/paymentservices/startSession"}

Пример ответа:

{
    "Model": {
        "epochTimestamp": 1545111111153,
        "expiresAt": 1545111111153,
        "merchantSessionIdentifier": "SSH6FE83F9B853E00F7BD17260001DCF910_0001B0D00068F71D5887F2726CFD997A28E0ED57ABDACDA64934730A24A31583",
        "nonce": "d6358e06",
        "merchantIdentifier": "41B8000198128F7CC4295E03092BE5E287738FD77EC3238789846AC8EF73FCD8",
        "domainName": "demo.tiptoppay.kz",
        "displayName": "demo.tiptoppay.kz",
        "signature": "308006092a864886f70d010702a0803080020101310f300d06096086480165030402010500308006092a864886f70d0107010000a080308203e230820388a00307650202082443f2a8069df577300a06082a8648ce3d040302307a312e302c06035504030c254170706c65204170706c69636174696f6e20496e746567726174696f6e204341202d20473331263024060355040b0c1d4170706c652043657274696669636174696f6e20417574686f7269747931133011060355040a0c0a4170706c6520496e632e310b3009060355040613025553301e170d3134303932353232303631315a170d3139303932343232303631315a305f3125302306035504030c1c6563632d736d702d62726f6b65722d7369676e5f5543342d50524f4431143012060355040b0c0b694f532053797374656d7331133011060355040a0c0a4170706c6520496e632e310b30090603550406130255533059301306072a8648ce3d020106082a8648ce3d03010703420004c21577edebd6c7b2218f68dd7090a1218dc7b0bd6f2c283d846095d94af4a5411b83420ed811f3407e83331f1c54c3f7eb3220d6bad5d4eff49289893e7c0f13a38202113082020d304506082b0601050507010104393037303506082b060105050730018629687474703a2f2f6f6373702e6170706c652e636f6d2f6f63737030342d6170706c6561696361333031301d0603551d0e041604149457db6fd57481868989762f7e578507e79b5824300c0603551d130101ff04023000301f0603551d2304183016801423f249c44f93e4ef27e6c4f6286c3fa2bbfd2e4b3082011d0603551d2004820114308201103082010c06092a864886f7636405013081fe3081c306082b060105050702023081b60c81b352656c69616e6365206f6e207468697320636572746966696361746520627920616e7920706172747920617373756d657320616363657074616e6365206f6620746865207468656e206170706c696361626c65207374616e64617264207465726d7320616e6420636f6e646974696f6e73206f66207573652c20636572746966696361746520706f6c69637920616e642063657274696669636174696f6e2070726163746963652073746174656d656e74732e303606082b06010505070201162a687474703a2f2f7777772e6170706c652e636f6d2f6365727469666963617465617574686f726974792f30340603551d1f042d302b3029a027a0258623687474703a2f2f63726c2e6170706c652e636f6d2f6170706c6561696361332e63726c300e0603551d0f0101ff040403020780300f06092a864886f76364061d04020500300a06082a8648ce3d04030203480030450220728a9f0f92a32ab999742bd55eb67340572a9687a1d62ef5359710f5163e96e902210091379c7d6ebe5b9974af40037f34c23ead98b5b4b7f70d355c86b2a81372f1b1308202ee30820275a0030201020208496d2fbf3a98da97300a06082a8648ce3d0403023067311b301906035504030c124170706c6520526f6f74204341202d20473331263024060355040b0c1d4170706c652043657274696669636174696f6e20417574686f7269747931133011060355040a0c0a4170706c6520496e632e310b3009060355040613025553301e170d3134303530363233343633305a170d3239303530363233343633305a307a312e302c06035504030c254170706c65204170706c69636174696f6e20496e746567726174696f6e204341202d20473331263024060355040b0c1d4170706c652043657274696669636174696f6e20417574686f7269747931133011060355040a0c0a4170706c6520496e632e310b30090603550406130255533059301306072a8648ce3d020106082a8648ce3d03010703420004f017118419d76485d51a5e25810776e880a2efde7bae4de08dfc4b93e13356d5665b35ae22d097760d224e7bba08fd7617ce88cb76bb6670bec8e82984ff5445a381f73081f4304606082b06010505070101043a3038303606082b06010505073001862a687474703a2f2f6f6373702e6170706c652e636f6d2f6f63737030342d6170706c65726f6f7463616733301d0603551d0e0416041423f249c44f93e4ef27e6c4f6286c3fa2bbfd2e4b300f0603551d130101ff040530030101ff301f0603551d23041830168014bbb0dea15833889aa48a99debebdebafdacb24ab30370603551d1f0430302e302ca02aa0288626687474703a2f2f63726c2e6170706c652e636f6d2f6170706c65726f6f74636167332e63726c300e0603551d0f0101ff0404030201063010060a2a864886f7636406020e04020500300a06082a8648ce3d040302036700306402303acf7283511699b186fb35c356ca62bff417edd90f754da28ebef19c815e42b789f898f79b599f98d5410d8f9de9c2fe0230322dd54421b0a305776c5df3383b9067fd177c2c216d964fc6726982126f54f87a7d1b99cb9b0989216106990f09921d00003182018d30820189020123458186307a312e302c06035504030c254170706c65204170706c69636174696f6e20496e746567726174696f6e204341202d20473331263024060355040b0c1d4170706c652043657274696669636174696f6e20417574686f7269747931133011060355040a0c0a4170706c6520496e632e310b300906035504061302555302082443f2a8069df577300d06096086480165030402010500a08195301806092a864886f70d010903310b06092a864886f70d010701301c06092a864886f70d010905310f170d3138313232303134323633395a302a06092a864886f70d010934311d301b300d06096086480165030402010500a10a06082a8648ce3d040302302f06092a864886f70d0109043122042066adfefd6fbe307934525c52b926dcf0734a2e8011a9c8558d7043d983960af3300a06082a8648ce3d04030204483046022100fc6436b2c9bde03c4691d2e3b0e23aca06e44ce0c05c7ff4fb34550f4079dd36022100d1c91be8ed57321fb1c7264f1a617311ed678609a75fed3be31cc0d5cea16cfe000000000000"
    },
    "Success": true,
    "Message": null
}

Локализация

По умолчанию API выдает сообщения для пользователей на русском языке. Для получения ответов, локализованных для других языков, передайте в параметрах запроса CultureName.

Список поддерживаемых языков:

Язык Часовой пояс Код
Русский MSK ru-RU
Английский CET en-US
Латышский CET lv
Азербайджанский AZT az
Русский ALMT kk
Украинский EET uk
Польский CET pl
Вьетнамский ICT vi
Турецкий TRT tr

Длинная запись

Длинная запись для авиа (airline addendum) — расширенная информация о маршрутной квитанции, которая передается вместе с транзакцией на обработку в платежную систему. Использование длинной записи позволяет сократить риски мошеннических операций и снизить стоимость обработки платежа.

Длинная запись состоит из информации о маршрутной квитанции, информации о сегментах, то есть перелетах и информации о пассажирах.

Информация о маршрутной квитанции включает в себя:

Параметр Формат Применение Описание
BookingRef String Обязательный, если не указан номер билета Номер брони
TicketNumber String Обязательный, если не указан номер брони Номер билета

Под сегментом понимается один авиаперелет: взлет и посадка. Необходимо указать все сегменты маршрута с перечнем следующих параметров:

Параметр Формат Применение Описание
FlightNumber String Обязательный Номер рейса
DepartureDateTime DateTime Обязательный Дата и время отправления
ArrivalDateTime DateTime Обязательный Дата и время прибытия
OriginatingCountry String Обязательный Страна вылета на русском или английском языке
OriginatingCity String Обязательный Город вылета на русском или английском языке
OriginatingAirportCode String(3) Обязательный Код аэропорта вылета — 3 буквы по классификации IATA
DestinationCountry String Обязательный Страна прилета на русском или английском языке
DestinationCity String Обязательный Город прилета на русском или английском языке
DestinationAirportCode String(3) Обязательный Код аэропорта прилета — 3 буквы по классификации IATA

Для передачи информации о пассажирах, необходимо по каждому указать имя и фамилию латиницей:

Параметр Формат Применение Описание
FirstName String Обязательный Имя пассажира
LastName String Обязательный Фамилия пассажира

Длинную запись можно передать в систему в параметре AirlineAddendum при вызове метода оплаты через API или в ответе на запрос проверки платежа.

Пример формирования длинной записи:

{
   "TicketNumber":"390 5241025377",
   "BookingRef":null,
   "Legs":[
      {
         "FlightNumber":"A3 971",
         "DepartureDateTime":"2014-05-26T05:15:00",
         "ArrivalDateTime":"2014-05-26T07:30:00",
         "OriginatingCountry":"Казахстан",
         "OriginatingCity":"Астана",
         "OriginatingAirportCode":"NQZ",
         "DestinationCountry":"Казахстан",
         "DestinationCity":"Астана",
         "DestinationAirportCode":"NQZ"
      },
      {
         "FlightNumber":"A3 204",
         "DepartureDateTime":"2014-05-26T09:45:00",
         "ArrivalDateTime":"2014-05-26T10:50:00",
         "OriginatingCountry":"Казахстан",
         "OriginatingCity":"Астана",
         "OriginatingAirportCode":"NQZ",
         "DestinationCountry":"Казахстан",
         "DestinationCity":"Астана",
         "DestinationAirportCode":"NQZ"
      },
      {
         "FlightNumber":"A3 980",
         "DepartureDateTime":"2014-06-06T09:00:00",
         "ArrivalDateTime":"2014-06-06T13:45:00",
         "OriginatingCountry":"Казахстан",
         "OriginatingCity":"Астана",
         "OriginatingAirportCode":"NQZ",
         "DestinationCountry":"Казахстан",
         "DestinationCity":"Астана",
         "DestinationAirportCode":"NQZ"
      }
   ],
   "Passengers":[
      {
         "FirstName":"KONSTANTIN",
         "LastName":"IVANOV"
      },
      {
         "FirstName":"JULIA",
         "LastName":"IVANOVA"
      }
   ]
}

Уведомления

Уведомление — HTTP-запрос от системы к вашему сайту. Подобные запросы также называют callback или webhook. В системе предусмотрено несколько видов уведомлений: для проверки возможности выполнить оплату, для информирования об успешных и неуспешных платежах, для оповещения об изменении подписок на рекуррентные платежи, а также для информирования о выданных кассовых чеках.

Check

Выполняется после того, как держатель заполнил платежную форму и нажал кнопку «Оплатить».

Служит для контроля прохождения платежа: система отправляет запрос на адрес сайта ТСП с информацией об оплате, а сайт должен подтвердить или отклонить возможность принять платеж.

Параметры передаются в теле запроса, список представлен в следующей таблице:

Параметр Формат Применение Описание
TransactionId Long Обязательный Номер транзакции в системе
Amount Number, точка в качестве разделителя, две цифры после точки Обязательный Сумма оплаты из параметров платежа
Currency String Обязательный Валюта: KZT/USD/EUR/GBP из параметров платежа (см. справочник)
PaymentAmount String Обязательный Сумма списания
PaymentCurrency String Обязательный Валюта списания
DateTime yyyy-MM-dd HH:mm:ss Обязательный Дата/время создания платежа во временной зоне UTC
CardId String Необязательный Уникальный идентификатор карты в системе TipTop Pay
CardFirstSix String(6) Обязательный Первые 6 цифр номера карты
CardLastFour String(4) Обязательный Последние 4 цифры номера карты
CardType String Обязательный Платежная система карты: Visa, MasterCard или Maestro
CardExpDate String Обязательный Срок действия карты в формате MM/YY
TestMode Bit (1 или 0) Обязательный Признак тестового режима
Status String Обязательный Статус платежа в случае успешного завершения: Completed — для одностадийных платежей, Authorized — для двухстадийных
OperationType String Обязательный Тип операции: Payment/Refund/CardPayout (см. справочник)
InvoiceId String Необязательный Номер заказа из параметров платежа
AccountId String Необязательный Идентификатор пользователя из параметров платежа
SubscriptionId String Необязательный Идентификатор подписки (для рекуррентных платежей)
TokenRecipient String Необязательный Токен получателя платежа
Name String Необязательный Имя держателя карты
Email String Необязательный E-mail адрес плательщика
IpAddress String Необязательный IP-адрес плательщика
IpCountry String(2) Необязательный Двухбуквенный код страны нахождения плательщика по ISO3166-1
IpCity String Необязательный Город нахождения плательщика
IpRegion String Необязательный Регион нахождения плательщика
IpDistrict String Необязательный Округ нахождения плательщика
IpLatitude String Необязательный Широта нахождения плательщика
IpLongitude  String Необязательный Долгота нахождения плательщика
Issuer String Необязательный Название банка-эмитента карты
IssuerBankCountry String(2) Необязательный Двухбуквенный код страны эмитента карты по ISO3166-1
Description String Необязательный Назначение оплаты из параметров платежа
CardProduct String Необязательный Тип карточного продукта
PaymentMethod String Необязательный Метод оплаты ApplePay, GooglePay
Data Json Необязательный Произвольный набор параметров, переданных в транзакцию

В ответ на запрос система ожидает получить ответ в JSON-формате с обязательным параметром code:

{"code":0}

Код определяет результат выполнения проверки возможности выполнить платеж и может принимать следующие значения:

Код Значение Результат
0 Платеж может быть проведен Система выполнит авторизацию платежа
10 Неверный номер заказа Платеж будет отклонен
11 Некорректный AccountId Платеж будет отклонен
12 Неверная сумма Платеж будет отклонен
13 Платеж не может быть принят Платеж будет отклонен
20 Платеж просрочен Платеж будет отклонен, плательщик получит соответствующее уведомление

Pay

Выполняется после того, как оплата была успешно проведена и получена авторизация эмитента.

Служит для информирования о проведенном платеже: система отправляет запрос на адрес ТСП с информацией об оплате, а сайт должен зафиксировать факт платежа.

Параметры передаются в теле запроса, список представлен в следующей таблице:

Параметр Формат Применение Описание
TransactionId Long Обязательный Номер транзакции в системе
Amount Number, точка в качестве разделителя, две цифры после точки Обязательный Сумма оплаты из параметров платежа
Currency String Обязательный Валюта: KZT/USD/EUR/GBP из параметров платежа (см. справочник)
PaymentAmount String Обязательный Сумма списания
PaymentCurrency String Обязательный Валюта списания
DateTime yyyy-MM-dd HH:mm:ss Обязательный Дата/время создания платежа во временной зоне UTC
CardId String Необязательный Уникальный идентификатор карты в системе TipTop Pay
CardFirstSix String(6) Обязательный Первые 6 цифр номера карты
CardLastFour String(4) Обязательный Последние 4 цифры номера карты
CardType String Обязательный Платежная система карты: Visa, MasterCard или Maestro
CardExpDate String Обязательный Срок действия карты в формате MM/YY
TestMode Bit (1 или 0) Обязательный Признак тестового режима
Status String Обязательный Статус платежа после авторизации: Completed — для одностадийных платежей, Authorized — для двухстадийных
OperationType String Обязательный Тип операции: Payment/CardPayout (см. справочник)
GatewayName String Обязательный Идентификатор банка-эквайера
InvoiceId String Необязательный Номер заказа из параметров платежа
AccountId String Необязательный Идентификатор пользователя из параметров платежа
SubscriptionId String Необязательный Идентификатор подписки (для рекуррентных платежей)
Name String Необязательный Имя держателя карты
Email String Необязательный E-mail адрес плательщика
IpAddress String Необязательный IP-адрес плательщика
IpCountry String(2) Необязательный Двухбуквенный код страны нахождения плательщика по ISO3166-1
IpCity String Необязательный Город нахождения плательщика
IpRegion String Необязательный Регион нахождения плательщика
IpDistrict String Необязательный Округ нахождения плательщика
IpLatitude String Необязательный Широта нахождения плательщика
IpLongitude  String Необязательный Долгота нахождения плательщика
Issuer String Необязательный Название банка-эмитента карты
IssuerBankCountry String(2) Необязательный Двухбуквенный код страны эмитента карты по ISO3166-1
Description String Необязательный Назначение оплаты из параметров платежа
AuthCode String Необязательный Код авторизации
Data Json Необязательный Произвольный набор параметров, переданных в транзакцию
Token String Необязательный Токен карты для повторных платежей без ввода реквизитов
TotalFee Decimal Необязательный Значение общей комиссии
CardProduct String Необязательный Тип карточного продукта
PaymentMethod String Необязательный Метод оплаты ApplePay, GooglePay
FallBackScenarioDeclinedTransactionId Long Необязательный Номер первой неуспешной транзакции
Rrn String Необязательный Уникальный номер банковской транзакции, который назначается обслуживающим банком
CustomFields Array Необязательный Кастомные поля, которые передает мерчант в запросе оплаты

В ответ на запрос система ожидает получить ответ в JSON-формате с обязательным параметром code:

{"code":0}

Код определяет результат обработки сервером ТСП уведомления о платеже и может принимать единственное значение:

Код Значение
0 Платеж зарегистрирован

Fail

Выполняется в случае, если оплата была отклонена, и используется для анализа количества и причин отказов.

Стоит учитывать, что факт отказа в оплате не является конечным — пользователь может оплатить со второго раза.

Параметры передаются в теле запроса, список представлен в следующей таблице:

Параметр Формат Применение Описание
TransactionId Long Обязательный Номер транзакции в системе
Amount Number, точка в качестве разделителя, две цифры после точки Обязательный Сумма оплаты из параметров платежа
Currency String Обязательный Валюта: KZT/USD/EUR/GBP из параметров платежа (см. справочник)
PaymentAmount String Обязательный Сумма списания
PaymentCurrency String Обязательный Валюта списания
DateTime yyyy-MM-dd HH:mm:ss Обязательный Дата/время создания платежа во временной зоне UTC
CardId String Необязательный Уникальный идентификатор карты в системе TipTop Pay
CardFirstSix String(6) Обязательный Первые 6 цифр номера карты
CardLastFour String(4) Обязательный Последние 4 цифры номера карты
CardType String Обязательный Платежная система карты: Visa, MasterCard или Maestro
CardExpDate String Обязательный Срок действия карты в формате MM/YY
TestMode Bit (1 или 0) Обязательный Признак тестового режима
Reason String Обязательный Причина отказа
ReasonCode Int Обязательный Код ошибки (см. справочник)
OperationType String Обязательный Тип операции: Payment/Refund/CardPayout (см. справочник)
InvoiceId String Необязательный Номер заказа из параметров платежа
AccountId String Необязательный Идентификатор пользователя из параметров платежа
SubscriptionId String Необязательный Идентификатор подписки (для рекуррентных платежей)
Name String Необязательный Имя держателя карты
Email String Необязательный E-mail адрес плательщика
IpAddress String Необязательный IP-адрес плательщика
IpCountry String(2) Необязательный Двухбуквенный код страны нахождения плательщика по ISO3166-1
IpCity String Необязательный Город нахождения плательщика
IpRegion String Необязательный Регион нахождения плательщика
IpDistrict String Необязательный Округ нахождения плательщика
IpLatitude String Необязательный Широта нахождения плательщика
IpLongitude  String Необязательный Долгота нахождения плательщика
Issuer String Необязательный Название банка-эмитента карты
IssuerBankCountry String(2) Необязательный Двухбуквенный код страны эмитента карты по ISO3166-1
Description String Необязательный Назначение оплаты из параметров платежа
Data Json Необязательный Произвольный набор параметров, переданных в транзакцию
Token String Необязательный Токен карты для повторных платежей без ввода реквизитов
PaymentMethod String Необязательный Метод оплаты ApplePay, GooglePay
FallBackScenarioDeclinedTransactionId Long Необязательный Номер первой неуспешной транзакции
Rrn String Необязательный Уникальный номер банковской транзакции, который назначается обслуживающим банком
CustomFields Array Необязательный Кастомные поля, которые передает мерчант в запросе оплаты

В ответ на запрос система ожидает получить ответ в JSON-формате с обязательным параметром code:

{"code":0}

Код определяет результат обработки сервером ТСП уведомления об отклоненном платеже и может принимать единственное значение:

Код Значение
0 Попытка зарегистрирована

Confirm

Выполняется после подтверждения платежа, проведенного по двухстадийной схеме.

Параметры передаются в теле запроса, список представлен в следующей таблице:

Параметр Формат Применение Описание
TransactionId Long Обязательный Номер транзакции в системе
Amount Number, точка в качестве разделителя, две цифры после точки Обязательный Сумма оплаты из параметров платежа
Currency String Обязательный Валюта: KZT/USD/EUR/GBP из параметров платежа (см. справочник)
PaymentAmount String Обязательный Сумма списания
PaymentCurrency String Обязательный Валюта списания
DateTime yyyy-MM-dd HH:mm:ss Обязательный Дата/время создания платежа во временной зоне UTC
CardFirstSix String(6) Обязательный Первые 6 цифр номера карты
CardLastFour String(4) Обязательный Последние 4 цифры номера карты
CardType String Обязательный Платежная система карты: Visa, MasterCard или Maestro
CardExpDate String Обязательный Срок действия карты в формате MM/YY
TestMode Bit (1 или 0) Обязательный Признак тестового режима
Status String Обязательный Статус платежа после авторизации: Completed
InvoiceId String Необязательный Номер заказа из параметров платежа
AccountId String Необязательный Идентификатор пользователя из параметров платежа
SubscriptionId String Необязательный Идентификатор подписки (для рекуррентных платежей)
Name String Необязательный Имя держателя карты
Email String Необязательный E-mail адрес плательщика
IpAddress String Необязательный IP-адрес плательщика
IpCountry String(2) Необязательный Двухбуквенный код страны нахождения плательщика по ISO3166-1
IpCity String Необязательный Город нахождения плательщика
IpRegion String Необязательный Регион нахождения плательщика
IpDistrict String Необязательный Округ нахождения плательщика
IpLatitude String Необязательный Широта нахождения плательщика
IpLongitude  String Необязательный Долгота нахождения плательщика
Issuer String Необязательный Название банка-эмитента карты
IssuerBankCountry String(2) Необязательный Двухбуквенный код страны эмитента карты по ISO3166-1
Description String Необязательный Назначение оплаты из параметров платежа
AuthCode String Необязательный Код авторизации
Data Json Необязательный Произвольный набор параметров, переданных в транзакцию
Token String Необязательный Токен карты для повторных платежей без ввода реквизитов
PaymentMethod String Необязательный Метод оплаты ApplePay, GooglePay
Rrn String Необязательный Уникальный номер банковской транзакции, который назначается обслуживающим банком

В ответ на запрос система ожидает получить ответ в JSON-формате с обязательным параметром code:

{"code":0}

Код определяет результат обработки сервером ТСП уведомления о платеже и может принимать единственное значение:

Код Значение
0 Платеж зарегистрирован

Refund

Выполняется в случае, если платеж был возвращен (полностью или частично) по вашей инициативе через API или личный кабинет.

Параметры передаются в теле запроса, список представлен в следующей таблице:

Параметр Формат Применение Описание
TransactionId Long Обязательный Номер транзакции возврата в системе
PaymentTransactionId Long Обязательный Номер оригинальной транзакции оплаты в системе
Amount Number, точка в качестве разделителя, две цифры после точки Обязательный Сумма возврата в валюте платежа
DateTime yyyy-MM-dd HH:mm:ss Обязательный Дата/время возврата по временной зоне UTC
OperationType String Обязательный Тип операции: Refund/CardPayout (см. справочник)
InvoiceId String Необязательный Номер заказа оригинальной операции
AccountId String Необязательный Идентификатор пользователя оригинальной операции
Email String Необязательный E-mail адрес плательщика
Data Json Необязательный Произвольный набор параметров, переданных в транзакцию
Rrn String Необязательный Уникальный номер банковской транзакции, который назначается обслуживающим банком
CustomFields Array Необязательный Кастомные поля, которые передает мерчант в запросе оплаты

В ответ на запрос система ожидает получить ответ в JSON-формате с обязательным параметром code:

{"code":0}

Код определяет результат обработки сервером ТСП уведомления о платеже и может принимать единственное значение:

Код Значение
0 Возврат зарегистрирован

Recurrent

Выполняется в случае, если статус подписки на рекуррентный платеж был изменен.

Параметры передаются в теле запроса, список представлен в следующей таблице:

Параметр Формат Применение Описание
Id String Обязательный Идентификатор подписки
AccountId String Обязательный Идентификатор пользователя
Description String Обязательный Назначение платежа в свободной форме
Email String Обязательный E-mail плательщика
Amount Number Обязательный Сумма платежа
Currency String Обязательный Валюта: KZT/USD/EUR/GBP из параметров платежа (см. справочник)
RequireConfirmation Bool Обязательный Если значение true — платеж будет выполнен по двухстадийной схеме
StartDate DateTime Обязательный Дата и время первого платежа по плану во временной зоне UTC
Interval String Обязательный Интервал. Возможные значения: Week, Month
Period Int Обязательный Период. В комбинации с интервалом 1 Month значит раз в месяц, а 2 Week — раз в две недели
Status String Обязательный Статусы подписок
SuccessfulTransactionsNumber Int Обязательный Количество успешных платежей
FailedTransactionsNumber Int Обязательный Количество неуспешных платежей (обнуляется после каждого успешного)
MaxPeriods Int Необязательный Максимальное количество платежей в подписке
LastTransactionDate yyyy-MM-dd HH:mm:ss Необязательный Дата и время последнего успешного платежа во временной зоне UTC
NextTransactionDate yyyy-MM-dd HH:mm:ss Необязательный Дата и время следующего платежа во временной зоне UTC

В ответ на запрос система ожидает получить ответ в JSON-формате с обязательным параметром code:

{"code":0}

Код определяет результат обработки сервером ТСП уведомления об изменении подписки и может принимать единственное значение:

Код Значение
0 Изменения зарегистрированы

Cancel

Выполняется в случае, если платеж был отменен по вашей инициативе через API или личный кабинет.

Параметры передаются в теле запроса, список представлен в следующей таблице:

Параметр Формат Применение Описание
TransactionId Long Обязательный Номер отмененной транзакции в системе
Amount Number, точка в качестве разделителя, две цифры после точки Обязательный Сумма отмененной транзакции в валюте платежа
DateTime yyyy-MM-dd HH:mm:ss Обязательный Дата/время отмены по временной зоне UTC
InvoiceId String Необязательный Номер заказа отмененной операции
AccountId String Необязательный Идентификатор пользователя отмененной операции
Email String Необязательный E-mail адрес плательщика
Data Json Необязательный Произвольный набор параметров, переданных в транзакцию
Rrn String Необязательный Уникальный номер банковской транзакции, который назначается обслуживающим банком

В ответ на запрос система ожидает получить ответ в JSON-формате с обязательным параметром code:

{"code":0}

Код определяет результат обработки сервером ТСП уведомления и может принимать единственное значение:

Код Значение
0 Возврат зарегистрирован

Проверка уведомлений

Все виды уведомлений — check, pay, fail, confirm, cancel, refund и recurrent содержат 2 HTTP-заголовка X-Content-HMAC и Content-HMAC, в которых находится проверочное значение запроса, вычисленное с помощью алгоритма HMAC. Отличие между ними только в том, что первый генерируется из URL decoded (или не encoded) параметров, а второй генерируется из URL encoded параметров, что может вызывать проблемы. Если вам необходимо проверять подлинность и целостность уведомлений, вы можете вычислить проверочное значение на своей стороне и сравнить с тем, что пришло в запросе. Совпадение подтверждает, что уведомление было отправлено от нас и пришло к вам в оригинальном виде.

При реализации проверки сообщения, обратите внимание на следующие моменты:

Примеры вычисления HMAC на разных языках программирования.

Адрес, с которого система отправляет уведомления — 91.216.178.243.

Для вас это означает, что:

Более подробно как отказаться от SSL3. После 8 июня https-уведомления на сервера, поддерживающие только SSL3, могут не доставляться.




Apple Pay

applepay

Удобный и безопасный способ оплаты от компании Apple. Пользователь единоразово привязывает карту к своему аккаунту Apple, а далее при оплате только подтверждает платеж отпечатком пальца или Face ID.

Технология работает в мобильных приложениях и браузере Safari на iPhone, iPad, Apple Watch, MacBook и компьютерах Мас.

Протестировать оплату через Apple Pay можно в нашем демо-магазине. Использовать можно как тестовые, так и реальные карточные данные.
Деньги списываться не будут.

Классическая интеграция

Apple Pay Merchant ID, сертификаты и домены

Для использования технологии Apple Pay вам необходимо зарегистрировать Merchant ID, сформировать платежный сертификат, сертификат для веб-платежей и подтвердить владение доменами сайтов, на которых будет производиться оплата.

Регистрация Merchant ID:

  1. Зайдите в консоль Apple Developer Account, далее в раздел «Certificates, IDs & Profiles», далее «Merchant IDs». Зарегистрируйте новый Merchant ID:

    • В поле Description укажите произвольное описание;
    • В поле Identifier укажите адрес вашего основного сайта в обратном порядке и с префиксом «merchant». Например, если адрес вашего основного сайт shop.domain.kz, то Identitfier — merchant.kz.domain.shop

  2. Сохраните результат.

Создание сертификатов:

  1. Напишите письмо на адрес [email protected] с указанием зарегистрированного в Apple Merchant ID и Public ID сайта. Наша служба поддержки сформирует два запроса на сертификаты и отправит вам обратным письмом.

  2. Сформируйте в консоли Apple Developer два сертификата: Payment Processing Certificate и Merchant Identity Certificate и передайте в нашу службу поддержки.

Подтверждение доменов:

  1. Добавьте домены в консоли Apple Developer для каждого сайта, где планируете принимать оплату через Apple Pay. Обратите внимание, что сайты должны использовать схему HTTPS и поддерживать протокол TLS 1.2.

  2. Подтвердите владение доменами.

В виджете появится возможность оплачивать через Apple Pay.

Прием платежей с Apple Pay

Схема оплаты включает в себя 3 этапа:

Apple Pay в мобильных приложениях

Используйте SDK PassKit от Apple для получения PaymentToken и метод оплаты по криптограмме в API для проведения платежа.

Упрощенная интеграция (только для веб-сайтов)

Мы упростили процедуру регистрации в Apple. Для веб-сайтов создание учетной записи в консоли Apple Developer при использовании наших платежных решений больше не является необходимостью. Теперь достаточно в личном кабинете в настройках сайта:

Для успешного включения опции ваш сайт должен работать по схеме HTTPS и поддерживать протокол TLS версии 1.2.

Если вы используете Checkout скрипт, вам необходимо самостоятельно разместить Apple Pay.
В случае использования виджета возможность оплаты Apple Pay появится автоматически после включения одноименной опции в нашем ЛК.

Самостоятельное размещение Apple Pay на сайте

Если вы хотите разместить кнопку Apple Pay непосредственно на вашем сайте по примеру ниже, а не через платёжный виджет, то следуйте дальнейшей инструкции.

Интеграция предполагает использование клиентской части (javascript) и серверной. На клиенте вы проверяете совместимость устройства и обрабатываете события: создание сессии, авторизация платежа, обработка платежа.

На серверной части необходимо выполнять вызовы API:

  1. Запуск сессии Apple Pay;

  2. Проведение оплаты по криптограмме с передачей Apple Pay токена в параметре CardCryptogramPacket;

Пример js кода:


if (window.ApplePaySession) { //проверка устройства
    var merchantIdentifier = 'Ваш Apple Merchant ID';
    var promise = ApplePaySession.canMakePaymentsWithActiveCard(merchantIdentifier);
    promise.then(function (canMakePayments) {
        if (canMakePayments) {
            $('#apple-pay').show(); //кнопка Apple Pay
        }
    });
}
$('#apple-pay').click(function () { //обработчик кнопки
    var supportedNetworksArray = ["visa", "mastercard"];

    var request = {
        // requiredShippingContactFields: ['email'], //Раскомментируйте, если вам нужен e-mail. Также можно запросить postalAddress, phone, name.
        countryCode: "KZ",
        currencyCode: "KZT",
        supportedNetworks: supportedNetworksArray,
        merchantCapabilities: ['supports3DS'],
        //Назначение платежа указывайте только латиницей!
        total: { label: 'Test', amount: '1.00' }, //назначение платежа и сумма
    }
    var session = new ApplePaySession(1, request);

    // обработчик события для создания merchant session.
    session.onvalidatemerchant = function (event) {

        var data = {
            validationUrl: event.validationURL
        };

        // отправьте запрос на ваш сервер, а далее запросите API TipTop Pay
        // для запуска сессии
        $.post("/ApplePay/StartSession", data).then(function (result) {
            session.completeMerchantValidation(result.Model);
        });
    };

    // обработчик события авторизации платежа
    session.onpaymentauthorized = function (event) {

        //var email = event.payment.shippingContact.emailAddress; //если был запрошен адрес e-mail
        //var phone = event.payment.shippingContact.phoneNumber; //если был запрошен телефон
        //все варианты смотрите на сайте https://developer.apple.com/reference/applepayjs/paymentcontact

        var data = {
            cryptogram: JSON.stringify(event.payment.token)
        };

        //передайте полученный токен на бэкэнд сервера и оттуда выполните 
        //запрос  оплаты по криптограмме https://developers.tiptoppay.kz/#oplata-po-kriptogramme,
        //используя этот токен в параметре CardCryptogramPacket
        $.post("/ApplePay/Pay", data).then(function (result) {
            var status;
            if (result.Success) {
                status = ApplePaySession.STATUS_SUCCESS;
            } else {
                status = ApplePaySession.STATUS_FAILURE;
            }

            session.completePayment(status);
        });
    };

    // Начало сессии Apple Pay
    session.begin();
});

Условия использования Apple Pay

Вы можете применять технологию Apple Pay с системой TipTop Pay на сайтах и в мобильных приложениях при соблюдении условий использования от компании Apple:

Google Pay™

googlepay

Способ оплаты от компании Google, который объединяет в себе возможности оплаты через приложение Google Pay в магазинах и обычной оплаты картой, сохраненной в аккаунте пользователя Google.

Технология работает в мобильных приложениях и браузерах Google Chrome, Mozilla Firefox, Apple Safari, Microsoft Edge, Opera или UCWeb UC на всех устройствах Android.

Протестировать оплату через Google Pay можно в нашем демо-магазине. Использовать можно как тестовые, так и реальные карточные данные.
Деньги списываться не будут.

Принцип работы Google Pay

Google Pay объединяет в себе возможности оплаты через приложение Google Pay (ранее Android Pay) в магазинах и обычной оплаты картой, сохраненной в аккаунте пользователя Google.

Если покупатель производит оплату в приложении или на сайте с мобильного устройства, поддерживающего Google Pay, ему будет предложено подтвердить оплату способом, зависящим от возможностей устройства.

При оплате с устройства без установленного приложения Google Pay, покупателю будет предложено выбрать сохраненную карту из его Google аккаунта и, на усмотрение процессора, пройти 3-D Secure аутентификацию.

Наша интеграция Google Pay включает поддержку двух методов авторизации: CRYPTOGRAM_3DS и PAN_ONLY.

Прием платежей с Google Pay

Схема оплаты включает в себя 3 этапа:

Интеграция

Регистрация сайтов и приложений

Для приема платежей в приложении или на сайте с прямой интеграцией:

  1. Проверьте, что соблюдены все требования по брендированию;
  2. Заполните форму регистрации, после чего с вами свяжется представитель Google и проинструктирует по дальнейшим шагам;
  3. Будьте готовы отправить на проверку сборку приложения (.apk) или ссылку на сайт со страницей оплаты.

Для приема платежей на сайте через виджет регистрация и проверка сайта не требуются.

Google Pay в мобильных приложениях

Используйте Google Pay API для получения PaymentData и метод оплаты по криптограмме в API для проведения платежа.

При формировании запроса на платежные данные укажите тип оплаты через шлюз: Wallet-Constants.PAYMENT_METHOD_TOKENIZATION_TYPE_PAYMENT_GATEWAY и добавьте два параметра:

  1. gateway: tiptoppay;
  2. gatewayMerchantId: ваш Public ID из личного кабинета TipTop Pay.
PaymentMethodTokenizationParameters params =
        PaymentMethodTokenizationParameters.newBuilder()
            .setPaymentMethodTokenizationType(
                WalletConstants.PAYMENT_METHOD_TOKENIZATION_TYPE_PAYMENT_GATEWAY)
            .addParameter("gateway", "tiptoppay")
            .addParameter("gatewayMerchantId", "ваш Public ID")
            .build();

Смотрите также:

Google Pay на сайте

Есть два варианта приема платежей Google Pay на вашем сайте: используя встроенные возможности виджета или прямая интеграция — размещение кнопки непосредственно на вашей страничке без дополнительных форм. В первом случае никакой дополнительной интеграции не требуется. Во втором — ваш сайт должен работать по схеме HTTPS и поддерживать протокол TLS версии 1.2. Домен сайта должен быть предварительно зарегистрирован и подтвержден в Google.

Прямая интеграция предполагает использование клиентской части (javascript) и серверной. На клиенте вы проверяете совместимость устройства и получаете платежные данные, а на сервере отправляете запрос на оплату в API.

Пример js кода:


var allowedPaymentMethods = ['CARD', 'TOKENIZED_CARD'];
var allowedCardNetworks = ['MASTERCARD', 'VISA']; 
var tokenizationParameters = {
    tokenizationType: 'PAYMENT_GATEWAY',
    parameters: {
        'gateway': 'tiptoppay',
        'gatewayMerchantId': 'pk_b9fa79f3d759c56a9b856d8ac59b1' //ваш public id
    }
}
function getGooglePaymentsClient() {
    return (new google.payments.api.PaymentsClient({ environment: 'PRODUCTION' }));
}

//обработчик загрузки Google Pay API
function onGooglePayLoaded() {
    var paymentsClient = getGooglePaymentsClient();
    //проверка устройства
    paymentsClient.isReadyToPay({ allowedPaymentMethods: allowedPaymentMethods })
        .then(function (response) {
            if (response.result) {
                $('#gpay-checkout').show(); //включение кнопки
                $('#gpay-checkout').click(onGooglePaymentButtonClicked);
            }
        });
}

//настройки
function getGooglePaymentDataConfiguration() {
    return {
        merchantId: '04349806409183181471', //выдается после регистрации в Google
        paymentMethodTokenizationParameters: tokenizationParameters,
        allowedPaymentMethods: allowedPaymentMethods,
        cardRequirements: {
            allowedCardNetworks: allowedCardNetworks
        }
    };
}

//информация о транзакции
function getGoogleTransactionInfo() {
    return {
        currencyCode: "KZT",
        totalPriceStatus: 'FINAL',
        totalPrice: '10.00'
    };
}

//обработчик кнопки
function onGooglePaymentButtonClicked() {
    var paymentDataRequest = getGooglePaymentDataConfiguration();
    paymentDataRequest.transactionInfo = getGoogleTransactionInfo();

    var paymentsClient = getGooglePaymentsClient();
    paymentsClient.loadPaymentData(paymentDataRequest)
        .then(function (paymentData) {
            processPayment(paymentData);
        });
}            

//обработка платежа
function processPayment(paymentData) {
    var data = {
        cryptogram: JSON.stringify(paymentData.paymentMethodToken.token)
    };

    // отправьте запрос на ваш сервер, а далее запросите API TipTop Pay
    // для проведения оплаты 
    $.post("/GooglePay/Pay", data).then(function (result) {
        if (result.Success) {
            //оплата успешно завершена
        } else {
            if (result.Model.PaReq) { 
                //требуется 3-d secure
            } else {
                //оплата отклонена
            }
        }
    });
}

В конце страницы необходимо прописать скрипт для вызова функций Google Pay API:

<script async src="https://pay.google.com/gp/p/js/pay.js" onload="onGooglePayLoaded()"></script>

Смотрите также:

Условия использования Google Pay

Вы можете применять технологию Google Pay с системой TipTop Pay на сайтах и в мобильных приложениях при соблюдении следующий требований:

Сценарии интеграции

Система предлагает различные варианты интеграции от очень простого до бесконечно функционального в зависимости от требований.

Платежная форма

Если вам не требуется проверять платежи перед оплатой и фиксировать факт после оплаты:

Регистрация платежей

Если вам необходимо регистрировать платежи в своей системе, но нет необходимости проверять перед оплатой, то ваши действия следующие:

Проверка и регистрация платежей

Если вам необходимо проверять и регистрировать платежи в своей системе, ваши действия следующие:

Автоплатежи для интернет-провайдеров

Платежное решение подходит для интернет-провайдеров, операторов связи и телекомов. Уведомления на проверку и регистрацию платежей могут быть настроены как в формате TipTop Pay, так и в формате QIWI (ОСМП).

provider_bill

Код формы:

    this.paySample3 = function () {
    var widget = new tiptop.Widget();

    var data = {};
    var auto = $('#recurrent-sample-3').is(':checked'); //проверка

    if (auto) { //включаем подписку

        var date = new Date(); //текущая дата
        date.setMonth(date.getMonth() + 1); //следующий месяц
        date.setDate(date.getDate() - 1); //минус один день

        var recurrent = { interval: 'Month', period: 1, startDate: date }; //один раз в месяц начиная со следующего месяца за минусом одного дня
        data.PaymentData = {
            recurrent: recurrent
        }
    }

    var amount = parseFloat($('#amount-sample-3').val());
    var accountId = $('#account-sample-3').val();

    widget.charge({ // options
        publicId: 'test_api_00000000000000000000002', //id из личного кабинета
        description: 'Пополнение счета абонента ' + accountId, //назначение
        amount: amount, //сумма
        currency: 'KZT', //валюта
        accountId: accountId, //идентификатор плательщика (обязательно для создания подписки)
        data: data
    },
    function (options) { // success
        //действие при успешной оплате
    },
    function (reason, options) { // fail
        //действие при неуспешной оплате
    });
};

$('#checkout-sample-3').click(paySample3);

Автоплатежи для благотворительных фондов

Платежное решение подходит для благотворительных фондов. Имя, фамилия, телефон, e-mail и любые другие данные с формы будут сохранены в виджете и переданы на ваш сервер через Pay-уведомление.

fond_donation

Код формы:

this.paySample4 = function () {
    var widget = new tiptop.Widget();

    var data = { //данные дарителя
        name: $('#name-sample-4').val(),
        lastName: $('#lastName-sample-4').val(),
        phone: $('#phone-sample-4').val()
    };

    var auto = $('#recurrent-sample-4').is(':checked'); //проверка

    if (auto) { //включаем подписку
        data.PaymentData = {
            recurrent: { interval: 'Month', period: 1 } //один раз в месяц начиная со следующего месяца
        }
    }

    var amount = parseFloat($('#amount-sample-4').val());
    var accountId = $('#email-sample-4').val();

    widget.charge({ // options
        publicId: 'test_api_00000000000000000000002', //id из личного кабинета
        description: 'Пожертвование в фонд ...', //назначение
        amount: amount, //сумма
        currency: 'KZT', //валюта
        accountId: accountId, //идентификатор плательщика (обязательно для создания подписки)
        email: accountId,
        data: data
    },
    function (options) { // success
        //действие при успешной оплате
    },
    function (reason, options) { // fail
        //действие при неуспешной оплате
    });
};

$('#checkout-sample-4').click(paySample4);

Платежи по подписке

Если вам нужно брать с ваших покупателей плату на регулярной основе, по расписанию, сценарий может быть следующим:

recurrent

Платежи в один клик

Если вам нужно сохранять данные карт на стороне платежного шлюза для последующей оплаты в один клик без ввода карточных данных и без 3-D Secure, сценарий может быть следующим:

1cl-1

Если пользователь согласится, сохраните после оплаты в его профиле маску карты (тип и последние 4 цифры), а также токен. Параметры карты и токен система возвращает в Pay-уведомлении и через API.


1cl-2

Если пользователь выбирает ранее использованную карту — вызывайте метод оплаты по токену через API.

1cl-3

Если пользователь не желает более платить с привязанной карты, удалите маску и токен из его профиля.

PCI DSS

PCI DSS — стандарт информационной безопасности, принятый в индустрии платежных карт Visa и Mastercard. Соблюдать требования стандарта обязаны все компании, которые принимают карты к оплате. Некоторым компаниям необходимо подтверждать свое соответствие.

Соответствие требованиям

Основное требование стандарта — максимально ограничить доступ к данным платежных карт. Оптимальное решение — вообще не иметь к ним доступа, а вместо этого использовать сертифицированных провайдеров для приема платежей. На практике это означает, что нельзя ни запрашивать, ни передавать номера карт. Если при звонке клиент говорит, что не проходит платеж, и начинает диктовать номер, нужно его прервать и объяснить, почему вы не можете получать данные карты. Если присылает по почте или скайпу — удалять сообщение и сообщать, что передавать данные карты небезопасно.

К охраняемым данным относятся полный номер карты и код CVV2/CVC2 (последние 3 цифры на обратной стороне). Имя владельца, срок действия и маскированный номер карты (первые 6 и последние 4 цифры) в защите по требованиям стандарта не нуждаются, поэтому их можно использовать в разумных пределах.

Соответствие PCI DSS вместе с TipTop Pay

TipTop Pay — сертифицированный сервис-провайдер с максимальным уровнем соответствия PCI DSS, предоставляющим право хранить данные платежных карт и обрабатывать более 6 миллионов платежей ежегодно. Подтверждение соответствия проходит каждый год в рамках сертификационного аудита.

Все платежные инструменты TipTop Pay спроектированы таким образом, что при их использовании вы автоматически соответствуете требованиям по безопасности. Дополнительных мер предпринимать не нужно.

Исключением является прием платежей по технологии Checkout. Для использования необходимо подтверждать соответствие: заполнить лист самооценки и ежеквартально проверять сайт на уязвимости специальным сканером.

Технология Checkout

Checkout — уникальная технология токенизации карт для приема платежей на вашем сайте, в форме без встроенных iframe элементов, что дает максимальный контроль и конверсию прохождения платежей. Данные платежных карт шифруются в браузере покупателя, поэтому ваш сайт не принимает участие в обработке и хранении номеров, что значительно сокращает область применения требований PCI DSS. Тем не менее, сайт влияет на безопасность карточных данных и для его защиты необходимо выполнять сканирование не менее одного раза в квартал для поиска вирусов и уязвимостей. Сканирование должно проводиться аккредитованным вендором (ASV) из списка, представленного на сайте совета PCI.

ASV-сканирование

ASV-сканирование — автоматизированная проверка вашего сайта на наличие уязвимостей. Сканер проверяет наличие вирусов, известных уязвимостей, таких как XSS, SQL Injections и так далее, после чего составляет детальный отчет с инструкцией по устранению проблем, если они были обнаружены.

Использование сканера необходимо для приема платежей по технологии Checkout, для остальных инструментов — виджет, мобильный SDK, рекарринг и рекуррент — его использование не требуется.

Выбор вендора для сканирования остается на ваше усмотрение, но он должен быть из списка на сайте совета PCI.

Онлайн-касса для интернет-расчетов

Формат передачи данных для онлайн-чека

Данные для чека необходимо передавать в формате json по примеру ниже:

var receipt = {
        Items: [ 
            {
                label: "Пластырь", // - обязательное поле
                price: 500, // цена одного товара - обязательное поле
                quantity: 1, // количество товара - обязательное поле
                amount: 500, // Сумма товара (price x quantity) - обязательное поле
                vat: 12, // Ставка НДС - обязательное поле,
            },
            {
                label: "Доставка", //, обязательное поле
                price: 500, // цена одного товара, обязательное поле
                quantity: 1, // количество товара, обязательное поле
                amount: 500, // сумма товара (price x quantity), обязательное поле
                vat : 12, // ставка НДС, обязательное поле
            }
        ],
        Amounts : {
            Electronic: 1000
        }
    };

    var data = {};
    data.PaymentData = {
        CustomerReceipt: receipt // Онлайн-чек
}

Описание параметров для формирования объекта СustomerReceipt смотрите в документации сервиса Kassir TipTop Pay.

Условия успешного создания чека

Данные для онлайн-чека можно передавать в параметры виджета, при оплате по криптограмме или токену, при подтверждении оплаты, при проведении возврата, а также через специальный API кассы.

Отправка покупателю онлайн-чека

На выбор покупателя кассовый чек необходимо отправить в письме на e-mail адрес или в СМС, Viber, WhatsApp, Telegram сообщении на номер телефона. Чек может быть отправлен системой TipTop Pay автоматически, при условии передачи e-mail адреса или номера телефона покупателя, или же вы самостоятельно можете отправлять чек — все необходимые реквизиты система передает в уведомлении Receipt.

Момент отправки чека

Чек должен быть отправлен покупателю в момент расчета. Для одностадийных платежей чек формируется сразу же после прохождения оплаты, для двухстадийных — при подтверждении операции.

Тестирование онлайн-чека

При работе в тестовом режиме кассовые чеки будут формироваться в демонстрационной ККТ с отладочным фискальным накопителем. Вы можете передать данные для онлайн-чека при оплате в тестовом режиме и проверить работу онлайн-кассы.

Тестирование

Сразу после создания нового сайта в ЛК он находится в тестовом режиме работы — это значит, что платежи и прочие операции будут проходить в режиме эмуляции.

Для тестирования можно использовать карты:

Тип Номер карты Результат оплаты Результат оплаты по токену
Карта Visa с 3-D Secure 4242 4242 4242 4242 Успешный результат Успешный результат
Карта Mastercard с 3-D Secure 5555 5555 5555 4444 Успешный результат Успешный результат
Карта Visa с 3-D Secure 4012 8888 8888 1881 Недостаточно средств на карте —
Карта Mastercard с 3-D Secure 5105 1051 0510 5100 Недостаточно средств на карте —
Карта Visa без 3-D Secure 4000 0000 0000 3055 Успешный результат Успешный результат
Карта Mastercard без 3-D Secure 5205 0000 0000 3055 Успешный результат Успешный результат
Карта Visa без 3-D Secure 4111 1111 1111 1111 Успешный результат Недостаточно средств на карте
Карта Mastercard без 3-D Secure 5200 8282 8282 8210 Успешный результат Недостаточно средств на карте
Карта Visa без 3-D Secure 4000 0566 5566 5556 Недостаточно средств на карте —
Карта Mastercard без 3-D Secure 5404 0000 0000 0043 Недостаточно средств на карте —

Тестирование Apple Pay

В тестовом режиме система принимает платежи по любой карте, привязанной к Apple Pay на сумму менее 10 000 тенге с успешным результатом не списывая деньги и отклоняет платежи на сумму более 10 000 тенге с ошибкой "Недостаточно средств".

Тестирование онлайн-кассы

При работе в тестовом режиме кассовые чеки будут формироваться в демонстрационной ККТ с отладочным фискальным накопителем.

Справочники

Коды ошибок

Ниже представлены коды ошибок, которые определяют причину отказа в проведении платежа.

Сообщение для плательщика виджет показывает самостоятельно, а в API за него отвечает параметр CardHolderMessage.

Код Название Причина Сообщение для плательщика
5001 Refer To Card Issuer Отказ эмитента проводить онлайн-операцию Свяжитесь с вашим банком или воспользуйтесь другой картой
5003 Invalid Merchant Отказ эмитента проводить онлайн-операцию Свяжитесь с вашим банком или воспользуйтесь другой картой
5004 Pick Up Card Карта потеряна Свяжитесь с вашим банком или воспользуйтесь другой картой
5005 Do Not Honor Отказ эмитента без объяснения причин
- неверно указан код CVV на картах Mastercard;
- внутренние ограничения банка, выпустившего карту;
- карта заблокирована или еще не активирована;
- на карте не включены интернет-платежи или не подключен 3DS.		 Свяжитесь с вашим банком или воспользуйтесь другой картой
5006 Error Отказ сети проводить операцию или неправильный CVV-код Проверьте правильность введенных данных карты или воспользуйтесь другой картой
5007 Pick Up Card Special Conditions Карта потеряна Свяжитесь с вашим банком или воспользуйтесь другой картой
5012 Invalid Transaction Карта не предназначена для онлайн-платежей Воспользуйтесь другой картой или свяжитесь с банком, выпустившим карту
5013 Amount Error Слишком маленькая или слишком большая сумма операции Проверьте корректность суммы
5014 Invalid Card Number Некорректный номер карты Проверьте правильность введенных данных карты или воспользуйтесь другой картой
5015 No Such Issuer Эмитент не найден Проверьте правильность введенных данных карты или воспользуйтесь другой картой
5017 Customer Cancellation Отказ по желанию держателя карты Воспользуйтесь другой картой
5019 Transaction Error Отказ эмитента без объяснения причин
- неверно указан код CVV на картах Mastercard;
- внутренние ограничения банка, выпустившего карту;
- карта заблокирована или еще не активирована;
- на карте не включены интернет-платежи или не подключен 3DS.		 Свяжитесь с вашим банком или воспользуйтесь другой картой
5030 Format Error Ошибка на стороне эквайера — неверно сформирована транзакция Повторите попытку позже
5031 Bank Not Supported By Switch Неизвестный эмитент карты Воспользуйтесь другой картой
5033 Expired Card Pickup Истек срок утери карты Свяжитесь с вашим банком или воспользуйтесь другой картой
5034 Suspected Fraud Отказ эмитента — подозрение на мошенничество Свяжитесь с вашим банком или воспользуйтесь другой картой
5036 Restricted Card Карта не предназначена для платежей Платежи для этой карты запрещены. Попробуйте другую карту
5041 Lost Card Карта потеряна Свяжитесь с вашим банком или воспользуйтесь другой картой
5043 Stolen Card Карта украдена Свяжитесь с вашим банком или воспользуйтесь другой картой
5051 Insufficient Funds Недостаточно средств Недостаточно средств на карте
5054 Expired Card Карта просрочена или неверно указан срок действия Проверьте правильность введенных данных карты или воспользуйтесь другой картой
5055 Invalid PIN Неверный PIN-код Воспользуйтесь другой картой
5057 Transaction Not Permitted Ограничение на карте
— внутренние ограничения банка, выпустившего карту;
— карта заблокирована или еще не активирована;
— на карте не включены интернет-платежи или не подключен 3DS.		 Свяжитесь с вашим банком или воспользуйтесь другой картой
5058 Transaction Not Permitted To Card Транзакция не разрешена по карте Свяжитесь с вашим банком или воспользуйтесь другой картой
5059 Suspected Fraud Decline Транзакция была отклонена банком по подозрению в мошенничестве Свяжитесь с банком или воспользуйтесь другой картой
5061 Exceeds Approval Amount Превышена сумма по карте Превышение лимита оплаты по карте. Измените настройки лимита или оплатите другой картой
5062 Restricted Card 2 Карта не предназначена для платежей Платежи для этой карты запрещены. Попробуйте другую карту
5063 Security Violation Карта заблокирована из-за нарушений безопасности Воспользуйтесь другой картой
5065 Exceed Withdrawal Frequency Превышен лимит операций по карте Свяжитесь с вашим банком или воспользуйтесь другой картой
5082 Incorrect CVV Неверный CVV-код Неверно указан код CVV
5091 Timeout Эмитент недоступен Повторите попытку позже или воспользуйтесь другой картой
5092 Cannot Reach Network Эмитент недоступен Повторите попытку позже или воспользуйтесь другой картой
5096 System Error Ошибка банка-эквайера или сети Повторите попытку позже
5204 Unable To Process Операция не может быть обработана по прочим причинам Свяжитесь с вашим банком или воспользуйтесь другой картой
5206 Authentication failed 3-D Secure авторизация не пройдена Свяжитесь с вашим банком или воспользуйтесь другой картой
5207 Authentication unavailable 3-D Secure авторизация недоступна Свяжитесь с вашим банком или воспользуйтесь другой картой
5300 Anti Fraud Лимиты эквайера на проведение операций Воспользуйтесь другой картой
5113 Gateways do not support the currently selected payment card Шлюз не поддерживает эмитента неРФ Воспользуйтесь другой картой
5761 No Phone Отсутствует номер телефона Воспользуйтесь другой картой
5762 Invalid Phone Некорректный номер телефона Воспользуйтесь другой картой
5763 Different Phones Номер телефона в запросе отличается Воспользуйтесь другой картой

Коды обработки ответов на check уведомление

Ниже предоставлены код регистрации ответов вашего сервиса на check-уведомление

Код Название Причина
3001 InvalidInvoiceId Обработчик уведомления вернул {"code":10}
3002 InvalidAccountId Обработчик уведомления вернул {"code":11}
3003 InvalidAmount Обработчик уведомления вернул {"code":12}
3004 OutOfDate Обработчик уведомления вернул {"code":20}
3005 FormatError Обработчик уведомления вернул код, отличный от ожидаемого
3006 Unavailable Сервис недоступен
3007 UnableToConnect Обработчик не отвечает (404, 504, 508 и т.д)
3008 NotAccepted Обработчик уведомления вернул {"code":13}

Типы операций

В таблице ниже представлены коды типов операций в уведомлениях.

Код Название
Payment Оплата
Refund Возврат
CardPayout Выплата на карту

Статусы операций

В таблице ниже представлены статусы транзакций, условия применения и возможные действия.

Статус Описание Применение Возможные действия
AwaitingAuthentication Ожидает аутентификации После перехода плательщика на сайт эмитента в ожидании результатов 3-D Secure Нет
Authorized Авторизована После получения авторизации Подтверждение, Отмена
Completed Завершена После подтверждения операции Возврат денег
Cancelled Отменена В случае отмены операции Нет
Declined Отклонена В случае невозможности провести операцию (нет денег на счете карты и т.п.) Нет

Статусы подписок (рекуррент)

В таблице ниже представлены статусы подписок, условия применения и возможные действия.

Статус Описание Применение Возможные действия
Active Подписка активна После создания и очередной успешной оплаты Отмена
PastDue Просрочена После одной или двух подряд неуспешных попыток оплаты Отмена
Cancelled Отменена В случае отмены по запросу Нет
Rejected Отклонена В случае трех неудачных попыток оплаты, идущих подряд Нет
Expired Завершена В случае завершения максимального количества периодов (если были указаны) Нет

Список валют

Наши партнеры принимают платежи в тенге, американских долларах, евро, фунтах стерлингов и 54 других валютах мира.

В таблице ниже представлены названия валют и их коды для использования в параметре currency виджета или API.

Название Код
Казахский тенге KZT
Евро EUR
Доллар США USD
Фунт стерлингов GBP
Украинская гривна UAH
Белорусский рубль (не используется с 1 июля 2016) BYR
Белорусский рубль BYN
Российский рубль RUB
Азербайджанский манат AZN
Швейцарский франк CHF
Чешская крона CZK
Канадский доллар CAD
Польский злотый PLN
Шведская крона SEK
Турецкая лира TRY
Китайский юань CNY
Индийская рупия INR
Бразильский реал BRL
Южноафриканский рэнд ZAR
Узбекский сум UZS
Болгарский лев BGN
Румынский лей RON
Австралийский доллар AUD
Гонконгский доллар HKD
Грузинский лари GEL
Киргизский сом KGS
Армянский драм AMD
Дирхам ОАЭ AED

Если необходимой вам валюты нет в списке, напишите нам на [email protected], и мы его обновим.

Коды временных зон

В таблице ниже представлены коды временных зон для преобразования времени.

Код Название
HST (UTC-10:00) Гавайи
AKST (UTC-09:00) Аляска
PST (UTC-08:00) Тихоокеанское время (США и Канада)
MST (UTC-07:00) Горное время (США и Канада)
CST (UTC-06:00) Центральное время (США и Канада)
EST (UTC-05:00) Восточное время (США и Канада)
AST (UTC-04:00) Атлантическое время (Канада)
BRT (UTC-03:00) Бразилия
UTC (UTC) Время в формате UTC
GMT (UTC) Дублин, Лиссабон, Лондон, Эдинбург
CET (UTC+01:00) Амстердам, Берлин, Берн, Вена, Рим, Стокгольм
CET (UTC+01:00) Белград, Братислава, Будапешт, Любляна, Прага
CET (UTC+01:00) Брюссель, Копенгаген, Мадрид, Париж
CET (UTC+01:00) Варшава, Загреб, Сараево, Скопье
EET (UTC+02:00) Афины, Бухарест
EET (UTC+02:00) Вильнюс, Киев, Рига, София, Таллин, Хельсинки
EET (UTC+02:00) Восточная Европа
EET (UTC+02:00) Калининград (RTZ 1)
MSK (UTC+03:00) Волгоград, Москва, Санкт-Петербург (RTZ 2)
MSK (UTC+03:00) Минск
AZT (UTC+04:00) Баку
AMT (UTC+04:00) Ереван
SAMT (UTC+04:00) Ижевск, Самара (RTZ 3)
GET (UTC+04:00) Тбилиси
TJT (UTC+05:00) Ашхабад, Ташкент
YEKT (UTC+05:00) Екатеринбург (RTZ 4)
ALMT (UTC+06:00) Астана, Алматы
NOVT (UTC+06:00) Новосибирск (RTZ 5)
KRAT (UTC+07:00) Красноярск (RTZ 6)
HKT (UTC+08:00) Гонконг, Пекин, Урумчи, Чунцин
IRKT (UTC+08:00) Иркутск (RTZ 7)
SGT (UTC+08:00) Куала-Лумпур, Сингапур
ULAT (UTC+08:00) Улан-Батор
YAKT (UTC+09:00) Якутск (RTZ 8)
VLAT (UTC+10:00) Владивосток, Магадан (RTZ 9)
SAKT (UTC+11:00) Чокурдах (RTZ 10)
ANAT (UTC+12:00) Анадырь, Петропавловск-Камчатский (RTZ 11)

Типы уведомлений

В таблице ниже представлены типы уведомлений.

Код Название
Check Check
Pay Pay
Fail Fail
Confirm Confirm
Refund Refund
Recurrent Recurrent
Cancel Cancel

Модули CMS Payments

Начните принимать онлайн-платежи через платёжные модули TipTop Pay. Модули подходят для любых интернет-магазинов и сервисов, которые хотят принимать оплату на базе готовых решений для WordPress, Joomla и других популярных CMS-систем и конструкторов сайтов. Это позволит вам быстро начать принимать платежи и облегчит процесс настройки.

1C Битрикс

GitLab

Возможности:

Совместимость:

Joomla HikaShop

GitLab

Возможности:

Совместимость:

Joomla VirtueMart

GitLab

Возможности:

Совместимость:

Joomla JoomShopping

GitLab

Возможности:

Совместимость:

OpenCart

GitLab

Возможности:

Совместимость:

PrestaShop

GitLab

Возможности:

Совместимость:

WooCommerce

GitLab

Возможности:

Совместимость:

Drupal UberCart

GitLab

Возможности:

Совместимость:

Drupal Commerce

GitLab

Возможности:

Совместимость:

Ecwid

Маркетплейс

Возможности:

Совместимость:

InSales

Маркетплейс

Возможности:

Совместимость:

Tilda

Инструкция

Возможности:

Совместимость:

Wix

Инструкция

Возможности:

Совместимость:

Bitrix24

Маркетплейс

Возможности:

Совместимость:

CS-Cart

GitLab, Маркетплейс

Возможности:

Совместимость:

Библиотеки

Flutter

плагин Flutter для интеграции TipTop Pay в приложениях для Android и iOS

pub.dev

Example