Skip to content

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.

Published 3 min read

Hand-drawn illustration of an order card labelled out_trade_no and trade_no linked to two payment_id cards, one crossed out, next to a person with folded arms
On this page
  1. Transaction ID vs order ID at a glance
  2. Order IDs: out_trade_no and trade_no
  3. The payment ID is a transaction, and it can change
  4. Refund and dispute numbers
  5. Event IDs and request IDs
  6. Which payment identifier to use for what
  7. Summary

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

IdentifierWho creates itWhat it identifiesStable?
out_trade_noYouYour order — the purchase in your systemYes
trade_no (TRD_…)KukoPayThe same order, in KukoPayYes
payment_idThe payment channelOne payment attempt for the orderNo — can change during checkout
out_refund_no / refund_noYou / KukoPayOne refundYes
dispute_no (dsp_…)KukoPayOne chargebackYes
id (evt_…)KukoPayOne event (and its webhooks)Yes
request_id (req_…)KukoPayOne API callYes
receipt_numberKukoPayThe receipt for a paid orderYes, 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_no is 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_no is KukoPay's; the refund lookup accepts either.
  • dispute_no identifies 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 the X-Request-Id header. 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

JobUse
Link a payment to your orderout_trade_no (or trade_no)
Look up an orderout_trade_no or trade_no in GET /v1/orders/{…}
Retry order creation safelyThe same out_trade_no
Retry a refund safelyThe same out_refund_no
Deduplicate webhooksEvent id
Reconcile moneyBalance transactions, each tied to its order, refund, dispute or payout — see payment reconciliation
Ask support about an API callrequest_id
Help a buyer find a chargereceipt_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_no is yours and trade_no is KukoPay's — both stable, both accepted by the order lookup;
  • payment_id can change during checkout, so never key orders on it;
  • out_refund_no makes refunds retry-safe, event id makes webhooks deduplicable, and request_id is what support needs;
  • store out_trade_no and trade_no on your order, and log every request_id.

Try it in the sandbox

Create a merchant account and request a test key. The sandbox needs no business verification.