Technical concepts
Resource IDs
Every public resource has a string ID that starts with a type prefix. Treat IDs as opaque.
Format#
An ID is a type prefix, an underscore, and a string of letters and digits, for example txn_0F8mQ2rXbT4kL9pZa. The prefix tells you the type of the resource. This helps when you read logs and when you debug.
Prefixes#
| Prefix | Resource | Example |
|---|---|---|
acct_ |
Account | acct_5Rn8bQ2xW7mK4tLzP |
txn_ |
Transaction | txn_0F8mQ2rXbT4kL9pZa |
txnitm_ |
Transaction line | txnitm_8QmZ3vK1pX6nT2bLw |
adj_ |
Transaction adjustment | adj_3Pq8WmK2vN7xL4tRb |
pay_ |
Payment | pay_3RtN6wYc8mK2hQvJd |
payatt_ |
Payment attempt | payatt_1Bx7NqT4vK9mL2wRc |
rfnd_ |
Refund | rfnd_9KcT4mW2xQ7bN5vLp |
cs_ |
Checkout session | cs_6HvB2nQx9LmT4kWpR |
plink_ |
Payment link | plink_4Tn8QmW1vX6kB3zLc |
prod_ |
Product | prod_5Tq8LmN2xB7vK4pRz |
price_ |
Price | price_4Wm9TqLz2Xb7KdN8r |
cus_ |
Customer | cus_2Lp7XcN4vB8mQ1tKd |
inv_ |
Invoice or credit note | inv_7NwQ2kT9xL4mB6vRc |
whevt_ |
Webhook event | whevt_7Kd2VpXn4TqB9mLzR |
whd_ |
Webhook delivery, in the Merxian-Delivery-Id header |
whd_2Rk9TmB4xN7vQ1pLc |
Rules for your code#
- Treat an ID as an opaque string. Do not parse the part after the prefix.
- Do not rely on the length of an ID. Store IDs in a text column of up to 255 characters.
- Do not infer order, time, or any other data from an ID. To sort, use the time fields of the resource.
- Compare IDs as exact, case-sensitive strings.
- An ID belongs to one environment. A sandbox ID does not exist in live, and the other way around.
Merxian can add new prefixes for new resources.
Your own references#
Resources accept your own references, so you can find a resource from your records without storing only the Merxian ID:
| Field | Resource |
|---|---|
externalReference |
Transaction |
clientReferenceId |
Checkout session |
reference |
Refund |
metadata |
Transaction, payment, checkout session |
See Reconcile with your records.