Integration guides

Cancel or adjust a transaction

A finalized transaction does not change. To stop it, cancel it. To change what it requires, add an adjustment.

On this page

Choose the right action
Cancel a transaction
Cancel a payment
Expire a checkout session
Add an adjustment
Rules
Correction reasons
Adjustments from Merxian

Choose the right action#

You want to	Use
Change a draft	PATCH`/v1/transactions/{transactionId}`
Stop a buyer from paying on a hosted page	POST`/v1/checkout-sessions/{sessionId}/expire`
Stop a payment that has not collected money	POST`/v1/payments/{paymentId}/cancel`
Stop a transaction that has not collected money	POST`/v1/transactions/{transactionId}/cancel`
Return money that was collected	Refund a payment
Change the amount that a finalized transaction requires	POST`/v1/transactions/{transactionId}/adjustments`

Cancel a transaction#

You can cancel a transaction that has not completed. You cannot cancel a transaction that has collected money or that has a payment in progress. Such a request returns 409 with the code not_cancelable. Wait for the payment result, or cancel the payment first.

Cancel a transaction

curl -X POST https://api.merxian.com/v1/transactions/txn_0F8mQ2rXbT4kL9pZa/cancel \
  -H "Authorization: Bearer $MERXIAN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "The buyer changed the purchase." }'

You receive transaction.canceled. A failed payment does not cancel its transaction.

Cancel a payment#

You can cancel a payment in the created, provider_requested, pending, or failed state, before it collects money. The response is 202 and the payment state is cancelled. You receive payment.canceled. A payment that does not exist returns 422 with the code lifecycleValidationFailed.

Expire a checkout session#

Expiring a session closes the hosted page and cancels a payment that the session started. When the session created its own draft transaction and no payment is in progress, Merxian also cancels that transaction. See Accept a payment with hosted checkout.

Add an adjustment#

An adjustment is a signed change to a finalized transaction. It is kept in the adjustments list of the transaction, oldest first.

Field	Meaning
`type`	Your label for the adjustment, for example `goodwill_credit`. It must not be blank.
`amountMinor`	The signed amount in minor units. `-2000` in `EUR` lowers the amount by €20.00.
`changesCollectibleAmount`	`true` when the adjustment changes what the transaction still requires. Then `adjustedRequiredAmount` and `remainingCollectibleAmount` change.
`reason`	Why you make the adjustment.
`sourceReference`	Your own reference, for example a support case.
`effectiveAt`	When the adjustment takes effect. Now when absent.
`correctionReason`	Makes the adjustment a commercial correction. See below.

Lower the amount of a transaction

curl -X POST https://api.merxian.com/v1/transactions/txn_0F8mQ2rXbT4kL9pZa/adjustments \
  -H "Authorization: Bearer $MERXIAN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "goodwill_credit",
    "amountMinor": -2000,
    "changesCollectibleAmount": true,
    "reason": "Late delivery.",
    "sourceReference": "CASE-311"
  }'

Rules#

A draft returns 409. Update the draft instead.
The required amount cannot go below zero.
The required amount cannot go below money that a payment already holds for collection.
After the transaction is completed, you cannot add an adjustment that raises the required amount.

Correction reasons#

Set correctionReason when the adjustment corrects the sale itself. The values are:

Value	Use it for
`refund`	Money returned to the buyer.
`credit_note`	A credit that a credit note documents.
`price_adjustment`	A price change after the sale.
`return`	Goods or a service that the buyer returned.
`bad_debt_relief`	An amount that you cannot collect.
`tax_classification_correction`	A change of the tax treatment of the sale.

Leave correctionReason out for a plain adjustment.

Adjustments from Merxian#

Merxian also records adjustments, for example when a chargeback moves money. Their actorType is not account. See Disputes.

After every adjustment you receive transaction.adjusted. The payload does not include the adjustments. Read the transaction to see them.