Skip to content
Merxian
DocumentationAPI reference
Dashboardmerxian.com

Technical concepts

Asynchronous results

Many payment operations finish after the API responds. A successful response means that Merxian accepted or created something, not always that money moved.

On this page

Three kinds of result#

Result Meaning Example
Accepted Merxian received a request and will act on it. The outcome is not known yet. A refund in the requested state
Created A resource exists, in its first state. A checkout session in the open state
Final The resource reached a state that ends its lifecycle, or the state that you wait for. A payment in the succeeded state

Payments and refunds depend on banks and card networks. They can take seconds or longer, and they can fail after the API responded.

What each response means#

Call Response What it means What it does not mean
Create a checkout session 201 The hosted page exists. The buyer paid.
Finalize a transaction 200 The amounts are frozen and the transaction can be collected. Money was collected.
Create a payment 201 The payment exists and its first attempt started. The payment succeeded.
Retry a payment 201 A new attempt started. The attempt succeeded.
Refund a payment 202 Merxian accepted the refund in the requested state. The money reached the buyer.
Cancel a payment 202 Merxian accepted the cancellation. Read the returned status for the state.

Learn the final result#

Webhook events are the main way to learn a result. Merxian sends an event to your endpoint when a resource changes.

Your server sends a refund request. Merxian answers 202 with a requested refund. Later, Merxian sends refund.succeeded to your webhook endpoint, which answers 200. Your server can read the refund to confirm.Your serverMerxianYour webhook endpoint1. POST /v1/payments/{id}/refunds2. 202 · status: requested3. refund.succeeded4. 200 OK5. GET /v1/refunds/{id} (optional)
A refund: the response comes first, the result comes later. A dashed line is a response or a later message.
  1. Your server sends the request.
  2. Merxian answers at once with the accepted state.
  3. Later, Merxian sends the event with the result to your webhook endpoint.
  4. Your endpoint answers 2xx.
  5. Your server can read the resource to confirm the state.

Reading the resource is the fallback. Use it when you did not receive an event in the time that you expect, or before an action that must not be repeated. Do not poll in a tight loop. See Rate limits.

States can change after you read them#

A state that you read can change a moment later. For example, a pending payment can become succeeded or failed, and a succeeded payment can later be refunded or disputed. Build your logic on state changes, not on one read:

  • Store the state with the time that you learned it.
  • Apply an event only if it moves the resource forward in your records. Events can arrive out of order. See Process events.
  • Treat a state value that you do not know as not final.

Each lifecycle is on its concept page: transactions, payments, refunds, and checkout sessions.

Next steps

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