FuturePayNG Logo
FuturePayNGv1.0.0
FuturePayNG Invoice Payment API v1.0.0

Errors, Sandbox Testing & Launch Checklist

Standard HTTP status codes, structured error payloads, testing card values for the staging environment, and the verified launch checklist.

warning1. HTTP Status Codes

Standard API Error Responses

FuturePayNG uses conventional HTTP response codes to indicate the success or failure of an API request:

Status CodeMeaningCause / Recommended Action
400 Bad RequestValidation ErrorRequired parameter missing or invalid JSON.
401 / 403 ForbiddenAuthentication FailedInvalid or revoked X-FuturePay-Api-Key header.
404 Not FoundResource MissingInvoice reference does not exist on this merchant account.
409 ConflictDuplicate ReferenceAn invoice with this orderReference already exists.
5xx Server ErrorTemporary OutageInternal network error. It is safe to retry with exponential backoff.
schema2. Error Response Schema

JSON Error Payload Structure

Sample 400 Bad Request PayloadJSON Error
{
  "status": "error",
  "code": "INVALID_AMOUNT",
  "message": "The invoice amount must be at least 100 NGN.",
  "errors": {
    "amount": [
      "The amount field must be greater than or equal to 100."
    ]
  },
  "timestamp": "2026-11-06T09:22:15.000Z"
}
Sample 409 Conflict (Duplicate Order Reference)JSON Error
{
  "status": "error",
  "code": "DUPLICATE_ORDER_REFERENCE",
  "message": "An invoice with orderReference 'ORDER-NG-89421' has already been created.",
  "data": {
    "existingInvoiceReference": "FP-INV-89421-XYZ"
  }
}
science3. Sandbox Testing Scenarios

Staging Environment Testing Values

Simulate Paid Invoice

Use any amount ending in .00 or trigger payment confirmation via the interactive web checkout simulator.

Simulate Abandoned/Expired

Leave invoice pending until expired or trigger POST /cancel.

Simulate Full Refund

Execute POST /refund on any paid test invoice reference.

fact_check4. Production Go-Live Checklist

Interactive Launch Readiness Tracker

Verify each critical milestone before switching your traffic to the production rail:

check
Store API Keys in Environment VariablesEnsure FUTUREPAY_API_KEY and FUTUREPAY_WEBHOOK_SECRET are kept out of source control (.env ignored in .gitignore).
check
Enforce HTTPS on Webhook URLWebhook receivers must accept incoming connections over valid SSL/TLS certificates.
Implement Constant-Time HMAC Signature CheckUse hash_equals() or crypto.timingSafeEqual() against X-FuturePay-Signature.
Display Invoice Expiration TimeDisplay the expiration date and time from paymentData.expires_at on the web checkout.
Handle Order IdempotencyPrevent duplicate order fulfillment by verifying if the order is already marked 'paid' in your database.
Test Sandbox ScenariosTrigger test payments, cancellations, and full refunds before going live.