Getting Started

API Access

API Reference

Hosted Checkout

Hosted Checkout lets you create a Checkout Session and redirect the customer to Appibase’s hosted payment page. It works for single items or full baskets, and isn’t limited to e-commerce use cases.

A Checkout Session creates a Payment object (similar to Stripe’s payment_intent). You’ll use the returned payment_id to check status later if needed.

Create a Checkout Session

Endpoint:

POST /api/v1/checkout_sessions

Use your Access Token:

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

Request body

{
  "customer_details": {
    "first_name": "Name",
    "last_name": "Surname",
    "phone": "+213600000000"
  },
  "email": "name@gmail.com",
  "client_ref": "123456",
  "locale": "fr",
  "return_url": "https://cosmetiques.tidjaria.com",
  "line_items": [
    {
      "name": "Gel Douche NIVEA Abricot 250ml",
      "currency": "dzd",
      "price_cents": 59000,
      "quantity": 2
    },
    {
      "name": "NIVEA visage tonique 200ml",
      "currency": "dzd",
      "price_cents": 71000,
      "quantity": 3
    }
  ],
  "shipping": {
    "amount_cents": 50000,
    "currency": "dzd"
  },
  "metadata": {
    "client_meta": {
      "terms_url": "https://aliments.tidjaria.com/content/3-conditions-utilisation"
    }
  }
}

Field notes

  • email is required.
  • client_ref is your reference for mapping the Checkout Session and Payment later.
  • locale supports en or fr.
  • return_url is where the customer returns after the payment flow completes.
  • line_items supports one item (quantity 1) or multiple items.
  • shipping is optional.
  • metadata is for your custom data. Use client_meta for your own keys; some keys are reserved.

customer_details behavior

  • If omitted, the hosted page won’t ask for customer details.
  • If provided as {}, the hosted page will ask the customer to fill the fields.
  • If provided with values, the details are shown for verification and are not editable.

Response

{
  "data": {
    "id": "cs_IKCzQK4pmvoNHI50TNJlvEgfqGNMZvAaRfh2XlU6ZnFEKnONFLnkP7",
    "type": "checkout_session",
    "attributes": {
      "payment_id": "pay_zpX37RAvfYgpQmuDBUg3dpZO",
      "client_ref": "123456",
      "email": "name@gmail.com",
      "currency": "dzd",
      "amount_subtotal_cents": 331000,
      "amount_total_cents": 381000,
      "customer_details": {
        "first_name": "Name",
        "last_name": "Surname",
        "phone": "+213600000000"
      },
      "locale": "fr",
      "return_url": "https://cosmetiques.tidjaria.com",
      "url": "http://appibase.com/123456/pay/cs_IKCzQK4pmvoNHI50TNJlvEgfqGNMZvAaRfh2XlU6ZnFEKnONFLnkP7?locale=fr",
      "metadata": {
        "client_meta": {
          "terms_url": "https://aliments.tidjaria.com/content/3-conditions-utilisation"
        }
      }
    }
  },
  "links": {
    "self": "http://appibase.com/api/v1/checkout_sessions"
  }
}

Use data.attributes.url to redirect the customer to the hosted checkout page.

Store data.id (Checkout Session ID) and data.attributes.payment_id for later status checks.

Redirect the customer

Redirect the customer to the Checkout Session URL returned in the response. Appibase hosts the payment flow and redirects the customer back to your return_url.

Related concepts

  • Payment object (Appibase equivalent of Stripe’s payment_intent).
  • GET Payment by ID (use payment_id if webhook delivery is disabled).

Errors and validation

  • Missing required fields (email, line_items).
  • Mixed currencies across line items.
  • Invalid or missing currency values.