Platform
ISO 8583 to REST
How a scheme's authorisation message becomes the JSON these APIs speak, field by field.
The ISO 8583 data elements are the standard and are accurate. Their mapping to the field names below is inferred from the published response schemas, not from a mapping document DgPays has confirmed. Treat the left column as fact and the correspondence as a strong reading that should be verified before you build against it.
- Whether the conversion is ever exposed as an API, or stays inside the platform.
- How DE 55 EMV data is surfaced, since no published field carries it.
- Which private-use data elements the Jaywan scheme requires for the UAE market.
Everything else on this portal speaks JSON over HTTP. The schemes underneath speak ISO 8583 — a positional binary message format from 1987 that still carries every card authorisation in the world. The platform sits between them.
You do not call the conversion. It happens inside, on the authorisation path, before anything you can reach. This page exists because the output of that conversion is what you read in every transaction response, and knowing which ISO data element a field came from tells you what it means and what it can contain far better than the field name does.
The message types you will meet
ISO 8583 · message types
| MTI | Name | What it is |
|---|---|---|
| 0100 | Authorisation request | The merchant asks whether the card can pay |
| 0110 | Authorisation response | The issuer answers, with a response code |
| 0200 | Financial request | The money moves |
| 0210 | Financial response | Confirmation that it did |
| 0400 | Reversal request | Undo an authorisation |
| 0420 | Reversal advice | Notification that one was undone |
An authorisation and its reversal are two messages sharing a retrieval reference number. That is why reversal on this platform takes a reference rather than an amount — the pairing is the scheme's, not ours.
The field mapping
The data elements that reach a response you can read:
ISO 8583 · data element to field
| DE | ISO name | Field in these APIs |
|---|---|---|
| 2 | Primary account number | maskedCardNumber — the PAN itself is replaced by shadowCardNumber |
| 3 | Processing code | trnCodeMatrixId, with trnCodeMatrixDescription |
| 4 | Transaction amount | trnAmount |
| 6 | Cardholder billing amount | amount |
| 7 | Transmission date and time | date |
| 11 | System trace audit number | Not surfaced — use rrn |
| 18 | Merchant category code | mcc, with mccDescription |
| 22 | POS entry mode | panEntryMode, with panEntryModeDescription |
| 37 | Retrieval reference number | rrn |
| 38 | Authorisation identification response | authorizationNumber |
| 39 | Response code | Not surfaced directly; the approve or decline is the call result |
| 42 | Card acceptor identification | merchantNumber |
| 43 | Card acceptor name and location | merchantName |
| 49 | Transaction currency code | trnCurrencyCode |
| 51 | Cardholder billing currency | currencyCode |
| 55 | EMV chip data | Not surfaced |
Two fields have no ISO parent and are the platform's own:
utid— a unique transaction identifier assigned by the platform. Whererrnis the scheme's handle, this is ours, and it is the one to quote in a support case.sourceNetwork— which scheme the message arrived from. ISO 8583 does not carry this; it is inferred from the link the message came in on.
What this means when you read a response
A masked PAN is not a truncation of a stored PAN. The platform never had the full number in a form you can reach. The mask is what DE 2 became.
rrn is not unique on its own. It is unique per acquirer per day, which is
the guarantee ISO 8583 makes and no more. If you are keying a table, key on
utid.
An amount is two fields, not one. DE 4 and DE 6 differ whenever the
transaction currency differs from the billing currency, which in the UAE market
is common rather than exceptional. Reading only amount gets a cardholder's
dispute wrong.
A missing field is not a zero. ISO 8583 is positional and a data element that was not present in the message is absent, not empty. That distinction survives into the JSON, which is why this portal renders "Not stated" rather than "Optional" against fields the specification says nothing about.