# Authenticate with business API key and secret Source: https://docs.useaxra.com/api-reference/authentication/authenticate-with-business-api-key-and-secret /openapi.json post /api/v1/business/auth/token # Regenerate API key Source: https://docs.useaxra.com/api-reference/authentication/regenerate-api-key /openapi.json post /api/v1/business/regenerate-api-key # Returns authenticated partner id (public contract surface) Source: https://docs.useaxra.com/api-reference/authentication/returns-authenticated-partner-id-public-contract-surface /openapi.json get /api/v1/treasury/whoami # Self-onboard a SANDBOX developer partner (authenticated; requires completed identity verification). TEST keys only. Source: https://docs.useaxra.com/api-reference/authentication/self-onboard-a-sandbox-developer-partner-authenticated;-requires-completed-identity-verification-test-keys-only /openapi.json post /api/v1/treasury/signup # Check which corridors are usable right now Source: https://docs.useaxra.com/api-reference/corridor-status/check-which-corridors-are-usable-right-now /openapi.json get /api/v1/status/corridors Returns one row per country, currency, method and direction, saying whether you can collect or pay out over it at this moment. `status` reflects end-to-end usability through Axra, not just whether an upstream network is reachable — a corridor that is not enabled for your account reports `disabled` rather than `operational`, so you never retry into a wall. The answer is measured on a schedule and served from cache, so it is cheap to poll and never blocks on an upstream check. If a refresh has been missed the payload comes back with `stale: true` and the last rows we actually measured; each row carries its own `checkedAt`. A `503` means we have no measurement to show yet — retry shortly. # Find customer by email Source: https://docs.useaxra.com/api-reference/customers/find-customer-by-email /openapi.json get /api/v1/business/customers/email/{email} Finds a customer by the email address on their account and returns their customer id with aggregate totals. Returns 404 when no account carries that email, or when that account has never paid you. # List customers Source: https://docs.useaxra.com/api-reference/customers/list-customers /openapi.json get /api/v1/business/customers Lists the customers you have collected from, derived from your own payment history, with the payment count and total collected for each. Paginated with `page` and `limit` (1 and 20 by default). # Remove a payment method Source: https://docs.useaxra.com/api-reference/customers/remove-a-payment-method /openapi.json delete /api/v1/business/customers/{customerId}/payment-methods/{paymentMethodId} Detaches a saved card from a customer so it can no longer be charged. A payment method that does not belong to that customer is a 400. # Retrieve a customer Source: https://docs.useaxra.com/api-reference/customers/retrieve-a-customer /openapi.json get /api/v1/business/customers/{customerId} Retrieves one customer with their saved cards and their 20 most recent payments to you. The customer must have paid you at least once and must have a stored customer profile: a payer who has only ever paid without one returns 404. # Set default payment method Source: https://docs.useaxra.com/api-reference/customers/set-default-payment-method /openapi.json put /api/v1/business/customers/{customerId}/default-payment-method Marks one of the saved cards on a customer as the default for future charges. Send `paymentMethodId` in the body; a payment method that does not belong to that customer is a 400. # Accept dispute loss (merchant opts not to contest) Source: https://docs.useaxra.com/api-reference/disputes/accept-dispute-loss-merchant-opts-not-to-contest /openapi.json post /api/v1/business/disputes/{paymentId}/accept-loss Concedes a dispute without contesting it, for when the evidence would not win or the amount is not worth defending. The payment must carry a dispute. # Get dispute count summary (open / won / lost) Source: https://docs.useaxra.com/api-reference/disputes/get-dispute-count-summary-open-won-lost /openapi.json get /api/v1/business/disputes/stats Returns the open, won and lost dispute counts for your account. Cheaper than listing disputes when all you need is the headline numbers. # Get dispute detail for a payment Source: https://docs.useaxra.com/api-reference/disputes/get-dispute-detail-for-a-payment /openapi.json get /api/v1/business/disputes/{paymentId} Retrieves the dispute on one of your payments, keyed on the PAYMENT id rather than on a dispute id. Returns the payment, the dispute with its reason and evidence deadline, the evidence bundle assembled for it (null if there is none yet) and any files you uploaded. A payment carrying no dispute is a 404. # Get merchant dispute defence policy Source: https://docs.useaxra.com/api-reference/disputes/get-merchant-dispute-defence-policy /openapi.json get /api/v1/business/disputes/policy/current Returns the defence policy applied to your disputes: whether evidence is submitted automatically, the minimum win score required before it is, the amount and currency below which a loss is accepted without contest, and your default evidence text. A default policy is created on first read. # List disputes for the authenticated merchant Source: https://docs.useaxra.com/api-reference/disputes/list-disputes-for-the-authenticated-merchant /openapi.json get /api/v1/business/disputes Lists disputes raised against your payments. `status` selects one of `open`, `won`, `lost` or `all` and DEFAULTS TO `open`, so pass `all` to see everything; narrow further with `currency`, `from` and `to`, and page with `page` and `limit`. Every response also carries the open, won and lost counts for the whole set, not just for the page. # Update merchant dispute defence policy Source: https://docs.useaxra.com/api-reference/disputes/update-merchant-dispute-defence-policy /openapi.json put /api/v1/business/disputes/policy/current Updates the defence policy; only the fields you send change. Use it to turn automatic submission on or off, move the win-score bar, or set the amount below which contesting a dispute is not worth it. # Upload merchant dispute evidence file Source: https://docs.useaxra.com/api-reference/disputes/upload-merchant-dispute-evidence-file /openapi.json post /api/v1/business/disputes/{paymentId}/evidence/upload Uploads a supporting file for a dispute as multipart form data under the field name `file`, up to 5 MB. Files accumulate: each upload is added to the ones already on the dispute rather than replacing them. The payment must carry a dispute, or the request is a 400. # Create an ephemeral Elements session (publishable key + amount + currency) Source: https://docs.useaxra.com/api-reference/elements/create-an-ephemeral-elements-session-publishable-key-+-amount-+-currency /openapi.json post /api/v1/elements/session Opens a short-lived tokenisation session for a browser payment form. It authenticates with your publishable key rather than a secret, so it is safe to call from the page: the key is resolved to an active account and a session id is returned with its lifetime in seconds. Rate-limited per publishable key. # Tokenize card data for a session (iframe / allowed origins only) Source: https://docs.useaxra.com/api-reference/elements/tokenize-card-data-for-a-session-iframe-allowed-origins-only /openapi.json post /api/v1/elements/tokenize Exchanges card details for a single-use token inside an open session, so the card number never reaches your own server. Callable only from an allow-listed origin — the browser `Origin` header is checked and a missing or unrecognised one is refused — and the session must still be live. Returns the token id with the card brand and last four digits. # Create fraud rule Source: https://docs.useaxra.com/api-reference/fraud/create-fraud-rule /openapi.json post /api/v1/business/fraud/rules # Delete fraud rule Source: https://docs.useaxra.com/api-reference/fraud/delete-fraud-rule /openapi.json delete /api/v1/business/fraud/rules/{id} # Evaluate fraud rules against sample payload Source: https://docs.useaxra.com/api-reference/fraud/evaluate-fraud-rules-against-sample-payload /openapi.json post /api/v1/business/fraud/rules/test # Get fraud rule Source: https://docs.useaxra.com/api-reference/fraud/get-fraud-rule /openapi.json get /api/v1/business/fraud/rules/{id} # List blocked entities (merchant-scoped + platform-wide) Source: https://docs.useaxra.com/api-reference/fraud/list-blocked-entities-merchant-scoped-+-platform-wide /openapi.json get /api/v1/business/fraud/blocked # List fraud rules Source: https://docs.useaxra.com/api-reference/fraud/list-fraud-rules /openapi.json get /api/v1/business/fraud/rules # Unblock a blocked entity (merchant-scoped only) Source: https://docs.useaxra.com/api-reference/fraud/unblock-a-blocked-entity-merchant-scoped-only /openapi.json delete /api/v1/business/fraud/blocked/{id} # Update fraud rule Source: https://docs.useaxra.com/api-reference/fraud/update-fraud-rule /openapi.json patch /api/v1/business/fraud/rules/{id} # Create a local-rails collection (S2S) Source: https://docs.useaxra.com/api-reference/local-rails/create-a-local-rails-collection-s2s /openapi.json post /api/v1/business/collections Starts a local bank transfer or mobile money collection and returns the instructions the customer follows to pay. The currency must be enabled on your account and the corridor priced, or the request is refused as unsupported; a `momo` channel additionally requires `customer.phone`. Send an `idempotencyKey` to make retries safe — a repeat returns the collection already created rather than a second one. The window defaults to 60 minutes for mobile money and 30 minutes for bank and EFT, overridable with `expiresInSeconds`. # Force-refresh a local-rails collection from the upstream provider Source: https://docs.useaxra.com/api-reference/local-rails/force-refresh-a-local-rails-collection-from-the-upstream-provider /openapi.json get /api/v1/business/collections/{id}/refresh Pulls the current state of a collection from upstream and returns the refreshed record, rather than serving the state last stored. Use it to reconcile when a webhook was missed; a collection already in a terminal state is returned unchanged with no upstream call. # List available local-rail channels Source: https://docs.useaxra.com/api-reference/local-rails/list-available-local-rail-channels /openapi.json get /api/v1/business/local-rails/channels Lists the local-rail channels open to a `country`, `currency` and `amount`, all three required. Channels that cannot take that amount are returned separately with a `BELOW_MIN` or `ABOVE_MAX` reason alongside the corridor bounds, so a below-minimum amount reveals the floor instead of coming back empty. Discovery only: it checks the channel catalogue and your currency configuration but not pricing, so a channel listed here can still be refused when you create the collection. # List local-rails collections Source: https://docs.useaxra.com/api-reference/local-rails/list-local-rails-collections /openapi.json get /api/v1/business/collections Lists your local-rail collections newest-first, cursor-paginated: pass `limit` (1 to 100, 25 by default) and `starting_after` set to the id of the last collection on the previous page. `hasMore` says whether another page exists. # Retrieve a local-rails collection Source: https://docs.useaxra.com/api-reference/local-rails/retrieve-a-local-rails-collection /openapi.json get /api/v1/business/collections/{id} Retrieves one collection you own by id, with its current status and payment instructions. # Create a payment link Source: https://docs.useaxra.com/api-reference/payment-links/create-a-payment-link /openapi.json post /api/v1/business/links Creates a reusable hosted payment page at a slug you choose. The slug is global and must be 3 to 30 characters of lowercase letters, digits and hyphens, not starting or ending with a hyphen; a slug already taken is a 409. `amountType` decides what the payer may pay: `fixed` requires `fixedAmount`, `preset` requires `presetAmounts`, and the default `flexible` lets the payer name an amount within `minAmount` and `maxAmount`. # Deactivate a payment link Source: https://docs.useaxra.com/api-reference/payment-links/deactivate-a-payment-link /openapi.json delete /api/v1/business/links/{id} Deactivates a payment link. This is a soft delete: the link and its payment history are kept, but the hosted page stops resolving and returns 404 to payers. Reversible by sending `isActive` true to `PATCH /business/links/{id}`. # List payment links Source: https://docs.useaxra.com/api-reference/payment-links/list-payment-links /openapi.json get /api/v1/business/links Lists every payment link on the account, newest first, including deactivated ones (`isActive` false). Not paginated. # Update a payment link Source: https://docs.useaxra.com/api-reference/payment-links/update-a-payment-link /openapi.json patch /api/v1/business/links/{id} Updates presentation and amount configuration in place; only the fields you send change. The slug is fixed at creation and cannot be changed here. Setting `isActive` to true reactivates a deactivated link. # Charge a card directly (server-to-server) Source: https://docs.useaxra.com/api-reference/payments/charge-a-card-directly-server-to-server /openapi.json post /api/v1/business/payment/charge Charges a card server-to-server, with no redirect to a hosted page. Name the card in EXACTLY ONE of `card`, `savedTokenId`, `mpgsSessionId` or `walletToken`: the schema cannot express that constraint, and sending none or more than one is a 400. `customerIp` must be the IP address of the end customer rather than of your server, because it feeds velocity checks, and the charge is refused without it. Server-to-server charging is entitled per account, so an account that does not hold it gets a 403 pointing at checkout sessions and payment links instead. Charges are idempotent on their own parameters: replaying an identical charge returns the original payment rather than charging twice. A response carrying `requiresAction` means 3-D Secure is required — send the payer to `requiresAction.redirectUrl`, then call `POST /business/payment/confirm-3ds`. Unknown body fields are rejected with a 400 rather than ignored, and numeric strings are coerced to numbers. # Confirm 3D Secure authentication Source: https://docs.useaxra.com/api-reference/payments/confirm-3d-secure-authentication /openapi.json post /api/v1/business/payment/confirm-3ds Completes a charge that came back with `requiresAction`, once the payer has finished the 3-D Secure challenge. Key it on the `transactionId` the charge returned, not on the payment id. The response carries the verdict from the card platform, but only a failure is written back to the payment: a successful authentication leaves the payment pending until the settlement webhook arrives, so treat your webhook endpoint as the authority on a completed payment. # Create a checkout session Source: https://docs.useaxra.com/api-reference/payments/create-a-checkout-session /openapi.json post /api/v1/business/payment/session Creates a hosted checkout session for one amount and returns `checkoutUrl` to send the payer to, valid for `expiresIn` seconds (one hour by default). If you include `card` or `savedTokenId` in the body the session is charged immediately instead and no `checkoutUrl` comes back — the response then reports `processing`, `3ds_required` with a `threeDsUrl`, or `failed`. # Create a payment link Source: https://docs.useaxra.com/api-reference/payments/create-a-payment-link /openapi.json post /api/v1/business/payment Creates a one-off hosted payment page for a fixed amount and returns its URL together with the payment id to track it by; a `payment.created` webhook fires immediately. Reach for it when you want one hosted checkout without configuring a reusable link — `POST /business/links` is the reusable, brandable equivalent. # Get payment details Source: https://docs.useaxra.com/api-reference/payments/get-payment-details /openapi.json get /api/v1/business/payment/{paymentId} Retrieves one payment by its Axra payment id, with card, customer, failure and authorisation detail normalised so the shape does not change with the rail that collected it. The projection is an allow-list: upstream identifiers and our own costs are never returned. # List merchant pricing per corridor (aggregated total fee, no provider breakdown) Source: https://docs.useaxra.com/api-reference/payments/list-merchant-pricing-per-corridor-aggregated-total-fee-no-provider-breakdown /openapi.json get /api/v1/business/psp-pricing The fee schedule in effect for your own account, aggregated to one total per corridor: a combined percentage in basis points, a fixed component and a fee floor, all in minor units of `feeCurrency`, and each row bounded by the amount band it applies to. Covers money-IN (collection) pricing only — payout fees come back on a payout quote. # List payments Source: https://docs.useaxra.com/api-reference/payments/list-payments /openapi.json get /api/v1/business/payments Lists the payments on your account newest-first across every rail, paginated with `page` and `limit` (1 and 20 by default). Narrow it with `status` and `search`. Same allow-listed projection as retrieving a single payment. # Refund a payment Source: https://docs.useaxra.com/api-reference/payments/refund-a-payment /openapi.json post /api/v1/business/payment/{paymentId}/refund Refunds a payment in full — there is no partial-refund parameter. The payment must be COMPLETED and no more than 180 days old; anything else is a 400. On success the payment moves to REFUNDED and a `payment.refunded` webhook fires carrying the refund id. If the refund is declined the response is a 422, and if its outcome cannot be confirmed yet it is a 503. In both cases the payment stays COMPLETED and no `payment.refunded` webhook is sent. Do not resubmit after a 503: our team checks the refund and follows up. # Cancel a draft or queued batch Source: https://docs.useaxra.com/api-reference/payout-batches/cancel-a-draft-or-queued-batch /openapi.json post /api/v1/business/payouts/batches/{id}/cancel Allowed only while the batch is DRAFT or QUEUED and no item has been dispatched. # Create a draft batch payout (payroll) + preview Source: https://docs.useaxra.com/api-reference/payout-batches/create-a-draft-batch-payout-payroll-+-preview /openapi.json post /api/v1/business/payouts/batches Validates up to BATCH_MAX_ITEMS line items, resolves each recipient (saved or inline — inline ones are sanctions-screened and saved), server-side quotes every item, and persists a DRAFT batch with child payouts in CREATED (not yet dispatched). Returns the per-item fee breakdown, summed totals, and an affordability flag. Idempotent on (business, idempotencyKey). # Get a batch payout with its line items Source: https://docs.useaxra.com/api-reference/payout-batches/get-a-batch-payout-with-its-line-items /openapi.json get /api/v1/business/payouts/batches/{id} Retrieves one batch with every line item: the per-item amounts, fees and payout status, plus the rows that failed to resolve at creation with the reason each failed, ordered by their index in the list you submitted. # List batch payouts for the active business Source: https://docs.useaxra.com/api-reference/payout-batches/list-batch-payouts-for-the-active-business /openapi.json get /api/v1/business/payouts/batches Lists batch payouts for the active business, newest first. Filter with `status` and page with `skip` and `take` (0 and 20 by default). Line items are not included — fetch a single batch for those. # Submit a draft batch for processing Source: https://docs.useaxra.com/api-reference/payout-batches/submit-a-draft-batch-for-processing /openapi.json post /api/v1/business/payouts/batches/{id}/submit Re-checks affordability against the live wallet balance, gates 2FA when the summed USD-equivalent >= $10k (dashboard path; api-key exempt), and transitions the batch DRAFT → QUEUED for the fan-out processor. # Archive a payout recipient (soft delete) Source: https://docs.useaxra.com/api-reference/payout-recipients/archive-a-payout-recipient-soft-delete /openapi.json delete /api/v1/business/payouts/recipients/{id} Archives a recipient. This is a soft delete: it drops out of the default listing and can no longer be fetched or paid, while payouts already sent to it keep their history. Idempotent — archiving an already archived recipient still returns 204. # Create a payout recipient Source: https://docs.useaxra.com/api-reference/payout-recipients/create-a-payout-recipient /openapi.json post /api/v1/business/payouts/recipients Creates a saved recipient you can pay by `recipientId`. Idempotent on the destination: sending the same rail + account details returns the existing recipient instead of a duplicate. Dashboard (JWT) requests are sanctions-screened on create and a match is refused with 403. Server-to-server requests authenticated with `x-api-key` are not screened by Axra — the merchant is the obligated party under the merchant agreement — and are never refused on a screening result. # Get a payout recipient by id Source: https://docs.useaxra.com/api-reference/payout-recipients/get-a-payout-recipient-by-id /openapi.json get /api/v1/business/payouts/recipients/{id} Retrieves one saved recipient by id, with the destination details masked. Archived recipients are not returned — an archived id is a 404. # List payout recipients for the active business Source: https://docs.useaxra.com/api-reference/payout-recipients/list-payout-recipients-for-the-active-business /openapi.json get /api/v1/business/payouts/recipients Lists saved payout recipients for the active business, newest first. Archived recipients are hidden unless you pass `includeArchived`; filter by `rail` and page with `page` and `limit` (1 and 20 by default, `limit` capped at 100). Destination details come back masked. # Update recipient label Source: https://docs.useaxra.com/api-reference/payout-recipients/update-recipient-label /openapi.json patch /api/v1/business/payouts/recipients/{id} Renames a recipient. The label is the only mutable field: destination details are frozen at creation, so correcting an account number means creating a new recipient. An archived recipient cannot be updated. # Cancel a scheduled payout Source: https://docs.useaxra.com/api-reference/payout-schedules/cancel-a-scheduled-payout /openapi.json delete /api/v1/business/payouts/schedules/{id} Sets status to CANCELLED (terminal). Idempotent on an already-cancelled schedule. # Create + authorize a scheduled payout Source: https://docs.useaxra.com/api-reference/payout-schedules/create-+-authorize-a-scheduled-payout /openapi.json post /api/v1/business/payouts/schedules Validates the cadence (MONTHLY day-of-month 1–28, optional) and the per-run USD cap (defaults to $50k, rejected above the $250k admin ceiling), sanctions-screens every recipient in the payload, verifies the transaction PIN on the dashboard path (api-key exempt), stamps authorizedAt/By, and computes the first nextRunAt. Unattended runs execute without re-authorization, bounded by maxRunAmountUsd. # Edit (re-authorize) a scheduled payout Source: https://docs.useaxra.com/api-reference/payout-schedules/edit-re-authorize-a-scheduled-payout /openapi.json put /api/v1/business/payouts/schedules/{id} Replaces the recipient list / amounts (new hire, resignation, raise) WITHOUT recreating the schedule — the cadence, day-of-month and nextRunAt timing are preserved. Every edit re-authorizes: it re-validates the payload + per-run cap, sanctions-screens every recipient in the new payload, re-verifies the transaction PIN on the dashboard path (api-key exempt), and re-stamps authorizedAt/By. Only ACTIVE/PAUSED schedules are editable; changing the cadence/timing still requires recreating the schedule. # Get a scheduled payout Source: https://docs.useaxra.com/api-reference/payout-schedules/get-a-scheduled-payout /openapi.json get /api/v1/business/payouts/schedules/{id} Returns the schedule plus a MASKED list of its recipients (`items[]`): label, rail, corridor (country · currency), and the configured per-run amount only. No account numbers / IBAN / phone and no partner names are exposed. # List scheduled payouts for the active business Source: https://docs.useaxra.com/api-reference/payout-schedules/list-scheduled-payouts-for-the-active-business /openapi.json get /api/v1/business/payouts/schedules Lists scheduled payouts for the active business, newest first. Filter with `status` and page with `skip` and `take` (0 and 20 by default). # Pause / resume / rename a scheduled payout Source: https://docs.useaxra.com/api-reference/payout-schedules/pause-resume-rename-a-scheduled-payout /openapi.json patch /api/v1/business/payouts/schedules/{id} Only the status (ACTIVE↔PAUSED) and name are editable here (no PIN). Changing the payload or per-run amount requires re-authorization (PIN + screening) — use PUT /schedules/:id. # Cancel a CREATED payout Source: https://docs.useaxra.com/api-reference/payouts/cancel-a-created-payout /openapi.json post /api/v1/business/payouts/{id}/cancel Cancels a payout that has not been dispatched yet. Only a payout still in CREATED can be cancelled; anything further along is a 409. The amount the attempt debited is reversed back to your balance. # Get a cross-currency payout quote (60s lock) Source: https://docs.useaxra.com/api-reference/payouts/get-a-cross-currency-payout-quote-60s-lock /openapi.json post /api/v1/business/payouts/quote Returns a signed quote token valid for 60 seconds. Pass the token to POST /v1/business/payouts within the window to lock the rate. # Get a single business payout Source: https://docs.useaxra.com/api-reference/payouts/get-a-single-business-payout /openapi.json get /api/v1/business/payouts/{id} Retrieves one payout by id, scoped to the active business — a payout belonging to another business is a 404. Use it to follow a payout to its terminal state. # Initiate a business payout Source: https://docs.useaxra.com/api-reference/payouts/initiate-a-business-payout /openapi.json post /api/v1/business/payouts Confirms a payout against a signed `quoteToken` (LOCAL_BANK / LOCAL_MOMO). Name the destination in exactly one of three ways: `recipientId` for a recipient saved via POST /v1/business/payouts/recipients; inline `recipient` to send the details on the payout itself; or, for requests authenticated with `x-api-key`, inline `destination`. The quote is scoped to corridor, amount and business — never to a recipient — so one token confirms any of the three. Screening differs by channel: dashboard (JWT) payouts are sanctions-screened and a saved recipient carrying a match is refused; `x-api-key` payouts are not screened by Axra (the merchant is the obligated party under the merchant agreement) and an inline recipient/destination is paid ad hoc rather than saved, so the payout returns recipientId null. Server-to-server payouts are also exempt from the interactive 2FA gate — the controls are the secret key and the per-corridor velocity caps. # List payouts for the active business Source: https://docs.useaxra.com/api-reference/payouts/list-payouts-for-the-active-business /openapi.json get /api/v1/business/payouts Lists payouts for the active business, newest first. Filter with `status` and `rail`, and page with `skip` and `take` (0 and 20 by default, `take` capped at 100). The response carries `total` alongside the page. # List supported banks / mobile money networks for a corridor Source: https://docs.useaxra.com/api-reference/payouts/list-supported-banks-mobile-money-networks-for-a-corridor /openapi.json get /api/v1/business/payouts/networks Returns the live upstream catalog filtered to status=active for the given country and rail. Pass the returned `id` back as the recipient `bankCode` (LOCAL_BANK) or `networkId` (LOCAL_MOMO). For Nigerian banks (`country=NG`, `rail=LOCAL_BANK`) the list is the NIBSS bank list and `id` = `code` = the 6-digit NIBSS bank code. # Resolve a beneficiary name from a bank account number Source: https://docs.useaxra.com/api-reference/payouts/resolve-a-beneficiary-name-from-a-bank-account-number /openapi.json post /api/v1/business/payouts/resolve-account Provider-neutral account-name lookup (NIP name enquiry) for a Nigerian bank account. Returns the resolved holder name for the given (accountNumber, networkId), where `networkId` is the 6-digit NIBSS bank code from GET /business/payouts/networks. # Create a treasury end-user Source: https://docs.useaxra.com/api-reference/treasury-—-end-users/create-a-treasury-end-user /openapi.json post /api/v1/treasury/users # Get a treasury end-user by id Source: https://docs.useaxra.com/api-reference/treasury-—-end-users/get-a-treasury-end-user-by-id /openapi.json get /api/v1/treasury/users/{id} # List treasury end-users Source: https://docs.useaxra.com/api-reference/treasury-—-end-users/list-treasury-end-users /openapi.json get /api/v1/treasury/users # Soft-delete a treasury end-user (status CLOSED) Source: https://docs.useaxra.com/api-reference/treasury-—-end-users/soft-delete-a-treasury-end-user-status-closed /openapi.json delete /api/v1/treasury/users/{id} # Update a treasury end-user Source: https://docs.useaxra.com/api-reference/treasury-—-end-users/update-a-treasury-end-user /openapi.json patch /api/v1/treasury/users/{id} # Get current KYC status for an end-user Source: https://docs.useaxra.com/api-reference/treasury-—-kyc/get-current-kyc-status-for-an-end-user /openapi.json get /api/v1/treasury/users/{id}/kyc # Initiate KYC verification for an end-user Source: https://docs.useaxra.com/api-reference/treasury-—-kyc/initiate-kyc-verification-for-an-end-user /openapi.json post /api/v1/treasury/users/{id}/kyc # Sandbox-only: manually approve pending KYC for an end-user Source: https://docs.useaxra.com/api-reference/treasury-—-kyc/sandbox-only:-manually-approve-pending-kyc-for-an-end-user /openapi.json post /api/v1/treasury/users/{id}/kyc/sandbox-approve # Sandbox-only: manually reject pending KYC for an end-user Source: https://docs.useaxra.com/api-reference/treasury-—-kyc/sandbox-only:-manually-reject-pending-kyc-for-an-end-user /openapi.json post /api/v1/treasury/users/{id}/kyc/sandbox-reject # Cancel a payout if it is still PENDING Source: https://docs.useaxra.com/api-reference/treasury-—-payouts/cancel-a-payout-if-it-is-still-pending /openapi.json post /api/v1/treasury/payouts/{id}/cancel # Get payout by id Source: https://docs.useaxra.com/api-reference/treasury-—-payouts/get-payout-by-id /openapi.json get /api/v1/treasury/payouts/{id} # Initiate a payout from an end-user wallet Source: https://docs.useaxra.com/api-reference/treasury-—-payouts/initiate-a-payout-from-an-end-user-wallet /openapi.json post /api/v1/treasury/payouts # List payouts for the authenticated partner Source: https://docs.useaxra.com/api-reference/treasury-—-payouts/list-payouts-for-the-authenticated-partner /openapi.json get /api/v1/treasury/payouts # Deposit instructions (fiat VA and/or crypto liquidation address) Source: https://docs.useaxra.com/api-reference/treasury-—-wallets/deposit-instructions-fiat-va-andor-crypto-liquidation-address /openapi.json get /api/v1/treasury/users/{id}/wallets/{walletId}/deposit_instructions # Get wallet balance from ledger Source: https://docs.useaxra.com/api-reference/treasury-—-wallets/get-wallet-balance-from-ledger /openapi.json get /api/v1/treasury/users/{id}/wallets/{walletId}/balance # Get wallet detail Source: https://docs.useaxra.com/api-reference/treasury-—-wallets/get-wallet-detail /openapi.json get /api/v1/treasury/users/{id}/wallets/{walletId} # List an end-user's wallets Source: https://docs.useaxra.com/api-reference/treasury-—-wallets/list-an-end-users-wallets /openapi.json get /api/v1/treasury/users/{id}/wallets # Partner ledger entries for this wallet currency (paginated) Source: https://docs.useaxra.com/api-reference/treasury-—-wallets/partner-ledger-entries-for-this-wallet-currency-paginated /openapi.json get /api/v1/treasury/users/{id}/wallets/{walletId}/transactions # Provision a wallet for an end-user (currency-scoped) Source: https://docs.useaxra.com/api-reference/treasury-—-wallets/provision-a-wallet-for-an-end-user-currency-scoped /openapi.json post /api/v1/treasury/users/{id}/wallets # Sandbox-only: credit a wallet for integration testing Source: https://docs.useaxra.com/api-reference/treasury-—-wallets/sandbox-only:-credit-a-wallet-for-integration-testing /openapi.json post /api/v1/treasury/users/{id}/wallets/{walletId}/sandbox-credit # Create a treasury webhook endpoint (signing secret returned once) Source: https://docs.useaxra.com/api-reference/webhooks/create-a-treasury-webhook-endpoint-signing-secret-returned-once /openapi.json post /api/v1/treasury/webhook-endpoints # Create a webhook endpoint (returns signing secret once) Source: https://docs.useaxra.com/api-reference/webhooks/create-a-webhook-endpoint-returns-signing-secret-once /openapi.json post /api/v1/webhook-endpoints # Delete a treasury webhook endpoint Source: https://docs.useaxra.com/api-reference/webhooks/delete-a-treasury-webhook-endpoint /openapi.json delete /api/v1/treasury/webhook-endpoints/{id} # Delete a webhook endpoint Source: https://docs.useaxra.com/api-reference/webhooks/delete-a-webhook-endpoint /openapi.json delete /api/v1/webhook-endpoints/{id} # Get a treasury webhook endpoint Source: https://docs.useaxra.com/api-reference/webhooks/get-a-treasury-webhook-endpoint /openapi.json get /api/v1/treasury/webhook-endpoints/{id} # Get a webhook endpoint Source: https://docs.useaxra.com/api-reference/webhooks/get-a-webhook-endpoint /openapi.json get /api/v1/webhook-endpoints/{id} # List deliveries for a treasury webhook endpoint Source: https://docs.useaxra.com/api-reference/webhooks/list-deliveries-for-a-treasury-webhook-endpoint /openapi.json get /api/v1/treasury/webhook-endpoints/{id}/deliveries # List deliveries for a webhook endpoint Source: https://docs.useaxra.com/api-reference/webhooks/list-deliveries-for-a-webhook-endpoint /openapi.json get /api/v1/webhook-endpoints/{id}/deliveries # List treasury webhook endpoints for the authenticated partner Source: https://docs.useaxra.com/api-reference/webhooks/list-treasury-webhook-endpoints-for-the-authenticated-partner /openapi.json get /api/v1/treasury/webhook-endpoints # List webhook endpoints for the business (API key) Source: https://docs.useaxra.com/api-reference/webhooks/list-webhook-endpoints-for-the-business-api-key /openapi.json get /api/v1/webhook-endpoints # Replay a webhook delivery (queues a new delivery) Source: https://docs.useaxra.com/api-reference/webhooks/replay-a-webhook-delivery-queues-a-new-delivery /openapi.json post /api/v1/webhook-endpoints/replay-delivery # Replay a webhook delivery (queues a new delivery) Source: https://docs.useaxra.com/api-reference/webhooks/replay-a-webhook-delivery-queues-a-new-delivery-1 /openapi.json post /api/v1/treasury/webhook-endpoints/replay-delivery # Rotate signing secret (returned once) Source: https://docs.useaxra.com/api-reference/webhooks/rotate-signing-secret-returned-once /openapi.json post /api/v1/webhook-endpoints/{id}/rotate-signing-secret # Rotate signing secret (returned once) Source: https://docs.useaxra.com/api-reference/webhooks/rotate-signing-secret-returned-once-1 /openapi.json post /api/v1/treasury/webhook-endpoints/{id}/rotate-signing-secret # Update a treasury webhook endpoint Source: https://docs.useaxra.com/api-reference/webhooks/update-a-treasury-webhook-endpoint /openapi.json patch /api/v1/treasury/webhook-endpoints/{id} # Update a webhook endpoint Source: https://docs.useaxra.com/api-reference/webhooks/update-a-webhook-endpoint /openapi.json patch /api/v1/webhook-endpoints/{id} # Authentication Source: https://docs.useaxra.com/authentication Pass your API key in the x-api-key header or exchange it for a short-lived JWT token. Learn both authentication methods and how to obtain your credentials. Every request to the Axra Pay API must be authenticated. Axra supports two methods: passing your API key directly in a request header, or exchanging your key and secret for a short-lived JWT token. Both methods work for all endpoints — choose the one that fits your architecture. ## Method 1: API key header The simplest way to authenticate is to include your API key in the `x-api-key` header on every request. This approach works well for server-side integrations where your API key is stored securely in an environment variable. ```bash theme={null} x-api-key: bk_live_abc123... ``` **Example request:** ```bash theme={null} curl -X POST https://api.useaxra.com/api/v1/business/checkout/session \ -H "x-api-key: bk_live_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "amount": 100.00, "currency": "USD", "customerEmail": "customer@example.com", "successUrl": "https://yoursite.com/success" }' ``` > [!NOTE] > > Checkout session `successUrl` is unchanged. For server-to-server card charges, pass `returnUrl` on `POST /business/payment/charge`. After 3DS the payer returns via Axra's page; we append `3ds=complete|failed` and `paymentId`. That URL is never shared with the card processor. > [!WARNING] > > Never expose your API key in client-side code, public repositories, or frontend JavaScript. Always make Axra Pay API calls from your server. *** ## Method 2: JWT token exchange For integrations that prefer short-lived credentials, you can exchange your `apiKey` and `apiSecret` for a JWT bearer token. The token expires after one hour and must be refreshed before it does. > [!NOTE] > > Your `webhookSecret` doubles as your `apiSecret` for token authentication. They are the same credential. ### Step 1: Request a token Send a `POST` request to `/business/auth/token` with your `apiKey` and `apiSecret` in the request body. ```bash cURL theme={null} curl -X POST https://api.useaxra.com/api/v1/business/auth/token \ -H "Content-Type: application/json" \ -d '{ "apiKey": "bk_live_abc123...", "apiSecret": "bs_live_xyz789..." }' ``` ```javascript Node.js theme={null} const response = await fetch( 'https://api.useaxra.com/api/v1/business/auth/token', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ apiKey: 'bk_live_abc123...', apiSecret: 'bs_live_xyz789...', }), } ); const { accessToken, expiresIn } = await response.json(); ``` **Request body parameters:** **apiKey** `string` *required* Your business API key. Starts with `bk_live_` for production or `bk_test_` for sandbox. **apiSecret** `string` *required* Your API secret. This is the same value as your `webhookSecret`. ### Step 2: Read the response A successful request returns the following fields: ```json theme={null} { "accessToken": "eyJhbGciOiJIUzI1NiIs...", "tokenType": "Bearer", "expiresIn": 3600, "businessId": "biz_01H...", "businessName": "Acme Corp" } ``` **accessToken** `string` *required* The JWT token to include in subsequent requests. **tokenType** `string` *required* Always `"Bearer"`. Use this as the prefix in your `Authorization` header. **expiresIn** `number` *required* Token lifetime in seconds. Always `3600` (one hour). **businessId** `string` The unique identifier for your business profile. **businessName** `string` Your registered business name. ### Step 3: Use the token Include the `accessToken` in the `Authorization` header of every subsequent request: ```bash theme={null} Authorization: Bearer eyJhbGciOiJIUzI1NiIs... ``` **Example authenticated request:** ```bash theme={null} curl -X GET https://api.useaxra.com/api/v1/business/payments \ -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." ``` > [!TIP] > > Refresh your token before it expires by calling `POST /business/auth/token` again with the same credentials. Build a refresh mechanism into your application rather than handling 401 errors reactively. ### Token error responses | HTTP status | Meaning | | - | - | | `401 Unauthorized` | The `apiKey` or `apiSecret` is invalid. | | `400 Bad Request` | The request body is missing `apiKey` or `apiSecret`. | *** ## Getting your credentials **1. Create an account** [Register at the Axra dashboard](https://app.useaxra.com/register) to create a business profile and generate your API credentials. **2. Copy your credentials immediately** Your `apiKey` (format: `bk_live_...`) and `webhookSecret` are shown **only once** when your account is created. Copy both values to a secure password manager or secrets vault before leaving the page. **3. Store credentials securely** Never hard-code credentials in your source code. Store them as environment variables or in a secrets management service such as AWS Secrets Manager, HashiCorp Vault, or your hosting provider's secret store. **4. Regenerate a lost API key** If you lose your API key, call `POST /business/regenerate-api-key` to issue a new one. Your previous key is immediately invalidated — update any running services before regenerating. ```bash theme={null} curl -X POST https://api.useaxra.com/api/v1/business/regenerate-api-key \ -H "x-api-key: bk_live_your_current_key" ``` > [!NOTE] > > Axra stores API keys as SHA-256 hashes. Your raw key is never stored on Axra's servers, which is why it cannot be retrieved after creation — only regenerated. *** ## Choosing an authentication method | | API key header | JWT token | | - | - | - | | **Setup complexity** | Minimal | Requires token exchange and refresh logic | | **Best for** | Server-side integrations, scripts, internal tools | Architectures that require short-lived credentials | | **Token lifetime** | Long-lived (until regenerated) | 1 hour | | **Revocation** | Regenerate key to invalidate | Tokens expire automatically | For most server-side integrations, the API key header is the simplest and most practical choice. Use JWT tokens if your security policy requires credentials that expire automatically. *** ## Next steps > [card] [Payments](/payments/overview) > > Start accepting payments with server-to-server card charging. > [card] [Checkout Sessions](/payments/checkout-sessions) > > Use a hosted payment page to accept payments without handling card data. # Changelog Source: https://docs.useaxra.com/changelog Changes to the Axra API that can affect an existing integration. ## 2026-10-12: `provider` on card payments now returns `card` The `provider` field on card payments now always returns `card`, whichever card processor handled the payment. Earlier responses could carry a processor-specific value. This applies to: * the `POST /business/payment/charge` response, including an idempotent replay of an earlier charge * the `payment.created` webhook for card payments The field is still present, so code that reads it keeps working. If your integration branched on a processor-specific value, switch it to `card`. `provider` is the payment method family, not routing information. It has never been needed to confirm, refund or reconcile a payment. # Introduction Source: https://docs.useaxra.com/introduction Accept payments, move money, and build financial products with Axra ## Welcome to Axra Axra is a financial infrastructure platform that lets you accept payments, manage wallets, and build banking products via API. > [card] [Accept Payments](/payments/overview) > > Accept card payments, mobile money, and bank transfers across Africa and globally. > [card] [Treasury (BaaS)](/treasury/overview) > > Build banking products for your users — KYC, wallets, payouts, and compliance built in. > [card] [API Reference](/api-reference) > > Complete API reference with code examples in every language. > [card] [SDKs](/sdks/node) > > Node.js, Python, Pay.js, and CLI tools to integrate in minutes. ## Quick start **1. Get your API keys** Sign up at [app.useaxra.com](https://app.useaxra.com/register) to get your test and live API keys. **2. Install the SDK** ```bash theme={null} npm install @useaxra/node ``` **3. Make your first API call** ```typescript theme={null} import { Axra } from '@useaxra/node'; const axra = new Axra('sk_test_...'); const payment = await axra.payments.create({ amount: 5000, currency: 'USD', }); console.log(payment); ``` ## Base URL All API requests are made to: ``` https://api.useaxra.com/api/v1 ``` ## Authentication Authenticate by including your API key in the `x-api-key` header (merchant endpoints) or `Authorization: Bearer` header (Treasury endpoints). ```bash theme={null} curl https://api.useaxra.com/api/v1/treasury/whoami \ -H "Authorization: Bearer sk_test_..." ``` # Disputes Source: https://docs.useaxra.com/manage/disputes Learn how chargebacks work on Axra Pay, how to retrieve dispute data via the API, and what steps you can take to reduce disputes and win them. A dispute — also called a chargeback — occurs when a cardholder contacts their bank to challenge a charge. The bank initiates a formal dispute process on the cardholder's behalf, and the outcome determines whether the funds are returned to the customer or kept by you. When a dispute is opened, Axra immediately debits the full charge amount from your merchant account and charges a **\$5.82 dispute fee**. This fee is non-refundable regardless of the outcome — even if you win the dispute. > [!WARNING] > > Disputes can occur weeks or months after the original transaction. Maintain records of customer orders, delivery confirmations, and communications so you can respond with evidence if needed. ## How disputes affect your account | Event | Merchant impact | | - | - | | `payment.disputed` | Charge amount debited + \$5.82 dispute fee charged | | `payment.dispute_won` | Charge amount re-credited (dispute fee not refunded) | | `payment.dispute_lost` | No further changes — funds already debited | Axra notifies you of each stage via [webhook events](/manage/webhooks). Subscribe to `payment.disputed`, `payment.dispute_won`, and `payment.dispute_lost` to track dispute outcomes in real time. ## List disputes Retrieve all disputes for your business account. ```bash theme={null} GET /business/disputes ``` **Authentication:** Required **Query parameters:** | Parameter | Type | Default | Description | | - | - | - | - | | `status` | string | `all` | Filter by outcome: `open`, `won`, `lost`, or `all` | | `page` | number | `1` | Page number for pagination | | `limit` | number | `20` | Results per page | **Example response:** ```json theme={null} { "data": [ { "id": "bpay_01H...", "amount": 49.99, "currency": "USD", "status": "DISPUTED", "metadata": { "disputeId": "dp_1Abc...", "disputeReason": "fraudulent", "merchantDisputeFee": 5.82 }, "business": { "id": "biz_01H...", "businessName": "Acme Corp" }, "updatedAt": "2026-03-20T16:00:00.000Z" } ], "meta": { "total": 3, "page": 1, "limit": 20, "totalPages": 1 } } ``` ## Get dispute statistics Retrieve an aggregate summary of dispute activity for your account. ```bash theme={null} GET /business/disputes/stats ``` **Authentication:** Required **Response fields:** | Field | Description | | - | - | | `open` | Number of disputes currently in progress | | `won` | Number of disputes resolved in your favor | | `lost` | Number of disputes resolved against you | | `total` | Total disputes across all statuses | | `winRate` | Percentage of resolved disputes you won | | `totalDisputeFees` | Total dispute fees charged to your account | ## Get dispute detail Retrieve full dispute information for a specific payment. ```bash theme={null} GET /business/disputes/:paymentId ``` **Authentication:** Required **Path parameters:** | Parameter | Description | | - | - | | `paymentId` | The ID of the payment to look up (e.g., `bpay_01H...`) | **Errors:** | Status | Meaning | | - | - | | `400` | The payment exists but has no dispute associated with it | | `404` | No payment found with the given ID | The response is the full payment object, with dispute metadata in the `metadata` field — including `disputeId`, `disputeReason`, and `merchantDisputeFee`. ## Reducing disputes The most effective way to manage disputes is to prevent them. Fewer disputes mean lower fees, a healthier account standing, and less time spent on evidence gathering. **1. Enable 3DS authentication** Use [3D Secure authentication](/payments/3ds-authentication) on card transactions. When a customer completes 3DS, fraud liability shifts from you to the card issuer — meaning you win most fraud-related disputes automatically. **2. Use clear billing descriptors** Make sure the charge description on your customers' bank statements clearly identifies your business. An unrecognized charge name is one of the most common reasons customers dispute a transaction. **3. Respond to disputes promptly** Card networks impose strict deadlines — typically 7–21 days — for submitting evidence. Respond as quickly as possible with relevant documentation: order receipts, delivery confirmations, customer communications, and usage logs. **4. Maintain transaction records** Keep records of customer interactions, order details, shipping/delivery confirmations, and any refund requests. These are your primary tools when building a dispute response. > [!TIP] > > If a customer contacts you directly about an issue before filing a dispute, resolving it promptly (including issuing a refund if warranted) is almost always cheaper than a chargeback. You avoid the dispute fee and protect your dispute rate. # Settlements Source: https://docs.useaxra.com/manage/settlements Understand the Axra Pay settlement lifecycle, fee deductions, and timeline for when captured payments are credited to your Axra merchant wallet. Settlement is the process by which funds from a captured payment move through the card networks and land in your Axra merchant wallet, where they become available for withdrawal. The process is not instantaneous — after a payment is captured, the funds spend time in transit through card network clearing before Axra can credit them to your account. Understanding the settlement flow helps you accurately forecast cash flow and identify any delays. ## Settlement flow **1. Payment captured** The customer's card is charged successfully. Axra fires a `payment.completed` webhook event. The payment's `settlementStatus` is set to `PENDING_SETTLEMENT`. **2. Funds in transit** The captured funds move through card network clearing. This typically takes **2–3 business days**. Weekends are excluded from this count. Your specific timeline may vary based on your merchant risk category and the terms in your merchant agreement. **3. Funds settled** Once clearing completes, Axra deducts platform fees and credits the net amount to your merchant wallet. The payment's `settlementStatus` updates to `SETTLED`, and Axra fires a `payment.settled` webhook event. ## Settlement statuses | Status | Description | | - | - | | `PENDING_SETTLEMENT` | Payment captured, awaiting fund clearance through card networks | | `SETTLED` | Funds cleared and credited to your merchant wallet | | `SETTLEMENT_FAILED` | Settlement failed — Axra operations team is automatically alerted | > [!NOTE] > > If settlement is not confirmed within the expected window, Axra runs an auto-settlement process hourly as a safety net to ensure your funds are credited without manual intervention. ## Fee deductions at settlement When a payment settles, Axra deducts platform fees before crediting your wallet. The net amount you receive is the captured payment amount minus the percentage rate fee and a flat per-transaction fee. ``` Settlement Amount: $100.00 Platform Fee (3.9%): - 3.90 Flat Transaction Fee: - 1.00 -------- Merchant Net: $ 95.10 ``` Your fee rate depends on your merchant tier: | Tier | Rate | Applies when | | - | - | - | | `low_risk` | 3.9% | Default for low-risk merchants | | `high_risk` | 4.5% | High-risk merchant category | | `custom` | Varies | Custom rate negotiated in your merchant agreement | All tiers include a flat **\$1.00 per-transaction fee** in addition to the percentage rate. > [!TIP] > > If you believe your fee tier is incorrect or want to discuss custom pricing, contact [support@useaxra.com](mailto:support@useaxra.com). ## Viewing settlement details You can inspect the settlement status and fee breakdown for any payment by calling the payment detail endpoint: ```bash theme={null} GET /business/payment/:paymentId ``` Check these fields in the response: | Field | Description | | - | - | | `settlementStatus` | Current settlement status (`PENDING_SETTLEMENT`, `SETTLED`, or `SETTLEMENT_FAILED`) | | `metadata.feeBreakdown` | Itemized fee breakdown applied at settlement, including the percentage fee and flat transaction fee | ## Handling settlement webhooks Subscribe to the `payment.settled` event in your [webhook handler](/manage/webhooks) to trigger downstream actions — such as fulfilling orders, updating accounting records, or initiating payouts — only after funds are confirmed in your wallet. ```json theme={null} { "event": "payment.settled", "timestamp": "2026-03-22T10:00:00.000Z", "data": { "paymentId": "bpay_01H...", "amount": "49.99", "currency": "USD", "settledAt": "2026-03-22T10:00:00.000Z" } } ``` > [!WARNING] > > Do not treat `payment.completed` as confirmation that funds are in your wallet. Use `payment.settled` for any logic that depends on fund availability. # Webhooks Source: https://docs.useaxra.com/manage/webhooks Receive real-time HTTP callbacks for payment completions, refunds, disputes, and settlements. Learn how to verify signatures and handle events reliably. Webhooks let Axra push payment events to your server the moment they happen, so you never need to poll the API to check whether a payment succeeded. When a payment event occurs — a charge completes, a dispute opens, or funds settle — Axra sends an HTTP POST request to the `webhookUrl` you configured in your business profile. Because many payment flows (like 3DS redirects or card network clearing) are asynchronous, you should always confirm payment status through webhooks rather than relying solely on the response from a charge request. ## Configure your webhook URL Set your webhook endpoint in the Axra dashboard under **Settings → Business Profile**, or update it programmatically: ```bash theme={null} PUT /business/config ``` ```json theme={null} { "webhookUrl": "https://your-domain.com/webhooks/axra" } ``` > [!NOTE] > > Your webhook URL must be publicly reachable. During local development, use a tool like [ngrok](https://ngrok.com) to expose your local server. ## Event types Axra delivers the following events to your webhook endpoint: | Event | Description | | - | - | | `payment.created` | A payment record was created (before capture). | | `payment.completed` | Payment captured successfully. | | `payment.failed` | Payment processing failed. | | `payment.settled` | Funds cleared and available for withdrawal. | | `payment.refunded` | Payment has been refunded. | | `payment.disputed` | A dispute (chargeback) has been opened. | | `payment.dispute_won` | Dispute resolved in your favor. | | `payment.dispute_lost` | Dispute resolved against you. | | `payment_link.session.completed` | A hosted checkout session completed successfully. | | `collection.created` | A local-rails collection was created. | | `collection.processing` | Funds have been detected, settlement is in progress. | | `collection.completed` | Funds settled; merchant USDC wallet credited. | | `collection.failed` | Collection failed (e.g. amount mismatch, provider rejection). | | `collection.expired` | Virtual account expired without payment. | | `payout.initiated` | A payout was accepted and the merchant wallet debited (status `CREATED`). | | `payout.submitted` | The payout was dispatched to the payout provider (status `SUBMITTED`). | | `payout.settled` | Funds were delivered to the recipient (status `SETTLED`). | | `payout.failed` | The payout failed; the wallet debit was reversed (status `FAILED`). | | `payout.cancelled` | A `CREATED` payout was cancelled before dispatch (status `CANCELLED`). | | `payout.review` | The payout is held for compliance/admin review (status `PENDING_REVIEW`). | | `invoice.created` | An invoice was issued. | | `invoice.paid` | An invoice was paid. | | `recurring_gift.charge.succeeded` | A recurring-gift schedule successfully charged. | | `recurring_gift.charge.failed` | A recurring-gift charge attempt failed. | ## Webhook payload structure Every webhook request shares the same envelope format: ```json theme={null} { "event": "payment.completed", "timestamp": "2026-03-20T14:30:05.000Z", "data": { ... } } ``` The `data` object varies by event type. Below are the payloads for each event. > [accordion] payment.created > > Fires when a payment record is created — before the funds are captured. Useful for pre-populating order rows in your system. > > ```json theme={null} > { > "paymentId": "bpay_01H...", > "amount": 49.99, > "currency": "USD", > "status": "PENDING", > "provider": "card" > } > ``` > > On a card payment `provider` is always `card`, whichever processor handled it. > [accordion] payment.completed > > Fires when a payment is captured successfully. Update your order status to reflect payment received. > > ```json theme={null} > { > "paymentId": "bpay_01H...", > "amount": "49.99", > "currency": "USD" > } > ``` > [accordion] payment.failed > > Fires when payment processing fails. The `reason` field contains the failure code. > > ```json theme={null} > { > "paymentId": "bpay_01H...", > "reason": "card_declined" > } > ``` > [accordion] payment.settled > > Fires when funds have cleared the card networks and are credited to your merchant wallet (minus fees). > > ```json theme={null} > { > "paymentId": "bpay_01H...", > "amount": "49.99", > "currency": "USD", > "settledAt": "2026-03-22T10:00:00.000Z" > } > ``` > [accordion] payment.refunded > > Fires when a refund is issued for a payment. > > ```json theme={null} > { > "paymentId": "bpay_01H...", > "amount": 49.99, > "currency": "USD", > "refundId": "re_1Abc..." > } > ``` > [accordion] payment.disputed > > Fires when a cardholder opens a dispute (chargeback). The full charge amount is debited from your account immediately, plus a non-refundable dispute fee. > > ```json theme={null} > { > "paymentId": "bpay_01H...", > "disputeId": "dp_1Abc...", > "disputeAmount": 49.99, > "disputeFee": 5.82, > "reason": "fraudulent" > } > ``` > [accordion] payment.dispute_won / payment.dispute_lost > > Fires when a dispute is resolved. If you win, the charge amount is re-credited to your account (the dispute fee is not refunded). If you lose, no further changes occur — the funds were already debited. > > ```json theme={null} > { > "paymentId": "bpay_01H...", > "won": true, > "chargeAmount": 49.99 > } > ``` > [accordion] collection.created > > Fires immediately after a collection is created through the direct API or hosted checkout. `data.object` mirrors `GET /business/collections/{id}`. > > On `channel`, `networkId` is the operator network we routed to — the value `customer.networkId` echoes back — and `channelId` is the underlying provider's own internal channel id, which is `null` whenever the provider gave us none. They are not interchangeable, and `channelId` is never a substitute for `networkId`. > > ```json theme={null} > { > "livemode": true, > "object": { > "id": "lcoll_01HVXYZ123456", > "object": "collection", > "status": "pending", > "amount": 10000, > "currency": "ngn", > "country": "NG", > "expiresAt": "2026-05-11T12:34:56Z", > "channel": { > "rail": "bank", > "provider": "PAGA", > "channelId": null, > "networkId": "9f3c81d2-4a6e-4b0f-9d17-2c5e8a71b430" > }, > "instructions": { > "kind": "bank_transfer", > "bankName": "Indulge MFB", > "accountNumber": "9906154084", > "accountName": "AXRA / Your Business", > "reference": null > }, > "metadata": { "orderId": "ord_1042" }, > "businessPaymentId": "bp_01HVXYZ123456", > "source": "api", > "createdAt": "2026-05-11T12:24:56Z" > } > } > ``` > [accordion] collection.processing > > Fires when inbound funds are detected and settlement is in progress. > > ```json theme={null} > { > "livemode": true, > "object": { > "id": "lcoll_01HVXYZ789012", > "object": "collection", > "status": "processing", > "amount": 5000, > "currency": "kes", > "country": "KE", > "expiresAt": "2026-05-11T12:44:56Z", > "channel": { > "rail": "momo", > "provider": "M-PESA", > "channelId": "a1f6b93c-70d4-4e28-8c5b-19e07f4ad662", > "networkId": "2b7e4f11-8c3a-4d59-b0e6-71a9c2d35f84" > }, > "instructions": { > "kind": "momo_prompt", > "phone": "+254712345678", > "prompt": "Approve the payment prompt from your mobile money provider." > }, > "metadata": null, > "businessPaymentId": "bp_01HVXYZ789012", > "source": "api", > "createdAt": "2026-05-11T12:34:56Z" > } > } > ``` > [accordion] collection.completed > > Fires when the collection settles and your USDC wallet is credited. Fulfill the order on this event. > > ```json theme={null} > { > "livemode": true, > "object": { > "id": "lcoll_01HVXYZ345678", > "object": "collection", > "status": "completed", > "amount": 2500, > "currency": "zar", > "country": "ZA", > "expiresAt": "2026-05-11T12:49:56Z", > "channel": { > "rail": "eft", > "provider": "Ozow", > "channelId": null, > "networkId": "6a4b2c08-3f91-4d7e-85ac-b21e9d0f47c3" > }, > "instructions": { > "kind": "hosted_page", > "url": "https://pay.ozow.com/...", > "provider": "Ozow" > }, > "metadata": { "orderId": "ord_2048" }, > "businessPaymentId": "bp_01HVXYZ345678", > "source": "session", > "createdAt": "2026-05-11T12:39:56Z" > } > } > ``` > [accordion] collection.failed > > Fires when the provider reports a terminal failure (for example, amount mismatch or rejection). > > ```json theme={null} > { > "livemode": true, > "object": { > "id": "lcoll_01HVXYZ901234", > "object": "collection", > "status": "failed", > "amount": 10000, > "currency": "ngn", > "country": "NG", > "expiresAt": "2026-05-11T12:34:56Z", > "channel": { > "rail": "bank", > "provider": "PAGA", > "channelId": null, > "networkId": "9f3c81d2-4a6e-4b0f-9d17-2c5e8a71b430" > }, > "instructions": { > "kind": "bank_transfer", > "bankName": "Indulge MFB", > "accountNumber": "9906154084", > "accountName": "AXRA / Your Business", > "reference": null > }, > "metadata": null, > "businessPaymentId": "bp_01HVXYZ901234", > "source": "api", > "createdAt": "2026-05-11T12:24:56Z" > } > } > ``` > [accordion] collection.expired > > Fires when deposit instructions expire before payment arrives. > > ```json theme={null} > { > "livemode": true, > "object": { > "id": "lcoll_01HVXYZ567890", > "object": "collection", > "status": "expired", > "amount": 5000, > "currency": "kes", > "country": "KE", > "expiresAt": "2026-05-11T12:44:56Z", > "channel": { > "rail": "momo", > "provider": "M-PESA", > "channelId": "a1f6b93c-70d4-4e28-8c5b-19e07f4ad662", > "networkId": "2b7e4f11-8c3a-4d59-b0e6-71a9c2d35f84" > }, > "instructions": { > "kind": "momo_prompt", > "phone": "+254712345678", > "prompt": "Approve the payment prompt from your mobile money provider." > }, > "metadata": null, > "businessPaymentId": "bp_01HVXYZ567890", > "source": "session", > "createdAt": "2026-05-11T12:34:56Z" > } > } > ``` > [accordion] payment_link.session.completed > > Fires when a hosted checkout / payment-link session is completed. `source` identifies the originator (`payment_link`, `invoice`, etc.) and `sourceId` is the originating resource ID. > > ```json theme={null} > { > "sessionId": "cs_01H...", > "source": "payment_link", > "sourceId": "plink_01H...", > "status": "COMPLETED", > "amount": 4999, > "currency": "USD" > } > ``` > [accordion] invoice.created > > Fires when a new invoice is issued. > > ```json theme={null} > { > "invoiceId": "inv_01H...", > "invoiceNumber": "INV-0001", > "status": "DRAFT", > "totalAmount": 5000, > "currency": "USD" > } > ``` > [accordion] invoice.paid > > Fires when an invoice is paid via its checkout session. > > ```json theme={null} > { > "invoiceId": "inv_01H...", > "invoiceNumber": "INV-0001", > "sessionId": "cs_01H..." > } > ``` > [accordion] recurring_gift.charge.succeeded > > Fires when a recurring-gift schedule successfully captures a charge. `chargeCount` is the cumulative number of successful charges on this schedule. > > ```json theme={null} > { > "recurringGiftId": "rg_01H...", > "paymentLinkId": "plink_01H...", > "amount": 5000, > "currency": "USD", > "chargeCount": 3, > "paymentIntentId": "pi_01H..." > } > ``` > [accordion] recurring_gift.charge.failed > > Fires when a recurring-gift charge attempt fails. `failureCount` tracks consecutive failures; the schedule is paused after the configured retry limit. > > ```json theme={null} > { > "recurringGiftId": "rg_01H...", > "paymentLinkId": "plink_01H...", > "error": "card_declined", > "failureCount": 1 > } > ``` > [accordion] payout.\* (initiated / submitted / settled / failed / cancelled / review) > > Fires across the payout lifecycle for outbound [local-rail payouts](/payments/payouts/local-rails). `data.object` is the same shape as `GET /v1/business/payouts/{id}`. Fulfill or reconcile your records on `payout.settled`; reverse on `payout.failed`. > > ```json theme={null} > { > "object": { > "id": "po_01H...", > "status": "SETTLED", > "rail": "LOCAL_BANK", > "amount": "100.00", > "currency": "USDC", > "recipientId": "rec_01H...", > "destinationMasked": { "country": "NG", "accountNumber": "••••6789", "bankName": "Example Bank" }, > "providerRef": "yc_01H...", > "settledAt": "2026-06-02T10:00:30.000Z", > "quote": { "dstAmount": "151000", "rate": "1510", "axraFee": "0.50", "currency": "NGN", "country": "NG" } > }, > "livemode": true > } > ``` ## Webhook request headers Axra includes these headers on every webhook request: | Header | Description | | - | - | | `Content-Type` | `application/json` | | `X-Axra-Signature` | HMAC-SHA256 signature of the raw request body | | `X-Axra-Event` | The event type (e.g., `payment.completed`) | ## Signature verification > [!WARNING] > > Always verify the `X-Axra-Signature` header before processing a webhook. Without verification, any party can send requests to your endpoint and trigger side effects in your system. To verify a webhook: **1. Get your webhook secret** Find your `webhookSecret` in the Axra dashboard under **Settings → API Keys**. Store it as an environment variable — never hardcode it. **2. Compute the expected signature** Compute an HMAC-SHA256 digest of the **raw request body** (the bytes as received, before any JSON parsing) using your `webhookSecret` as the key. **3. Compare using constant-time equality** Compare the computed digest to the value in the `X-Axra-Signature` header using a constant-time comparison function. This prevents timing attacks. **4. Reject if signatures do not match** Return a `401 Unauthorized` response immediately. Do not process the event. ```javascript Node.js theme={null} const crypto = require('crypto'); function verifyWebhookSignature(rawBody, signature, webhookSecret) { const expectedSignature = crypto .createHmac('sha256', webhookSecret) .update(rawBody) .digest('hex'); return crypto.timingSafeEqual( Buffer.from(signature, 'hex'), Buffer.from(expectedSignature, 'hex'), ); } app.post('/webhook', (req, res) => { const signature = req.headers['x-axra-signature']; const rawBody = JSON.stringify(req.body); if (!verifyWebhookSignature(rawBody, signature, process.env.AXRA_WEBHOOK_SECRET)) { return res.status(401).send('Invalid signature'); } const { event, data } = req.body; switch (event) { case 'payment.completed': // Update your order status break; case 'payment.settled': // Funds are now available break; case 'payment.disputed': // Alert your fraud team break; } res.status(200).send('OK'); }); ``` ```python Python theme={null} import hmac import hashlib def verify_webhook(raw_body: bytes, signature: str, secret: str) -> bool: expected = hmac.new( secret.encode(), raw_body, hashlib.sha256 ).hexdigest() return hmac.compare_digest(signature, expected) ``` ```go Go theme={null} func verifyWebhook(body []byte, signature, secret string) bool { mac := hmac.New(sha256.New, []byte(secret)) mac.Write(body) expected := hex.EncodeToString(mac.Sum(nil)) return hmac.Equal([]byte(signature), []byte(expected)) } ``` > [!NOTE] > > Use the **raw** request body bytes for signature computation — not a re-serialized version of the parsed JSON. JSON serialization is not guaranteed to be deterministic, and any whitespace difference will cause verification to fail. ## Retry policy Axra considers a delivery successful when your endpoint responds with an HTTP `2xx` status code within 30 seconds. If delivery fails, Axra retries with the following schedule: | Attempt | Delay after failure | | - | - | | 1 | Immediate | | 2 | 30 seconds | | 3 | 60 seconds | | 4 | 90 seconds | | 5 | 120 seconds | After 5 failed attempts, the webhook delivery is marked permanently failed. You can review failed deliveries and trigger manual redelivery in the **Axra dashboard → Webhooks → Delivery Logs**. ## Best practices 1. **Return `200` quickly** — acknowledge receipt immediately, then process the event in a background job. Long-running handlers risk timeouts and unnecessary retries. 2. **Handle duplicates** — network retries mean your endpoint may receive the same event more than once. Use `paymentId` as an idempotency key to ensure you process each event exactly once. 3. **Always verify signatures** — reject any request where `X-Axra-Signature` does not match your computed value. 4. **Use HTTPS in production** — plain HTTP webhook URLs are rejected for live-mode credentials. 5. **Use ngrok during local development** — run `ngrok http 3000` to get a public URL that tunnels to your local server. # 3D Secure (3DS) Source: https://docs.useaxra.com/payments/3ds Add 3DS authentication to card payments for fraud reduction and liability shift 3D Secure adds an additional authentication step for card payments, reducing fraud and shifting liability from the merchant to the card issuer. Axra handles 3DS transparently -- your integration is the same regardless of the card network or issuing bank. *** ## How 3DS Works 3DS introduces a challenge step where the cardholder's bank verifies their identity (via SMS code, biometric, or app confirmation) before the payment is authorized. *** ## Integration Flow ### Server-to-Server (S2S) 3DS Flow Pass `returnUrl` on the charge. After 3DS the payer returns via Axra's page; we append `3ds=complete|failed` and `paymentId`. The URL is never shared with the card processor. ``` Your Server Axra API Card Network Issuing Bank | | | | | 1. POST /payment/charge | | | | (card + returnUrl) | | | |---------------------------->| | | | | 2. Forward charge request | | | |----------------------------->| | | | | 3. Check 3DS required | | | |----------------------->| | | | 4. 3DS challenge URL | | | |<-----------------------| | | 5. Return requires_action | | | |<-----------------------------| | | 6. Response: | | | | {status: requires_action, | | | | requiresAction: { | | | | redirectUrl: "..." | | | | }} | | | |<----------------------------| | | | | | | | 7. Redirect customer | | | | to redirectUrl | | | |.............................>| (customer's browser) | | | | | | | | 8. Customer completes 3DS challenge | | | |<--- - - - - - - - - -->| | | | | | | 9. Customer returns via Axra's page, then | | | to returnUrl?3ds=complete|failed&paymentId=… | |<.............................| (customer's browser) | | | | | | | 10. POST /payment/confirm-3ds | | | {transactionId} | | | |---------------------------->| | | | | 11. Confirm payment | | | |----------------------------->| | | | | 12. Verify with issuer | | | |----------------------->| | | | 13. Auth result | | | |<-----------------------| | | 14. Charge result | | | |<-----------------------------| | | 15. Response: | | | | {status: succeeded} | | | |<----------------------------| | | | | | | | 16. Webhook: payment.completed | | |<----------------------------| | | | | | | ``` ### Checkout Session 3DS Flow For checkout sessions, 3DS is handled entirely within the Axra-hosted checkout page. The customer never leaves the checkout experience. ``` Your Server Axra API Checkout Page Card Network | | | | | 1. POST /payment/session | | | |---------------------------->| | | | 2. {checkoutUrl} | | | |<----------------------------| | | | | | | | 3. Redirect customer | | | | to checkoutUrl | | | |.............................>| 4. Load session | | | |--------------------->| | | | | | | | 5. Customer enters card & submits | | | | | | | 6. POST /checkout/session/:id/charge | | |<---------------------| | | | | | | | 7. Process charge | | | |--------------------------------------------->| | | 8. requires_action | | | |<---------------------------------------------| | | | | | | 9. Return 3DS URL | | | |--------------------->| | | | | 10. Show 3DS iframe | | | | or redirect | | | | | | | | 11. Customer completes| | | | 3DS challenge | | | | | | | 12. POST /checkout/session/:id/confirm-3ds | | |<---------------------| | | | | | | | 13. Confirm payment | | | |--------------------------------------------->| | | 14. Succeeded | | | |<---------------------------------------------| | | | | | | 15. Redirect to | | | | successUrl | | | |--------------------->| | | | | | | 16. Webhook: payment.completed | | |<----------------------------| | | | | | | ``` *** ## Implementation Guide ### Step 1: Initiate the Charge Include a `returnUrl` in your charge request. After 3DS the customer returns via Axra's page; we then send them to your `returnUrl` with `3ds=complete` or `3ds=failed` and `paymentId` appended. Your `returnUrl` is never shared with the card processor. ```bash theme={null} curl -X POST https://api.useaxra.com/api/v1/business/payment/charge \ -H "x-api-key: bk_live_abc123..." \ -H "Content-Type: application/json" \ -d '{ "amount": 99.99, "currency": "usd", "card": { "number": "4000002500003155", "expiryMonth": 12, "expiryYear": 2028, "cvv": "123" }, "returnUrl": "https://yoursite.com/payment/3ds-return?order=1234", "customerIp": "203.0.113.42", "browser": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 ...", "browserDetails": { "acceptHeaders": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8", "colorDepth": 24, "javaEnabled": false, "javascriptEnabled": true, "language": "en-US", "screenHeight": 1080, "screenWidth": 1920, "timeZone": -60 } }' ``` > [!WARNING] > > **`browser` and `browserDetails` are required in practice.** They are the EMV-3DS2 device > signals the issuer uses to decide whether it can authenticate without challenging the > cardholder. Omit them and the issuer will usually demand a challenge — and we have observed > issuers **failing the authentication instead of presenting one**, so the payment dies with no > prompt ever shown. > > We cannot fill them in for you: on a server-to-server charge the request reaches us from your > server, not the cardholder's browser. See > [Collecting the browser signals](/payments/card-payments) for a copy-paste snippet. ### Step 2: Check for 3DS Requirement Inspect the response. If `status` is `requires_action`, the customer must complete a 3DS challenge. ```json theme={null} { "paymentId": "bpay_01H...", "status": "requires_action", "transactionId": "txn_3Abc...", "requiresAction": { "type": "3ds_redirect", "redirectUrl": "https://pay.useaxra.com/3ds/authenticate?..." } } ``` The `requiresAction` object contains: | Field | Type | Description | | - | - | - | | `type` | string | `3ds_redirect`, `3ds_challenge`, or `fingerprint` | | `redirectUrl` | string | URL to redirect the customer for authentication | ### Step 3: Redirect the Customer Redirect the customer's browser to the `redirectUrl`: ```javascript theme={null} // React / Next.js if (response.status === 'requires_action') { window.location.href = response.requiresAction.redirectUrl; } ``` ### Step 4: Handle the Return After the customer completes (or cancels) the 3DS challenge, they return via Axra's page and are then sent to your `returnUrl` with `3ds=complete|failed` and `paymentId`. Confirm the payment: ```bash theme={null} curl -X POST https://api.useaxra.com/api/v1/business/payment/confirm-3ds \ -H "x-api-key: bk_live_abc123..." \ -H "Content-Type: application/json" \ -d '{ "transactionId": "txn_3Abc..." }' ``` ### Step 5: Handle the Result ```javascript theme={null} const result = await confirmPayment(transactionId); if (result.status === 'succeeded') { // Payment confirmed! Wait for payment.completed webhook // to update order status in your system. showSuccessPage(); } else if (result.status === 'failed') { // 3DS authentication failed or was declined showErrorPage('Payment authentication failed. Please try again.'); } ``` *** ## When is 3DS Required? 3DS may be triggered by: 1. **Card issuer rules:** Some issuers require 3DS for all online transactions 2. **SCA regulation (PSD2):** Required for European card payments over certain thresholds 3. **Risk scoring:** Axra's risk engine may trigger 3DS for suspicious transactions 4. **Amount thresholds:** Some regions require 3DS above certain amounts Not all transactions will require 3DS. When 3DS is not needed, the charge completes immediately with `status: "succeeded"`. *** ## Error Handling ### 3DS Failures | Scenario | Response Status | What to Do | | - | - | - | | Card requires 3DS | `requires_action` | Redirect customer to `redirectUrl` | | Customer cancels 3DS | `failed` | Show error, allow retry | | 3DS authentication fails | `failed` | Show error, suggest different card | | 3DS timeout | `failed` | Show error, allow retry | | Card does not support 3DS | `succeeded` | Payment completes without 3DS (frictionless) | ### Common Mistakes 1. **Missing `returnUrl`:** Without a return URL, the customer has nowhere to go after 3DS. Always include it for S2S charges. 2. **Not checking `requires_action`:** If you ignore this status, the payment stays pending forever. 3. **Confirming without 3DS completion:** Calling confirm-3ds before the customer completes the challenge will fail. 4. **Hardcoding `transactionId`:** Always use the `transactionId` from the charge response -- it is unique per transaction. *** ## Testing 3DS ### Test Cards | Card Number | Behavior | | - | - | | `4000002500003155` | 3DS required, authentication succeeds | | `4000008260003178` | 3DS required, authentication fails | | `4242424242424242` | No 3DS required (frictionless) | | `4000000000003220` | 3DS2 required (newer protocol) | ### Testing Flow 1. Use a sandbox/test API key 2. Charge with a 3DS test card 3. Follow the `redirectUrl` -- in test mode the challenge auto-completes 4. Confirm the payment 5. Verify the `payment.completed` webhook fires *** ## Liability Shift When 3DS authentication succeeds: * **Fraud liability shifts** from the merchant to the card issuer * If a fraudulent chargeback occurs, the merchant is protected * Dispute fees may be waived for 3DS-authenticated transactions This is a significant benefit: 3DS-authenticated payments have a much lower dispute rate. Where possible, we recommend enabling 3DS for all transactions. # Card Payments Source: https://docs.useaxra.com/payments/card-payments Charge cards server-to-server with the Axra Payments API Server-to-server (S2S) charging lets your backend send card details directly to Axra. It puts your servers in PCI DSS scope, so it is **off by default** — approval of your business account does not enable it. > [!NOTE] > > Most integrations do not need S2S. [Checkout sessions](/payments/checkout-sessions) and payment > links keep card data on Axra's hosted page, which keeps you out of PCI scope. Those work on > every approved account with no extra step. ## Check whether it's enabled `GET /v1/business/config` returns your current entitlement: ```bash theme={null} curl https://api.useaxra.com/api/v1/business/config \ -H "x-api-key: YOUR_API_KEY" ``` ```json theme={null} { "id": "…", "businessName": "…", "isActive": true, "s2sChargingEnabled": false } ``` If `s2sChargingEnabled` is `false`, contact support to request access. Charging before it is granted returns `403`: ```json theme={null} { "statusCode": 403, "message": "Server-to-server card charging is not enabled for this business. Use a checkout session or payment link, or contact support to request access." } ``` ## Charge a card ```bash theme={null} curl -X POST https://api.useaxra.com/api/v1/business/payment/charge \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "amount": 50.00, "currency": "USD", "card": { "number": "4111111111111111", "expiryMonth": "12", "expiryYear": "2030", "cvv": "123", "holderName": "Jane Doe" }, "customerIp": "203.0.113.42", "email": "jane@example.com", "returnUrl": "https://your-site.example/order/1234/complete", "browser": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 ...", "browserDetails": { "acceptHeaders": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8", "colorDepth": 24, "javaEnabled": false, "javascriptEnabled": true, "language": "en-US", "screenHeight": 1080, "screenWidth": 1920, "timeZone": -60 } }' ``` `returnUrl` is still the payer's destination after 3DS. After the challenge they return via Axra's page; we then send them to your `returnUrl` with `3ds=complete` or `3ds=failed` and `paymentId` appended. That URL is never shared with the card processor. `customerIp` must be **your customer's** IP address, not your server's. It feeds risk scoring and the 3DS authentication request; sending your own IP degrades both. > [!WARNING] > > **Always send `browser` and `browserDetails`.** The card issuer uses these EMV-3DS2 signals to > decide whether it can authenticate the cardholder without a challenge. When they are missing, > the issuer commonly falls back to demanding a challenge — and in production we have seen > issuers then **fail the authentication outright** rather than present one, so the payment dies > with no prompt ever shown to the customer. > > They cannot be derived on our side: on a server-to-server charge the HTTP request comes from > **your server**, not the cardholder's browser. Collect them in the browser and pass them > through, exactly as you already do for `customerIp`. ### Collecting the browser signals ```js theme={null} // Run this in the cardholder's browser and post the result to your server // alongside the card details. function collectBrowserData() { const tz = new Date().getTimezoneOffset(); return { browser: navigator.userAgent, browserDetails: { acceptHeaders: 'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8', colorDepth: screen.colorDepth ?? 24, javaEnabled: typeof navigator.javaEnabled === 'function' ? navigator.javaEnabled() : false, javascriptEnabled: true, language: navigator.language || 'en-US', screenHeight: screen.height, screenWidth: screen.width, timeZone: tz, }, }; } ``` If a payment fails authentication and these were absent, the payment's `failure.hint` will say so — see [Retrieving a payment](/payments/card-payments). ## 3DS handling If the card requires 3D Secure, the response comes back with `requiresAction` and a `redirectUrl`. Send the customer there, then confirm via `POST /v1/business/payment/confirm-3ds`. See the [3DS guide](/payments/3ds) for the full flow. Confirming and refunding are **not** gated on the S2S entitlement, so a charge already in flight always completes. > [card] [API Reference](/api-reference/business-payments/charge-card) > > See full endpoint documentation. # Checkout Sessions Source: https://docs.useaxra.com/payments/checkout-sessions Create an Axra Pay hosted checkout page in one API call. Customers enter card details on Axra's secure page — no PCI DSS scope added to your integration. 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. > [!NOTE] > > If you need full control over the payment UI or want to charge cards programmatically from your server, use the [Payments API](/payments/overview) 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. > [!WARNING] > > 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 ` 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 ```bash cURL theme={null} 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" } }' ``` ```javascript Node.js theme={null} const response = await fetch( 'https://api.useaxra.com/api/v1/business/payment/session', { method: 'POST', headers: { 'x-api-key': process.env.AXRA_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ 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', }, }), } ); const session = await response.json(); // Redirect the customer to the hosted checkout page res.redirect(session.checkoutUrl); ``` ```python Python theme={null} import os, requests response = requests.post( "https://api.useaxra.com/api/v1/business/payment/session", headers={ "x-api-key": os.environ["AXRA_API_KEY"], "Content-Type": "application/json", }, json={ "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", }, }, ) session = response.json() # Flask example: redirect(session["checkoutUrl"]) print(session["checkoutUrl"]) ``` **201 Created — session created successfully** ```json theme={null} { "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. ```javascript Node.js (Express) theme={null} 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 }); }); ``` > [!TIP] > > 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. ```javascript Node.js (Express) theme={null} 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](/manage/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. > [!NOTE] > > 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. # Local payment methods Source: https://docs.useaxra.com/payments/local-payment-methods Collect bank transfers, mobile money, and instant EFT — settled in USDC. Local payment methods let customers pay in their local currency through bank transfer, mobile money, or instant EFT. Axra mints deposit instructions, tracks the collection, and credits your merchant wallet in USDC when funds settle. ## Supported countries & rails | Country | Currency | Rails available | Status | | - | - | - | - | | Nigeria | NGN | Bank transfer (instant) | Live | | South Africa | ZAR | Instant EFT | Live | | Kenya | KES | Mobile money (M-PESA) | Live | | Tanzania | TZS | Mobile money, bank | Live | | Uganda | UGX | Mobile money | Live | | Rwanda | RWF | Mobile money (MTN) | Live | | Malawi | MWK | Mobile money | Live | | Zambia | ZMW | Mobile money, bank | Live | | Botswana | BWP | Mobile money, bank | Live | | Cameroon | XAF | Mobile money (MTN, Orange) | Live | | Ghana, additional CFA franc (XOF) markets, DRC, Ethiopia | GHS, XOF, CDF, ETB | — | Coming soon | ## How it works **1. Create a collection** Call `POST /business/collections` from your server, or start a hosted checkout session and let the customer pick a local rail on pay.useaxra.com. **2. Customer pays** Show bank details, trigger a mobile-money prompt, or redirect the customer to an instant-EFT hosted page, depending on the rail. **3. Settle in USDC** Axra detects the inbound payment, runs settlement, and credits your USDC wallet. Confirm completion with `collection.completed` (or `payment_link.session.completed` for hosted checkout). ## Integration paths > [card] [Hosted Checkout](/payments/local-rails-checkout) > > Redirect customers to pay.useaxra.com — we handle the UI. > [card] [Direct API (server-to-server)](/payments/local-rails-api) > > Mint deposit instructions from your backend, render them in your own UI. ## Settlement model Every successful collection settles into your USDC wallet through the same canonical payment chain used for cards and crypto. Axra charges a 1% platform fee on local rails, plus the provider fee for the selected channel. ## Webhooks Subscribe to `collection.*` events to drive fulfillment without polling. See [Webhooks](/manage/webhooks) for signature verification, retries, and sample payloads for `collection.created`, `collection.processing`, `collection.completed`, `collection.failed`, and `collection.expired`. # Local rails — server-to-server Source: https://docs.useaxra.com/payments/local-rails-api Mint deposit instructions directly from your backend. No redirect required. > [!WARNING] > > Enable local rails for the currencies you want to accept in your Axra dashboard before calling this endpoint. ## Create a collection `POST /business/collections` Create a collection and return deposit instructions for the customer. Amounts are in major local currency units (for example, `10000` NGN). `customer.name` and `customer.email` are optional. Both are stored on the collection record for your own reconciliation and shown in your Axra dashboard; they are not forwarded to the underlying payment provider. `customer.phone` is required for mobile money — it is forwarded to the provider so the deposit prompt reaches the right number. `customer.networkId` is optional but **strongly recommended on mobile money**. It names the payer's operator — MTN, Orange, Wave — and comes from `networks[]` on [`GET /business/local-rails/channels`](#list-available-channels). On a corridor with more than one operator the payer is on exactly **one** of them, and a collection sent to the wrong one fails. If you omit `networkId` we infer the operator from `customer.phone`, which is correct for the overwhelming majority of numbers but **cannot detect a ported number** — one that has moved between operators and kept its original prefix. If your checkout already asks the payer which wallet they use, send it and we will use your answer instead of guessing. If you send a `networkId` that isn't currently routable for the corridor we reject the collection with a `400` and the code `NETWORK_NOT_ROUTABLE`, rather than quietly routing the payer to a different operator. An explicit `networkId` is treated as a fact about the payer, not as a hint. ### Reading `channel` on the response Every collection response carries a `channel` object with two ids that are **not** interchangeable: * **`channel.networkId`** — the operator network we routed this collection to. This is the value `customer.networkId` echoes back, and the one to quote when asking us about routing. * **`channel.channelId`** — the underlying provider's own internal channel id. It is `null` whenever the provider gave us none, which is common on bank and hosted-page collections. Treat it as opaque: it is not an operator, and it is never a substitute for `networkId`. ### Bank transfer (NGN) ```bash theme={null} curl -X POST https://api.useaxra.com/api/v1/business/collections \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "amount": 10000, "currency": "ngn", "country": "NG", "customer": { "name": "Adaobi Okeke", "email": "adaobi@example.com" }, "channel": { "rail": "bank" } }' ``` ```json Response theme={null} { "id": "lcoll_01HVXYZ123456", "object": "collection", "status": "pending", "amount": 10000, "currency": "ngn", "country": "NG", "expiresAt": "2026-05-11T12:34:56Z", "channel": { "rail": "bank", "provider": "PAGA", "channelId": null, "networkId": "9f3c81d2-4a6e-4b0f-9d17-2c5e8a71b430" }, "instructions": { "kind": "bank_transfer", "bankName": "Indulge MFB", "accountNumber": "9906154084", "accountName": "AXRA / Your Business", "reference": null }, "metadata": null, "businessPaymentId": "bp_01HVXYZ123456", "createdAt": "2026-05-11T12:24:56Z" } ``` ### Mobile money (KES — M-PESA) `customer.phone` is required for MoMo collections. KE resolves to a single operator, so `customer.networkId` is unnecessary here. On a multi-operator corridor — Cameroon (MTN / Orange), for example — send it. See [Choosing the right mobile-money operator](#choosing-the-right-mobile-money-operator). ```bash theme={null} curl -X POST https://api.useaxra.com/api/v1/business/collections \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "amount": 5000, "currency": "kes", "country": "KE", "customer": { "name": "James Kamau", "email": "james@example.com", "phone": "+254712345678" }, "channel": { "rail": "momo" } }' ``` ```json Response theme={null} { "id": "lcoll_01HVXYZ789012", "object": "collection", "status": "pending", "amount": 5000, "currency": "kes", "country": "KE", "expiresAt": "2026-05-11T12:44:56Z", "channel": { "rail": "momo", "provider": "M-PESA", "channelId": "a1f6b93c-70d4-4e28-8c5b-19e07f4ad662", "networkId": "2b7e4f11-8c3a-4d59-b0e6-71a9c2d35f84" }, "instructions": { "kind": "momo_prompt", "phone": "+254712345678", "prompt": "Approve the payment prompt from your mobile money provider." }, "metadata": null, "businessPaymentId": "bp_01HVXYZ789012", "createdAt": "2026-05-11T12:34:56Z" } ``` ### Link-confirmed mobile money (XOF — Wave) > [!WARNING] > > **Do not assume `rail: "momo"` means `kind: "momo_prompt"`.** Some mobile-money > providers confirm on a hosted page instead of an on-device push. In Côte d'Ivoire > and Senegal, Wave returns `kind: "hosted_page"` on a `momo` rail, and the payment > **cannot complete unless you send the customer to `instructions.url`**. Always > branch on `instructions.kind`, never on `channel.rail`. After paying, the customer is returned to the URL you set once in **Settings → Payer return URL**, or via `PUT /v1/business/config` (`returnUrl`). It must be https on your verified business website domain. If you leave it empty, customers see Axra's payment confirmation page. > [!NOTE] > > Per-request `successUrl` on collections is **deprecated and ignored**. Set the return URL on the business, not on each collection. ```json Response theme={null} { "id": "lcoll_01HVXYZ901234", "object": "collection", "status": "pending", "amount": 10000, "currency": "xof", "country": "CI", "expiresAt": "2026-05-11T13:34:56Z", "channel": { "rail": "momo", "provider": "Wave", "channelId": "c7d90e14-5b62-4af8-93c1-08e2d4f7ba36", "networkId": "4e28d5b7-9a13-4c60-8f2d-6b31ca07e945" }, "instructions": { "kind": "hosted_page", "url": "https://pay.wave.com/...", "provider": "Wave" }, "metadata": null, "businessPaymentId": "bp_01HVXYZ901234", "createdAt": "2026-05-11T12:34:56Z" } ``` Handle both shapes with one branch: ```ts theme={null} switch (collection.instructions.kind) { case 'hosted_page': // Wave (XOF momo), Ozow (ZAR eft) — the customer MUST open this URL. // Do not branch on `provider` either: it names the operator the payer // pays (e.g. "Wave") — a display label, not a flow discriminator. Only // `kind` tells you whether there is a URL the customer must open. return redirect(collection.instructions.url); case 'momo_prompt': // M-PESA, MTN — the customer approves on their handset; nothing to open. return showAwaitingApproval(collection.instructions.prompt); case 'bank_transfer': return showBankDetails(collection.instructions); } ``` ### Instant EFT (ZAR — Ozow) For hosted-page rails, redirect the customer to `instructions.url`. After they pay, they return to your configured payer return URL (or Axra's confirmation page if none is set). Per-request `successUrl` is deprecated and ignored. ```bash theme={null} curl -X POST https://api.useaxra.com/api/v1/business/collections \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "amount": 2500, "currency": "zar", "country": "ZA", "customer": { "name": "Thabo Mokoena", "email": "thabo@example.com" }, "channel": { "rail": "eft" } }' ``` ```json Response theme={null} { "id": "lcoll_01HVXYZ345678", "object": "collection", "status": "pending", "amount": 2500, "currency": "zar", "country": "ZA", "expiresAt": "2026-05-11T12:49:56Z", "channel": { "rail": "eft", "provider": "Ozow", "channelId": null, "networkId": "6a4b2c08-3f91-4d7e-85ac-b21e9d0f47c3" }, "instructions": { "kind": "hosted_page", "url": "https://pay.ozow.com/...", "provider": "Ozow" }, "metadata": null, "businessPaymentId": "bp_01HVXYZ345678", "createdAt": "2026-05-11T12:39:56Z" } ``` ## Handle the completion webhook Fulfill orders when Axra delivers `collection.completed`, not when you return deposit instructions to the customer. 1. Subscribe to `collection.completed` on your webhook endpoint (or include it in the endpoint event list). 2. Verify `X-Axra-Signature` against the raw request body using your webhook secret. See [Webhooks](/manage/webhooks). 3. Read `data.object` — the payload mirrors `GET /business/collections/{id}`. 4. Mark the order paid and release goods or services only after `status` is `completed`. ```javascript theme={null} app.post('/webhooks/axra', (req, res) => { const signature = req.headers['x-axra-signature']; if (!verifyWebhookSignature(req.rawBody, signature, process.env.AXRA_WEBHOOK_SECRET)) { return res.status(401).send('Invalid signature'); } const { event, data } = req.body; if (event === 'collection.completed' && data.object.status === 'completed') { fulfillOrder(data.object.metadata?.orderId, data.object.id); } res.status(200).send('OK'); }); ``` ## Channel discovery List channels before creating a collection when your UI needs to show available rails dynamically, or to discover the per-channel minimum and maximum amounts. ```bash theme={null} curl "https://api.useaxra.com/api/v1/business/local-rails/channels?country=NG¤cy=ngn&amount=10000" \ -H "x-api-key: YOUR_API_KEY" ``` Each channel in the response includes `min` and `max` in the local currency's major units. `min: 0` means no lower bound; `max: 0` means no upper bound. Filter or sort on these in your UI so customers don't see rails their amount doesn't qualify for. ```json theme={null} { "channels": [ { "rail": "bank", "provider": "Paystack", "providerHint": "PAYSTACK", "min": 100, "max": 0 }, { "rail": "momo", "provider": "MTN Uganda", "providerHint": "MTN_UGANDA", "min": 15000, "max": 0 } ], "networks": [ { "networkId": "6168c869-0243-4f32-807a-ddd55b131e3e", "name": "MTN", "rail": "momo" }, { "networkId": "830042b7-61a3-483a-8a19-5052b77f1516", "name": "Orange", "rail": "momo" } ], "limits": { "minAmount": 100, "maxAmount": 0 } } ``` ### Choosing the right mobile-money operator `networks[]` lists the mobile-money operators available on the corridor. **A channel is not an operator** — a channel is how we route, an operator is the wallet the payer actually holds money in. Where `networks[]` returns more than one entry, the payer is on exactly **one** of them, and a collection sent to the wrong operator fails at the provider. Two ways to handle it: 1. **Ask the payer** (recommended). Show the operator names from `networks[]`, and pass the chosen `networkId` as `customer.networkId` on create. This is the only approach that is correct for a **ported number**, where the phone prefix no longer indicates the operator. 2. **Let us infer it.** Omit `customer.networkId` and we derive the operator from `customer.phone`. Correct for the overwhelming majority of numbers, but blind to porting. `rail` on a `networks[]` entry is **optional** and is omitted when the provider does not tell us which rail the network runs on. A missing `rail` does not mean the network is unusable — it means we will not guess. Until 2026-09-10 every entry was reported as `momo`, which advertised bank networks as mobile-money operators; treat an absent `rail` as "unknown", not as "not mobile money". Operator availability changes without notice — read `networks[]` per corridor rather than hard-coding IDs. ### Mobile money on a multi-operator corridor (XAF — Cameroon) Cameroon carries both MTN and Orange. Read `networks[]` from `GET /business/local-rails/channels`, let the payer pick, and pass the chosen `networkId`: ```bash theme={null} curl -X POST https://api.useaxra.com/api/v1/business/collections \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "amount": 2000, "currency": "xaf", "country": "CM", "customer": { "name": "Bruno Jonas", "phone": "+237672487542", "networkId": "6168c869-0243-4f32-807a-ddd55b131e3e" }, "channel": { "rail": "momo" } }' ``` Omit `networkId` and we infer MTN from the `672` prefix. Send it and we use your value — which is the only way to be right when the payer has ported their number between operators. ### Minimums and maximums Local-rail channels have provider-side minimum (and sometimes maximum) amounts. If you call `POST /business/collections` with an `amount` that doesn't fit any channel for the requested `rail` and `country/currency`, you get a `400` with the actual minimum surfaced: ```json theme={null} { "success": false, "error": { "code": "Amount 5000 UGX does not fit any momo channel for UG (minimum is 15000 UGX). Call GET /v1/business/local-rails/channels?country=UG¤cy=ugx&amount=5000 to see what's available.", "statusCode": 400 } } ``` These limits are set by our settlement partners per corridor and change without notice — always read them from `/business/local-rails/channels` rather than hard-coding values in your client. ## Idempotency Pass `idempotencyKey` on create to dedupe retries within one hour. A duplicate key returns the original collection instead of minting a second virtual account. ## Polling Webhooks are the source of truth. If you must poll, call `GET /business/collections/{id}` about every five seconds while `status` is `pending` or `processing`. Use `GET /business/collections/{id}/refresh` to force a provider resync before giving up. ## Status reference | Status | Meaning | | - | - | | `pending` | Deposit instructions are active; waiting for customer payment. | | `processing` | Inbound funds detected; settlement is in progress. | | `completed` | Collection settled; merchant USDC wallet credited. | | `failed` | Collection failed (amount mismatch, provider rejection, or other terminal error). | | `expired` | Instructions expired before payment arrived. | ## Error codes | HTTP | Code | When | | - | - | - | | `400` | `CURRENCY_UNSUPPORTED` | Currency or country is not enabled for your business, or the requested currency is not yet live (for example GHS). | | `400` | `CUSTOMER_PHONE_REQUIRED` | `channel.rail` is `momo` but `customer.phone` is missing. | | `400` | — | Amount is below the channel minimum or above the maximum for the requested rail. The error message includes the actual min/max. Discover both upfront via `/business/local-rails/channels`. | | `400` | — | The requested rail is not available for the given country/currency. The error message lists which rails ARE available. | | `404` | — | Collection id does not exist for your business. | > [card] [API Reference](/api-reference/local-rails/create-collection) > > Full endpoint documentation. > [card] [Payer return URL](/payments/return-url) > > Set the URL customers return to after paying. Collections `successUrl` is ignored. # Local rails — hosted checkout Source: https://docs.useaxra.com/payments/local-rails-checkout Accept bank, MoMo, and EFT through Axra's hosted checkout. Hosted checkout is the fastest way to accept local rails when you do not need to render deposit instructions yourself. Create a checkout session, send the customer to pay.useaxra.com, and let Axra show the rail picker and payment UI. ## 1. Create a checkout session `POST /business/payment/session` Set `currency` to any supported local-rail currency (see [Local payment methods](/payments/local-payment-methods) for the full list). Card checkout uses the same endpoint with `usd` or other card currencies. ```bash theme={null} 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": 10000, "currency": "ngn", "description": "Order #1042", "customerEmail": "adaobi@example.com", "successUrl": "https://yourapp.com/payment/success?session={SESSION_ID}", "cancelUrl": "https://yourapp.com/payment/cancelled", "expiresIn": 1800, "metadata": { "orderId": "1042" } }' ``` ## 2. Redirect the customer Send the customer's browser to `checkoutUrl` from the session response. The session id in the URL is the auth context for the session-scoped local-rail endpoints. ## 3. Customer pays via local rail On pay.useaxra.com the customer chooses bank transfer, mobile money, or instant EFT when the session currency supports it. Axra calls the session-bound local-rail endpoints under the hood: * `GET /checkout/sessions/{sessionId}/local-rail/channels` * `POST /checkout/sessions/{sessionId}/local-rail/initiate` * `GET /checkout/sessions/{sessionId}/local-rail/status` Your integration only needs the session create call and redirect; you do not call those endpoints unless you are building a custom checkout UI on top of a session. ## 4. Receive webhook + redirect When the collection completes, Axra redirects the customer to your `successUrl` and sends `payment_link.session.completed` to your webhook URL. Treat the webhook as authoritative — the redirect alone does not guarantee settlement. ## How currencies map to rails | Session currency | Country | Rails shown in checkout | | - | - | - | | `ngn` | Nigeria | Bank transfer (instant) | | `zar` | South Africa | Instant EFT | | `kes` | Kenya | Mobile money (M-PESA) | | `tzs` | Tanzania | Mobile money, bank | | `ugx` | Uganda | Mobile money | | `rwf` | Rwanda | Mobile money | | `mwk` | Malawi | Mobile money | | `zmw` | Zambia | Mobile money, bank | | `bwp` | Botswana | Mobile money, bank | | `xaf` | Cameroon | Mobile money | ## When to use this vs. direct API Hosted checkout is zero-effort when a redirect is acceptable. Use the [server-to-server collections API](/payments/local-rails-api) when you embed deposit instructions in your own app, run backend-to-backend flows, or need channel discovery before showing payment options. # Overview Source: https://docs.useaxra.com/payments/overview Charge cards server-to-server, confirm 3DS challenges, retrieve payment details, list transactions, and issue refunds using the Axra Pay Payments API. 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. > [!NOTE] > > The base URL for all Axra Pay API requests is `https://api.useaxra.com/api/v1`. All requests must be made over HTTPS. > [card] [Checkout sessions](/payments/checkout-sessions) > > Hosted checkout for cards and local rails. > [card] [Card payments](/payments/card-payments) > > Server-to-server card charging. > [card] [Local payment methods](/payments/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](/payments/3ds-authentication) for the full flow. > [!WARNING] > > 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 ` 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. **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. **email** `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. After 3DS the payer returns via Axra's page; we append `3ds=complete` or `3ds=failed` and `paymentId`. This URL is never shared with the card processor. **billingAddress** `object` Customer billing address. Improves authorization rates and is required by some card networks for address verification. **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* What you asked us to charge, in major currency units, matching the request. **chargedAmount** `number` *required* What the customer's card was charged. May exceed `amount` by `serviceFee`. The customer's statement shows this figure. Equals `amount` when there is no service fee. **serviceFee** `number` *required* Service fee added on top of `amount`. `chargedAmount = amount + serviceFee`. Zero when there is no uplift. Always present. **currency** `string` *required* ISO 4217 currency code. **provider** `string` Payment method family. Always `"card"` on a card charge, whichever processor handled it. **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. > [!WARNING] > > 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* **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 returns via Axra's page and is then sent to your `returnUrl` with `3ds=complete|failed` and `paymentId`. Your `returnUrl` is never shared with the card processor. ### Example ```bash cURL theme={null} 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" } }' ``` ```javascript Node.js theme={null} 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); } ``` > [!NOTE] > > S2S `returnUrl` is still honoured as the payer's destination after 3DS. The payer returns via Axra's page; we append `3ds=complete` or `3ds=failed` and `paymentId`. The URL is never shared with the card processor. **Success response** ```json theme={null} { "paymentId": "pay_01HXYZ123456", "status": "succeeded", "amount": 49.99, "currency": "usd", "provider": "card", "transactionId": "txn_9a3f21bc", "createdAt": "2026-04-14T10:23:45.000Z" } ``` **3DS required response** ```json theme={null} { "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 they return via Axra's page, then to your `returnUrl` (with `3ds=complete|failed` and `paymentId`). Call this endpoint with the `transactionId` from the original charge response to finalize the payment. Your `returnUrl` is never shared with the card processor. > [!NOTE] > > 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 ```bash cURL theme={null} 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" }' ``` ```javascript Node.js theme={null} 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); } ``` ```json theme={null} { "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 **id** `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 ```bash cURL theme={null} curl --request GET \ --url https://api.useaxra.com/api/v1/business/payment/pay_01HXYZ123456 \ --header 'x-api-key: YOUR_API_KEY' ``` ```javascript Node.js theme={null} 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); ``` ```json theme={null} { "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](#get-a-payment) response. **pagination** `object` **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 ```bash cURL theme={null} curl --request GET \ --url 'https://api.useaxra.com/api/v1/business/payments?page=1&limit=20' \ --header 'x-api-key: YOUR_API_KEY' ``` ```javascript Node.js theme={null} 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`); ``` ```json theme={null} { "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"`. > [!WARNING] > > 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 ```bash cURL theme={null} curl --request POST \ --url https://api.useaxra.com/api/v1/business/payment/pay_01HXYZ123456/refund \ --header 'x-api-key: YOUR_API_KEY' ``` ```javascript Node.js theme={null} 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); ``` ```json theme={null} { "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`. | | `422` | The refund was declined and nothing was refunded. The payment stays `COMPLETED` and no `payment.refunded` webhook is sent. | | `503` | The refund outcome could not be confirmed yet. The payment stays `COMPLETED` and no `payment.refunded` webhook is sent. Do not resubmit: our team checks the refund and follows up. | *** ## 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. > [!TIP] > > 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](mailto: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. # Local-rail payouts Source: https://docs.useaxra.com/payments/payouts/index Send African bank transfers and mobile money payouts from your USDC balance using the Business Payouts API. Pay out to local bank accounts and mobile money wallets across supported African corridors. Funds debit your merchant USDC wallet at the locked FX rate. The flow is quote → confirm: you receive a signed quote token valid for 60 seconds, then submit the payout with a saved `recipientId`, an inline `recipient`, or an inline `destination`. The quote is scoped to corridor, amount and business — not to a recipient — so one token confirms any of the three. > [!NOTE] > > The payout endpoints accept the same credentials as the rest of the API — pass your `x-api-key` header (or a JWT from token exchange) on every call. Payouts are fully server-to-server, at parity with the [Collections API](/payments/local-rails-api); no dashboard interaction is required. > [card] [Get a quote](/payments/payouts/quote) > > Lock FX before confirming a payout. > [card] [Corridors & recipient shapes](/payments/payouts/local-rails) > > Supported countries and required fields. ## Flow overview 1. **(Optional) Create a recipient** — `POST /v1/business/payouts/recipients` with bank or mobile-money details, and reuse the returned `recipientId` on every later payout. Skip this step if you send the destination inline on confirm. The call is idempotent on the destination: sending the same rail and account details returns the existing recipient rather than creating a duplicate. 2. **Request a quote** — `POST /v1/business/payouts/quote` with rail, corridor, and either `srcAmount` (USDC) or `dstAmount` (local currency). 3. **Confirm the payout** — `POST /v1/business/payouts` with `quoteToken`, **exactly one** of `recipientId`, an inline `recipient`, or an inline `destination`, and `idempotencyKey`, within the 60-second window. 4. **Track status** — poll `GET /v1/business/payouts/{id}` or subscribe to payout webhooks. > [!NOTE] > > **Sanctions screening is channel-dependent.** Requests authenticated with `x-api-key` are not screened by Axra — under your merchant agreement you are the obligated party for beneficiary screening, and an inline `recipient` or `destination` is paid ad hoc rather than saved (the payout returns `recipientId: null`). Requests made from the Axra dashboard with a user JWT are screened, and a match is refused with `403`. ## SDK quick start ```bash Node.js theme={null} npm install @useaxra/node@0.6.0 ``` ```bash Python theme={null} pip install axra==0.4.0 ``` ```typescript theme={null} import { Axra } from '@useaxra/node'; const axra = new Axra(process.env.AXRA_SECRET_KEY!); const quote = await axra.payouts.quote({ rail: 'LOCAL_BANK', country: 'NG', currency: 'NGN', srcAmount: '100.00', }); ``` ```python theme={null} from axra import Axra client = Axra(os.environ["AXRA_SECRET_KEY"]) quote = client.payouts.quote( rail="LOCAL_BANK", country="NG", currency="NGN", src_amount="100.00", ) ``` > [!NOTE] > > Collections (inbound local rails) are documented under [Local rails — server-to-server](/payments/local-rails-api). This section covers **outbound** payouts only. # Local payout corridors Source: https://docs.useaxra.com/payments/payouts/local-rails Supported destination countries and recipient field requirements for LOCAL_BANK and LOCAL_MOMO payouts. > [!WARNING] > > Corridors and limits may change. Use the quote endpoint to validate amounts before confirming payouts. ## Overview `LOCAL_BANK` and `LOCAL_MOMO` let you settle to a **local bank account** or **mobile money wallet** in a supported corridor. Your payout is funded from your business **USDC balance** using a locked FX quote (quote → confirm). Jump to: * Supported corridors table (below) * [Payout quote](/payments/payouts/quote) ## Supported corridors 19 destination countries are supported. `LOCAL_BANK` is available where we have local bank-transfer coverage; `LOCAL_MOMO` is available where the corridor has active mobile-money payout channels. Always confirm an amount with the [quote endpoint](/payments/payouts/quote) before paying out — corridor and rail availability can change. | Country | Currency | `LOCAL_BANK` | `LOCAL_MOMO` | | - | - | :-: | :-: | | Nigeria (NG) | NGN | Yes | — | | Kenya (KE) | KES | Yes | Yes | | South Africa (ZA) | ZAR | Yes | — | | Tanzania (TZ) | TZS | Yes | Yes | | Uganda (UG) | UGX | Yes | Yes | | Rwanda (RW) | RWF | Yes | Yes | | Malawi (MW) | MWK | Yes | Yes | | Zambia (ZM) | ZMW | Yes | Yes | | Botswana (BW) | BWP | Yes | Yes | | Cameroon (CM) | XAF | Yes | Yes | | Benin (BJ) | XOF | — | Yes | | Burkina Faso (BF) | XOF | — | Yes | | Côte d'Ivoire (CI) | XOF | — | Yes | | Mali (ML) | XOF | — | Yes | | Senegal (SN) | XOF | — | Yes | | Togo (TG) | XOF | — | Yes | | Gabon (GA) | XAF | — | Yes | | Republic of the Congo (CG) | XAF | — | Yes | | DR Congo (CD) | CDF | — | Yes | > [!NOTE] > > The West Africa (XOF), additional Central Africa (XAF), and DR Congo (CDF) corridors are **mobile-money only** — pay out with `LOCAL_MOMO`. Use `GET /v1/business/payouts/networks?country=&rail=LOCAL_MOMO` to list the available carriers/networks for the recipient before confirming. ## Recipient shapes per rail You can pay out in one of two ways. Both are fully supported — pick per payout, not per integration. * **Saved recipient (3 calls):** create a recipient with `POST /v1/business/payouts/recipients`, then reference it by `recipientId` on every payout. Best when you pay the same payee repeatedly. The create call is idempotent on the destination — sending the same rail and account details returns the existing recipient rather than a duplicate — so it is safe to call before every payout. * **Inline recipient (2 calls):** pass a `recipient` (or `destination`) object directly on `POST /v1/business/payouts` — no pre-created recipient needed. Best at high destination cardinality, where a saved recipient per payout is address-book noise. Provide **exactly one** of `recipientId`, `recipient`, or `destination` on confirm; sending two is rejected with `RECIPIENT_AMBIGUOUS`. The inline `recipient` uses the same fields as the saved-recipient `details` object (shown below). > [!NOTE] > > **What happens to an inline recipient depends on how you authenticate.** > > * **Merchant API (`x-api-key`)** — the inline recipient or `destination` is paid as an **ad-hoc destination**: Axra does not sanctions-screen it and does not save it, so the payout comes back with `recipientId: null` and there is nothing to reuse by id. Under your merchant agreement you are the obligated party for beneficiary screening. If you want a reusable id, call `POST /v1/business/payouts/recipients` first — the two-step flow works exactly as before. > * **Dashboard (user JWT)** — the inline recipient is created, sanctions-screened, and saved to your recipient book, and a screening match is refused with `403`. > > A `destination` object on `LOCAL_BANK` / `LOCAL_MOMO` is accepted **only** on the `x-api-key` channel. ### Get the network / bank list first For `LOCAL_BANK` and `LOCAL_MOMO`, you must select an **opaque upstream network identifier** using: `GET /v1/business/payouts/networks?country=NG&rail=LOCAL_BANK` That endpoint returns a list of supported banks or mobile-money networks for the corridor. Use the returned `id` as: * `bankCode` for `LOCAL_BANK` * `networkId` for `LOCAL_MOMO` Recipients are created with `POST /v1/business/payouts/recipients`. Use `label` to identify the payee in your dashboard. ### Local bank (`LOCAL_BANK`) ```json theme={null} { "label": "Payroll — Jane Doe", "rail": "LOCAL_BANK", "details": { "country": "NG", "accountNumber": "0123456789", "accountName": "Jane Doe", "bankCode": "058", "bankName": "GTBank" } } ``` > [!NOTE] > > `bankCode` is the `id` returned by `GET /v1/business/payouts/networks?country=NG&rail=LOCAL_BANK`. ### Local mobile money (`LOCAL_MOMO`) ```json theme={null} { "label": "Field agent — Payee", "rail": "LOCAL_MOMO", "details": { "country": "CM", "phoneNumber": "+237612345678", "accountName": "Payee Name", "networkId": "network_opaque_id", "networkName": "Network Name" } } ``` > [!NOTE] > > `phoneNumber` must be E.164 (e.g. `+254712345678`). `networkId` is the `id` returned by > `GET /v1/business/payouts/networks?country=CM&rail=LOCAL_MOMO`. ## Cross-currency quote → confirm flow Local-rail payouts use a two-step flow to lock FX and fees: 1. `POST /v1/business/payouts/quote` returns a signed `quoteToken` (valid for 60 seconds). 2. `POST /v1/business/payouts` confirms the payout by passing `quoteToken` back, along with **exactly one** of a saved `recipientId`, an inline `recipient` object, or an inline `destination`. If the quote is expired, invalid, or issued for a different business workspace, the create call fails. The quote is scoped to **corridor + amount + business** and carries no recipient, so a single `quoteToken` confirms any of the three destination shapes. Quoting first and only then deciding whether to use a saved or an inline destination is supported. ### Quote and confirm (Node + Python) ```typescript Node.js theme={null} import { Axra } from '@useaxra/node'; const axra = new Axra(process.env.AXRA_SECRET_KEY!); // 1) Quote (locks FX + fee for 60s) const quote = await axra.payouts.quote({ rail: 'LOCAL_BANK', country: 'NG', currency: 'NGN', srcAmount: '100.00', }); // 2) Confirm (references locked quote by token) const payout = await axra.payouts.create({ rail: 'LOCAL_BANK', quoteToken: quote.quoteToken, recipientId: 'rec_01H...', idempotencyKey: 'payout-ng-2026-06-02-0001', }); console.log(payout.id, payout.status); ``` ```python Python theme={null} import os from axra import Axra client = Axra(os.environ["AXRA_SECRET_KEY"]) # 1) Quote (locks FX + fee for 60s) quote = client.payouts.quote( rail="LOCAL_BANK", country="NG", currency="NGN", src_amount="100.00", ) # 2) Confirm (references locked quote by token) payout = client.payouts.create( rail="LOCAL_BANK", quote_token=quote.quote_token, recipient_id="rec_01H...", idempotency_key="payout-ng-2026-06-02-0001", ) print(payout.id, payout.status) ``` ### Single-call payout with an inline recipient Skip the separate recipient-creation call by passing the recipient inline on confirm. Exactly one of `recipientId`, `recipient`, or `destination` is required. On the `x-api-key` channel the inline recipient is paid as an ad-hoc destination — not screened by Axra, not saved, and the payout returns `recipientId: null`. See the note under [Recipient shapes per rail](#recipient-shapes-per-rail). ```typescript Node.js theme={null} const quote = await axra.payouts.quote({ rail: 'LOCAL_BANK', country: 'NG', currency: 'NGN', srcAmount: '100.00', }); const payout = await axra.payouts.create({ rail: 'LOCAL_BANK', quoteToken: quote.quoteToken, recipient: { country: 'NG', accountNumber: '0123456789', accountName: 'Jane Doe', bankCode: '058', bankName: 'Example Bank', }, idempotencyKey: 'payout-ng-2026-06-02-0001', }); ``` ```python Python theme={null} quote = client.payouts.quote( rail="LOCAL_BANK", country="NG", currency="NGN", src_amount="100.00", ) payout = client.payouts.create( rail="LOCAL_BANK", quote_token=quote.quote_token, recipient={ "country": "NG", "account_number": "0123456789", "account_name": "Jane Doe", "bank_code": "058", "bank_name": "Example Bank", }, idempotency_key="payout-ng-2026-06-02-0001", ) ``` ### Quote-token error codes These codes can be returned when confirming a payout (`POST /v1/business/payouts`) with a `quoteToken`: * `INVALID_QUOTE_TOKEN`: Token is malformed or signature validation failed. * `QUOTE_EXPIRED`: Token is older than the 60-second TTL. * `QUOTE_BUSINESS_MISMATCH`: Token was issued for a different business workspace. * `INSUFFICIENT_PAYOUT_LIQUIDITY`: Liquidity is temporarily unavailable to settle the corridor. * `TREASURY_FROZEN`: Payouts are temporarily disabled for treasury safety checks. * `PAYOUT_CORRIDOR_NOT_ENABLED`: Your business is not enabled for this corridor. ### Recipient error codes * `RECIPIENT_REQUIRED`: Neither `recipientId` nor an inline `recipient` / `destination` was provided. * `RECIPIENT_AMBIGUOUS`: More than one of `recipientId`, `recipient`, `destination` was provided. Send exactly one. * `RECIPIENT_RAIL_MISMATCH`: The inline `recipient.rail` does not match the payout `rail`. * `RECIPIENT_NOT_FOUND`: No recipient with that `recipientId` in this business workspace, or its rail differs from the payout rail. * `QUOTE_RECIPIENT_COUNTRY_MISMATCH`: The destination country does not match the country the quote was issued for. * `403 Recipient failed sanctions screening`: Returned on the **dashboard (JWT)** channel only, for a recipient that matched a sanctions/PEP list. `x-api-key` requests are not screened by Axra and never receive this. ## NG bank-name resolve (Nigeria only) To validate an NG NUBAN and resolve the account-holder name: `POST /v1/business/payouts/resolve-account` Request: ```json theme={null} { "country": "NG", "accountNumber": "0123456789", "networkId": "058" } ``` Response: ```json theme={null} { "accountNumber": "0123456789", "accountName": "JANE DOE", "accountBank": "GTBank" } ``` > [!NOTE] > > This endpoint validates `country="NG"` and rejects other countries. Mobile money has no equivalent “name resolve” API. ## Idempotency `idempotencyKey` is **required** on `POST /v1/business/payouts`. * Reusing the same key returns the original payout record for that key. * Use a new key for every user-initiated payout attempt to avoid accidental deduping. ## 2FA threshold The **\$10,000 USD-equivalent** TOTP requirement applies **only to interactive dashboard payouts**. When a human initiates a payout at or above this amount from the Axra dashboard, a fresh TOTP code (`twoFactorCode`) is required, and a missing code returns `401` with `code: "TWO_FACTOR_REQUIRED"`. > [!NOTE] > > **Server-to-server payouts (API key) are exempt from the 2FA gate.** For programmatic payouts there is no interactive TOTP step at any amount — the controls are your secret API key and per-corridor velocity caps. You never need to send `twoFactorCode` from a server integration. Axra does not sanctions-screen destinations on this channel; under your merchant agreement beneficiary screening is your obligation. ## Settlement webhooks Local-rail payouts emit the same business payout events as other rails. Subscribe via [Webhooks](/manage/webhooks). Event types: * `payout.initiated` — payout accepted and ledger-debited (status `CREATED`). * `payout.submitted` — dispatched to the payout provider (status `SUBMITTED`). * `payout.settled` — funds delivered to the recipient (status `SETTLED`). * `payout.failed` — dispatch or settlement failed; the debit is reversed (status `FAILED`). * `payout.cancelled` — a `CREATED` payout was cancelled before dispatch (status `CANCELLED`). * `payout.review` — payout held for compliance/admin review (status `PENDING_REVIEW`). The `data.object` of each event is the same shape as `GET /v1/business/payouts/{id}`. ## Fee model Merchants see **only the aggregated total** via `GET /v1/business/psp-pricing`. Rates are set per-merchant (your SLA), and the quote response includes the total Axra fee for the corridor. ## Confirm payout (raw API) After quoting, confirm with **either** a saved `recipientId` **or** an inline `recipient` object (exactly one). Saved recipient: ```json theme={null} { "rail": "LOCAL_BANK", "quoteToken": "", "recipientId": "", "idempotencyKey": "merchant-supplied-unique-key" } ``` Inline recipient. Note the **nested** `{ label, rail, details }` shape on the raw API — the SDKs accept the flat form shown above and map it for you, so copying the SDK shape into a raw request returns `400`. On the `x-api-key` channel this is paid ad hoc: not screened by Axra, not saved, `recipientId: null` on the payout. ```json theme={null} { "rail": "LOCAL_BANK", "quoteToken": "", "recipient": { "label": "Jane Doe", "rail": "LOCAL_BANK", "details": { "country": "NG", "accountNumber": "0123456789", "accountName": "Jane Doe", "bankCode": "058", "bankName": "Example Bank" } }, "idempotencyKey": "merchant-supplied-unique-key" } ``` > [!NOTE] > > Full integration guides and webhook event reference will be expanded in a later docs release. For OpenAPI field-level detail, see the [API Reference](/api-reference) tab. # Payout quote Source: https://docs.useaxra.com/payments/payouts/quote Lock FX for 60 seconds before confirming a local-rail payout. `POST /v1/business/payouts/quote` Returns a signed `quoteToken`, destination amount, rate, fee, and `expiresAt`. Pass the token to `POST /v1/business/payouts` within 60 seconds to lock the rate. ## Request Provide exactly one of `srcAmount` (USDC debited from your wallet) or `dstAmount` (local currency the recipient receives). `srcCurrency` defaults to `USDC`. | Field | Required | Description | | - | - | - | | `rail` | Yes | `LOCAL_BANK` or `LOCAL_MOMO` | | `country` | Yes | ISO-2 destination country (e.g. `NG`) | | `currency` | Yes | Local currency code (e.g. `NGN`) | | `srcAmount` | XOR | USDC amount as decimal string (e.g. `"100.00"`) | | `dstAmount` | XOR | Local amount as decimal string | ## Responses | HTTP | Meaning | | - | - | | `200` | Quote issued — use `data.quoteToken` on create | | `400` | Invalid corridor or amount | | `410` | Quote token expired or invalid (on create, not quote) | | `503` | FX rate temporarily unavailable for corridor | ```bash cURL theme={null} curl -X POST https://api.useaxra.com/api/v1/business/payouts/quote \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "rail": "LOCAL_BANK", "country": "NG", "currency": "NGN", "srcCurrency": "USDC", "srcAmount": "100.00" }' ``` ```typescript Node.js theme={null} import { Axra } from '@useaxra/node'; const axra = new Axra(process.env.AXRA_SECRET_KEY!); const quote = await axra.payouts.quote({ rail: 'LOCAL_BANK', country: 'NG', currency: 'NGN', srcAmount: '100.00', }); console.log(quote.quoteToken, quote.dstAmount, quote.expiresAt); ``` ```python Python theme={null} from axra import Axra client = Axra(os.environ["AXRA_SECRET_KEY"]) quote = client.payouts.quote( rail="LOCAL_BANK", country="NG", currency="NGN", src_amount="100.00", ) print(quote.quote_token, quote.dst_amount, quote.expires_at) ``` ```json Response theme={null} { "success": true, "data": { "quoteToken": "eyJ...", "srcAmount": "100.00", "dstAmount": "165000.00", "rate": "0.000606", "axraFee": "1.50", "expiresAt": "2026-06-01T12:01:00.000Z", "rail": "LOCAL_BANK", "country": "NG", "currency": "NGN" } } ``` > [card] [API Reference](/api-reference/business-payouts/quote) > > Full OpenAPI schema. # Payer return URL Source: https://docs.useaxra.com/payments/return-url Set once where customers return after paying. Collections successUrl is ignored; S2S card returnUrl still works. Set a payer return URL once on your business. After a local-rails collection, customers are sent there. If you leave it empty, they see Axra's payment confirmation page. ## Set it **Dashboard:** Settings → Payer return URL. **API:** ```bash theme={null} curl -X PUT https://api.useaxra.com/api/v1/business/config \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "returnUrl": "https://pay.yourdomain.com/done" }' ``` The URL must be `https` on your verified business website domain (the registrable domain of your KYB website). Subdomains of that domain are allowed. Send `"returnUrl": null` to clear it. `GET /v1/business/config` returns `returnUrl` and `verifiedDomain`. ## Collections `successUrl` is ignored `POST /v1/business/collections` still accepts `successUrl`, but the field is **deprecated and ignored**. The payer is returned to the business return URL, or to Axra's confirmation page if none is configured. ## Card 3DS `returnUrl` still works Server-to-server card charges (`POST /v1/business/payment/charge`) still honour per-request `returnUrl` as the payer's destination after 3DS. After the challenge the payer returns via Axra's page; we append `3ds=complete` or `3ds=failed` and `paymentId`. That URL is never shared with the card processor. ## Checkout sessions are unchanged `CheckoutSession.successUrl` and `cancelUrl` still work. They are not gated by this setting. ## Errors | Code | Meaning | | - | - | | `RETURN_URL_INVALID` | Not an https URL (or it has credentials, a fragment, an IP, or localhost). | | `RETURN_URL_DOMAIN_MISMATCH` | Host is not on your verified KYB domain. | | `RETURN_URL_DOMAIN_UNVERIFIED` | No verified business website is on file. | # Quickstart Source: https://docs.useaxra.com/quickstart Charge a card or create a Treasury partner in under 5 minutes ## Option 1: Accept a payment **1. Install the Node SDK** ```bash theme={null} npm install @useaxra/node ``` **2. Create a payment** ```typescript theme={null} import { Axra } from '@useaxra/node'; const axra = new Axra('sk_test_...'); const payment = await axra.payments.create({ amount: 5000, // $50.00 in cents currency: 'USD', source: 'pm_card_visa', }); console.log(`Payment ${payment.id}: ${payment.status}`); ``` ## Option 2: Treasury — build a banking product **1. Sign up as a Treasury partner** ```bash theme={null} curl -X POST https://api.useaxra.com/api/v1/treasury/signup \ -H "Content-Type: application/json" \ -d '{"name":"My Fintech","slug":"my-fintech"}' ``` Save the returned `secretKey` (`sk_test_...`). **2. Create an end-user** ```bash theme={null} curl -X POST https://api.useaxra.com/api/v1/treasury/users \ -H "Authorization: Bearer sk_test_..." \ -H "Content-Type: application/json" \ -d '{"externalId":"user_123","email":"jane@example.com","name":"Jane Doe"}' ``` **3. Run KYC (sandbox auto-approves)** ```bash theme={null} curl -X POST https://api.useaxra.com/api/v1/treasury/users/{id}/kyc \ -H "Authorization: Bearer sk_test_..." \ -H "Content-Type: application/json" \ -d '{"applicant":{"firstName":"Jane","lastName":"Doe","email":"approve@sandbox.useaxra.com"}}' ``` Using `approve@sandbox.useaxra.com` auto-approves in sandbox. **4. Create a wallet and fund it** ```bash theme={null} # Create wallet curl -X POST https://api.useaxra.com/api/v1/treasury/users/{id}/wallets \ -H "Authorization: Bearer sk_test_..." \ -d '{"currency":"NGN"}' # Sandbox credit curl -X POST https://api.useaxra.com/api/v1/treasury/users/{id}/wallets/{walletId}/sandbox-credit \ -H "Authorization: Bearer sk_test_..." \ -d '{"amount":"1000","currency":"NGN"}' ``` ## Sandbox fixtures | Email | KYC outcome | | - | - | | `approve@sandbox.useaxra.com` | Instantly approved | | `reject@sandbox.useaxra.com` | Instantly rejected with reason | | `pending@sandbox.useaxra.com` | Stays pending — use `sandbox-approve` to advance | | Payout metadata | Outcome | | - | - | | `{ "test_outcome": "fail_insufficient_funds" }` | Payout fails immediately | | `{ "test_outcome": "delay_24h" }` | Payout completes after 24h delay | | *(none)* | Payout completes after 2s | # Error Codes Source: https://docs.useaxra.com/reference/error-codes Payment error codes returned by the Axra API This document lists all payment error codes returned by the Axra Business Payments API. These codes appear in charge and refund responses when a payment fails. *** ## Error Response Format When a charge or refund fails, the response includes an `error` object: ```json theme={null} { "paymentId": "bpay_01H...", "status": "failed", "amount": 49.99, "currency": "usd", "transactionId": "", "error": { "code": "card_declined", "message": "The card was declined by the issuing bank.", "isRetryable": false } } ``` | Field | Type | Description | | - | - | - | | `code` | string | Normalized Axra error code (see table below) | | `message` | string | Human-readable error message | | `isRetryable` | boolean | Whether the operation can be retried with the same inputs | *** ## Payment Error Codes ### Card Errors | Code | Description | Retryable | Suggested Action | | - | - | - | - | | `card_declined` | The card was declined by the issuing bank | No | Ask customer to use a different card or contact their bank | | `insufficient_funds` | The card has insufficient funds to complete the transaction | No | Ask customer to use a different card or add funds | | `invalid_card` | The card number is invalid or does not match any known card type | No | Ask customer to re-enter card details | | `expired_card` | The card has expired | No | Ask customer to use a non-expired card | | `invalid_cvv` | The CVV/CVC code is incorrect | No | Ask customer to re-enter the CVV | | `lost_stolen_card` | The card has been reported lost or stolen | No | Ask customer to use a different card | ### Authentication Errors | Code | Description | Retryable | Suggested Action | | - | - | - | - | | `authentication_required` | The transaction requires 3D Secure authentication | No | Redirect customer to the 3DS challenge URL | ### Processing Errors | Code | Description | Retryable | Suggested Action | | - | - | - | - | | `processing_error` | A generic processing error occurred | Yes | Retry after a brief delay | | `rate_limit` | Too many requests in a short period | Yes | Wait and retry with exponential backoff | | `provider_unavailable` | The payment processor is temporarily unreachable | Yes | Retry later | ### Validation Errors | Code | Description | Retryable | Suggested Action | | - | - | - | - | | `invalid_amount` | The charge amount is invalid (e.g., negative, zero, too large) | No | Correct the amount and retry | | `invalid_currency` | The currency code is not supported | No | Use a supported currency code (ISO 4217) | ### Transaction Errors | Code | Description | Retryable | Suggested Action | | - | - | - | - | | `duplicate_transaction` | A transaction with these parameters was already processed | No | The original payment was likely successful. Check existing payments before retrying | | `refund_exceeds_amount` | The refund amount exceeds the original charge amount | No | Reduce the refund amount | | `transaction_not_found` | The referenced transaction was not found | No | Verify the transaction ID is correct | ### Configuration Errors | Code | Description | Retryable | Suggested Action | | - | - | - | - | | `configuration_error` | Merchant payment configuration is missing or invalid | No | Verify payment settings in the Axra dashboard | ### Catch-All | Code | Description | Retryable | Suggested Action | | - | - | - | - | | `unknown` | An unexpected error occurred | No | Contact Axra support with the payment details | *** ## HTTP Error Codes In addition to payment-specific errors, the API returns standard HTTP error codes: ### 400 Bad Request Returned when the request is malformed or contains invalid data. ```json theme={null} { "statusCode": 400, "message": "Cannot refund a payment with status \"PENDING\"", "error": "Bad Request" } ``` **Common causes:** * Missing required fields (`amount`, `currency`, `card`) * Invalid field values (negative amount, expired card date) * Invalid state transition (refunding a non-completed payment) * Checkout session expired or already completed * S2S charging not enabled for your business * Payment older than 180-day refund window * Too many payment attempts on a checkout session (rate limited to 5 per 15 minutes) ### 401 Unauthorized Returned when authentication fails. ```json theme={null} { "statusCode": 401, "message": "Invalid API key or secret", "error": "Unauthorized" } ``` **Common causes:** * Invalid or missing `x-api-key` header * Expired JWT token * Invalid API key / secret combination * Business profile deactivated ### 404 Not Found Returned when the requested resource does not exist. ```json theme={null} { "statusCode": 404, "message": "Payment not found", "error": "Not Found" } ``` **Common causes:** * Invalid payment ID * Payment belongs to a different business * Checkout session does not exist ### 409 Conflict Returned when the operation conflicts with existing state. ```json theme={null} { "statusCode": 409, "message": "Business profile already exists for this user", "error": "Conflict" } ``` **Common causes:** * Attempting to create a duplicate business profile *** ## Dispute-Related Errors Disputes are not errors per se, but they have financial consequences: | Event | Merchant Impact | | - | - | | `payment.disputed` | Full charge amount debited + dispute fee | | `payment.dispute_won` | Full charge amount re-credited (dispute fee NOT refunded) | | `payment.dispute_lost` | No further changes (charge + fee already debited) | Dispute fees are non-refundable regardless of outcome. The best defense against disputes is: 1. Use 3DS authentication (shifts fraud liability to issuer) 2. Provide clear billing descriptors 3. Respond to disputes promptly with evidence 4. Maintain records of customer transactions and communication *** ## Debugging Tips 1. **Look at `isRetryable`:** Only retry when this is `true`. Retrying non-retryable errors wastes quota and may trigger rate limits. 2. **Use test cards:** Test card numbers trigger specific error scenarios. See the [API Reference](./api-reference.md#testing) for the full list. 3. **Review webhook delivery logs:** Failed webhook deliveries are logged and visible in the Axra dashboard. 4. **Contact support:** For `unknown` errors or persistent `configuration_error`, contact Axra support with the `paymentId` and `transactionId`. # Testing Source: https://docs.useaxra.com/reference/testing Use sandbox API keys, test cards, and local webhook tunnels to fully validate your Axra Pay integration before switching to live credentials. Before you go live, you should exercise every payment flow your integration supports — successful charges, declines, 3DS challenges, refunds, and webhook delivery — against the Axra sandbox environment. The sandbox uses the same API surface as production, so code that works in testing will work in production without modification. This page walks you through the test environment setup, available test cards, and a pre-launch checklist to make sure nothing is missed. ## Test environment Axra provides a fully isolated sandbox environment. Test mode does not process real payments and will never charge a real card. | Setting | Value | | - | - | | Test base URL | `https://staging-api.useaxra.com` | | Production base URL | `https://api.useaxra.com/api/v1` | | API key prefix | `bk_test_` | Obtain your sandbox API keys from the **API Keys** section of the [Axra dashboard](https://app.useaxra.com). Test keys are prefixed with `bk_test_` to distinguish them from live keys (`bk_live_`). > [!WARNING] > > Never use a live API key in a test or development environment, and never use a test API key in production. Test keys are rate-limited differently and will not process real funds. ## Test cards Use these card numbers in the sandbox to trigger specific payment outcomes. For all test cards, use any future expiry date and any 3-digit CVV. | Card number | Result | | - | - | | `4242 4242 4242 4242` | Successful charge, no 3DS required | | `4000 0000 0000 0002` | Card declined | | `4000 0025 0000 3155` | 3DS authentication required — succeeds | | `4000 0082 6000 3178` | 3DS authentication required — fails | | `4000 0000 0000 9995` | Insufficient funds | | `4000 0000 0000 3220` | 3DS2 required | > [!TIP] > > In test mode, 3DS challenges are auto-completed by the sandbox — you are not redirected to a real bank page. This lets you test the full authentication flow without any manual steps. ## Testing the full checkout flow Use this flow to verify your end-to-end checkout session integration: **1. Create a checkout session** Call `POST /business/payment/session` with your test API key. Use a valid amount and currency. **2. Open the checkout URL** Open the `checkoutUrl` from the response in a browser. You will see Axra's hosted payment page. **3. Enter a test card** Enter one of the test card numbers from the table above. Use any future expiry date and any 3-digit CVV. **4. Complete the payment** Submit the form. If you used a 3DS card, the sandbox will auto-complete the authentication challenge. **5. Verify the webhook** Confirm that your server receives a `payment.completed` webhook event. Check that you return a `2xx` response within 30 seconds, and that your application correctly updates the order or fulfillment status. ## Testing a direct charge For server-to-server (S2S) charging, you can test the charge endpoint directly with `curl`: ```bash theme={null} # Test a successful charge curl -X POST https://staging-api.useaxra.com/business/payment/charge \ -H "x-api-key: bk_test_your_test_key" \ -H "Content-Type: application/json" \ -d '{ "amount": 49.99, "currency": "usd", "card": { "number": "4242424242424242", "expiryMonth": 12, "expiryYear": 2028, "cvv": "123" }, "email": "test@example.com" }' ``` Replace `bk_test_your_test_key` with your actual sandbox API key. Swap out the card number to trigger a different outcome — for example, use `4000000000000002` to test your declined-card handling. > [!NOTE] > > S2S charging must be enabled for your business in the Axra dashboard before you can use the charge endpoint. If you receive a `400` with a message about S2S not being enabled, contact [support@useaxra.com](mailto:support@useaxra.com). ## Testing webhooks locally Your local development server is not reachable from the internet by default. Use [ngrok](https://ngrok.com) to create a public tunnel to your local machine. **1. Install and start ngrok** Download ngrok from [ngrok.com](https://ngrok.com), then expose your local server: ```bash theme={null} ngrok http 3000 ``` ngrok will print a public URL such as `https://abc123.ngrok.io`. **2. Set your webhook URL** In the Axra dashboard, open your business profile settings and set the **Webhook URL** to your ngrok tunnel with your webhook path appended — for example: ``` https://abc123.ngrok.io/webhook ``` **3. Trigger a test payment** Create a checkout session or fire a test charge. Axra will send webhook events to your ngrok URL, which forwards them to your local server. **4. Inspect the delivery** The ngrok web interface at `http://localhost:4040` shows every request and response in real time. Use it to inspect the payload and debug your signature verification logic. > [!WARNING] > > ngrok URLs change each time you restart the tunnel (unless you have a paid plan with reserved domains). Update your webhook URL in the dashboard whenever your tunnel URL changes. ## Verifying idempotency Axra deduplicates charge requests within a 1-minute window based on the request parameters. To verify this is working: 1. Send the same charge request twice with identical parameters within 60 seconds. 2. Confirm that both responses return the **same `paymentId`** — this means the second request returned the cached result rather than creating a new charge. 3. Check that no duplicate payment appears in your dashboard. This behavior protects against double-charges caused by network retries. Make sure your application handles idempotent responses correctly — do not treat a repeated `paymentId` as an error. ## Pre-launch checklist Before switching to your live API key, verify that your integration handles each of these scenarios correctly: | Scenario | What to verify | | - | - | | Successful payment flow | `payment.completed` webhook received; order fulfilled | | 3DS authentication flow | Customer redirected and authenticated; payment confirmed via webhook | | Card declined | User shown an appropriate error; no order created | | Insufficient funds | User shown an appropriate error; no order created | | Webhook signature verification | Your endpoint rejects requests with an invalid `X-Axra-Signature` | | Refund flow | Refund created via API; `payment.refunded` webhook received | | Checkout session creation and redirect | Session created; `checkoutUrl` opens the hosted payment page correctly | > [!TIP] > > Run through the full checklist with both a success card (`4242424242424242`) and a decline card (`4000000000000002`) to make sure your application responds correctly to both outcomes. # CLI Source: https://docs.useaxra.com/sdks/cli Login, forward webhooks locally, and trigger test events from the command line ## Installation ```bash theme={null} npm install -g @useaxra/cli ``` ## Commands ### Login Save your API key for future commands: ```bash theme={null} axra login --api-key sk_test_... ``` Credentials are stored in `~/.config/axra/credentials.json` with `0600` permissions. You can also use environment variables: ```bash theme={null} export AXRA_API_KEY=sk_test_... export AXRA_API_BASE=https://api.useaxra.com # optional ``` ### Listen (webhook forwarding) Forward webhook events to your local development server: ```bash theme={null} axra listen --forward-to http://localhost:3000/webhooks ``` This opens a WebSocket connection to the Axra API and forwards every webhook event to your local URL with the `Axra-Signature` header intact — so you can test signature verification locally. ### Trigger (test events) Send a test webhook event to your active `axra listen` session: ```bash theme={null} axra trigger payment.completed ``` Available test events: | Event | Description | | - | - | | `payment.completed` | Successful payment | | `payment.failed` | Failed payment (card declined) | | `treasury.payout.completed` | Payout completed | | `treasury.payout.failed` | Payout failed | | `treasury.wallet.deposit.completed` | Wallet deposit received | | `treasury.user.created` | New end-user created | ## Full workflow ```bash theme={null} # Terminal 1: start webhook listener axra listen --forward-to http://localhost:3000/webhooks # Terminal 2: trigger a test event axra trigger payment.completed # Your local server receives the event with valid signature ``` > [!TIP] > > Use `axra listen` during development instead of exposing your local server with ngrok. It's faster and doesn't require port forwarding. # Node.js SDK Source: https://docs.useaxra.com/sdks/node Install @useaxra/node and start accepting payments in minutes ## Installation ```bash theme={null} npm install @useaxra/node ``` ## Quick start ```typescript theme={null} import { Axra } from '@useaxra/node'; const axra = new Axra('sk_test_...', { baseUrl: 'https://api.useaxra.com', }); // Create a payment const payment = await axra.payments.create({ amount: 5000, currency: 'USD', }); ``` ## Configuration | Option | Type | Default | Description | | - | - | - | - | | `baseUrl` | `string` | `https://api.useaxra.com` | API base URL | | `apiVersion` | `string` | `2026-04-15` | Sent as `Axra-Version` header | | `maxNetworkRetries` | `number` | `2` | Automatic retries on 5xx errors | ## Treasury API ```typescript theme={null} const axra = new Axra('sk_test_...'); // partner secret key // Create an end-user const user = await axra.treasury.users.service.treasuryUsersControllerCreate({ requestBody: { externalId: 'user_123', email: 'jane@example.com', name: 'Jane Doe', }, }); ``` ## Webhook signature verification ```typescript theme={null} import { verifyAxraWebhookSignature, constructWebhookEvent } from '@useaxra/node'; app.post('/webhooks', (req, res) => { const signature = req.headers['axra-signature']; const event = constructWebhookEvent( 'whsec_your_signing_secret', req.body, signature, ); switch (event.type) { case 'payment.completed': break; case 'treasury.payout.completed': break; } res.status(200).send('ok'); }); ``` ## Available services | Namespace | Description | | - | - | | `axra.payments` | Card payments and deposits | | `axra.collections` | Inbound local-rail collections | | `axra.payouts` | Outbound local-rail payouts — `quote`, `create` (saved `recipientId` or inline `recipient`; inline is paid ad hoc and not saved on the `x-api-key` channel), `get`, `list`, `cancel` | | `axra.recipients` | Saved payout recipients — `create` (idempotent on the destination), `get`, `list` | | `axra.withdrawals` | Withdrawal operations | | `axra.transfers` | Transfer operations | | `axra.fxRates` | FX rate lookups | | `axra.kyc` | KYC verification | | `axra.webhookEndpoints` | Webhook endpoint management | | `axra.treasury.users` | Treasury end-user CRUD | | `axra.treasury.kyc` | Treasury KYC | | `axra.treasury.wallets` | Treasury wallets | | `axra.treasury.payouts` | Treasury payouts | # Pay.js Source: https://docs.useaxra.com/sdks/pay-js Embed secure, PCI-scoped card input fields directly in your payment form ## Installation ```bash theme={null} npm install @useaxra/pay-js ``` Or load via CDN: ```html theme={null} ``` ## Quick start ```html theme={null}
``` ## Element types | Type | Description | Min height | | - | - | - | | `card` | Card number, expiry, CVC | 48px | | `payment` | Card + cardholder name + postal code | 120px | | `paymentRequestButton` | Apple Pay / Google Pay button | 40px | ## Configuration ```typescript theme={null} const axra = Axra('pk_test_...', { elementsHost: 'https://pay.useaxra.com', // default apiBaseUrl: 'https://api.useaxra.com', // default }); ``` ## Server-side session creation Before mounting Elements, create a session from your server: ```bash theme={null} curl -X POST https://api.useaxra.com/api/v1/elements/session \ -H "Content-Type: application/json" \ -d '{ "publishableKey": "pk_test_...", "amount": 19.99, "currency": "usd" }' ``` Response: ```json theme={null} { "id": "es_abc123...", "expiresInSeconds": 900 } ``` ## Tokenization response ```typescript theme={null} // Success { token: { id: "tok_abc123..." } } // Error { error: { code: "invalid_card", message: "Card number is invalid" } } ``` > [!WARNING] > > Never send raw card numbers to your server. Always tokenize with Pay.js first, then send the token ID. # Python SDK Source: https://docs.useaxra.com/sdks/python Install the axra Python package and integrate in minutes ## Installation ```bash theme={null} pip install axra ``` ## Quick start ```python theme={null} from axra import Axra client = Axra(api_key="sk_test_...") # Create a payment payment = client.payments.create( amount=5000, currency="usd", ) print(payment.id) ``` ## Configuration | Option | Type | Default | Description | | - | - | - | - | | `api_key` | `str` | required | Your secret API key | | `base_url` | `str` | `https://api.useaxra.com` | API base URL | | `api_version` | `str` | `2026-04-15` | Sent as `Axra-Version` header | | `max_network_retries` | `int` | `2` | Automatic retries on 5xx | | `timeout_seconds` | `float` | `60.0` | Request timeout | ## Local-rail payouts `client.payouts` and `client.recipients` send outbound local-rail payouts. Pay a saved recipient by `recipient_id`, or pass `recipient=` inline to quote and pay in a single call. On the `x-api-key` channel an inline recipient is paid as an ad-hoc destination — not screened by Axra and not saved, so the payout returns `recipient_id: None`; use `client.recipients.create(...)` first if you need a reusable id. See [Local-rail payouts](/payments/payouts/local-rails) for corridors and recipient fields. ```python theme={null} quote = client.payouts.quote( rail="LOCAL_BANK", country="NG", currency="NGN", src_amount="100.00", ) payout = client.payouts.create( rail="LOCAL_BANK", quote_token=quote.quote_token, recipient={ "country": "NG", "account_number": "0123456789", "account_name": "Jane Doe", "bank_code": "058", "bank_name": "Example Bank", }, idempotency_key="payout-ng-2026-06-02-0001", ) print(payout.id, payout.status) ``` | Method | Description | | - | - | | `client.payouts.quote(...)` | Lock an FX quote (60s) for a local-rail payout | | `client.payouts.create(...)` | Confirm a payout — saved `recipient_id` or inline `recipient` | | `client.payouts.get(id)` / `client.payouts.list(...)` | Retrieve / list payouts | | `client.recipients.create(...)` | Save a reusable payout recipient | ## Webhook signature verification ```python theme={null} from axra.webhooks import construct_event @app.route("/webhooks", methods=["POST"]) def handle_webhook(): signature = request.headers.get("Axra-Signature") event = construct_event( payload=request.data, signature_header=signature, secret="whsec_your_signing_secret", ) if event["type"] == "payment.completed": # handle payment pass return "ok", 200 ``` ## Full API access The Python SDK includes a fully generated API client for all endpoints: ```python theme={null} # Access the full generated client response = client.http.get("/api/v1/treasury/whoami") ``` # End-users Source: https://docs.useaxra.com/treasury/end-users Create and manage end-users for your Treasury integration End-users represent your customers within the Axra Treasury system. Each end-user can have KYC verification, wallets, and payouts. ## Create an end-user ```bash theme={null} curl -X POST https://api.useaxra.com/api/v1/treasury/users \ -H "Authorization: Bearer sk_test_..." \ -H "Content-Type: application/json" \ -d '{ "externalId": "user_123", "email": "jane@example.com", "name": "Jane Doe" }' ``` **Response:** ```json theme={null} { "id": "eu_abc123", "partnerId": "p_xyz", "externalId": "user_123", "email": "jane@example.com", "name": "Jane Doe", "status": "ACTIVE" } ``` ## Partner isolation Every API call is scoped to your partner. You cannot access another partner's end-users. This is enforced at the database level — Partner A receives `404` when querying Partner B's user IDs. > [card] [API Reference](/api-reference/treasury/create-end-user) > > See full endpoint documentation with request/response schemas. # KYC Source: https://docs.useaxra.com/treasury/kyc Run identity verification for your end-users KYC (Know Your Customer) verification is required before end-users can receive deposits or make payouts. Axra runs KYC through our compliance pipeline and returns a status you can poll. ## Initiate KYC ```bash theme={null} curl -X POST https://api.useaxra.com/api/v1/treasury/users/{id}/kyc \ -H "Authorization: Bearer sk_test_..." \ -H "Content-Type: application/json" \ -d '{ "applicant": { "firstName": "Jane", "lastName": "Doe", "email": "jane@example.com" } }' ``` ## Sandbox fixtures | Email | KYC outcome | | - | - | | `approve@sandbox.useaxra.com` | Instantly approved | | `reject@sandbox.useaxra.com` | Instantly rejected with reason | | `pending@sandbox.useaxra.com` | Stays pending — use `sandbox-approve` to advance | ## Manual sandbox approval ```bash theme={null} curl -X POST https://api.useaxra.com/api/v1/treasury/users/{id}/kyc/sandbox-approve \ -H "Authorization: Bearer sk_test_..." ``` > [card] [API Reference](/api-reference/treasury/initiate-kyc) > > See full endpoint documentation. # Overview Source: https://docs.useaxra.com/treasury/overview Build banking products with Axra Treasury — KYC, wallets, payouts, and compliance ## What is Treasury? Axra Treasury is a Banking-as-a-Service (BaaS) API that lets fintechs build banking products for their users. You manage the product experience — Axra handles KYC, wallets, payouts, and compliance. ## How it works **1. Sign up as a partner** Self-service sandbox signup — get `sk_test_*` and `pk_test_*` keys immediately. No human approval needed for test mode. **2. Create end-users** Create user accounts for your customers via the API. Each user gets KYC verification through our compliance pipeline. **3. Provision wallets** Create multi-currency wallets (USDC, NGN, EUR, etc.) for your users. Each wallet supports deposits via bank transfer, crypto, or mobile money. **4. Process payouts** Initiate payouts to bank accounts, mobile money, or crypto addresses. Axra routes to the optimal rail automatically. ## Key concepts | Concept | Description | | - | - | | **Partner** | Your organization. Has API keys, fee schedule, velocity limits. | | **End-user** | Your customer. Has KYC status, wallets, transaction history. | | **Wallet** | A currency-scoped balance container. Supports deposits and withdrawals. | | **Payout** | A withdrawal from a wallet to an external destination (bank, mobile money, crypto). | ## Partner isolation Every API call is scoped to your partner. You cannot see or access another partner's end-users, wallets, or payouts. This is enforced at the database level. ## Sandbox Test mode is fully functional without touching real payment rails: * KYC fixtures for instant approve/reject * Sandbox wallet credits (no real deposits needed) * Payout simulation with configurable outcomes * Webhook events fire to your registered endpoints # Payouts Source: https://docs.useaxra.com/treasury/payouts Send money from end-user wallets to bank accounts, mobile money, or crypto Payouts withdraw funds from an end-user's wallet to an external destination. Axra routes to the optimal rail automatically based on the destination (bank, crypto, mobile money) and the destination currency. ## Create a payout ```bash theme={null} curl -X POST https://api.useaxra.com/api/v1/treasury/payouts \ -H "Authorization: Bearer sk_test_..." \ -H "Content-Type: application/json" \ -d '{ "partnerEndUserId": "eu_abc123", "partnerWalletId": "w_xyz", "amount": "100", "destinationType": "mobile_money", "destination": { "country": "NG", "accountNumber": "+2348000000000", "accountName": "Jane Doe", "networkName": "MTN" } }' ``` ## Sandbox payout outcomes Control results in sandbox with `metadata.test_outcome`: | Value | Behavior | | - | - | | *(none)* | Completes after 2 seconds | | `fail_insufficient_funds` | Fails immediately, reverses ledger | | `delay_24h` | Completes after 24 hours | > [card] [API Reference](/api-reference/treasury/create-payout) > > See full endpoint documentation. # Sandbox Source: https://docs.useaxra.com/treasury/sandbox Test your Treasury integration end-to-end without real money Sandbox mode lets you integrate every Treasury endpoint without touching real payment rails. No upstream provider calls are made — all outcomes are simulated. ## Getting sandbox keys ```bash theme={null} curl -X POST https://api.useaxra.com/api/v1/treasury/signup \ -H "Content-Type: application/json" \ -d '{"name": "My Fintech", "slug": "my-fintech"}' ``` Returns `sk_test_*` and `pk_test_*` keys immediately. No approval needed. ## KYC fixtures | Email | Outcome | | - | - | | `approve@sandbox.useaxra.com` | Instant approval | | `reject@sandbox.useaxra.com` | Instant rejection | | `pending@sandbox.useaxra.com` | Pending — call `sandbox-approve` to advance | ## Sandbox wallet credit ```bash theme={null} curl -X POST .../wallets/{walletId}/sandbox-credit \ -H "Authorization: Bearer sk_test_..." \ -d '{"amount": "5000", "currency": "NGN"}' ``` ## Payout simulation | `metadata.test_outcome` | Result | | - | - | | *(empty)* | Completes in 2s | | `fail_insufficient_funds` | Fails + reverses ledger | | `delay_24h` | Completes after 24h | ## Webhook events All sandbox events fire to your registered webhook endpoints — same format as production. # Wallets Source: https://docs.useaxra.com/treasury/wallets Create multi-currency wallets for your end-users Each end-user can have wallets in multiple currencies (USDC, NGN, EUR, etc.). Wallets hold balances and support deposits via bank transfer, crypto, or mobile money. ## Create a wallet ```bash theme={null} curl -X POST https://api.useaxra.com/api/v1/treasury/users/{id}/wallets \ -H "Authorization: Bearer sk_test_..." \ -H "Content-Type: application/json" \ -d '{"currency": "NGN"}' ``` ## Check balance ```bash theme={null} curl https://api.useaxra.com/api/v1/treasury/users/{id}/wallets/{walletId}/balance \ -H "Authorization: Bearer sk_test_..." ``` ## Sandbox credit Fund a wallet in sandbox without real deposits: ```bash theme={null} curl -X POST .../wallets/{walletId}/sandbox-credit \ -H "Authorization: Bearer sk_test_..." \ -d '{"amount": "1000", "currency": "NGN"}' ``` > [card] [API Reference](/api-reference/treasury/create-wallet) > > See full endpoint documentation.