Skip to main content

Payment gateway integration

Any payment gateway can integrate with OMS through GraphQL mutations and webhooks. The integration has three goals:

  • Push the e-commerce payment transactions into OMS, including the provider fees — essential for Calicantus to reconcile and report the payment activity accurately.
  • Report the disputes (chargebacks, claims) opened against those transactions, if the gateway manages them.
  • Execute the refunds requested by OMS: when a refund is requested in OMS, OMS notifies the gateway with a webhook; the gateway executes the refund on its own circuit and reports the outcome back in OMS.
note

This integration assumes the gateway already provides a plugin/app compatible with the e-commerce platform the purchases come from: the orders reach OMS through the e-commerce channel, not through this integration. The scope described here is only the direct exchange between OMS and the payment gateway.

How the integration works​

Push the payment transactions​

When the shopper completes a payment on the e-commerce platform, the gateway records the transaction in OMS with the paymentExternalTransactionCreate mutation.

  • Every transaction is recorded against a payment merchant (see What you need to get started) and references the order it pays by its number: this is what ties the payment to the e-commerce purchase in OMS.
  • Always send the provider fees when the gateway knows them — they are what makes the reconciliation accurate. Fees can also be attached or corrected later.

Use the paymentExternalTransactionUpdate mutation to keep the transaction in sync with the gateway, typically to move it from pended to completed or failed, or to attach final provider fee data.

If a refund is initiated on the gateway side, record it in OMS with the paymentExternalTransactionRefund mutation: a child transaction with a negative amount (and its own fees, if any), linked to the original payment and referencing the repayment request (return) or the order it belongs to. Refunds requested by OMS follow a different flow, see below.

The Create, update and refund external transactions guide documents the field-by-field rules of these mutations, with verified examples; Payment transaction and dispute statuses documents the allowed status transitions and how refunds affect the original transaction.

Report the disputes​

If the gateway manages disputes, it can track them in OMS against the original payment: the paymentExternalDisputeCreate mutation records a new dispute linked to an existing external transaction, and the paymentExternalDisputeUpdate mutation follows its lifecycle (status, reason, defense deadline).

The Create and update external disputes guide documents the field-by-field rules of both mutations, with verified examples.

At any time, the recorded transactions and disputes can be retrieved back from OMS — see Query external transactions and disputes.

Execute the refunds requested by OMS​

When a refund for a transaction is requested in OMS, OMS records the refund as a new external transaction with a negative amount and notifies the gateway by sending the refund_requested webhook event to the endpoint registered for the integration. The event payload contains the refund transaction — its amount is the amount to refund — together with the original payment transaction it refunds. See Events for the event payload and Introduction to Webhooks for the delivery, authentication and retry rules.

On receiving the event, the gateway:

  1. Executes the refund on its own payment circuit for the requested amount.
  2. Reports the outcome in OMS with the paymentExternalTransactionUpdate mutation on the refund transaction received in the event, moving its status to completed (or failed) and attaching the provider fees, if any — see Update an external transaction.

Things to know:

  • The refund transaction is created by OMS in requested status. Besides moving it straight to completed or failed, the gateway can use pended as an intermediate status — for example to track the authorization before the capture.
  • The same event can be delivered more than once (see the retry policy): use the event id to process each refund request only once.
  • The event is emitted only for the refund transactions created internally by OMS: the refunds the gateway records through the API never trigger it, so the gateway can never receive back a refund it recorded itself.
  • If the refund is marked failed, the related order is flagged for attention in OMS and an operator will retry it, producing a new refund transaction and a new refund_requested event. There is no maximum time to report the outcome.
  • Partial refunds are supported: the requested amount can be lower than the original payment, and the same payment can receive multiple refund requests over time.

What you need to get started​

Everything below is agreed with and configured by Calicantus — to start the onboarding, contact developers@calicant.us:

  1. API credentials — the integration authenticates like any other API client: see Authentication.
  2. A payment merchant — every transaction is recorded against a merchant, identified by the merchant code submitted on creation. Merchants are configured for you by Calicantus.
  3. A webhook endpoint — required to receive the refund_requested event. The endpoint requirements and the supported authentication methods are described in Introduction to Webhooks.

Before going live, also review the core concepts of the API in Getting started — in particular Errors and Rate limiting.