> ## Documentation Index
> Fetch the complete documentation index at: https://developers.ligdicash.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tokens and identifiers

> Difference between token, request_id, transaction_id, and external_id in the LigdiCash API — which identifier to use for what.

The LigdiCash API circulates several identifiers across requests, responses, and callbacks. They have distinct roles and are not interchangeable. Mixing up `token` and `transaction_id`, for example, is one of the most common mistakes during a first integration.

## Summary table

| Identifier       | Generated by | Format      | Where it appears                                    | Role                                               |
| ---------------- | ------------ | ----------- | --------------------------------------------------- | -------------------------------------------------- |
| `token`          | LigdiCash    | Long string | Create response + callback                          | Call `confirm`                                     |
| `request_id`     | LigdiCash    | `PXXXXXXXX` | Payment page + callback                             | Short displayable reference                        |
| `transaction_id` | The merchant | Free-form   | `custom_data` of the request + callback + dashboard | Merchant reconciliation                            |
| `external_id`    | The merchant | Free-form   | `invoice` field of the request                      | Equivalent of `transaction_id`, alternative syntax |

## The token

The `token` is generated by LigdiCash when each transaction is created. It is returned in the create response:

```json theme={null}
{
  "response_code": "00",
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
}
```

Its **only purpose** is to be passed to the `confirm` endpoint to check a transaction's status. Store it in your database as soon as the transaction is created.

<Warning>
  The value of `token` in the callback is different from the one obtained at creation. Never use the token as a transaction identifier — it is not stable. Use your `transaction_id` for reconciliation.
</Warning>

## The request\_id

The `request_id` is a short identifier generated by LigdiCash for each transaction. Its format is `PXXXXXXXX` — for example `P2756808232026`.

It is displayed on the LigdiCash payment page and is present in the callback. Its short form makes it easy to communicate: a merchant can show it to their customer as a payment reference, for example on a receipt or in a tracking interface.

<Tip>
  The `request_id` is a good identifier to show your customers for tracking or support — it is short, unique, and recognized by LigdiCash.
</Tip>

## The transaction\_id

The `transaction_id` is an identifier that **you generate on the merchant side** and inject into the `custom_data` field of your request. LigdiCash returns it to you in the callback and displays it in your dashboard among your payin and payout transactions.

It is the pivot of your reconciliation: it links a LigdiCash transaction with your own order management system.

The format is entirely free — order reference, UUID, short customer-readable code, etc.

See [The transaction\_id pattern](/en/concepts/transaction-id-pattern) for best practices on format and usage.

## The external\_id

The `external_id` is the direct equivalent of `transaction_id` — they serve the same purpose. The difference is their location in the request: `external_id` is a field of the `invoice` block, while `transaction_id` is injected into `custom_data`.

```json theme={null}
"invoice": {
  "total_amount": 5000,
  "devise": "XOF",
  "external_id": "ORD-2026-00042",
  "otp": "",
  ...
}
```

Use one or the other depending on what fits your architecture better — not both at the same time. In API responses, these two fields will have the same value.

<Note>
  Both are returned in the callback. Use whichever fits your architecture best — they will have the same value in API responses.
</Note>

## Related pages

* [The transaction\_id pattern](/en/concepts/transaction-id-pattern) — format, lifecycle, extraction in the callback
* [Securing the callback](/en/payment-api/callback/security) — why re-verify with the stored token
* [Response codes and statuses](/en/concepts/response-codes-and-statuses)