Core concepts

Transactions

A transaction is the payable record of a sale. It holds the lines, the buyer, the amounts, and the tax. Every payment collects a transaction.

On this page

What a transaction is
How it relates to other resources
Lines or an amount
Lifecycle
Draft and finalize
Revisions
Amounts
Adjustments
References and metadata
What to build

What a transaction is#

A transaction is the business record of one sale. It answers one question: how much must the buyer pay, and for what. It is the source of truth for the amount.

A transaction ID starts with txn_, for example txn_0F8mQ2rXbT4kL9pZa.

How it relates to other resources#

A payment collects money for one transaction. A transaction can have more than one payment over time, but only one active payment at a time. See Payments.
A checkout session is a hosted page where a buyer pays one transaction. A session is optional. See Checkout sessions.
A payment link creates a new checkout session and a new transaction for each buyer. See Payment links.
Each line refers to a catalog price. See Products and prices.
A transaction can refer to a stored customer with customerId. See Customers.

The API returns a transaction without its payments. To read them, use GET/v1/transactions/{transactionId}/payments.

Lines or an amount#

A transaction gets its total from one of two sources. The amountSource field tells you which.

Source	Request field	Result
`line_items`	`lines`, each with a `catalogPriceId` or a `productId`, and a `quantity`	Merxian takes the name, the unit amount, and the tax code of each line from your catalog. You cannot send your own description or unit amount.
`amount_only`	`amount`, in minor units	The transaction has no lines, only an amount.

When Merxian calculates tax for your account, a transaction must have lines. An amount-only request returns 422 with the code amount_only_not_allowed. You cannot change a transaction from one source to the other.

Lifecycle#

The states of a transaction. A double border marks a final state.

From	To	Cause
(new)	`draft`	You create the transaction, or a checkout session or a payment link creates it.
`draft`	`ready`	You finalize the transaction.
`ready`	`processing`	A payment of the transaction is created or is being processed.
`processing`	`completed`	The payments collected the full amount that the transaction requires.
`ready`, `processing`	`past_due`	The `dueAt` time passed and money is still to be collected.
`past_due`	`processing`	A payment is processed after the due date.
`draft`, `ready`, `processing`, `past_due`	`canceled`	You cancel the transaction, or a checkout session ends and cancels the draft that it created.

completed and canceled are final. A failed payment does not move a transaction back from processing. The buyer can try again with a new payment.

Each state change sends a webhook event, for example transaction.ready and transaction.completed. In webhook payloads, the state values are upper case, for example COMPLETED.

Draft and finalize#

A draft can change. Use PATCH/v1/transactions/{transactionId} to replace its content, and POST/v1/transactions/preview to see the amounts of a request without creating anything.

When you finalize, Merxian calculates the final amounts, discounts, and tax, and freezes them with the buyer, line, and price details. The transaction becomes ready, and only a ready transaction can be collected.

Revisions#

revision goes up by one each time the transaction changes. To prevent lost updates on a draft, send the revision that you last read in the If-Match header as W/"<revision>". If the transaction changed after that revision, the update returns 409 with the code revision_conflict. See Build a transaction.

Amounts#

All amounts are integers in the minor unit of the transaction currency. 14280 in EUR is €142.80. See Money and currencies.

Field	Meaning
`amounts.subtotal`	The sum of the line subtotals.
`amounts.discount`	The discount, for example from a promotion code.
`amounts.net`	The amount before tax, after the discount.
`amounts.tax`	The tax.
`amounts.total`	The amount to pay when the transaction was finalized.
`adjustedRequiredAmount`	The amount to collect after adjustments.
`remainingCollectibleAmount`	The amount that is still to be collected.
`authorizedAmount`	The amount that payments authorized.
`capturedAmount`	The amount that payments captured.
`netCollectedAmount`	The captured amount less refunds.
`refundedAmount`	The amount refunded.

Two status fields summarize the transaction:

paymentStatus is the payment progress: unpaid, pending, partially_paid, paid, partially_refunded, or refunded.
taxStatus is the tax state: not_applicable when no tax applies, pending when Merxian does not yet have the buyer details to calculate the tax, and calculated when amounts.tax holds the result.

Adjustments#

An adjustment is a signed change to a finalized transaction. You cannot adjust a draft. When changesCollectibleAmount is true, the adjustment changes adjustedRequiredAmount and remainingCollectibleAmount. An adjustment cannot bring the required amount below zero, and you cannot add a positive adjustment after the transaction is completed.

Merxian also records adjustments, for example when a payment is charged back. Each adjustment sends transaction.adjusted. See Disputes.

References and metadata#

externalReference holds your own ID for the sale, for example a reference number from your own system. It appears in webhook payloads as external_reference.
metadata holds up to 50 key-value pairs. A key has at most 64 characters, a value at most 1024.

What to build#

Store the transaction ID with your own record of the sale.
Use transaction.completed as the signal to deliver.
Handle past_due and canceled by closing or following up on your record.