Making Your First Payment

This guide walks you through sending your first payment using the Luqra Now API, from obtaining credentials to tracking a completed transfer.

Prerequisites

  • A Luqra Now account with sandbox access
  • A sandbox API key (prefixed luqra-now.org.test), or a UAT key (prefixed luqra-now.org.uat) if your organization tests on UAT
  • At least one originator ID that can be used as the originator of the payment request (provided during onboarding)

1. Verify your API key

Confirm your key works by listing your originators:

curl "https://staging.api.now.luqra.com/v1/originators/" \
  -H "Authorization: Bearer luqra-now.org.test.YOUR_API_KEY"

A successful response looks like:

{
  "data": [ ... ],
  "meta": { "timestamp": "2026-02-26T12:00:00.000Z" }
}

If you receive a 401 error, double-check that your key is active and correctly formatted in the Authorization header.

2. Create a contact

Before you can move money, you need a contact. A contact is the party on the other side of a payment from your originator: the party you pay on an outbound payment, and the party you debit on an inbound one. The same contact record works for both. Create one with their name and bank account details. email, phoneNumber, and legalAddress are optional -- leave them out if your records do not carry them.

curl -X POST https://staging.api.now.luqra.com/v1/contacts/ \
  -H "Authorization: Bearer luqra-now.org.test.YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "originatorId": "ORIGINATOR_ID",
    "entityType": "INDIVIDUAL",
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "jane@example.com",
    "phoneNumber": "+19497037012",
    "legalAddress": {
      "addressLine1": "123 Main St",
      "city": "Springfield",
      "state": "IL",
      "postalCode": "62701",
      "countryCode": "US"
    },
    "bankAccount": {
      "subType": "CHECKING",
      "achRoutingNumber": "021000021",
      "achAccountNumber": "123456789"
    }
  }'

Save the contactId from the response -- you'll need it in the next step.

{
  "data": {
    "contactId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "createdAt": "2026-02-26T12:00:00.000Z"
  },
  "meta": { "timestamp": "2026-02-26T12:00:00.000Z" }
}

3. Create a payment

direction decides which way the money moves, and it is read from your originator's point of view:

directionDebitedCreditedUse it to
OUTBOUNDYour originatorThe contactPay the contact
INBOUNDThe contactYour originatorCollect from the contact

Everything else about the request is the same in both directions, except which achSecCode values are accepted (see below). paymentAmount is a positive integer in minor units (cents for USD), never signed, so 5000 means $50.00 whichever way the money moves. It must be at least 1 and at most 10000000, a technical ceiling of the schema rather than the limit that applies to your payments, which is agreed when you onboard (see Payment Rails). An amount outside that range is rejected with a 400 VALIDATION_ERROR.

externalPaymentId is optional: your own reference for the payment, such as an invoice or order number. It is not unique, it is echoed on reads and webhooks, and it travels to the receiving bank in the addenda record. See Managing Payments for how it is formatted there.

The Idempotency-Key header is required. A fresh UUID per request is the recommended shape -- it makes retries safe without creating duplicates. See Idempotency and Retries for details.

State the ACH entry class with achSecCode

The NACHA Standard Entry Class (SEC) Code for the ACH transaction identifies the authorization method and the type of entry. achSecCode is required on every payment. Supported values:

achSecCodeMeaningAllowed with direction
WEBConsumer authorized through an internet website or mobile applicationINBOUND
PPDConsumer authorized through a written and signed or similarly authenticated authorizationINBOUND, OUTBOUND
TELConsumer authorized through an oral authorization via the telephoneINBOUND
CCDBusiness-to-business (corporate) transactionINBOUND, OUTBOUND

An INBOUND payment (a debit) accepts WEB, PPD, TEL, or CCD. An OUTBOUND payment (a credit) accepts PPD or CCD. Credits and refunds for consumer debit transactions authorized under the WEB or TEL SEC Codes originate as PPD credit entries.

The SEC Code you provide is transmitted on the ACH entry exactly as submitted. Luqra Now does not determine or infer the appropriate SEC Code. As the originator you are responsible for supplying the correct SEC Code and maintaining the authorization records required by applicable NACHA rules.

TEL entries do not support addenda records under NACHA rules. Consequently, externalPaymentId and the remittance note are not included in the ACH entry delivered to the receiving financial institution on a TEL debit. paymentNote is still retained on the payment and appears as the ACH company entry description. WEB, PPD, and CCD entries carry the addenda record described in Managing Payments.

A missing, unsupported, or direction-mismatched code is rejected with a 400 VALIDATION_ERROR whose details entry has field set to achSecCode. Branch on issue; the message wording may change:

Requestissuemessage
achSecCode absent or nullvalidation_ach_sec_code_requiredSEC code is required. Send WEB, PPD, TEL, or CCD.
Any value other than WEB, PPD, TEL, CCD (for example CTX, IAT, or lowercase web)validation_ach_sec_code_invalidSEC code provided is not valid. Send WEB, PPD, TEL, or CCD.
WEB or TEL on an OUTBOUND paymentvalidation_ach_sec_code_outbound_credit_onlySEC code provided is not valid for an OUTBOUND payment. Send PPD or CCD.

Payments you read back echo the code in achSecCode.

Outbound: pay a contact

curl -X POST https://staging.api.now.luqra.com/v1/payments/ \
  -H "Authorization: Bearer luqra-now.org.test.YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "originatorId": "ORIGINATOR_ID",
    "contactId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "paymentAmount": 5000,
    "direction": "OUTBOUND",
    "achSecCode": "CCD",
    "paymentNote": "Water filter #132",
    "externalPaymentId": "ORDER132"
  }'

The response contains the new payment ID:

{
  "data": {
    "paymentId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
  },
  "meta": { "timestamp": "2026-02-26T12:00:05.000Z" }
}

Behind the scenes, Luqra Now creates the payment and begins executing it on the appropriate rail.

Inbound: collect from a contact

The same call with direction set to INBOUND debits the contact and credits your originator. The only other fields that change are achSecCode, which now describes the debit, and the references in paymentNote and externalPaymentId: this example collects from an individual who authorized it online.

curl -X POST https://staging.api.now.luqra.com/v1/payments/ \
  -H "Authorization: Bearer luqra-now.org.test.YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "originatorId": "ORIGINATOR_ID",
    "contactId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "paymentAmount": 5000,
    "direction": "INBOUND",
    "achSecCode": "WEB",
    "paymentNote": "Invoice 1042",
    "externalPaymentId": "INV1042"
  }'

The response has the same shape as an outbound create:

{
  "data": {
    "paymentId": "9f8b7a6c-5d4e-4f3a-2b1c-0d9e8f7a6b5c"
  },
  "meta": { "timestamp": "2026-02-26T12:00:05.000Z" }
}

On a read, contact.bankAccount is the account that was debited rather than the account that was credited. The field is the same, its role flips with direction. See Managing Payments for the full response shape.

4. Verify the contact was created

List contacts for your originator to confirm everything is set up:

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

What's next