Инструкция по работе с карточными токенами Kassa24 Business

Для успешной интеграции с сервисом Kassa24 Business, выполните следующие шаги:

• Проведите интеграцию согласно технической документации сервиса Kassa24 Business.

• Обратитесь в службу технической поддержки и запросите включение функции карточных токенов.

• При создании транзакции с параметром tokenization: true клиенту будет предложено ввести данные карты. После успешной оплаты в ваш коллбэк придёт поле cardToken — токен карты в строковом формате.

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

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

• При необходимости вы можете получить список всех токенов, связанных с клиентом, по запросу GET /card/tokens?phone=....

• Полученный токен сохраняется на вашей стороне и используется при последующих платежах. Для этого передавайте его в параметре cardToken, вместе с тем же значением phone, которое использовалось при привязке.

Важно: Настоящая инструкция описывает работу с токенами при приёме платежей. Инструкция по работе с токенами при выплатах доступна здесь.

Ниже пример платежного запроса с использованием ранее полученного cardToken:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "merchantId":"your_login",
  "amount":12500,
  "returnUrl":"https://yoursite.kz/payment/complete",
  "description":"Test payment for [email protected]",
  "callbackUrl":"https://yoursite.kz/payment/callback",
  "acquiringId":5,
  "customerData":{
    "phone":"77007777777",
    "cardToken":"9a796429-6bf7-4611-a04c-d7b179f33e41"
  },
  "type":1,
  "demo":true
}

Важно: Если вы передаёте параметр returnUrl в теле запроса, клиент будет перенаправлен на указанный URL после завершения оплаты.

Больше примеров по созданию транзакций с токенами вы можете найти тут.

Создание токена

Этот запрос используется для инициации платёжной транзакции и получения ссылки, по которой клиент сможет оплатить картой. Если вы указываете параметр tokenization: true, система создаст токен карты, но он не вернётся сразу в ответе на запрос.

Как работает процесс:

1. Вы отправляете запрос на POST /payment/create с параметром tokenization: true

2. В ответе вы получаете ссылку на форму оплаты (url) — её нужно передать клиенту.

3. Клиент переходит по ссылке, вводит данные карты и подтверждает платёж.

4. После успешной оплаты в коллбэке (на ваш callbackUrl) приходит токен карты — поле cardToken.

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

Обратите внимание, что токен приходит только в коллбэке, после оплаты, а не в теле ответа этого запроса

1
POST /payment/create

Заголовки запроса

Тело запроса

1
2
3
4
5
6
7
{
    "merchantId": "your_login",
    "tokenization": true,
    "customerData": {
        "phone": "77007777777"
    }
}

Описание переменных

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

1
2
3
4
{
    "url": "https://ecommerce.pult24.kz/payment/view?id=9876543210",
    "id": "9876543210"
}

Описание переменных ответа

Получение списка токенов по номеру телефона

Операция получения списка токенов, связанных с указанным номером телефона. Позволяет получить информацию о сохраненных картах клиента.

1
GET /card/tokens

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

Заголовки запроса

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

1
https://ecommerce.pult24.kz/card/tokens?phone=77007777777

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

1
2
3
4
5
6
[
    {
        "ID": "9a796429-6bf7-4611-a04c-d7b179f33e41",
        "Pan": "1111222233334444"
    }
]

Описание переменных ответа

Удаление токена

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

1
POST /card/tokens/remove

Заголовки запроса

Тело запроса

1
2
3
{
    "id": "9a796429-6bf7-4611-a04c-d7b179f33e41"
}

Описание переменных

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

1
2
3
{
    "removed": true
}

Описание переменных ответа

Общие замечания

• Все запросы требуют авторизации с использованием заголовка Authorization в формате Basic.
• Номера телефонов должны содержать строго 11 цифр и передаваться в виде строки.
• Вместо реального номера телефона можно передавать другой уникальный идентификатор — при условии, что он также состоит из 11 цифр (например, "77007777777"). Этот идентификатор должен использоваться во всех последующих запросах, связанных с токенами, включая создание, получение и удаление карты.
• Идентификаторы (например, merchantId, id карты) должны быть предоставлены соответствующими значениями, полученными от системы.