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.

amount

number

required

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

currency

string

required

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

card

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

card.number

string

Full card number, digits only, no spaces.

card.expiryMonth

number

Expiry month as an integer from 1 to 12.

card.expiryYear

number

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

card.cvv

string

Card verification value (3 or 4 digits).

card.holderName

string

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

savedTokenId

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.

description

string

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

customerIp

string

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

returnUrl

string

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

billingAddress

object

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

Show billingAddress properties

billingAddress.firstName

string

First name.

billingAddress.lastName

string

Last name.

billingAddress.address

string

Street address.

billingAddress.city

string

City.

billingAddress.state

string

State or province.

billingAddress.zip

string

Postal or ZIP code.

billingAddress.country

string

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

saveCard

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.

metadata

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"

paymentId

string

required

Unique Axra Pay identifier for this payment.

status

string

required

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

amount

number

required

Charged amount in major currency units, matching the request.

currency

string

required

ISO 4217 currency code.

transactionId

string

required

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

createdAt

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"

status

string

required

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

requiresAction

object

required

Show requiresAction properties

type

string

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

redirectUrl

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"
    }
  }'

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

transactionId

string

required

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

Response fields

paymentId

string

The Axra Pay payment identifier.

status

string

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

success

boolean

true if authentication and charge completed successfully.

transactionId

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"
  }'

{
  "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

paymentId

string

required

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

Response fields

string

Unique payment identifier.

businessId

string

Your Axra Pay business ID.

amount

number

Charged amount in major currency units.

currency

string

ISO 4217 currency code.

status

string

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

type

string

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

transactionId

string

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

settlementStatus

string

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

settledAt

string

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

metadata

object

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

createdAt

string

ISO 8601 creation timestamp.

updatedAt

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'

{
  "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

page

number

default:"1"

Page number to retrieve. Starts at 1.

limit

number

default:"20"

Number of payments per page. Maximum 100.

Response fields

payments

array

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

pagination

object

Show pagination properties

page

number

Current page number.

limit

number

Items per page.

total

number

Total number of payments across all pages.

totalPages

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'

{
  "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

paymentId

string

required

The ID of the payment to refund.

Response fields

paymentId

string

The ID of the refunded payment.

status

string

"REFUNDED" on success.

refundId

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'

{
  "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

Payments

Treasury

Webhooks

SDKs

Documentation Index

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