Orders & Checkout

Create orders and start subscriptions with GetPaidHQ, including how to start a subscription from a payment token you already obtained from your payment processor.

Orders are how subscriptions are created. You do not create a subscription directly — you create an order for one or more priced items, then complete that order with a payment. Completing the order activates any recurring items as subscriptions and starts their billing.

There is no direct subscription-create endpoint. Every subscription is born from an order. See the Subscriptions API for managing a subscription once it exists.

The two-step flow

Create the order — POST /api/orders. You supply the customer, the gateway (psp_id), and a cart of priced items. The server creates the order and a pending subscription for each distinct recurring billing cadence in the cart.
Complete the order — POST /api/orders/{id}/complete. You supply a payment method and the details of the payment. The server activates the subscriptions and, after the database commit, starts each subscription's recurring billing workflow.

All amounts are in the currency's minor units (e.g. cents, kobo).

Starting a subscription from a payment token you already have

A common integration is: you have already collected and charged the customer elsewhere (your own checkout, the gateway's inline widget, or a third-party flow), and you hold a reusable charge token from the gateway. GetPaidHQ can store that token against the customer and run all future recurring charges with it — you do not need a GetPaidHQ-hosted checkout page.

The token must be a reusable gateway credential, not a one-time card token. For Paystack this is the authorization_code, which the gateway only returns after a successful charge — so you must have charged the card at least once before you can re-bill it. GetPaidHQ stores the token as-is and does not verify it at storage time; an invalid token only surfaces at the next charge.

You can supply the token in one of two ways:

Inline at completion — pass a payment_method object containing the token in the complete-order request (shown below). GetPaidHQ creates the payment method for you.
Pre-stored — create the payment method first via POST /api/customers/{id}/payment-methods, then reference its id as payment_method_id when you create or complete the order.

End-to-end example

Create the order

POST https://api.getpaidhq.com/api/orders
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "customer": {
    "email": "customer@example.com",
    "first_name": "John",
    "last_name": "Doe"
  },
  "psp_id": "Paystack",
  "cart": {
    "currency": "NGN",
    "items": [
      { "product_id": "prod_123", "price_id": "price_123", "quantity": 1 }
    ]
  }
}

You may pass an existing customer.id instead of customer details, and an existing payment_method_id if you have already stored the payment method.

The response wraps the created order plus any gateway-specific payload under psp:

{
  "order": {
    "id": "order_123",
    "customer_id": "cus_123",
    "status": "pending",
    "currency": "NGN",
    "total": 290000,
    "items": [ /* ... */ ]
  },
  "psp": null
}

Complete the order with your token

Pass the reusable token inline as a payment_method, and record the payment you already took in payment. Use amount to record the charge you collected externally; set it to 0 if you are not recording an upfront charge.

POST https://api.getpaidhq.com/api/orders/order_123/complete
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "payment_method": {
    "psp": "Paystack",
    "name": "Visa ending 4242",
    "type": "card",
    "token": "AUTH_pmx3upmp",
    "is_default": true
  },
  "payment": {
    "psp_id": "Paystack",
    "reference": "your-charge-reference",
    "amount": 290000,
    "currency": "NGN",
    "completed_at": "2026-06-17T10:30:00Z"
  }
}

completed_at must be an RFC 3339 timestamp. To reference a payment method you stored earlier instead of supplying a token inline, send "payment_method_id": "pm_123" in place of the payment_method object.

The response is the updated order with status: "completed".

Confirm the subscription started

List the subscriptions the order activated:

GET https://api.getpaidhq.com/api/orders/order_123/subscriptions
Authorization: Bearer YOUR_API_KEY

[
  {
    "id": "sub_123",
    "order_id": "order_123",
    "status": "active",
    "currency": "NGN",
    "payment_method_id": "pm_123",
    "billing_interval": "month",
    "billing_interval_qty": 1,
    "renews_at": "2026-07-17T10:30:00Z"
  }
]

From here, recurring charges run automatically against the stored token. Manage the subscription through the Subscriptions API.

Create an order

POST https://api.getpaidhq.com/api/orders

Parameters

customer object required — The customer. Provide an existing id, or email / first_name / last_name / phone to create one.
psp_id string required — The payment gateway to bill through, e.g. Paystack or CheckoutDotCom.
cart object — Required unless session_id is given. Contains currency (required) and items[], each with product_id, price_id, and quantity.
session_id string — Use an existing checkout session/cart instead of an inline cart.
payment_method_id string — Bill an already-stored payment method.
options object — Gateway options passed to the gateway. For gateways that support a hosted page, {"type": "hosted"} returns a redirect URL under psp.
metadata object — Custom key/value metadata.

The server creates one pending subscription per distinct recurring billing cadence in the cart; one-time items do not create subscriptions.

Complete an order

POST https://api.getpaidhq.com/api/orders/{id}/complete

Provide either payment_method_id (an existing payment method) or a payment_method object containing a gateway token.

Parameters

payment_method_id string — Reference an existing stored payment method.
payment_method object — Create a payment method inline. Fields: psp, name, type (e.g. card), token (the reusable gateway token), is_default, billing_address, details.
payment object — The payment to record. Fields: psp_id, reference, amount (minor units; 0 records no upfront charge), currency, completed_at (RFC 3339), metadata.
metadata object — Custom key/value metadata.

Completing the order links the payment method to each pending subscription, marks them active (or trial), and starts their recurring billing.

Hosted / redirect checkout

If you create an order with options: {"type": "hosted"} on a gateway that supports it, the create-order response returns a gateway redirect URL under psp. The customer pays on the gateway's page, and the gateway's webhook completes the order and activates the subscription — you do not call /complete yourself in that case.

Other order endpoints

GET https://api.getpaidhq.com/api/orders/{id}             # Retrieve an order
GET https://api.getpaidhq.com/api/orders                  # List orders (paginated)
GET https://api.getpaidhq.com/api/orders/{id}/subscriptions  # Subscriptions for an order

Orders & Checkout

On this page