Overview

The Payments API gives you full programmatic control over the payment lifecycle. You can charge cards directly from your server without a hosted page, retrieve individual payments or paginated transaction lists, and issue refunds — all authenticated with your API key. Every charge is automatically deduplicated within a one-minute window, and 3D Secure challenges are surfaced as a structured requires_action response so you can redirect the cardholder without changing your integration.

The base URL for all Axra Pay API requests is https://api.useaxra.com/api/v1. All requests must be made over HTTPS.

Checkout sessions

Hosted checkout for cards and local rails.

Card payments

Server-to-server card charging.

Local payment methods

Bank transfers, mobile money, and instant EFT settled in USDC.

Charge a card (server-to-server)

POST /business/payment/charge Use this endpoint to charge a card directly from your server. You must have server-to-server (S2S) charging enabled on your business account. If the card requires a 3DS challenge, the response will contain a requiresAction object instead of an immediate succeeded status — see 3DS authentication for the full flow.

You must enable server-to-server charging in your Axra Pay dashboard before using this endpoint. Calls from accounts without S2S enabled will return a 400 error.

Authentication

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

Request parameters

Card details — provide either card or savedTokenId, not both.

number

required

Charge amount in major currency units (e.g., 49.99 for $49.99). Do not pass cents.

string

required

ISO 4217 currency code in lowercase (e.g., "usd", "eur", "ngn").

object

Raw card details. Required if savedTokenId is not provided. Supply this object only over a server-to-server connection — never expose card data on the client.

Show card properties

string

Full card number, digits only, no spaces.

number

Expiry month as an integer from 1 to 12.

number

Expiry year as a 4-digit integer (e.g., 2027).

string

Card verification value (3 or 4 digits).

string

Cardholder name as it appears on the card. Optional but recommended.

string

A previously saved card token. Required if card is not provided. Tokens are created when saveCard: true is included in a prior charge request.

string

Customer email address. Used to send payment receipts.

string

A short description of the payment (e.g., "Order #1042"). Stored on the payment record and visible in your dashboard.

string

Customer’s IP address. Recommended — Axra Pay’s fraud scoring engine uses this signal to assess risk.

string

URL to redirect the customer to after they complete (or cancel) a 3DS challenge. Required if your cards may trigger 3DS.

object

Customer billing address. Improves authorization rates and is required by some card networks for address verification.

Show billingAddress properties

string

First name.

string

Last name.

string

Street address.

string

City.

string

State or province.

string

Postal or ZIP code.

string

ISO 3166-1 alpha-2 country code (e.g., "NG", "GH").

boolean

default:"false"

When true, Axra Pay tokenizes the card and returns a savedTokenId you can use for future charges without requiring the customer to re-enter card details.

object

Arbitrary key-value pairs (string keys, string or number values). Stored on the payment and returned in webhook events. Useful for attaching internal order IDs or customer references.

Responses

Immediate success — status: "succeeded"

string

required

Unique Axra Pay identifier for this payment.

string

required

"succeeded" — the charge was accepted by the card network.

number

required

Charged amount in major currency units, matching the request.

string

required

ISO 4217 currency code.

string

required

Axra transaction reference for this charge. Required when calling POST /business/payment/confirm-3ds.

string

required

ISO 8601 timestamp of when the charge was created.

A status: "succeeded" response means the charge was accepted, but the payment record remains in PENDING state until the payment.completed webhook fires. Do not fulfil orders based on the charge response alone — always wait for the webhook.

3DS required — status: "requires_action"

string

required

"requires_action" — the card issuer requires an additional authentication step before completing the charge.

object

required

Show requiresAction properties

string

Authentication type. One of "3ds_redirect", "3ds_challenge", or "fingerprint".

string

URL to redirect the customer’s browser to in order to complete the 3DS challenge. After the challenge, the customer is sent to your returnUrl.

Example

curl --request POST \
  --url https://api.useaxra.com/api/v1/business/payment/charge \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "amount": 49.99,
    "currency": "usd",
    "card": {
      "number": "4242424242424242",
      "expiryMonth": 12,
      "expiryYear": 2027,
      "cvv": "123",
      "holderName": "Amara Osei"
    },
    "email": "amara@example.com",
    "description": "Order #1042",
    "customerIp": "197.210.55.10",
    "returnUrl": "https://yourapp.com/payment/callback",
    "saveCard": false,
    "metadata": {
      "orderId": "1042",
      "customerId": "cust_abc123"
    }
  }'

const response = await fetch(
  'https://api.useaxra.com/api/v1/business/payment/charge',
  {
    method: 'POST',
    headers: {
      'x-api-key': process.env.AXRA_API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      amount: 49.99,
      currency: 'usd',
      card: {
        number: '4242424242424242',
        expiryMonth: 12,
        expiryYear: 2027,
        cvv: '123',
        holderName: 'Amara Osei',
      },
      email: 'amara@example.com',
      description: 'Order #1042',
      customerIp: '197.210.55.10',
      returnUrl: 'https://yourapp.com/payment/callback',
      saveCard: false,
      metadata: { orderId: '1042', customerId: 'cust_abc123' },
    }),
  }
);

const payment = await response.json();

if (payment.status === 'requires_action') {
  // Redirect the customer to complete 3DS
  redirect(payment.requiresAction.redirectUrl);
} else if (payment.status === 'succeeded') {
  // Wait for payment.completed webhook before fulfilling
  console.log('Charge accepted:', payment.paymentId);
}

Success response

{
  "paymentId": "pay_01HXYZ123456",
  "status": "succeeded",
  "amount": 49.99,
  "currency": "usd",
  "transactionId": "txn_9a3f21bc",
  "createdAt": "2026-04-14T10:23:45.000Z"
}

3DS required response

{
  "paymentId": "pay_01HXYZ789012",
  "status": "requires_action",
  "transactionId": "txn_7d8e42af",
  "requiresAction": {
    "type": "3ds_redirect",
    "redirectUrl": "https://3ds.useaxra.com/challenge?token=abc123"
  }
}

Confirm a 3DS challenge

POST /business/payment/confirm-3ds After a customer completes a 3DS challenge and is redirected back to your returnUrl, call this endpoint with the transactionId from the original charge response to finalize the payment.

Call this endpoint after the customer has completed the 3DS challenge in their browser. Calling it prematurely will result in a failed confirmation.

Request parameters

string

required

The transactionId returned in the original POST /business/payment/charge response when status was "requires_action".

Response fields

string

The Axra Pay payment identifier.

string

Final charge status: "succeeded" or "failed".

boolean

true if authentication and charge completed successfully.

string

Transaction reference, matching the value from the original charge.

Example

curl --request POST \
  --url https://api.useaxra.com/api/v1/business/payment/confirm-3ds \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "transactionId": "txn_7d8e42af"
  }'

const result = await fetch(
  'https://api.useaxra.com/api/v1/business/payment/confirm-3ds',
  {
    method: 'POST',
    headers: {
      'x-api-key': process.env.AXRA_API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ transactionId: 'txn_7d8e42af' }),
  }
);

const confirmation = await result.json();

if (confirmation.success) {
  // Await the payment.completed webhook to fulfil the order
  console.log('3DS confirmed:', confirmation.paymentId);
} else {
  // Authentication failed — prompt the customer to try a different card
  console.error('3DS failed for transaction:', confirmation.transactionId);
}

{
  "paymentId": "pay_01HXYZ789012",
  "status": "succeeded",
  "success": true,
  "transactionId": "txn_7d8e42af"
}

Get a payment

GET /business/payment/:paymentId Retrieve the full details of a single payment by its ID. Use this endpoint to check the current status of a payment, inspect fee breakdowns, or confirm settlement.

Path parameters

string

required

The unique Axra Pay payment ID (e.g., pay_01HXYZ123456).

Response fields

string

Unique payment identifier.

string

Your Axra Pay business ID.

number

Charged amount in major currency units.

string

ISO 4217 currency code.

string

Payment lifecycle status. "COMPLETED" means the payment has been confirmed and funds are allocated for settlement. Other possible values: "PENDING", "FAILED", "REFUNDED".

string

Payment method type (e.g., "card").

string

Axra transaction reference for the charge. Use when contacting support about a specific payment.

string

Settlement state: "PENDING", "SETTLED", or "FAILED".

string

ISO 8601 timestamp of when the funds were settled to your account. null if not yet settled.

object

All metadata key-value pairs submitted with the original charge, plus an Axra-generated feeBreakdown object showing processing fees.

string

ISO 8601 creation timestamp.

string

ISO 8601 timestamp of the last status change.

Example

curl --request GET \
  --url https://api.useaxra.com/api/v1/business/payment/pay_01HXYZ123456 \
  --header 'x-api-key: YOUR_API_KEY'

const response = await fetch(
  'https://api.useaxra.com/api/v1/business/payment/pay_01HXYZ123456',
  {
    headers: { 'x-api-key': process.env.AXRA_API_KEY },
  }
);

const payment = await response.json();
console.log(payment.status, payment.settlementStatus);

{
  "id": "pay_01HXYZ123456",
  "businessId": "biz_9f3a21c",
  "amount": 49.99,
  "currency": "usd",
  "status": "COMPLETED",
  "type": "card",
  "transactionId": "txn_9a3f21bc",
  "settlementStatus": "SETTLED",
  "settledAt": "2026-04-15T08:00:00.000Z",
  "metadata": {
    "orderId": "1042",
    "customerId": "cust_abc123",
    "feeBreakdown": {
      "processingFee": 1.74,
      "netAmount": 48.25,
      "currency": "usd"
    }
  },
  "createdAt": "2026-04-14T10:23:45.000Z",
  "updatedAt": "2026-04-14T10:24:01.000Z"
}

List payments

GET /business/payments Retrieve a paginated list of all payments for your business, ordered by creation time (most recent first).

Query parameters

number

default:"1"

Page number to retrieve. Starts at 1.

number

default:"20"

Number of payments per page. Maximum 100.

Response fields

array

Array of payment objects. Each object has the same structure as the Get a payment response.

object

Show pagination properties

number

Current page number.

number

Items per page.

number

Total number of payments across all pages.

number

Total number of pages at the current limit.

Example

curl --request GET \
  --url 'https://api.useaxra.com/api/v1/business/payments?page=1&limit=20' \
  --header 'x-api-key: YOUR_API_KEY'

const response = await fetch(
  'https://api.useaxra.com/api/v1/business/payments?page=1&limit=20',
  {
    headers: { 'x-api-key': process.env.AXRA_API_KEY },
  }
);

const { payments, pagination } = await response.json();
console.log(`Showing ${payments.length} of ${pagination.total} payments`);

{
  "payments": [
    {
      "id": "pay_01HXYZ123456",
      "amount": 49.99,
      "currency": "usd",
      "status": "COMPLETED",
      "transactionId": "txn_9a3f21bc",
      "createdAt": "2026-04-14T10:23:45.000Z"
    },
    {
      "id": "pay_01HWXY654321",
      "amount": 120.00,
      "currency": "ngn",
      "status": "PENDING",
      "transactionId": "txn_3c1b09da",
      "createdAt": "2026-04-13T18:11:02.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 348,
    "totalPages": 18
  }
}

Refund a payment

POST /business/payment/:paymentId/refund Issue a full refund for a completed payment. The refund is applied to the original card and the payment status is updated to "REFUNDED".

Refunds are only available within 180 days of the original payment. Refund requests on payments older than 180 days will return a 400 error. You can only refund payments with a status of "COMPLETED".

Path parameters

string

required

The ID of the payment to refund.

Response fields

string

The ID of the refunded payment.

string

"REFUNDED" on success.

string

Unique identifier for the refund record.

Example

curl --request POST \
  --url https://api.useaxra.com/api/v1/business/payment/pay_01HXYZ123456/refund \
  --header 'x-api-key: YOUR_API_KEY'

const response = await fetch(
  'https://api.useaxra.com/api/v1/business/payment/pay_01HXYZ123456/refund',
  {
    method: 'POST',
    headers: { 'x-api-key': process.env.AXRA_API_KEY },
  }
);

const refund = await response.json();
console.log('Refund ID:', refund.refundId);

{
  "paymentId": "pay_01HXYZ123456",
  "status": "REFUNDED",
  "refundId": "ref_88bc4210"
}

Error responses

Status	Reason
`400`	Payment is not in `COMPLETED` status, or is older than 180 days.
`404`	No payment found with the given `paymentId`.

Idempotency

Axra Pay automatically deduplicates charge requests to prevent accidental double charges. If two requests are made within the same one-minute window with the same combination of:

Business ID
Card last four digits (or savedTokenId)
amount
currency

…the second request returns the existing payment record rather than creating a new charge. No additional action is required on your end — idempotency is applied automatically.

If you need to charge the same card for the same amount multiple times in quick succession (e.g., split payments), wait at least 60 seconds between requests, or use a different card token.

Rate limiting

Context	Limit
API requests	Per-business limit — contact support@useaxra.com for your current threshold.
Checkout charge attempts	Max 5 attempts per session per 15-minute window.

When you exceed a rate limit, the API returns a 429 Too Many Requests response. Implement exponential backoff before retrying.

Payments

Treasury

Webhooks

SDKs

Checkout sessions

Card payments

Local payment methods

Charge a card (server-to-server)

Authentication

Request parameters

Responses

Example

Confirm a 3DS challenge

Request parameters

Response fields

Example

Get a payment

Path parameters

Response fields

Example

List payments

Query parameters

Response fields

Example

Refund a payment

Path parameters

Response fields

Example

Error responses

Idempotency

Rate limiting

Checkout sessions

Card payments

Local payment methods

​Charge a card (server-to-server)

​Authentication

​Request parameters

​Responses

​Example

​Confirm a 3DS challenge

​Request parameters

​Response fields

​Example

​Get a payment

​Path parameters

​Response fields

​Example

​List payments

​Query parameters

​Response fields

​Example

​Refund a payment

​Path parameters

​Response fields

​Example

​Error responses

​Idempotency

​Rate limiting

Charge a card (server-to-server)

Authentication

Request parameters

Responses

Example

Confirm a 3DS challenge

Request parameters

Response fields

Example

Get a payment

Path parameters

Response fields

Example

List payments

Query parameters

Response fields

Example

Refund a payment

Path parameters

Response fields

Example

Error responses

Idempotency

Rate limiting