IDs, Amounts and Dates

Payment Labs uses a few formats everywhere in the API. Getting them right avoids most validation errors and every rounding error.

Before you start

No prerequisites. Every other guide relies on the formats on this page.

IDs

Payment Labs creates an ID for every object. IDs are strings: a short prefix, a hyphen, and a 26-character time-ordered identifier, for example B-01JBX7R2M4Q8T6N3K5W9Y1Z0AC.

Treat IDs as opaque. Store them as variable-length strings and compare them exactly, including case. The prefix helps you read logs; do not parse it or use it to decide what an object is, because some prefixes are shared between object types and older objects may use another format.

Your reference IDs

Most objects you create accept a referenceId: your own identifier, so you can find the object again and match it to your records.

payeeReferenceId identifies a payee together with payeeEmail. Reusing a reference ID with a different email, or an email with a different reference ID, changes the existing payee rather than creating a new one. Read Payee Reference IDs before you send payments to existing payees.

Recommendations:

• Always send payeeReferenceId, set to the stable ID of the person in your system, never to something that changes such as an email.
• Send a referenceId on every batch, payment and checkout. It is searchable, so you can check whether a create request succeeded before you retry it.

Amounts in requests

The format depends on the operation. Check the field description on the reference page.

Rules for every amount:

• Decimal strings hold digits and an optional . only: no sign, no thousands separator, no currency symbol. "1250.00" is valid; "1,250.00" and "$1250" are rejected with INVALID_CURRENCY.
• Use no more decimal places than the currency has: two for USD and EUR, none for JPY. Wallet credits and charges reject extra decimals. Elsewhere, do not rely on Payment Labs to round for you; round in your code first.
• Send amounts greater than zero.
• Never use binary floating point to calculate amounts in your code. Work in minor units as integers, or with a decimal library, and format the result for the request.

Amounts in responses: the Money object

Responses return amounts as a Money object:

{
  "value": 125.5,
  "currency": "USD",
  "formattedValue": "$125.50",
  "digits": 2,
  "wholeValue": 12550
}

Some batch totals are lists of Money objects, one per currency, because a batch can hold payments from ledger accounts in different currencies.

Currencies and exchange

• Currencies are ISO 4217 codes in upper case, such as USD, EUR, GBP.
• A payout is paid from your ledger account's currency: sourceAmount. The payee receives destinationAmount in the currency of their payment method. When the two differ, Payment Labs converts at submit time. Use Submit Payment Dry Run to preview the rate, fees and the amount the payee receives.
• A checkout charges the buyer in the checkout's currency. Payment Labs decides which currencies your account accepts.

Countries

Countries are ISO 3166-1 alpha-2 codes in upper case, such as US, GB, DE.

Dates and times

• Timestamps are ISO 8601 strings in UTC, with milliseconds: 2026-10-28T14:03:11.482Z. Send timestamps in the same format.
• Date-only fields (for example a checkout's expiresAt when you create it) take YYYY-MM-DD. Where an operation also takes a time zone (userTimezone, IANA format such as America/New_York), the date ends at the end of that day in that zone.

Enumerations

Status and type fields hold upper-case or kebab-case strings exactly as listed on each reference page, such as COMPLETED or remote-contractors. Send them exactly as written. Payment Labs adds new values over time, so your code must accept values it does not know: log them and treat them as "in progress" or "other" rather than failing.

Spelling differs between objects and is significant: a cancelled payment or subscription is CANCELLED, a cancelled subscription plan is CANCELED.

Next steps

• Idempotency and Retries
• Payee Reference IDs