Changelog

What changed in each version of the Luqra Now API, newest first. The version is the one shown on the API Reference. This page covers the /v1 endpoints and webhook payloads.

Each change is marked Breaking or Non-breaking:

  • Breaking: your integration can stop working unless you change it. Make the change before the version reaches production.
  • Non-breaking: your integration keeps working.

It also says what you need to do:

  • Action required: you must change your integration.
  • Action recommended: you should change it, for example to handle a new response.
  • No action required: you can ignore the change.

Affects lists the endpoints a change touches, so you can search your code for them. Your client must ignore fields it does not recognize; see the Introduction.

Each version is marked Unreleased, or Released with the date it reached production. Upcoming versions appear only on the Sandbox docs: a version is listed there as Unreleased as soon as it is on Sandbox, so you can prepare before it reaches production. The production docs list a version once it is released.

1.12.0

Unreleased

Contacts: legalAddress can be null

Breaking · Action required

Affects: POST /v1/contacts, PATCH /v1/contacts/:id, GET /v1/contacts, GET /v1/contacts/:id

What changed:

  • legalAddress is optional when you create a contact. Leave it out or send null for no address.
  • Send legalAddress: null on update to remove the address.
  • Any response that returns a contact can have legalAddress: null. This can happen even if you always send an address, because contacts can also be saved without one in the Luqra Now dashboard.
  • If you send an address, all its fields except addressLine2 are still required.
  • Originators and webhook payloads don't change.

What to do: check legalAddress for null before you read its fields, everywhere you read a contact. Otherwise your code fails on the first contact without an address. See Managing Contacts.

All endpoints: new UAT environment

Non-breaking · No action required

Affects: every /v1 endpoint

What changed: a new UAT (user acceptance testing) environment previews each release before production. Its base URL is https://uat.api.now.luqra.com/v1, and its API keys start with luqra-now.org.uat. UAT runs a simulated bank rail, so no payment reaches a real bank. Sandbox and production don't change.

What to do: nothing is required. Your Luqra contact tells you whether to test on Sandbox or UAT. See Testing in Sandbox.

Payments: payments created in the dashboard carry achSecCode

Non-breaking · Action recommended

Affects: GET /v1/payments, GET /v1/payments/:id, payment.* webhook events

What changed:

  • A payment created in the Luqra Now dashboard now carries an SEC Code. Before, achSecCode was null on every dashboard-created payment.
  • A payment created without a payment link carries the code chosen when it was created.
  • A payment link has no code until the counterparty submits their bank details: achSecCode is null while the payment is AWAITING_CONFIRMATION, and stays null if it is canceled first.
  • When they submit, they say whether the account is personal or business, and that sets the code: WEB (personal) or CCD (business) on a request, PPD (personal) or CCD (business) on a send. From QUEUED on, every response and event carries it.
  • On Sandbox, a link created before this version may already show a code while it waits. The counterparty's choice replaces it, so payment.queued can show a different achSecCode than payment.awaiting_confirmation.
  • Payments created with POST /v1/payments don't change.

What to do: for a payment link, read achSecCode from the payment.queued event or from GET /v1/payments/:id once the payment is QUEUED, and expect null before that. If your code assumed null on every dashboard-created payment, expect a code now. See Payment Links.

1.11.0

Unreleased

All endpoints: rate limits and 429 RATE_LIMITED

Non-breaking · Action recommended

Affects: every /v1 endpoint

What changed:

  • Your organization can have a per-second limit, a per-minute limit, or both. All API keys of your organization share them.
  • Over a limit, any /v1 endpoint returns 429 Too Many Requests with the error code RATE_LIMITED and a Retry-After header: the number of seconds to wait.
  • Responses to authenticated requests carry X-RateLimit-Limit-Second and X-RateLimit-Remaining-Second, or the -Minute pair, for each limit that is set. A header can be missing if we could not check the limit for a moment. Treat a missing header as unknown, not as zero.
  • We tell you your limits before we enforce them for your organization. Until then, requests over a limit still go through.

What to do: on a 429, wait the number of seconds in Retry-After, then retry the same request. For POST /v1/payments, reuse the same Idempotency-Key. Don't treat a 429 as a final failure. Read your limits from the headers instead of hard-coding them. See Rate Limits.

Statements: PDF amounts are no longer cut off

Non-breaking · No action required

Affects: GET /v1/statements/:id/download

What changed: in the PDF's Daily Transaction Activity table, amounts over six figures now print in full instead of ending in "…". The Transaction Fees header no longer breaks mid-word.

What to do: nothing is required.

1.10.0

Unreleased

Webhooks: notificationEmail, and failing endpoints hold events

Non-breaking · No action required

Affects: POST /v1/webhooks, PATCH /v1/webhooks/:id, GET /v1/webhooks, GET /v1/webhooks/:id, webhook delivery

What changed:

  • New optional field notificationEmail (up to 254 characters) on create and update. Send null on update to clear it. Every response that returns an endpoint includes it, null when it is not set. We email this address when an endpoint starts holding events and when we disable it.
  • If every delivery to an endpoint fails for 15 minutes, we hold its events instead of retrying each one.
  • Every 15 minutes, we test the endpoint with one held event. When that delivery works, we send all held events, oldest first.
  • If the endpoint still fails after 3 days, we disable it and keep its held events. When you enable it again, we send them.
  • A 4xx response no longer drops an event, and a disabled endpoint no longer skips events. Both now hold them.
  • Event payloads don't change.

What to do: nothing is required. After you fix a failing endpoint or enable a disabled one, expect a burst of held events, oldest first. Set notificationEmail to hear about failures early. See Webhooks.

Contacts: 503 BANK_NAME_UNAVAILABLE when the bank has no name on file

Non-breaking · Action recommended

Affects: POST /v1/contacts, PATCH /v1/contacts/:id

What changed: sometimes the bank directory knows a routing number but has no bank name for it. Saving a contact with that routing number now fails with 503 and the error code BANK_NAME_UNAVAILABLE (Error fetching bank name, please retry), and nothing is saved. On update, this only happens when the routing number changes. Before, the contact was saved with an empty bank name, and its payments failed later.

What to do: retry the same request after a short wait, as for any 503. See Errors.

Payments: failureReason no longer shows technical details

Non-breaking · No action required

Affects: GET /v1/payments, GET /v1/payments/:id, payment.* webhook events

What changed: a failureReason with technical details (hostnames, IP addresses, ports, account numbers, or stack traces), or longer than 500 characters, is now replaced with a safe message. That is the payment's own failure message when it is safe to show, or otherwise a general message for the payment's status. Other reasons don't change.

What to do: nothing is required. Base your logic on failureCode, not on the text of failureReason. See Managing Payments.

Payments: the ACH addenda record uses * as its separator

Breaking · Action required

Affects: POST /v1/payments

What changed:

  • On an ACH payment, the addenda record sent to the receiving bank is now externalPaymentId*paymentNote. It used to be externalPaymentId|paymentNote.
  • An * or \ inside either value becomes a space, so the only * is the separator. A | is no longer replaced.
  • The 79-character limit and the TEL exception don't change.

What to do: if you or your payees read the addenda record, for example to match payments, split it on the first * instead of |. Otherwise the whole record reads as one value. See Managing Payments.

Statements: the CSV has one row per payment

Breaking · Action required

Affects: GET /v1/statements, GET /v1/statements/:id/download

What changed:

  • The CSV export has one row per payment instead of one per transaction.
  • The columns are Date, Status, Type, Contact, Description, External ID, Amount, Discount Fee, Transaction Fee, Return Fee, Completed At, and Returned At. Status, Completed At, and Returned At are new.
  • Type is Debit or Credit. It used to be PAYMENT, RETURN, FEE_COLLECTION, or REFUND.
  • Amounts are always positive. Outbound payments used to be negative.
  • A payment shows up in the period its debit reached the bank, or in the period it was returned. The statement totals count the same way: totalPaymentCount and totalProcessingVolumeMinorUnits cover payments whose debit reached the bank in the period, and totalReturnCount and totalReturnVolumeMinorUnits cover payments returned in it.

What to do: update your CSV reader. Read columns by header name, handle the new Type values, and take the direction from Type instead of the amount's sign. Otherwise your reader misreads the file. See Statements.

1.9.1

Released 2026-10-01

The first version used in production. Earlier changes are not listed.