Процесс работы

Шаг 1 - Создайте заказ

Для доступа к API необходимо обратиться к нашим контактным лицам с запросом на получение ключа API_KEY. После получения ключа, вам потребуется включить его в заголовки (headers) запросов веб-интерфейса следующим образом:


api-key: <API_KEY>

Для создания заказа первоначально требуется отправить POST-запрос методом HTTP с телом, содержащим данные в формате JSON, по следующему URL-адресу:

https://api-dev.asadalpay.com/api/orders/create-order

Пример JSON, который нужно приложить к телу запроса:

{
  "products": [
    {
      "name": "Шоколад",
      "price": 200,
      "quantity": 2
    },
    {
      "name": "Очки",
      "price": 2000,
      "quantity": 4
    }
  ],
  "currency": "KZT",
  "external_id": "string",
  "description": "Оплата за груз",
  "attempts": 5,
  "mcc": "5533",
  "capture_method": "HOLD",
  "back_url": "https://asadalpay.com",
  "notify_url": "https://asadalpay.com"
}

Поля содержат следующие данные:

Поле	Тип данных	Описание
products	array	Список покупок
currency	string	Валюта оплаты
external_id	string	ID заказа в вашей системе
description	string	Описание заказа
attempts	int	Максимальное количество попыток оплаты по этому заказу
mcc	string	Код вида торговой точки
capture_method	string	Метод платежа
back_url	string	Ссылка на которую надо перенаправить после успешного платежа
notify_url	string	Вебхук на который прилетает данные после оплаты

Структура объекта products:


{
  "name": "Шоколад",
  "price": 200,
  "quantity": 2
}

Поля должны содержать следующие данные:

Поле	Тип данных	Описание
name	string	Название продукта
price	float	Цена продукта
quantity	int	Количество

Шаг 2 - Перенаправьте клиента на платежную форму

После POST запроса вы должны получить JSON со следующим телом:

{
  "created_at": "2023-10-17T22:09:47.971488",
  "updated_at": "2023-10-17T22:09:47.971488",
  "uuid": "f629ce3a-08b7-4be1-9121-371f59ddcc7a",
  "amount": 8400,
  "back_url": "https://asadalpay.com",
  "notify_url": "https://asadalpay.com",
  "description": "Оплата за груз",
  "status": "UNPAID",
  "currency": "KZT",
  "checkout_url": "http://pay-dev.asadalpay.com/checkout/
  f629ce3a-08b7-4be1-9121-371f59ddcc7a",
  "external_id": "string",
  "receiver": "merchant_test",
  "products": [
    {
      "name": "Шоколад",
      "price": 200,
      "quantity": 2
    },
    {
      "name": "Очки",
      "price": 2000,
      "quantity": 4
    }
  ]
}

Поля должны содержать следующие данные:

Поле	Тип данных	Описание
created_at	string	Время создания заказа
updated_at	string	Время обновления заказа
uuid	string	uuid заказа
amount	float	Сумма заказа
back_url	string	Страница перенаправления
notify_url	string	Вебхук для обратного ответа
description	string	Описание заказа
status	string	Статус заказа
currency	string	Валюта заказа
checkout_url	string	Ссылка на форму оплаты
external_id	string	Id мерчанта
receiver	string	Название мерчанта
products	array	Список продуктов заказа

Поле checkout_url содержит ссылку на страницу оплаты по которому перейдет конечный клиент и указав платежные данные совершит покупку

Платежная форма выглядит следующим образом:

Шаг 3 - Получите результаты оплаты

Заказ можно считать успешным, как только он перешел в статус PAID в зависимости от способа списания денег.

Если пользователь передумает платить или что-то пойдет не так, заказ останется в статусе UNPAID.

Также вы можете следить за статусом, запрашивая информацию о заказе удобной для вас периодичностью. Для этого вам понадобится идентификатор заказа — значение параметра uuid в созданном объекте заказа.

GET: https://api-dev.asadalpay.com/api/orders/{order_uuid}

Подтверждение заказа

В случае если при создании заказа была указана поле HOLD в capture_method то после оплаты происходит холдирование платежа со статусом «Удержание» (IN_HOLD). После чего необходимо будет её подтвердить в личном кабинете в CRM-системе либо через API.

Request

POST запрос по следующему url:

https://api-dev.asadalpay.com/api/orders/confirm/{order_uuid}

// Body

{
    "reason" : "{причина подтверждение}"
}

// Headers:

"api-key": "eyJhbGciO..."

Response

{
        "name": "CONFIRM", (Название транзакции),
        "payment_status": "CONFIRMED", (Статус платежа),
        "status": "SUCCEEDED", (Статус транзакции),
        "error_code": "", (Код ошибки),
        "error_description": "", (Описание ошибки)
}

Отмена платежа

Если заказ был создан, оплачен и захолдирован (capture_method) то его можно отменить если не было совершено подтверждение. Отменить платеж можно в личном кабинете в CRM-системе либо через API.

Request

POST запрос по следующему url:

https://api-dev.asadalpay.com/api/orders/cancel/{order_uuid}

// Body

{
"reason" : "{причина отмены}"
}

// Headers:

"api-key": "eyJhbGciO..."

Response

{
        "name": "CANCEL", (Название транзакции),
        "payment_status": "CANCELLED", (Статус платежа),
        "status": "SUCCEEDED", (Статус транзакции),
        "error_code": "", (Код ошибки),
        "error_description": "", (Описание ошибки)
}

Возврат отмененного платежа

Если заказ был оплачен, подтвержден и необходимо совершить возврат (refund). Возврат платежа можно совершить в личном кабинете CRM-системы либо через API:

Request

POST запрос по следующему url:

https://api-dev.asadalpay.com/api/orders/refund/{order_uuid}

// Body

{
    "reason" : "{причина возврата}"
}

// Headers:

"api-key": "eyJhbGciO..."

Response

{
        "name": "REFUND", (Название транзакции),
        "payment_status": "REFUNDED", (Статус платежа),
        "status": "SUCCEEDED", (Статус транзакции),
        "error_code": "", (Код ошибки),
        "error_description": "", (Описание ошибки)
}

Фильтрация платежей

Можно произвести фильтрацию платежей через API. Фильтрация производится по следующим полям:

1. Статуc:

Query: status

CONFIRMED - Подтвержден
IN_HOLD - Захолдирован
DECLINED - Отклонен
TDS_AUTH_REQUIRED - На стадии 3ds
CANCELLED - Отменен
REFUNDED - Возвращен

2. Дата:

Query:

from-date - фильтрация платежей от этой даты. В формате %Y-%m-%d. Например, 2023-06-12
to-date - фильтрация платежей до этой даты. В формате %Y-%m-%d. Например, 2023-06-16

3. Сумма:

Query:

min-amount - минимальная сумма для фильтрации
max-amount - максимальная сумма для фильтрации

4. UUID:

Query:

uuid - идентификатор платежа
order-uuid - платежи по id заказу

5. Платежным системам:

Query:

card_system - фильтрации по МПС (значения могут быть VISA, MASTERCARD)

Request

Необходимо поля отправить как Query. Обязательное поле: page (номер страницы)

GET запрос по следующему url:

https://api-dev.asadalpay.com/api/transactions?page=1&limit=10 \\ Headers
"api-key": "eyJhbGciO..."

Response

total_pages - это общее количество страниц
payments - платежи
created_at - дата создания платежа
updated_at - дата обновления платежа
merchant_name - название мерчанта
email - почта пользователя
amount - сумма заказа
order_uuid - идентификатор заказа
status - статус платежа
uuid - идентификатор платежа
total_fee_amount - общая сумма комиссии
card_system - МПС
reimbursement_amount - сумма возмещения за минусом комиссии
transactions - история действия с платежем
created_at - дата создания
updated_at - дата обновления
name - название транзакции (
- REFUND - Транзакция Возврата
- CANCEL -Транзакция отмены
- CONFIRM - Транзакция Подтверждения
- INIT_HOLD - Транзакция двухфакторного платежа
- INIT_AUTO_PAYMENT - Транзакция однофакторного платежа )
error_code - код ошибки
error_description - описание ошибки


{
  "total_pages": 6,
  "payments": [
    {
      "created_at": "2024-02-12T15:49:29.229051",
      "updated_at": "2024-02-12T16:48:34.789161",
      "merchant_name": "testmerchant",
      "email": "test122@mail.ru",
      "amount": 400.51,
      "order_uuid": "bdab8978-4180-47db-8bf4-c7dfdb04ead8",
      "status": "REFUNDED",
      "uuid": "77c76550-ff57-4cbc-87fe-c0afef607f44",
      "total_fee_amount": 0,
      "card_system": "VISA",
      "reimbursement_amount": 400.51,
      "transactions": [
        {
          "created_at": "2024-02-12T15:49:29.229051",
          "updated_at": "2024-02-12T15:49:29.266188",
          "name": "INIT_AUTO_PAYMENT",
          "status": "SUCCEEDED",
          "error_code": null,
          "error_description": null
        },
        {
          "created_at": "2024-02-12T16:48:34.767161",
          "updated_at": "2024-02-12T16:48:34.789161",
          "name": "REFUND",
          "status": "SUCCEEDED",
          "error_code": null,
          "error_description": null
        }
      ]
    },
  ]
}