Hosted checkout

Payment lifecycle

Every payment moves through a small, explicit set of states. Terminal states never change again.

Statuses

Status	Terminal	Meaning / next step
`REQUIRES_ACTION`	No	Created. Open the checkoutUrl, or cancel.
`PROCESSING`	No	Consent given, the operator is charging. Wait for the webhook.
`SUCCEEDED`	Soft	Paid. Grant access. Later changes arrive as entitlement and subscription events.
`FAILED`	Yes	Declined or not completed. Offer to try again with a new payment.
`EXPIRED`	Yes	The session passed expiresAt without completing.
`CANCELED`	Yes	Canceled by you before completion.

Read a payment

Partner console — payments list and detail

GET/v1/payments/{paymentUid}

Your server’s synchronous source of truth, for example when the customer returns before the webhook arrives.

curl https://api.sandbox.paylumia.com/v1/payments/pay_4mK9pQeRw2Ns6TfXb1Zy0a \
  -H "Authorization: Bearer $PAYLUMIA_TOKEN"

200 OK

{
  "success": true,
  "data": {
    "object": "payment",
    "paymentUid": "pay_4mK9pQeRw2Ns6TfXb1Zy0a",
    "mode": "HOSTED",
    "status": "SUCCEEDED",
    "orderId": "0b8f3f5e-3f55-4c1a-9a44-2f0c7f0b9d61",
    "subscriberUid": "sbr_7Hq2LmN4pR8sT1vW",
    "productUid": "premium",
    "offerUid": "premium_daily",
    "expiresAt": "2026-09-20T15:30:00Z",
    "metadata": { "orderRef": "order-8891" }
  }
}

Cancel a payment

POST/v1/payments/{paymentUid}/cancel

Allowed while the payment is still waiting on the customer (REQUIRES_ACTION). Never after SUCCEEDED. The body is empty; the response is the payment with status: CANCELED.

cURL

curl -X POST https://api.sandbox.paylumia.com/v1/payments/pay_4mK9pQeRw2Ns6TfXb1Zy0a/cancel \
  -H "Authorization: Bearer $PAYLUMIA_TOKEN"