Documentation Index
Fetch the complete documentation index at: https://docs.useaxra.com/llms.txt
Use this file to discover all available pages before exploring further.
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.
When a charge or refund fails, the response includes an error object:
{
"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.
{
"statusCode": 400,
"message": "Cannot refund a payment with status \"PENDING\"",
"error": "Bad Request"
}
- 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.
{
"statusCode": 401,
"message": "Invalid API key or secret",
"error": "Unauthorized"
}
- 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.
{
"statusCode": 404,
"message": "Payment not found",
"error": "Not Found"
}
- Invalid payment ID
- Payment belongs to a different business
- Checkout session does not exist
409 Conflict
Returned when the operation conflicts with existing state.
{
"statusCode": 409,
"message": "Business profile already exists for this user",
"error": "Conflict"
}
- Attempting to create a duplicate business profile
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) |
- Use 3DS authentication (shifts fraud liability to issuer)
- Provide clear billing descriptors
- Respond to disputes promptly with evidence
- Maintain records of customer transactions and communication
Debugging Tips
- Look at
isRetryable: Only retry when this is true. Retrying non-retryable errors wastes quota and may trigger rate limits.
- Use test cards: Test card numbers trigger specific error scenarios. See the API Reference for the full list.
- Review webhook delivery logs: Failed webhook deliveries are logged and visible in the Axra dashboard.
- Contact support: For
unknown errors or persistent configuration_error, contact Axra support with the paymentId and transactionId.
