Errors

If an API request fails, Archefusion returns a clear error response to help you identify the issue and debug faster. The error response follows a consistent structure:

Field	Type	Description
success	Boolean	Indicates the status of the request.
statusCode	Number	Indicates the outcome of the request.
message	String	Indicates the reason why the request failed.
data	Object	Contains additional details about the reason why the request failed.

Example:

{
    "success": false,
    "statusCode": 400,
    "message": "Bad Request Exception",
    "data": {
        "errors": [
            "currency must be longer than or equal to 3 characters",
            "currency must be a string"
        ]
    }
}

Error types

Amount must be a number conforming to the specified constraints

Meaning: The amount field is missing.Solution: Ensure that you provide a valid amount in the amount field before sending a request to the initiate payment endpoint.

No matching smart routing rule. Using default provider order.

Meaning: The provided paymentMethod field or currency field does not match your configured smart routing rule or is missing.Solution: Ensure that you provide a valid paymentMethod and currency that matches your smart routing rule before sending a request to the initiate payment endpoint.

MerchantOrderId must be longer than or equal to 1 characters / merchantOrderId should not be empty / merchantOrderId must be a string

Meaning: The merchantOrderId field is missing.Solution: Ensure that you provide a merchantOrderId field before sending a request to the initiate payment endpoint.

Currency must be longer than or equal to 3 characters / currency must be a string

Meaning: The currency field is missing.Solution: Ensure that you provide a valid currency field before sending a request to the initiate payment endpoint.

Currency not supported by merchant

Meaning: The currency provided in the payment request is not supported by the gateway that Archefusion routed the payment to. This typically happens when no smart routing rule matches the transaction currency and the default gateway does not support it.Solution: Configure a smart routing rule for the currency you want to accept and ensure at least one active gateway supports it. Visit the supported gateways and payment methods page to see which currencies each gateway supports.

Payment not found

Meaning: The provided paymentId in the verify payment request is invalid.Solution: Provide a valid paymentId.

No active payment gateways configured

Meaning: Your connected payment gateways are inactive.Solution: Navigate to Payment Gateways > Gateway Providers and select your connected gateway. Toggle the gateway status to active.

Korapay customer email is required

Meaning: The customer.email field is missing.Solution: Ensure you provide a valid customer email address in your initiate payment payload, especially when you have the Korapay gateway configured.

Failed payments

A payment can fail even when the API request itself succeeds. If your first configured gateway and all its fallback gateways fail to process the payment, the transaction is marked as failed.

This response returns statusCode: 200 and message: "Payment initiated". Always check data.status, not the HTTP status code or message, to confirm the outcome. A failed payment has data.status set to "FAILED" and data.executionStatus set to "failed".

When a payment fails after all gateways are exhausted, the failure details are returned inside the recommendedGateway.session object: Example response The following shows what the response typically looks like when all gateways, the recommended gateway, and every fallback fail to process a payment.

{
  "status": true,
  "statusCode": 200,
  "message": "Payment initiated",
  "data": {
    "paymentId": "7e392127-c76c-4a1d-a6ae-d8f18ac018a8",
    "merchantOrderId": "order_9f83c2a7b14e",
    "status": "FAILED",
    "executionStatus": "failed",
    "currency": "NGN",
    "amount": 100,
    "recommendedGateway": {
      "name": "flutterwave",
      "session": {
        "failedAt": "2026-07-24T23:40:59.316Z",
        "lastError": "provider_down: forced gateway initiation failure for monnify",
        "errorClass": "provider_down",
        "initiationError": "provider_down: forced gateway initiation failure for paystack"
      }
    },
    "fallbackGateways": [
      { "name": "monnify", "reason": "plan-fallback" },
      { "name": "paystack", "reason": "plan-fallback" }
    ],
    "routingMode": "smart"
  }
}

How to reduce failed payments

This failure happens only when every gateway in your routing plan is unavailable, which is rare. To reduce the chance of it:

Configure more than one gateway in your smart routing rules, so Archefusion has fallbacks to try if the first is down. See smart routing.
Keep your gateway credentials valid and your gateways active, so they are not skipped during routing.

API Reference

Payments

Error types

Failed payments

How to reduce failed payments

​Error types

​Failed payments

​How to reduce failed payments

Error types

Failed payments

How to reduce failed payments