Payment Lifecycle

Every payment in Luqra Now follows a defined lifecycle from creation to completion. Understanding the status transitions helps you build reliable integrations.

Status flow

The diagram below traces payments created through the API. Payments created through non-API surfaces (such as the Luqra dashboard) may start in AWAITING_CONFIRMATION and transition to QUEUED once the recipient confirms; from QUEUED onward the flow is identical.

                          (start)
                          API call
                             │
                             ▼
                         ┌────────┐
              ┌──────────┤ QUEUED ├──────────────┐
              │          └────┬───┘              │
              │               │                  │
              ▼               ▼                  ▼
         ┌─────────┐    ┌───────────┐       ┌────────┐
         │ BLOCKED │    │PROCESSING │       │ FAILED │
         └─────────┘    └─────┬─────┘       └────────┘
                              │
              ┌───────────────┼─────────────────────┐
              │               │                     │
              ▼               ▼                     ▼
         ┌────────┐     ┌───────────┐      ┌──────────────────┐
         │ FAILED │     │ COMPLETED │      │ FAILED_IN_FLIGHT │
         └────────┘     └─────┬─────┘      └────────┬─────────┘
           (rare)             │  ▲                  │
                              │  └───late signal ───┘
                              │
                              ▼
                        ┌───────────┐
                        │ RETURNED  │
                        └───────────┘

Status reference

Status	Description	Terminal?
`AWAITING_CONFIRMATION`	Payment was created via the Luqra Now app and is waiting for the recipient to confirm before being queued. API-created payments do not enter this state.	No
`QUEUED`	Queued for processing on the payment rail	No
`PROCESSING`	Submitted to the payment rail	No
`COMPLETED`	Luqra Now has handed the payment off to the payment network. For ACH, the receiving bank typically credits the recipient's account within 1-2 business days after this point.	No
`FAILED`	A failure prevented processing. No funds were moved. Check `failureCode` and `failureMessage` for details -- some failures are recoverable by fixing the named record and creating a new payment. See "Handling FAILED payments" below.	Yes
`FAILED_IN_FLIGHT`	Payment was submitted but confirmation was not received in time; under review	Yes
`BLOCKED`	Payment was stopped by our automated review process and will not be processed	Yes
`RETURNED`	A completed payment was returned by the receiving bank (e.g., ACH return code R01)	Yes

How transitions happen

AWAITING_CONFIRMATION -> QUEUED: The recipient confirmed the payment through the Luqra Now app. The system enqueues the payment and processing begins. API-created payments skip this step.

QUEUED -> PROCESSING: The system picks up the payment and submits it to the payment rail.

PROCESSING -> COMPLETED: The payment network has accepted the payment for processing. For ACH, this means the payment has been delivered to the ACH network. For FedNow, confirmation is near-instant.

QUEUED -> FAILED: Either validation rejected the originator's or contact's data (failureCode is INVALID_ORIGINATOR_DATA or INVALID_CONTACT_DATA), or an unexpected error occurred (failureCode is INTERNAL_ERROR). No funds were moved.

COMPLETED -> RETURNED: The receiving bank returned the payment after it was accepted. Common reasons include closed accounts (R02), insufficient funds (R01), or authorization issues (R07). Returns are terminal.

PROCESSING -> FAILED: In rare cases, an internal error may prevent the system from submitting the payment to the payment rail. No funds were moved. This is a terminal state -- the payment will not be retried automatically. Most integrations will never encounter this status.

PROCESSING -> FAILED_IN_FLIGHT: The payment was submitted to the payment rail but the expected confirmation was not received within the normal timeframe. This does not necessarily mean the payment failed -- it may still settle. The Luqra team is automatically notified and will investigate. No action is required from you; we will reach out if anything is needed.

QUEUED -> BLOCKED: In rare cases, our automated review process may hold a payment before it begins processing. A blocked payment will not be released or processed further. This is part of our standard safeguards and does not indicate a problem with your account or integration.

Handling FAILED payments

FAILED is terminal for that specific payment, but a failure caused by bad input data is recoverable -- you fix the named record and create a new payment with a fresh Idempotency-Key. The new payment reads the latest data from the originator and contact records you reference, so the validation that failed before will succeed once the bad field is corrected. Branch your handling on failureCode:

`failureCode`	What it means	Recovery
`INVALID_ORIGINATOR_DATA`	A field on the originator was rejected (email, phone, address, etc.). The `failureMessage` names the field.	Update the originator record (`PATCH /v1/originators/:id` once available), then create a new payment with a fresh `Idempotency-Key`. The same `externalPaymentId` may be reused.
`INVALID_CONTACT_DATA`	A field on the contact was rejected. The `failureMessage` names the field.	Update the contact record (`PATCH /v1/contacts/:id`), then create a new payment with a fresh `Idempotency-Key`. The same `externalPaymentId` may be reused.
`INTERNAL_ERROR`	An unexpected error occurred.	Wait a few minutes and create a new payment with a fresh `Idempotency-Key`. If the error persists, contact support.

The original FAILED payment remains in your payment history. Both attempts can share the same externalPaymentId so they tie together in your reporting.

Failure and return details

When a payment ends in a failure or returned state, two response fields surface diagnostic information:

failureReason -- A human-readable string explaining why the payment failed. Populated when status is FAILED or FAILED_IN_FLIGHT. The text is informational; wording may change over time, so do not parse it programmatically.
returnReasonCode -- The ACH return code reported by the receiving bank when status is RETURNED. Common codes include R01 (insufficient funds), R02 (account closed), and R07 (authorization revoked). May be null if the receiving bank did not include a code on the return.

Each field is null when the status condition above does not apply.

Fee collection

Fees are not deducted from individual payments. Luqra Now aggregates fees and collects them through a separate fee collection process. This keeps the payment amount clean and predictable for your users.

Testing in Sandbox

Payment Rails