Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.useaxra.com/llms.txt

Use this file to discover all available pages before exploring further.

Checkout Sessions let you redirect customers to an Axra-hosted payment page instead of collecting card details yourself. You create a session with a single API call, redirect the customer to the returned URL, and Axra handles card entry, validation, 3D Secure authentication, and the post-payment redirect — all without any card data touching your servers. Because Axra absorbs the card data handling, you are not in PCI DSS scope for card storage or transmission.
If you need full control over the payment UI or want to charge cards programmatically from your server, use the Payments API instead. Both approaches support 3DS and webhooks.

​
How checkout sessions work

1

Create a session

Call POST /business/payment/session from your server with the payment amount, currency, and redirect URLs. Axra returns a checkoutUrl and a sessionId.
2

Redirect the customer

Send the customer’s browser to the checkoutUrl. You can do this with a server-side redirect or by opening the URL in a new window, but a full-page redirect gives the best experience.
3

Customer completes payment

The customer enters their card on Axra’s hosted page. If the card requires 3DS, Axra handles the challenge entirely within the checkout experience — the customer never leaves the Axra-hosted page.
4

Customer is redirected

On success, Axra redirects the customer to your successUrl. If the customer clicks “Cancel” or the session expires, they are sent to your cancelUrl. The successUrl supports a {SESSION_ID} placeholder that Axra replaces with the actual session ID.
5

Confirm via webhook

After the redirect, verify the payment by waiting for the payment.completed webhook event. Do not fulfil orders based on the URL redirect alone — the webhook is the authoritative confirmation.
Always confirm payment completion via the payment.completed webhook. A customer can reach your successUrl without a successful payment (e.g., by navigating directly to the URL). Only the webhook guarantees the charge succeeded.

​
Create a checkout session

POST /business/payment/session Creates a new hosted checkout session and returns a URL to redirect your customer to.

​
Authentication

Pass your API key in the x-api-key header, or include a valid JWT Authorization: Bearer <token> header.

​
Request parameters

​
amount
number
required
Payment amount in major currency units (e.g., 25.00). Minimum value is 0.50.
​
currency
string
required
ISO 4217 currency code in lowercase (e.g., "usd", "eur", "ngn").
​
successUrl
string
required
URL to redirect the customer to after a successful payment. You can include the {SESSION_ID} placeholder — Axra will replace it with the actual session ID on redirect. Example: "https://yourapp.com/payment/success?session={SESSION_ID}".
​
cancelUrl
string
required
URL to redirect the customer to if they cancel the checkout or if the session expires.
​
description
string
Short description displayed on the Axra-hosted checkout page (e.g., "Subscription — Pro Plan"). Helps customers recognize what they are paying for.
​
customerEmail
string
Customer email address. Pre-fills the email field on the checkout page so the customer does not have to type it.
​
expiresIn
number
default:"3600"
How long the session remains valid, in seconds. Minimum 300 (5 minutes). After expiry, customers visiting the checkoutUrl are redirected to your cancelUrl.
​
metadata
object
Arbitrary key-value pairs attached to the session and included in the payment.completed webhook payload. Use this to store your internal order ID, user ID, or any other reference.

​
Response fields

​
sessionId
string
required
Unique identifier for the checkout session. Use this to look up the associated payment later.
​
checkoutUrl
string
required
The fully-formed URL to redirect your customer to. Valid until expiresAt.
​
expiresAt
string
required
ISO 8601 timestamp indicating when the session expires.
​
amount
number
required
The session amount in major currency units, confirming what was set.
​
currency
string
required
ISO 4217 currency code confirming the session currency.

​
Example

curl --request POST \
  --url https://api.useaxra.com/api/v1/business/payment/session \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "amount": 25.00,
    "currency": "usd",
    "description": "Subscription — Pro Plan",
    "customerEmail": "amara@example.com",
    "successUrl": "https://yourapp.com/payment/success?session={SESSION_ID}",
    "cancelUrl": "https://yourapp.com/payment/cancelled",
    "expiresIn": 1800,
    "metadata": {
      "orderId": "sub_pro_9982",
      "userId": "usr_abc123"
    }
  }'
201 Created — session created successfully 
{
  "sessionId": "cs_01HABC987654",
  "checkoutUrl": "https://checkout.useaxra.com/pay/cs_01HABC987654",
  "expiresAt": "2026-04-14T11:23:45.000Z",
  "amount": 25.00,
  "currency": "usd"
}

​
Handling the post-payment redirect

When Axra redirects to your successUrl, the URL will contain the session ID if you included the {SESSION_ID} placeholder. You can read this value from the query string to associate the redirect with the correct order.
Node.js (Express)
app.get('/payment/success', async (req, res) => {
  const sessionId = req.query.session;

  // Do NOT fulfil the order yet — wait for the webhook instead.
  // Use sessionId to show a "processing" screen to the customer.
  res.render('payment-processing', { sessionId });
});
Show a “payment processing” message on your success page and fulfil the order only after receiving the payment.completed webhook. This avoids fulfilling orders for redirects that do not correspond to a completed payment.

​
Listening for payment confirmation

Configure a webhook URL in your Axra Pay dashboard and handle the payment.completed event. The payload includes the sessionId in the metadata object alongside any custom metadata you provided when creating the session.
Node.js (Express)
app.post('/webhooks/axra', express.raw({ type: 'application/json' }), (req, res) => {
  const event = JSON.parse(req.body);

  if (event.type === 'payment.completed') {
    const { paymentId, metadata } = event.data;
    const orderId = metadata.orderId;

    // Safe to fulfil the order now
    fulfillOrder(orderId);
  }

  res.sendStatus(200);
});
See Webhooks for signature verification and the full event schema.

​
Session expiry

If a customer does not complete payment before the session expires, Axra redirects them to your cancelUrl. The expired session cannot be reactivated — create a new session if the customer wants to try again.
The minimum session duration is 300 seconds (5 minutes). For checkout flows with multiple steps before payment, set expiresIn to at least 900 seconds (15 minutes) to avoid premature expiry.