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)
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, address, and bank account details.

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:

`direction`	Debited	Credited	Use it to
`OUTBOUND`	Your originator	The contact	Pay the contact
`INBOUND`	The contact	Your originator	Collect from the contact

Everything else about the request is the same in both directions. paymentAmount is a positive integer in minor units (cents for USD), never signed, so 5000 means $50.00 whichever way the money moves.

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.

Before you create an INBOUND payment, make sure you hold the contact's authorization to debit their account. That obligation is yours as the party initiating the debit.

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",
    "paymentNote": "Water filter #132"
  }'

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. No other field changes.

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",
    "paymentNote": "Invoice 1042"
  }'

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

Learn about sandbox testing for development and error handling
Understand the full payment lifecycle and status transitions
Set up idempotency to safely retry failed requests

Errors

Managing Payments