Пользовательская платежная интеграция

В этом документе объясняется, как Monetization поддерживает обработку платежей для сторонних платежных провайдеров, которые не поддерживаются из коробки, или для случаев, когда логика обработки платежей реализуется вне Monetization через ваши интеграционные процессы.
Категория:

Темы в этом документе:

Сторонняя обработка платежей в Monetization

Сторонняя обработка платежей поддерживается двумя способами: synchronous и asynchronous. Synchronous method требует немедленного ответа от вашего payment integration component. Asynchronous method экспортирует invoices из Monetization, а затем импортирует payments позже.

Асинхронная обработка платежей

При asynchronous payment processing вы экспортируете invoices из Monetization, а payments полностью обрабатываются вне Monetization. После получения результатов обработки платежей вы импортируете их через CSV files или API Monetization.

Экспорт invoices

Invoices можно экспортировать из Monetization двумя способами: настроить invoice export mapper и scheduled exporting job для выгрузки files в SFTP location, либо подписаться на invoice creation через webhook. Во втором случае при создании нового invoice Monetization отправляет invoice request на указанный URL address.

Exporting job - CSV file to SFTP

Чтобы экспортировать invoices как CSV files, настройте Invoice Export mapper, который сопоставляет invoice parameters с columns CSV file. В Monetization это настраивается в Business configuration Export Invoice mappers.

Example of invoice export mapper configuration Рисунок 1: Example of invoice export mapper configuration

Invoice exports планируются через Exporting Jobs. Это могут быть one-off tasks или автоматические tasks за конкретные periods. Exporting Job сохранит exported CSV file в соответствующее SFTP location, например storage/invoice/folder_name/file_name.csv.

Example of invoice export job Рисунок 2: Example of invoice export job

Notification - webhook method

Экспорт invoices через webhooks позволяет получать invoices сразу после создания. Для этого настройте Invoice Notification Rule, которая отправляет каждый created invoice как JSON body request на указанный URL address вместе с заранее настроенными headers.

Example of invoice creation webhook configuration Рисунок 3: Example of invoice creation webhook configuration

Импорт payments

Payments можно импортировать через CSV file в SFTP location или через API call. В обоих случаях payment import должен содержать данные, достаточные для сопоставления payment с customer, invoice или bill.

CSV file import via SFTP

Для CSV import настройте import mapper, который сопоставляет columns CSV file с payment fields в Monetization. Затем загрузите CSV file в согласованное SFTP location, откуда Monetization сможет его обработать.

Import via API call

API import используется, когда ваша интеграция получает payment result и сразу отправляет его в Monetization. API request должен быть authenticated и содержать payment reference, amount, currency, status и связанные identifiers.

Authentication

Для API calls используйте стандартную authentication Monetization. Credentials и token handling зависят от вашей tenant configuration.

Payment import request

Payment import request должен передавать результат оплаты. Если payment успешен, Monetization применяет его к соответствующему invoice или bill. Если payment failed или canceled, статус должен отражать результат обработки.

Синхронная обработка платежей

Synchronous payment processing используется, когда Monetization напрямую вызывает сторонний payment provider во время customer, card или transaction operation. Ваша интеграция должна вернуть ответ немедленно, чтобы Monetization мог продолжить workflow.

Настройка стороннего payment provider

Сторонний payment provider настраивается в System configuration Payment gateways. Укажите URL, API key и при необходимости headers, которые нужны вашей интеграции.

Customer operations

Customer operations позволяют Monetization создать, обновить, прочитать или удалить customer record у внешнего payment provider.

Create customer (without card)

Create customer используется, когда Monetization создает customer у payment provider без сохранения card. Request обычно содержит customer identifiers, name, email и billing data. Response должен вернуть external customer reference.

Update customer

Update customer используется, когда customer data меняется в Monetization и эти изменения нужно передать payment provider.

Read customer

Read customer используется для получения текущего customer state у payment provider.

Delete customer

Delete customer используется, когда customer больше не должен существовать у payment provider или должен быть deactivated.

Card operations

Card operations управляют setup и удалением card/payment method.

Setup (setup card request)

Setup card request создает или подготавливает card setup у payment provider. В зависимости от provider это может вернуть redirect URL, setup token или другой reference, который нужен для завершения card registration.

Delete card

Delete card удаляет card или payment method у payment provider. Response должен подтвердить, что удаление выполнено или что card больше не активна.

Transaction operations

Transaction operations используются для authorization, capture, charge, void и refund.

Authorization

Authorization резервирует сумму на payment method, но еще не списывает ее окончательно.

Capture

Capture подтверждает ранее выполненную authorization и завершает списание.

Charge

Charge выполняет прямое списание без отдельного authorization step.

Void

Void отменяет transaction, которая еще не была окончательно captured или settled.

Refund

Refund возвращает клиенту полностью или частично уже списанную сумму.

Error handling

Интеграция должна возвращать понятные error responses, чтобы Monetization мог показать корректный статус операции и сохранить diagnostic information. Ошибки должны различать validation errors, authentication errors, provider errors, network/timeouts и business declines.

Предыдущая
Устройства