Быстрый старт

API позволяет принимать платёжи онлайн — в вебе и на мобильных устройствах. Эта статья поможет вам принять первый платёж, при этом вашим покупателям будут доступны все способы оплаты, которые вы подключили.

Подготовка

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

Шаг 1. Создайте платёж

Платёж — главная сущность API. Чтобы его создать, вам понадобятся сумма платёжа и URL, на который пользователь вернётся после оплаты.

Если хотите добавить описание платёжа, которое вы увидите в личном кабинете, а пользователь — при оплате, передайте его в параметре description. Описание должно быть не более 128 символов.

Отправьте API запрос и передайте в нём данные для создания платёжа и данные для аутентификации (идентификатор магазина и секретный ключ).

Пример запроса на создание платёжа

curl https://kassa.amra-bank.com/api/v1/payments \
  -X POST \
  -u <Идентификатор магазина>:<Секретный ключ> \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {
          "value": "100.00",
          "currency": "RUB"
        },
        "returnUrl": "https://www.merchant-website.com/return_url",
        "description": "Заказ №1",
        "metadata": {
          "orderId": 1
        }
      }'

Шаг 2. Отправьте пользователя на страницу оплаты

В теле ответа от API вы получите созданный объект платёжа в статусе pending. Для оплаты перенаправьте пользователя на confirmationUrl.

Пример созданного объекта платёжа

{
  "status":"pending",
  "capturedAt":null,
  "canceledAt":null,
  "cancelError":null,
  "cardInfo":null,
  "id":"953fce21-75a7-473a-b89e-f6b445bdc369",
  "amount": {
    "value":"100.00",
    "currency":"RUB"
  },
  "createdAt":"2022-07-05T09:41:24.065Z",
  "description":"Заказ №1",
  "confirmation": {
    "type":"redirect",
    "confirmationUrl":"https://kassa.amra-bank.com/pages/v1/payment-confirm/953fce21-75a7-473a-b89e-f6b445bdc369"
  },
  "metadata":{
    "orderId": 1
  },
  "recipient":"7fe8ade9-5f4c-4b06-9a2f-bf3ed3a29c6b"
}

После успешной оплаты (или если что-то пойдёт не так) API вернёт пользователя на returnUrl, который вы передали при создании платёжа.

Шаг 3. Дождитесь успешного выполнения платёжа

Платёж можно считать успешным только в том случае, если он перешёл в статус succeeded. Если пользователь передумает платить (или что-то пойдёт не так), платёж перейдёт в статус canceled.

Чтобы узнать статус платёжа, подпишитесь на уведомления от API.

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

Ура, вы приняли первый платёж!