Verify · reconcile

Check payment status

A webhook is a push; this is the pull. Retrieve the current status of a checkout session or a PaymentIntent at any time — to reconcile, to verify before you fulfil, or as the safety net when a delivery is delayed or your endpoint was down. Both endpoints are idempotent and read the same source of truth, so you can poll them freely.

ℹ

Use it alongside webhooks

Production integrations use both: the webhook for instant fulfilment, and a status check on your return page (plus an occasional reconcile poll) as the safety net. Key fulfilment on the intent/session id so acting on a terminal status twice is harmless.

Hosted checkout — a session

Retrieve a checkout session by its cs_… id. No API key is required — the unguessable session id is the bearer, so a return page can read it directly in the browser. This is what the hosted-checkout return page polls.

GET /v1/checkout/sessions/:idbash

curl https://api.merashub.com/v1/checkout/sessions/cs_...

# → {
#   "id": "cs_...",
#   "amount_minor": 15,
#   "currency": "DJF",
#   "status": "complete",
#   "success_url": "https://yoursite.example/e/evt?ref=tkt_...",
#   "cancel_url": "https://yoursite.example/e/evt",
#   "merchant": { "id": "m_...", "trade_name": "..." }
# }

Name	Type	Description
`open`	status	Session created; the customer has not picked a payment method yet.
`processing`	status	Paid; settlement is in flight on the rail (awaiting confirmation).
`complete`	status	Settled. This is your signal to fulfil.
`canceled`	status	The customer cancelled, or the attempt was declined.
`failed`	status	The payment failed. Let the customer retry (a fresh attempt reuses the session).
`expired`	status	The session lapsed before payment. Create a new one.

Direct API — a PaymentIntent

Retrieve a PaymentIntent by its pi_… id. Authenticate with your secret key (server-side), or a publishable key plus the intent's client_secret as a query param (browser-side — the same pairing the SDK uses to poll).

GET /v1/payment_intents/:idbash

# Server-side — secret key:
curl https://api.merashub.com/v1/payment_intents/pi_... \
  -H "Authorization: Bearer sk_live_..."

# Browser-side — publishable key + client_secret:
curl "https://api.merashub.com/v1/payment_intents/pi_...?client_secret=pi_..._secret_..." \
  -H "Authorization: Bearer pk_live_..."

# → {
#   "id": "pi_...",
#   "status": "succeeded",
#   "amount_minor": 15,
#   "currency": "DJF",
#   "metadata": { "reference": "tkt_..." }   // your keys, echoed back
# }

Name	Type	Description
`requires_payment_method`	status	Created; no method chosen yet.
`requires_action`	status	Awaiting OTP, a redirect, or a wallet approval.
`processing`	status	Captured; settlement in flight.
`succeeded`	status	Settled. Fulfil now.
`canceled`	status	You or the customer cancelled, or the provider declined.
`failed`	status	The payment failed. Start a new attempt.

Session ↔ intent status

A checkout session wraps a PaymentIntent, so its status is the intent's status mapped to session vocabulary. Treat complete / succeeded as terminal-success and fulfil; treat canceled / failed / expired as terminal-dead and offer a retry.

Name	Type	Description
`intent: succeeded`	→ session	complete
`intent: requires_action / processing`	→ session	processing
`intent: canceled`	→ session	canceled
`intent: failed`	→ session	failed
`intent: requires_payment_method`	→ session	open