Overview

Integration overview

Your server talks to the Merxian API. The buyer pays on a page that Merxian hosts. Merxian reports the result to your webhook endpoint. This page shows each step and who does it.

On this page

The parts of an integration
The flow
Choose an integration path
Direct payments
What you must build

The parts of an integration#

Part	Owner	Role
Your frontend	You	Shows your products and starts checkout. It never holds an API key.
Your server	You	Calls the Merxian API with a secret API key. Stores the IDs that Merxian returns.
Merxian API	Merxian	Creates and reads transactions, checkout sessions, payments, and refunds.
Hosted checkout	Merxian	The page where the buyer enters details and pays.
The buyer		Pays in a browser.
Your webhook endpoint	You	Receives signed events from Merxian.
Your fulfilment logic	You	Releases goods or access when an event reports that money arrived.

The flow#

A hosted checkout integration, step by step. A dashed line is a response or a later message.

Step	Who acts	Call or event	Timing
1	Buyer	Clicks your checkout button.
2	Your server	`POST /v1/checkout-sessions` with catalog prices, `successUrl`, and `cancelUrl`.	Synchronous
3	Merxian	Returns the `open` session with its `url`. Keep the `url` from this response.	Synchronous
4	Your server	Redirects the buyer to the `url`.
5	Buyer	Enters details and pays. Merxian calculates the tax, when it applies, and collects the payment.
6	Merxian	Redirects the buyer to your `successUrl`, or to `cancelUrl` after a cancel.	Not proof of payment
7	Merxian	Sends `checkout.completed`, `payment.succeeded`, and `transaction.completed`.	Asynchronous, any order
8	Your webhook endpoint	Verifies the signature, stores the event, returns `2xx`, then fulfils.

Choose an integration path#

Path	How it works	Use it when
Checkout session with a draft	Your server sends prices in `transactionDraft`. Merxian creates the transaction and the session in one call.	You sell catalog products on your own site. This is the simplest path.
Payment link	You create one link. Each buyer who opens it gets a new session and a new transaction.	You sell without a site of your own, for example from an email or a social profile.
Transaction, then checkout session	Your server creates and, if you want, finalizes a transaction. Then it creates a session with `transactionId`.	You need the transaction ID before checkout, want to preview the tax, or build the transaction in several steps.

Read the guides for each path: Accept a payment with hosted checkout, Sell with payment links, and Build a transaction.

Direct payments#

The API also has POST /v1/payments, which creates a payment for a ready transaction without a checkout session. It supports two interaction modes:

off_session collects without the buyer present. Your account must be enabled for it, and the buyer must have a stored payment method.
embedded is for the Merxian payment component. The component is not yet generally available.

Most integrations should use a checkout session.

What you must build#

A server-side API client. Keep the API key on your server. Send an Idempotency-Key on every create and command request. See Idempotency.
A webhook endpoint. It must verify the Merxian-Signature header before it trusts an event. See Verify signatures.
Idempotent event processing. Merxian can send an event more than once and in any order. Process each event id once. See Process events.
Reconciliation. Store the Merxian IDs with your own records, and set clientReferenceId or externalReference to your own reference. See Reconcile with your records.
Failure handling. Handle failed payments, expired sessions, and refunds. See Handle payment results.