Look up customers

The customer lookup API lets you read back a customer you already created — by the same customerReference you sent when accepting a payment — and list that customer's payment history.

There are two endpoints, both under /api/v1/customers and both authenticated with your app API key + secret:

• GET /customers/{externalId} — the customer's contact identity only.
• GET /customers/{externalId}/payments — that customer's payments, newest first.

All amounts are integer minor units (paisa): 150000 means 1,500.00 BDT. Reads are scoped to your app — and, for the payments list, to your credential's mode — so you can never see another app's (or the other mode's) data. See App isolation.

The flow

Authentication & scope

Both endpoints require the app API-key headers; there is no request body. The app_id is taken from the credential that authenticated the request, never from the caller.

X-Api-Key: oi_test_8f3c1a9b2d4e
X-Api-Secret: sk_test_2b7e9f0a4c6d8e1f

The mode (TEST or LIVE) is derived from the API credential that authenticated the request — never from the request body. There is one nuance worth understanding up front, because the two endpoints treat mode differently:

Look up a customer

curl http://localhost:8080/api/v1/customers/cust_4821 \
  -H "X-Api-Key: oi_test_8f3c1a9b2d4e" \
  -H "X-Api-Secret: sk_test_2b7e9f0a4c6d8e1f"

{
  "data": {
    "externalCustomerId": "cust_4821",
    "name": "Rumana Karim",
    "email": "[email protected]",
    "phone": "+8801712345678"
  },
  "meta": { "success": true, "message": null, "errorCode": null, "timestamp": "2026-06-30T12:05:00Z" },
  "pagination": null
}

Customer response (CustomerDto)

Contact identity only. Null fields are omitted from the JSON, so a customer who paid without any name/email/phone returns just externalCustomerId.

See Customers for how a reference is find-or-created at payment time.

List a customer's payments

curl http://localhost:8080/api/v1/customers/cust_4821/payments \
  -H "X-Api-Key: oi_test_8f3c1a9b2d4e" \
  -H "X-Api-Secret: sk_test_2b7e9f0a4c6d8e1f"

{
  "data": [
    {
      "id": 4821,
      "reference": "PAY-7K2QF8M3ND",
      "status": "SUCCEEDED",
      "applicationId": 42,
      "mode": "TEST",
      "amountMinor": 150000,
      "currency": "BDT",
      "gateway": "SSLCOMMERZ",
      "checkoutUrl": "http://localhost:3000/checkout/PAY-7K2QF8M3ND",
      "metadata": { "orderId": "ord_99812", "cartRef": "cart_5567" },
      "createdAt": "2026-06-30T12:00:00",
      "updatedAt": "2026-06-30T12:04:18"
    },
    {
      "id": 4733,
      "reference": "PAY-3D9H2KQ7BW",
      "status": "EXPIRED",
      "applicationId": 42,
      "mode": "TEST",
      "amountMinor": 50000,
      "currency": "BDT",
      "gateway": "SSLCOMMERZ",
      "checkoutUrl": "http://localhost:3000/checkout/PAY-3D9H2KQ7BW",
      "createdAt": "2026-06-29T09:14:02",
      "updatedAt": "2026-06-29T09:44:02"
    }
  ],
  "meta": { "success": true, "message": null, "errorCode": null, "timestamp": "2026-06-30T12:05:00Z" },
  "pagination": null
}

Equivalent to the by-reference payment list

This endpoint is identical to the by-reference form on the payments API:

curl "http://localhost:8080/api/v1/payments?customerReference=cust_4821" \
  -H "X-Api-Key: oi_test_8f3c1a9b2d4e" \
  -H "X-Api-Secret: sk_test_2b7e9f0a4c6d8e1f"

Both run the same app- and mode-scoped by-reference lookup and return the same newest-first PaymentDto list — GET /customers/{externalId}/payments ≡ GET /payments?customerReference={externalId}. Use whichever fits your code path. See Accept a payment.

Payment response (PaymentDto)

Each element is the same PaymentDto returned by create and the status lookup. Null fields are omitted.

Error reference

All errors use the standard envelope with data: null and a machine-readable meta.errorCode. See Responses & errors.

A lookup for an unknown (or cross-app) customer id:

{
  "data": null,
  "meta": {
    "success": false,
    "message": "Customer not found with id: cust_9999",
    "errorCode": "RESOURCE_NOT_FOUND",
    "timestamp": "2026-06-30T12:05:00Z"
  },
  "pagination": null
}

Related