Платежные транзакции

• Используемые структуры
  • Транзакция
  • Мета-данные
• Способы оплаты
  • Доступные способы
  • Наличные
  • Картой оффлайн
  • Бонусы
  • Картой онлайн
  • Привязанной картой
  • Изменение способа оплаты
• Методы
  • Создание транзакции
  • Подтверждение транзакции
  • Отмена транзакции
  • Возврат транзакции

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

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

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

Используемые структуры

Транзакция оплаты заказа

Описание полей

Мета-данные транзакции оплаты заказа

Описание полей

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

Получение доступных способов оплаты

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

Мы рекомендуем запрашивать список способов оплаты для текущего заказа непосредственно перед отображением этого списка покупателям. Для этого нужно выполнить GET-запрос на URL https://api.zenky.io/v2/orders/{orderId}/payment-methods. В ответ вы получите список с доступными способами оплаты.

Ответ

[
    {
        "id": "cash",
        "name": "Наличные"
    },
    {
        "id": "credit-card",
        "name": "Картой при получении"
    }
]

Наличные

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

Для создания транзакции платежа наличными средствами в качестве значения поля method необходимо использовать cash.

Сумма сдачи будет храниться в мета-поле change.

Оффлайн-платёж картой (через терминал)

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

Бонусы

Оплата бонусами происходит в 2 шага:

1. Регистрация платежа (создание платежа с методом оплаты bonuses);
2. Подтверждение платежа кодом из SMS или ПИН-кодом покупателя.

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

Картой онлайн

На данный момент Zenky поддерживает оплату онлайн с помощью Интернет-эквайринга Cloudpayments.

Cloudpayments

Оплата через Cloudpayments происходит в 2 этапа:

1. Создаётся транзакция с типом оплаты (поле method) cloudpayments на нужную сумму;
2. В ответе будут перечислены параметры для виджета Cloudpayments (для отображения на веб-страницах), а так же URL страницы с автоматическим открытием виджета (для мобильных приложений).

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

Подтверждение транзакции происходит автоматически.

Список полей виджета

Полный список доступных полей виджета можно посмореть в документации Cloudpayments.

Отдельная страница оплаты

Zenky по умолчанию предоставляет страницу оплаты заказа с подключенным виджетом Cloudpayments. Вы можете её использовать, к примеру, в мобильном приложении.

URL страницы оплаты будет указан в поле meta.payment_page_url способа оплаты online.

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

1. Покупатель должен выбрать в качестве способа оплаты метод "Картой онлайн";
2. После оформления заказа необходимо открыть модальное окно со страницей оплаты. Транзакция оплаты загрузится автоматически;
3. Дождитесь, пока покупатель завершит оплату (см. раздел Результат оплаты ниже), а затем закройте окно оплаты;
4. Покажите покупателю страницу успешной оплаты.

Результат оплаты

• После успешной оплаты к URL страницы виджета будет добавлен путь /success (например, если URL страницы оплаты выглядит как https://example.org/payment/cloudpayments/1/2, то после успешной оплаты он превратится в https://example.org/payment/cloudpayments/1/2/success);

• В случае ошибки или отказа покупателя от оплаты к URL страницы виджета будет добавлен путь /failed (например, если URL страницы оплаты выглядит как https://example.org/payment/cloudpayments/1/2, то после отказа он превратится в https://example.org/payment/cloudpayments/1/2/failed).

Привязанной картой

Оплата ранее сохранённой картой требует аутентификации покупателя и передачи ID ранее сохранённой карты (поле card_token_id).

Изменение способа оплаты

После оформления заказа способ его оплаты можно сменить, выполнив PUT-запрос на https://api.zenky.io/v2/orders/{orderId}/payment-method, передав следующие параметры:

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

Методы

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

Для создания транзакции необходимо указать способ оплаты и сумму оплаты:

• Если производится оплата наличными, суммой оплаты является купюра. Если пользователь оплачивает без сдачи, указывается полная сумма заказа;
• Если пользователь оплачивает заказ картой, указывается полная сумма заказа;
• Если пользователь оплачивает часть заказа (или весь заказ) бонусами, указывается сумма оплаты.

Оплата бонусами

При оплате бонусами покупатель может выбрать способ подтверждения транзакции (поле confirmation_method).

Возможные значения поля confirmation_method

Оплата картой онлайн

При оплате картой (онлайн) покупатель может сохранить карту для оплаты будущих заказов в один клик. Для этого нужно передать параметр save_card (bool).

Оплата ранее сохранённой картой

При оплате ранее сохранённой картой необходимо передать ID карты в параметре card_token_id.

Автоматическое подтверждение

Если заказ создаётся пользователем-кассиром (или любым другим пользователем, имеющим доступ к управлению магазином), платёж может быть автоматически подтверждён (кроме бонусов).

Для этого нужно передать в поле confirmed значение true.

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

Бонусы

При оплате заказа бонусами пользователю может быть отправлен код подтверждения в SMS (если в качестве значения параметра confirmation_method была передана строка sms).

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

Если же параметр confirmation_method не был передан (или было передано значение pin), покупателю нужно будет указать свой ПИН-код для подтверждения транзакции.

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

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

Остальные способы

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

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

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

Отмена транзакций

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

С отменённой транзакцией нельзя будет проводить никакие действия.

Отмену транзакций может выполнять только пользователь-сотрудник магазина (уровня кассир или выше).

Возврат транзакций

На поведение возвратов транзакций влияет настройка "Задержка возвратов" магазина. В случае, если у магазина нет задержки возвратов, возврат произойдет при получении запроса.

Иначе же будет создана заявка на возврат с задержкой, выбранной в настройках. В течение этого времени можно отменить возврат и транзакция не изменится.

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

Возврат транзакций может выполнять только пользователь-сотрудник магазина (уровня кассир или выше).

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

Отмена возврата

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

После отмены возврата можно снова инициировать новый возврат.