Skip to content
Merxian
DocumentationAPI reference
Dashboardmerxian.com

Core concepts

Payments

A payment is one intent to collect money for a transaction. Its result arrives after the API call returns, so you learn it from webhook events.

On this page

What a payment is#

A payment collects money for one transaction. The transaction says how much is owed. The payment is one try to collect it from the payer.

A payment ID starts with pay_, for example pay_3RtN6wYc8mK2hQvJd. The payment object uses paymentId for its ID.

How payments are created#

In most integrations, you do not create payments yourself. When the buyer pays on a checkout session, Merxian creates the payment.

You can also create a payment for a ready transaction with POST/v1/payments. The interactionMode field sets how the payer takes part:

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

A transaction has at most one active payment. A second create request for the same transaction returns 422 with the code paymentValidationFailed.

Attempts#

A payment has one or more attempts. paymentAttemptId is the ID of the current attempt, for example payatt_1Bx7NqT4vK9mL2wRc.

When a payment fails and the failure allows a retry, POST/v1/payments/{paymentId}/retry starts a new attempt. The payment keeps its ID and gets a new paymentAttemptId. A payment has at most five attempts.

Capture#

Capture is automatic. When a payment succeeds, the money is authorized and captured. You cannot authorize now and capture later.

Next action#

nextAction tells you what must happen to complete the payment. It can be null when nothing is known yet.

nextAction.type What you do
none Nothing.
redirect Send the payer to nextAction.url.
wait_for_webhook Nothing. The result arrives later as a webhook event.
mount_payment_component Used only by the payment component, which is not yet generally available.

Lifecycle#

The main payment transitions. created goes to provider_requested, which goes to pending. pending goes to succeeded, failed, or cancelled. failed can go back to provider_requested on retry, or to expired. succeeded goes to partially_refunded or refunded. expired is the only state with no exit.retrycreatedprovider_requestedpendingsucceededfailedcancelledpartially_refundedexpiredrefunded
The main transitions of a payment. The table lists every transition. A double border marks a final state.
State Meaning Can move to
created Merxian created the payment. provider_requested, succeeded, failed, cancel_requested
provider_requested Merxian sent the payment for processing. pending, succeeded, failed, cancel_requested
pending Processing started. Merxian waits for the result. succeeded, failed, cancel_requested, cancelled, expired
succeeded The money was authorized and captured. partially_refunded, refunded
partially_refunded Part of the payment was refunded. partially_refunded, refunded, succeeded
refunded The full payment was refunded. partially_refunded, succeeded
failed The attempt was refused or could not be completed. provider_requested (on retry), cancel_requested, expired
cancel_requested A cancellation is in progress. cancelled, succeeded
cancelled The payment was cancelled. succeeded
expired The payer did not complete the payment in time. None

Only expired has no exit. Two moves back are possible:

  • A payment in cancelled or cancel_requested can still move to succeeded, when the money was authorized before the cancellation took effect.
  • A payment in refunded or partially_refunded can move back, when a refund is reversed. See Refunds.

Treat a state that you do not know as not final.

How you learn the result#

The response to a create or retry request tells you that Merxian accepted the payment. It does not tell you that money moved. The result arrives later.

  1. Listen for the payment events: payment.succeeded, payment.failed, payment.canceled, and payment.expired.
  2. When you need the current state, read the payment with GET/v1/payments/{paymentId}.

In webhook payloads, the cancelled state is written canceled, and a disputed payment has the state dispute_opened. See the event catalogue.

Cancel a payment#

POST/v1/payments/{paymentId}/cancel cancels a payment that has not collected money. You can cancel in the created, provider_requested, pending, or failed state. To return money that was collected, refund the payment.

What to build#

  • Record the payment ID with your transaction record.
  • Handle payment.succeeded and payment.failed in your webhook endpoint, and process each event once.
  • Let the buyer try again after a failure. On hosted checkout, the session stays open until it expires.

Next steps

Try refund, payment.succeeded,POST /v1/transactions, orIdempotency-Key.