Get started
Fields on every request
The operations differ, the vocabulary does not. A few fields turn up across most of the surface, and getting them right once is what makes the rest of the integration mechanical. Counts are measured over the 335 published operations that take a body.
What recurs, and how widely
| Field | On | What it is |
|---|---|---|
| channel | 187 of 335 | The caller's channel code. Not decoration: the platform authorises against it, and several operations behave differently per channel. Decide yours before you write anything — the codes are in Channels. |
| shadowCardNumber | 169 of 335 | The platform's reference to a card, in place of the card number. Safe to store and to log; it is what almost every card operation is keyed by. |
| cardRefNumber | 34 of 335 | The card record's own reference. Where an operation takes both, they are not interchangeable — one names the card, the other the record. |
| customerNumber | 79 of 335 | The customer the card belongs to. Limit and customer-level operations are keyed by it rather than by a card. |
| mainCardRefNumber | 20 of 335 | The main card a supplementary or virtual card hangs off. It is what makes the limit pool shared. |
| branchCode | 23 of 335 | The branch, where the operation needs one — branch delivery makes it mandatory rather than optional. |
A card number is not the key.
cardNumber appears on a small, named set of operations. Everything else works from shadowCardNumber, and a response carrying a real card number is the exception rather than the rule — see Authentication on field-level encryption.
Headers
| Header | Required | What it does |
|---|---|---|
| Authorization | Yes | Bearer <access_token>. Every operation except the token service's own. |
| Content-Type | Yes | application/json. Every operation takes and returns JSON. |
| evrst-ptrnid | No | Your own correlation id for the call. The portal's generated code samples set it because a request you can find again in a log is worth the one line; the platform does not require it. |
Reading a field's constraints
The specifications state a type and nothing else. Everything a bank plans against — the width, the permitted values, what the field is checked against — was read out of the services and is published on the field in the reference. Three habits save time:
- Take the width from the reference, not from the column you imagine. The bound a caller meets is usually the definition table the value is checked against, not the column it is stored in — a code can fit the column and still be impossible to define.
- Send a code where a code is asked for. A field named for a status, a reason or a type takes the platform's code, not its description. The value lists are on the field in the reference and in Key terms.
- Treat a nullable field as optional only if the operation says so. Nullability in these documents is a C# artefact; the operation's own validation is what rejects an absent value.