Testing in Sandbox

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

Sandbox vs production

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 and production share the same API endpoints. The environment is determined entirely by your API key prefix.

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:

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.