Актуальные операции Checkout Controller

Таблица синхронизирована с текущими CheckoutPaymentController и DTO. Для merchant-операций требуется header merchantId.

HTTP Endpoint Request Response
POST /payment/v1/checkout-payments/init InitCheckoutPaymentRequest InitCheckoutPaymentResponse
POST /payment/v1/checkout-payments/post-init PostInitCheckoutPaymentRequest InitCheckoutPaymentResponse
POST /payment/v1/checkout-payments/pre-init PreInitCheckoutPaymentRequest PreInitCheckoutPaymentResponse
POST /payment/v1/checkout-payments/complete CheckoutPaymentRequest CardPaymentResponse
POST /payment/v1/checkout-payments/3ds-init CheckoutPaymentRequest ThreeDSInitResponse
POST /payment/v1/checkout-payments/3ds-verify-complete VerifyThreeDSRequest CheckoutThreeDSVerifyCompleteResponse
POST /payment/v1/checkout-payments/3ds-verify-complete-for-failed-payment VerifyThreeDSForFailedPaymentRequest 204 No Content
POST /payment/v1/checkout-payments/point PointInquiryRequest PointInquiryResponse
GET /payment/v1/checkout-payments/{token} Path: token CardPaymentResponse
GET /payment/v1/checkout-payments/retrieve/{token} Path: token, header: partnerId CheckoutPaymentResponse

Платежная страница

Платежи через общую платежную страницу осуществляются в 2 этапа: инициация и завершение. В запросе инициализации в API Odero отправляется запрос на создание формы. В результате этого запроса отправителю запроса возвращается 2 значения. Одно из этих значений token, а другое pageUrl. После этого шага URL-адрес, возвращаемый pageUrl, открывается в браузере или отображается с помощью iframe. Параметр iframe=True должен быть добавлен к этому значению URL, чтобы можно было отображать с помощью iframe. URL- адрес в параметре callbackUrl отправляется в форме значения token, после процесса создания оплаты. Карту можно сохранить с помощью общей платежной страницы, а также оплату можно произвести с помощью сохраненной карты.

Сохранение карты

Чтобы сохранить карту при оплате через общую платежную страницу, пользователю необходимо выбрать «сохранить мою карту» на странице оплаты. Карты также можно сохранить для платежей, совершенных не через общую страницу оплаты. Сохранение карты

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

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

Запуск общей платежной страницы

URL

Ниже приведена информация о endpoint и методе http, используемых для запуска платежа с общей платежной страницы:

HTTP Metod URL
POST /payment/v1/checkout-payments/init

Параметры запроса для запуска платежа

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

Название параметра Тип Обязательный Объяснение
conversationId string Нет Значение "бумеранг", которое может быть отправлено с запросом и получено с ответом. Его можно использовать для связывания разных запросов друг с другом. Обычно используется номер заказа мерчанта, связанный с платежом.
price decimal Да Общая сумма платежа. Сумма товаров/услуг в корзине, должна быть равна этой сумме.
paidPrice decimal Да Общая сумма, которая заплатит клиент, рассчитывается с учётом таких разниц, как комиссионные и скидки. Платежи, которые полностью или частично собираются в кошельке и сумма, которая взимается с кошелька, включаются в эту сумму.
moneyBoxPrice decimal Нет Сумма списания из MoneyBox. Значение по умолчанию — 0. При значении больше нуля необходимо передать moneyBoxUserId.
buyerId long Нет ID покупателя, с которым связан платеж. Это относится к значению ID в системе Odero, а не к значению ID в собственной системе мерчанта.
cardUserKey string Нет Просмотр сохраненного ключа карты пользователя: Информация о сохраненной карте
currency Currency Да См. : Валюты Валюта, в которой будет произведена оплата.
paymentGroup PaymentGroup Да См. : группы оплат
callbackUrl string Да* Адрес, который будет использоваться для доставки результата от банка мерчанта при платежах, осуществляемых с помощью 3D Secure (см. Прием оплаты с 3D Secure )
items PaymentItem[] Да (см. : Информация о распределении платежей) Информация о распределении платежей. Должна быть отправлена хотя бы одна часть, а сумма отправленных частей должна быть равна значению полю price .
plan PaymentPlan Нет** (см.: Информация о подписке) Данные плана подписки. Все поля обязательны для заполнения.

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

**: Это поле является обязательным, если PaymentGroup не произвела оплату (SUBSCRIPTION)

Параметр Тип Обязательный Описание
moneyBoxUserId long Условно Идентификатор MoneyBox при moneyBoxPrice больше нуля.
paymentPhase string Нет Фаза платежа; по умолчанию AUTH.
enabledInstallments integer[] Нет Варианты рассрочки на checkout-странице.
enabledInstallmentsForCommercial integer[] Нет Рассрочка для коммерческих карт.
enabledBanks integer[] Нет Ограничивает доступные банки.
externalCustomerId string Нет Идентификатор клиента мерчанта; максимум 255 символов.
invoiceTotalAmount decimal Нет Итоговая сумма счёта.
storeCardEnable boolean Нет Разрешает сохранение карты; по умолчанию true.
cardHolder object Нет Данные name, email и phoneNumber владельца карты.
expireAfterMinutes integer Нет Срок действия checkout-токена в минутах.
redirectOnFailure boolean Нет Перенаправление на callback URL при ошибке; по умолчанию false.
invoiceNo string Нет Номер счёта.
taxNumber string Нет Налоговый номер клиента.
customerEmail string Нет Электронная почта клиента.
description string Нет Описание платежа; максимум 255 символов.
informUrl string Нет URL уведомлений для поддерживаемых сценариев.

Поля элемента платежа

Каждый объект items поддерживает поля externalId, subExternalId, externalProductUniqueId, name, price, subMerchantId, subMerchantPrice, withHoldingPrice, productItemCode, skuCode, maturity, itemDetail, vatRate и giftCard. Поле price обязательно и не может быть отрицательным. Допускается не более 250 элементов.

Параметры возврата

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

Название параметра Тип Всегда доступен Объяснение
token string Да Значение unique uuid4, созданное для общей страницы оплаты и платежной транзакции.
pageUrl string Да Сюда входит адрес страницы, на которую должен быть перенаправлен пользователь. При переходе на эту страницу через browser открывается общая страница оплаты.
tokenExpireDate localDateTime Да Поле tokenExpireDate представляет время истечения токена платежной страницы. Это значение, которое указывает, когда токен платежа и связанный с ним URL платежной страницы истекут и станут недействительными.

3D Secure

Процесс оплаты 3D Secure, который начинается с запроса на создание платежной формы, отправленного мерчантом, продолжается после подтверждения пользователем. После того, как пользователь вводит отправленный ему код подтверждения, результат проверки передается в API Odero соответствующим банком. API Odero согласовывает полученный результат с некоторой информацией о платеже и отправляет запрос на callbackUrl, отправленный мерчантом в запросе на запуск платежа.

Параметры, отправляемые в Callback URL

Следующие параметры передаются с использованием метода HTTP POST в качестве form variable. Параметры, содержащиеся в запросе, которые будут отправляться со стороны Odero на callbackUrl следующие:

Название параметра Тип Всегда доступен Объяснение
token string Да Значение unique uuid4, созданное для общей страницы оплаты и платежной транзакции.
subscriptionId long Нет ID значение успешной повторной оплаты. Отправляется, когда PaymentGroup SUBSCRIPTION равны.
multiPaymentbooleanНетПризнак составного платежа.
paymentIdListlong[]НетСписок идентификаторов платежей.
callbackUrlstringДаURL мерчанта для получения результата checkout.
merchantIdlongДаИдентификатор мерчанта платежа.
successbooleanДаПризнак успешной проверки и завершения платежа.
paymentOrderintegerНетПорядок платежа в составном платеже.
conversationIdstringНетКорреляционное значение из запроса инициализации.
paidPricedecimalДаОбщая списанная сумма.
merchantPanelPaymentbooleanДаПризнак платежа из панели мерчанта.
redirectOnFailurebooleanНетПризнак перенаправления на callback URL при ошибке.

Запрос на оплату

Платежи, сделанные с использованием общей платежной страницы, можно исследовать с помощью значения token. URL-адрес, request и response использованные для исследовательского процесса, приведены ниже.

URL

Ниже приведена информация о endpoint и методе http, используемых для запуска платежа с общей платежной страницы:

HTTP Method URL
GET /payment/v1/checkout-payments/{token}

Параметры возврата

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

Название параметра Тип Всегда доступен Объяснение
id long Да ID платежа
createdDate date Да Дата первого создания платежа
updatedDate date Да Дата обновления платежа
orderId string Да Отличительный ID номер, созданный в связи с платежом. Для полной оплаты с кошелька, он создается со стороны Odero, в других случаях создается банком.
price decimal Да Общая корзиночная чена платежа.
paidPrice decimal Да Общая взимаемая сумма
walletPrice decimal Да Сумма, снятая с кошелька
paymentType PaymentType Да см. : Валюты
currency Currency Да см. : Валюты
paymentStatus PaymentStatus Да см. : Статусы платежа
conversationId string Нет Значение conversationId, отправленное мерчантом в запросе платежа.
paymentCard PaymentCard Да (см. : Информация о платежной карте и комиссии) Информация о платежной карте и комиссии.
paymentRefunds PaymentRefund[] Да (см. : Информация о возврате платежа) Список возвратов, связанных с оплатой.
paymentTransactions PaymentTransaction[] Да (см. : Информация о распределении платежей) Детали раздач, входящих в оплату.
Поле Тип Описание
pointPrice decimal Сумма, оплаченная карточными баллами.
giftCardPrice decimal Сумма, оплаченная подарочной картой.
loyaltyPointPrice decimal Сумма, оплаченная баллами лояльности.
additionalInstallment integer Количество дополнительных платежей рассрочки.
paymentGroup string Группа платежа.
paymentPhase string Фаза платежа, например AUTH.
cardToken string Токен сохранённой карты.
paidWithStoredCard boolean Признак использования сохранённой карты.
connectorType string Тип connector-а обработки платежа.
paymentError object Структурированная информация об ошибке.
hostReference string Банковский/host reference.
authCode string Код авторизации банка.
bankCode long Идентификатор банка.
subscriptionId long Идентификатор связанной подписки.
htmlContent string HTML для поддерживаемых платёжных сценариев.
bankCardHolderName string Имя владельца карты от банка.
merchantName string Название филиала мерчанта.
cardId long Идентификатор сохранённой карты.
pfCommissionAmountForMerchant decimal Сумма комиссии платформы для мерчанта.
pfCommissionAmountForSubmerchant decimal Сумма комиссии платформы для субмерчанта.
pfCommissionRateForMerchant decimal Ставка комиссии платформы для мерчанта.
pfCommissionRateForSubmerchant decimal Ставка комиссии платформы для субмерчанта.
averageValor string Информация о среднем сроке расчёта.

Информация о платежной карте и комиссии

Сумма отправляется со всеми платежами, в том числе собранными с кошелька.

Название параметра Тип Всегда доступен Объяснение
cardType CardType Нет (см. : Типы карт) Занимает место при полной или частичной оплате с картой. Определяет тип карты.
cardAssociation CardAssociation Нет (см. : Строение карт) Занимает место при полной или частичной оплате с картой. Указывает учреждение, к которому привязана карта.
cardBrand string Нет Занимает место при полной или частичной оплате с картой. Он имеет то же значение, что и cardBrand в данных карты в запросе платежа.
cardHolderName string Нет Занимает место при полной или частичной оплате с картой. Отражает имя и фамилию владельца карты.
binNumber string Нет Занимает место при полной или частичной оплате с картой. Отражает первые 6 цифр карты.
lastFourDigits string Нет Занимает место при полной или частичной оплате с картой. Отражает последние 4 цифры карты.
installment integer Да Показывает количество рассрочек карты. Значения, которые он может получить: 1, 2, 3, 6, 9 и 12
isThreeDS boolean Нет Занимает место при полной или частичной оплате с картой. Указывает, был ли произведен платеж с использованием 3D Secure.
mdStatus integer Нет (см. : MD Статус) Он занимает место в платежах, осуществляемые с помощью 3D Secure, которые полностью или частично снимаются с карты. Указывает статус проверки 3D Secure.
pfCommissionRateAmount decimal Да Размер комиссии, полученной Odero в качестве платежного посредника.
merchantCommissionRate decimal Да Комиссионная ставка, применяемая к платежу мерчантом.
merchantCommissionRateAmount decimal Да Общая комиссионная сумма, полученная мерчантом от платежа.
error Error Нет (см. : Информация о проблеме) Занимает место в платежах, которые завершились с проблемой. Содержит информацию о проблеме.

Информация, связанная с отменой платежа

Содержит подробную информацию о полном возврате платеж. Параметры, входящие в эти информации, перечислены в следующей таблице:

Название платежа Тип Всегда доступен Объяснение
id long Да ID отмененного процесса, созданный Odero.
createdDate date Да Дата отмены
refundStatus string Да см. : Статусы возврата
refundDestinationType RefundDestinationType Да см. : Типы возврата
price decimal Да Отмененная сумма.
refundBankPrice decimal Да Возврат на карту после отмены.
refundWalletPrice decimal Отмена Возврат в кошелек после отмены.
conversationId string Да Значение conversationId отправленное мерчантом в запросе на отмену.
paymentType PaymentType Да (см. : Типы оплат) Тип вычета при отмене платежа.
error Error Нет (см. : Информация о проблеме) Происходит в случае сбоя отмены. Содержит информацию об ошибке

Информация, связанная с распределением платежей

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

Название параметра Тип Всегда доступен Объяснение
id long Да ID распределения платежей.
createdDate date Да Дата создания распределения платежей.
externalId string Нет External ID, связанный с распределением платежа, отправленный в запросе платежа.
transactionStatus TransactionStatus Да (см. : Статусы денежных переводов) Значение, указывающее статус отправки денег, связанных с распределением.
transactionStatusDate date Да Показывает последнюю дату, когда изменился статус денежного перевода для распределения.
price decimal Да Корзиночная цена распределения платежей.
paidPrice decimal Да Доля от общей суммы, собранной для выплаты по соответствующему распределению.
walletPrice decimal Да Доля от общей суммы, собранной с кошелька для оплаты, по соответствующему распределению.
merchantPayoutAmount decimal Да Доля денег, которая будет отправлена мерчанту, в связи с платежом, соответсвующая распределению.
subMerchantId long Нет ID субмерчанта, с которым связан распределение платежей.
subMerchantName string Да Происходит, когда субмерчант связан с распределением платежей. Сюда входит имя соответствующего мерчанта.
subMerchantPrice decimal Да Происходит, когда субмерчант связан с распределением платежей. Это доля от общей суммы, подлежащая переводу из суммы платежа субмерчанту по соответствующему распределению.
subMerchantPayoutRate decimal Да Происходит, когда субмерчант связан с распределением платежей. Это соотношение денег, которые должны быть отправлены субмерчанту, относительно платежа, к деньгам, которые должны быть отправлены мерчанту.
subMerchantPayoutAmount decimal Да Происходит, когда субмерчант связан с распределением платежей. Указывает сумму, которая будет отправлена субмерчанту для оплаты.
payout Payout Да (см. : Распределение платежей Распределение денежных переводов) Сюда входит распределение сумм денежных переводов между мерчантом, субмерчантом и Odero в отношении распределения платежей.
paymentTransactionCard PaymentTransactionCard Да (см. : Информация о карте и комиссиях распределения платежей) Сюда входит информация о карте и комиссионных, связанных с распределением платежей.
paymentTransactionRefunds PaymentTransactionRefund[] Да (см. : Информация о возврате распределения платежей) Список информаций о полном или частичном возврате платежей в отношении распределения платежей.

Информация о карте и комиссии распределении платежей

Сюда входит информация о карте и комиссиях, связанных с разделением платежей.

Название параметра Тип Всегда доступен Объяснение
merchantCommissionRate decimal Да Комиссионная ставка, применяемая субмерчантом к палтежу.
merchantCommissionRateAmount decimal Да Доля платежа от суммы комиссии, полученной мерчантом
pfCommissionRateAmount decimal Да В качестве платежного посредника доля Odero в распределении платежа из суммы комиссии, полученной от платежа.

Распределение платежей Распределение денежных переводов

Сюда входит разделение доли платежного перевода между мерчантом, субмерчантом и Odero. Валютой распределения денег всегда является AZN, поэтому при платежах, осуществляемых в других валютах, будет существовать курсовая разница. Эти различия указаны в полях pfConversionRate и pfConversionRateAmount.

Название параметра Тип Всегда доступен Объяснение
paidPrice decimal Да Доля от общей суммы, собранной для выплаты по соответствующему распределению.
currency Currency Да см. : Валюты
merchantPayoutAmount decimal Да Доля стоимости денег, которая будет отправлена мерчанту в связи с оплатой в валюте AZN, согласно соответствующему распределению.
subMerchantPayoutAmount decimal Да Доля стоимости денег в валюте AZN, подлежащая отправке мерчанту в связи с оплатой, согласно соответствующему распределению.
pfCommissionRateAmount decimal Да Доля стоимости денег, которая будет отправлена в Odero в качестве платежного посредника, в валюте AZN согласно соответствующему распределению.
pfConversionRate decimal Да Разница обменного курса, на которой основан Odero, при денежных переводах, осуществляемых в валюте, отличной от AZN. AZN в платежах равен 0.
pfConversionRateAmount decimal Да Разница обменного курса, на которой основан Odero, при денежных переводах, осуществляемых в валюте, отличной от AZN. AZN в платежах равен 0.

Информация о возврате, связанная с распределением платежей

Полная и частичная, удачная или неудачная информация о возврате платежа.

Название параметра Тип Всегда доступен Объяснение
id long Да ID отмененного процесса, созданный Odero
createdDate date Да Дата отмены
refundStatus string Да см. : Типы возврата
price decimal Да Отмененная сумма
refundBankPrice decimal Да Возврат на карту после отмены.
refundWalletPrice decimal Отмена Возврат в кошелек после отмены.
conversationId string Да Значение conversationId отправленное мерчантом в запросе на отмену.
paymentType PaymentType Да (см. : Типы платежей) Тип вычета при отмене платежа.
isAfterSettlement boolean Да Производится ли возврат средств после перевода выплаты.
error Error Нет (см: Информация о проблеме) Происходит в случае сбоя отмены. Содержит информацию об ошибке

Примеры кодов

Вы можете просмотреть примеры кодов в Odero API client с открытым исходным кодом: