Payments

Use the Payments API to retrieve the current status of a payment. This is a fallback when webhooks are unavailable or delayed.

Payment IDs are returned when you create a Checkout Session.

Idempotency

When creating a payment, send an Idempotency-Key header. Appibase stores the first successful or failed result for that key and replays it on retries.

Reusing the same key with different parameters returns 409 Conflict. Keys are retained for 24 hours.

Idempotency-Key: 3f1a2e3b-9b9f-4af8-bf2f-f1ce4ef5d8f7

Retrieve a payment

Endpoint:

GET /api/v1/payments/:id

Use your Storefront Access Token and JSON:API content type:

Authorization: Bearer {access_token}
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json

Response

{
  "data": {
    "id": "pay_j9LafqUhkk8Hp8gsFKwzHe7r",
    "type": "payment",
    "attributes": {
      "order_id": 2027671153,
      "payment_ref": "3Jgw3DXCjO7lgsAAALFL",
      "client_ref": "123456",
      "gateway": "satim",
      "currency": "dzd",
      "amount_cents": 381000,
      "amount_received_cents": 381000,
      "email": "name@gmail.com",
      "status": "succeeded",
      "paid": true,
      "gateway_meta": {},
      "metadata": {
        "shipping": {
          "currency": "dzd",
          "amount_cents": 50000
        },
        "line_items": [
          {
            "name": "Gel Douche NIVEA Abricot 250ml",
            "currency": "dzd",
            "quantity": 2,
            "price_cents": 59000
          },
          {
            "name": "NIVEA visage tonique 200ml",
            "currency": "dzd",
            "quantity": 3,
            "price_cents": 71000
          }
        ]
      }
    }
  },
  "links": {
    "self": "http://appibase.com/api/v1/payments/pay_j9LafqUhkk8Hp8gsFKwzHe7r"
  }
}

Status meanings

requires_payment_method: payment was created and is waiting for the customer to complete the checkout flow.
unconfirmed: customer returned from the checkout flow but SATIM confirmation has not completed yet. The paid flag indicates whether the payment should be treated as succeeded or failed.
succeeded: payment completed successfully.
failed: payment failed.

If the status remains requires_payment_method 10 minutes after creation, the payment is incomplete.

Status decision table

Status	Paid	Interpretation
requires_payment_method	false	Customer hasn’t completed checkout. If this persists > 10 minutes, treat as incomplete.
unconfirmed	true	Treat as succeeded while confirmation is pending.
unconfirmed	false	Treat as failed while confirmation is pending.
succeeded	true	Payment completed successfully.
failed	false	Payment failed.

When to poll

Use webhooks as the primary source of truth.
Use GET /payments/:id as a fallback or for manual status checks.