API response and request conventions

When in doubt, check the endpoint’s API reference. It’s the source of truth for a specific endpoint’s fields, formats, and response shape. The conventions below show up across many Payabli endpoints but aren’t applied uniformly, so don’t assume one endpoint behaves like another. Handle them defensively.

Response shapes

Payabli responses come in three shapes. Don’t assume one envelope or reuse another call’s shape. Check each endpoint’s reference page.

The unified A-prefixed response codes apply to v2 Pay In endpoints only, not the whole platform. Other endpoints carry their own responseCode/resultCode and isSuccess flag. See the Pay In unified response codes reference.

Field casing and field names

Casing and field names aren’t consistent across the API. The customer ID is one example: it’s customerId on a customer record, but PayorId or Customer.customerId on a transaction. Other variations you’ll run into (not a complete list):

• Request vs. response casing: for example, you send firstname and read back Firstname.
• The same value in two casings: for example, both vendorId and VendorId appear across endpoints.
• Mixed casing within one record: for example, customerId and customerNumber (camelCase) next to Firstname, Email, and Balance (PascalCase).
• Id as a prefix or a suffix: for example, IdBill vs. billId, or idInvoice vs. invoiceId.

Don’t try to memorize the variations. Confirm the exact field names for an endpoint in its API reference, and normalize at the boundary. Treat response field names as case-insensitive, and map each response into your own typed model as soon as you receive it. A small tolerant helper does it once:

1
function field(obj, ...names) {
2
  for (const n of names) if (obj?.[n] != null) return obj[n];
3
  const lower = Object.fromEntries(
4
    Object.entries(obj ?? {}).map(([k, v]) => [k.toLowerCase(), v])
5
  );
6
  for (const n of names) if (lower[n.toLowerCase()] != null) return lower[n.toLowerCase()];
7
  return undefined;
8
}

When you join records, collect the identifier from any of the names it might use. The customer ID on a transaction is the common trap.

Date formats

Accepted date formats vary by endpoint and aren’t confirmed uniform across the API. Check the endpoint’s reference for what it accepts. Where you have a choice, use ISO YYYY-MM-DD and keep it consistent. Some fields also accept sentinels. For example, a subscription’s endDate accepts untilcancelled for an open-ended autopay.

Querying data

The Query API is the read, list, and reporting layer. Send a GET request to /api/Query/{resource}/{entry} for customers, transactions, invoices, bills, subscriptions, chargebacks, and more.

The supported filters, pagination, and response shape vary by query endpoint, so check the endpoint’s reference for what it accepts. Common patterns:

• Filters: field(op)=value, where op is typically eq, gt, ge, lt, le, ne, ct (contains), or in. Which fields and operators an endpoint accepts differ.
• Pagination: limitRecord (page size) and fromRecord (offset), where supported.
• Envelope: list responses commonly come back as { Summary, Records } (with Summary.totalRecords and totalPages), but not every endpoint follows this. Confirm the shape per endpoint.

For the full query syntax and the filter fields each endpoint supports, see the reporting overview.

Using an SDK

The official SDKs handle authentication, typing, serialization, and field casing for you, so most of the conventions above don’t surface when you use one. If you run into a gap, contact the Payabli team. Examples include an operation the SDK doesn’t expose, or a request or response that doesn’t match what the API accepts.