Transaction Identifiers

Using the wrong transaction ID is one of the most common DigetPay integration mistakes. This guide explains each identifier, where to obtain it, and when to use it.

🚧
Rule of thumb: Status, Capture, Refund, and Void operations require the Gateway Transaction ID — never the Checkout Session ID.

Identifier overview

Identifier	Description	Used For
Merchant Order ID	Your unique order reference generated by your system.	Tracking orders and reconciling payments in your application.
Checkout Session ID	Returned when creating a payment link. Identifies the hosted checkout session.	Opening the hosted checkout and tracking the payment session.
Gateway Transaction ID	Generated after a successful payment.	Transaction Status, Capture, Refund, and Void APIs.
Numeric Payment ID	Internal payment reference returned in some API responses.	Reference only — not supported for Status or Refund APIs.

{
  "merchantOrderId": "ORDER-20260721-001",
  "checkoutSessionId": "70471003-64ee-4ae7-a639-e607b45e890b",
  "gatewayTransactionId": "2232e99b-0257-47d5-bbfd-022c8951767f",
  "numericPaymentId": "0808779145497567115585"
}

Merchant Order ID

The Merchant Order ID is generated by your application and included in the payment request.

Example:

{
  "merchantOrderId": "ORDER-20260721-001"
}

Best practices

Generate a unique value for every payment.
Do not reuse the same ID for multiple transactions.
UUIDs or timestamp-based values are recommended.

Checkout Session ID

The Checkout Session ID is returned by the Create Payment Link API.

Example:

{
  "id": "70471003-64ee-4ae7-a639-e607b45e890b",
  "redirectUrl": "https://fin-admin.digetpay.com/pay/checkout/..."
}

Use this ID to:

Launch the hosted checkout.
Track the checkout session.

Do not use it for:

Transaction Status
Capture
Refund
Void

Gateway Transaction ID

The Gateway Transaction ID identifies the completed payment transaction.

It is the only identifier accepted by:

GET /payment/checkout/status
POST /payment/refund
POST /payment/s2s/capture
POST /payment/s2s/void

Example:

{
  "transactionId": "2232e99b-0257-47d5-bbfd-022c8951767f"
}

How to obtain the Gateway Transaction ID

You can retrieve the Gateway Transaction ID from:

Webhook notifications (recommended)
Transaction Status API
DigetPay Merchant Dashboard

Example webhook payload:

{
  "transactionId": "2232e99b-0257-47d5-bbfd-022c8951767f",
  "orderId": "ORDER-20260721-001",
  "status": "APPROVED"
}

Best practice: Store the Gateway Transaction ID together with your Merchant Order ID immediately after the payment succeeds. This simplifies future Status, Capture, Refund, and Void operations.

Common mistakes

Mistake	Why it fails
Using the Checkout Session ID for Status or Refund	It identifies the checkout session, not the completed payment.
Using the Numeric Payment ID	Status and Refund APIs require the Gateway Transaction UUID.
Calling the wrong Status endpoint	Use the documented Fin Status API for your integration.

❗️
If the Status API returns 404, an empty response, or Refund fails unexpectedly, verify that you are using the Gateway Transaction ID, not the Checkout Session ID.

Related guides

Testing Guide

Validate your integration on the Fin Staging environment.

Query Transaction Status

Retrieve the current status of a payment transaction.

Process Refund

Refund a completed payment using the Gateway Transaction ID.

Receiving Webhooks

Capture transaction events and store the Gateway Transaction ID automatically.