Testing in Sandbox

The Luqra Now sandbox environment lets you test contact creation, payment submission, and error handling without moving real funds.

Sandbox, UAT, and production

SandboxUATProduction
Key prefixluqra-now.org.testluqra-now.org.uatluqra-now.org.live
Fund movementNoneNoneReal
Payment railsSimulatedSimulatedLive
Bank account validationFormat-checkFormat-checkFormat-check

Getting started

Use your sandbox API key for all test requests:

curl "https://staging.api.now.luqra.com/v1/contacts/?originatorId=ORIGINATOR_ID" \
  -H "Authorization: Bearer luqra-now.org.test.YOUR_API_KEY"

Sandbox, UAT, and production are separate environments with their own API hosts: sandbox is https://staging.api.now.luqra.com, UAT is https://uat.api.now.luqra.com, and production is https://api.now.luqra.com. Use a luqra-now.org.test key against the sandbox host, a luqra-now.org.uat key against the UAT host, and a luqra-now.org.live key against the production host. The test bank accounts and error scenarios below apply to UAT as well. UAT runs a simulated rail: each bank step is acknowledged within seconds, while payout timing (credit delay and submit window) matches production.

Test bank accounts

Bank account validation checks the format -- routing numbers must be 9 digits with a valid ABA checksum, and account numbers must be 5-17 alphanumeric characters. This applies to both sandbox and production.

You can use any well-formed routing and account number for testing:

Routing numberDescription
021000021JPMorgan Chase (valid checksum)
011401533Bank of America (valid checksum)
091000019Federal Reserve Bank (valid checksum)

Payment processing in sandbox

Sandbox payments progress through the full lifecycle without moving real funds. An intent moves from QUEUED to PROCESSING and on to COMPLETED once the simulated rail acknowledges the payment. The timing of the simulated sandbox environment matches the timing in production.

RETURNED and FAILED_IN_FLIGHT are not produced automatically in sandbox. To exercise handling for these statuses, see the Payment Lifecycle reference and structure your code to react to status fields directly rather than relying on observing every transition during sandbox testing.

Testing error scenarios

To test how your integration handles failures, you can:

  • Invalid contact -- Send a payment to a contactId that doesn't belong to the originator. Returns a 404 error.
  • Missing fields -- Omit required fields to trigger 400 validation errors with detailed field-level messages.
  • Idempotency replay -- Send two POST /v1/payments requests with the same Idempotency-Key and the same body. The second returns the original payment id. Send a third request with the same key but a different body -- it returns 409 IDEMPOTENCY_KEY_REUSED_WITH_DIFFERENT_BODY.
  • Missing Idempotency-Key -- Omit the header on POST /v1/payments to trigger 400 IDEMPOTENCY_KEY_REQUIRED.
  • Expired keys -- Use a revoked API key to verify your error handling for 401 responses.

Best practices

  • Use sandbox for all development and staging environments. Never use production keys in non-production environments.
  • Validate error handling. Intentionally trigger errors to make sure your integration handles them gracefully.
  • Test idempotency. Send a payment, then retry with the same Idempotency-Key and verify that no duplicate is created.