Transaction ID vs order ID: which payment identifier to store, and which to match on
Transaction ID vs order ID explained: what each payment identifier means, which one to store, which to reconcile on, and which to give support.
On this page
An order ID identifies what is being bought; a transaction ID identifies one attempt to pay for it. One order can have several transactions — a declined card, then a wallet, then a successful card payment — and one transaction belongs to exactly one order. Mixing the two up is one of the most common sources of reconciliation bugs: code that matches payments by a transaction ID that changed halfway through checkout.
This guide explains every identifier you meet in a KukoPay integration — order IDs, payment IDs, refund numbers, event and request IDs — which ones to store, which to match on, and which to give support.
Transaction ID vs order ID at a glance
| Identifier | Who creates it | What it identifies | Stable? |
|---|---|---|---|
out_trade_no | You | Your order — the purchase in your system | Yes |
trade_no (TRD_…) | KukoPay | The same order, in KukoPay | Yes |
payment_id | The payment channel | One payment attempt for the order | No — can change during checkout |
out_refund_no / refund_no | You / KukoPay | One refund | Yes |
dispute_no (dsp_…) | KukoPay | One chargeback | Yes |
id (evt_…) | KukoPay | One event (and its webhooks) | Yes |
request_id (req_…) | KukoPay | One API call | Yes |
receipt_number | KukoPay | The receipt for a paid order | Yes, once assigned |
Order IDs: out_trade_no and trade_no
out_trade_no is your own order number — up to you, unique per app and environment. It is also an idempotency key: creating an order again with the same out_trade_no and the same content returns the existing order instead of a second one — see what is an idempotency key.
trade_no is KukoPay's number for the same order, returned when the order is created. Sandbox orders start TRD_SB_.
The order lookup accepts either one:
curl "https://api.kukopay.com/v1/orders/ORD_20261118_0001" \
-H "X-Api-Key: $KUKOPAY_API_KEY"So you rarely need to store both — but storing trade_no next to your order costs nothing and makes support conversations faster.
The payment ID is a transaction, and it can change
payment_id identifies the channel payment currently attached to the order. It changes when the buyer switches method at checkout — the unfinished payment is cancelled first, then a new one is created — so one order can pass through several payment IDs before it is paid. See payment status explained.
The rule: never use payment_id as the key for an order. Match payments to orders by trade_no / out_trade_no and the payment.succeeded event. A payment that still arrives on an order that is already paid or closed is refunded automatically — see duplicate payments.
Refund and dispute numbers
out_refund_nois your refund number and the refund's idempotency key — a retried refund request with the same number returns the original refund instead of refunding twice. It is required for live refunds.refund_nois KukoPay's; the refund lookup accepts either.dispute_noidentifies a chargeback; disputes are created by the buyer's bank, so there is no merchant-side number.
Event IDs and request IDs
- Event
id(evt_…) is the same on every retry of the same webhook. Store it under a unique constraint to process each event once — see payment webhook idempotency. request_id(req_…) identifies one API call. It is in every response body and theX-Request-Idheader. Log it: it is what support asks for, and it finds the call in your API logs — see payment API error handling.
Which payment identifier to use for what
| Job | Use |
|---|---|
| Link a payment to your order | out_trade_no (or trade_no) |
| Look up an order | out_trade_no or trade_no in GET /v1/orders/{…} |
| Retry order creation safely | The same out_trade_no |
| Retry a refund safely | The same out_refund_no |
| Deduplicate webhooks | Event id |
| Reconcile money | Balance transactions, each tied to its order, refund, dispute or payout — see payment reconciliation |
| Ask support about an API call | request_id |
| Help a buyer find a charge | receipt_number or out_trade_no from their receipt |
Summary
- An order ID identifies the purchase; a transaction (payment) ID identifies one attempt to pay for it, and one order can have several;
- on KukoPay,
out_trade_nois yours andtrade_nois KukoPay's — both stable, both accepted by the order lookup; payment_idcan change during checkout, so never key orders on it;out_refund_nomakes refunds retry-safe, eventidmakes webhooks deduplicable, andrequest_idis what support needs;- store
out_trade_noandtrade_noon your order, and log everyrequest_id.
Try it in the sandbox
Create a merchant account and request a test key. The sandbox needs no business verification.