Emirates ID on Long-Lived Payments — Sending It as a TPP, Checking It as an LFI
A long-lived payment consent is authorized once and then pays many times. From v2.2, the TPP sends a retail User's Emirates ID in Risk.DebtorIndicators.EmiratesId on every POST /payments under such a consent, so the LFI can confirm that each payment is being made for the same User who authorized the consent.
One identifier, on every payment
A Single Instant Payment consent is authorized and used once. Every other payment consent is long-lived: the User authorizes it at the LFI once, and the TPP then initiates payments under it for weeks or months, often with the User not present. Each of those later payments reaches the LFI with no authentication of its own — only the consent it was made under.
v2.1 identifies the User initiating a payment in Risk.DebtorIndicators only by name. v2.2 adds EmiratesId (changelog §21), and for long-lived consents the TPP requirements make it mandatory for retail Users. The LFI compares it with the Emirates ID it holds for the PSU behind the consent.
| Who | What | When |
|---|---|---|
| TPP | Captures the retail User's Emirates ID | Before the first payment under the consent |
| TPP | Sends it in Risk.DebtorIndicators.EmiratesId inside the encrypted PII | Every POST /payments under a long-lived consent |
| LFI | Compares it with the Emirates ID held for the PSU | On receiving POST /payments at its Ozone Connect endpoint |
Risk is part of the payment PII, which the TPP signs and encrypts to the LFI. The API Hub passes it through without decrypting it, so the Emirates ID is never held centrally. See Payment PII Encryption.
Every payment type except Single Instant Payment
The requirement applies to the seven multi-payment types. An LFI can tell them apart from a Single Instant Payment consent by its ControlParameters:
| Payment type | Identified on the consent by | TPP requirements |
|---|---|---|
| Fixed Defined Schedule | ConsentSchedule.MultiPayment | Payment Initiation |
| Fixed Periodic Schedule | ConsentSchedule.MultiPayment | Payment Initiation |
| Fixed On Demand | ConsentSchedule.MultiPayment | Payment Initiation |
| Variable Defined Schedule | ConsentSchedule.MultiPayment | Payment Initiation |
| Variable Periodic Schedule | ConsentSchedule.MultiPayment | Payment Initiation |
| Variable On Demand | ConsentSchedule.MultiPayment | Payment Initiation |
| Delegated SCA | IsDelegatedAuthentication: true, with an empty ConsentSchedule | Payment Initiation |
A Single Instant Payment consent carries ConsentSchedule.SinglePayment instead, and is out of scope.
Capture it, then send it on every payment
- For a retail User, the TPP MUST capture the User's Emirates ID before initiating payments under a long-lived consent.
- The TPP MUST send it in
Risk.DebtorIndicators.EmiratesIdin the PII of everyPOST /paymentsunder that consent — not only the first. - The value must match
^784-?[0-9]{4}-?[0-9]{7}-?[0-9]{1}$: the 15 digits of the Emirates ID, with or without hyphens.
{
"Risk": {
"DebtorIndicators": {
"EmiratesId": "784-1990-1234567-1",
"Authentication": { "...": "..." },
"...": "..."
},
"TransactionIndicators": { "...": "..." },
"CreditorIndicators": { "...": "..." }
}
}The rule is listed in the Payment Initiation requirements of each multi-payment type (linked above), and the field is described on the Risk page.
An LFI that checks the Emirates ID rejects a payment under a long-lived consent that does not carry one, as well as one that carries the wrong one. Both come back as 400 Consent.BusinessRuleViolation — see For LFIs.
Compare it with the PSU behind the consent
When your Ozone Connect POST/payments endpoint receives a payment, you can check the Emirates ID as part of validating the PII:
| Step | What to do |
|---|---|
| 1 | Identify the consent from o3-consent-id and check that it is long-lived — it does not carry ConsentSchedule.SinglePayment. |
| 2 | Identify the customer from o3-psu-identifier — the reference your LFI patched onto the consent when the User authorized it — and check that the customer is retail. |
| 3 | Read Risk.DebtorIndicators.EmiratesId from the decrypted payment-time PII. |
| 4 | Compare it with the Emirates ID you hold for that customer, ignoring hyphens. |
// The pattern makes the hyphens optional, so 784-1990-1234567-1 and
// 784199012345671 are the same Emirates ID. Compare the digits only.
const digits = (id: string) => id.replace(/-/g, '')
// Single Instant Payment is the only consent that carries
// ControlParameters.ConsentSchedule.SinglePayment; every other payment
// consent is long-lived.
const isLongLived = (consent: PaymentConsent) =>
!consent.ControlParameters.ConsentSchedule?.SinglePayment
function checkEmiratesId(
consent: PaymentConsent, // the consent identified by o3-consent-id
customer: Customer, // resolved from o3-psu-identifier
pii: PaymentPII, // the decrypted payment-time PII
): ErrorResponse | null {
if (!isLongLived(consent) || customer.type !== 'Retail') return null
const sent = pii.Risk?.DebtorIndicators?.EmiratesId
if (!sent) {
return {
errorCode: 'Consent.BusinessRuleViolation',
errorMessage: 'Validation failed for AEPaymentPII: risk.debtorIndicators.emiratesID is required for a long-lived payment consent',
}
}
if (digits(sent) !== digits(customer.emiratesId)) {
return {
errorCode: 'Consent.BusinessRuleViolation',
errorMessage: 'Validation failed for AEPaymentPII: risk.debtorIndicators.emiratesID does not match the PSU ID',
}
}
return null
}Error responses
Reject the payment with 400 and Consent.BusinessRuleViolation:
| Condition | errorCode | errorMessage |
|---|---|---|
EmiratesId is absent | Consent.BusinessRuleViolation | Validation failed for AEPaymentPII: risk.debtorIndicators.emiratesID is required for a long-lived payment consent |
EmiratesId does not match the PSU | Consent.BusinessRuleViolation | Validation failed for AEPaymentPII: risk.debtorIndicators.emiratesID does not match the PSU ID |
{
"errorCode": "Consent.BusinessRuleViolation",
"errorMessage": "Validation failed for AEPaymentPII: risk.debtorIndicators.emiratesID is required for a long-lived payment consent"
}{
"errorCode": "Consent.BusinessRuleViolation",
"errorMessage": "Validation failed for AEPaymentPII: risk.debtorIndicators.emiratesID does not match the PSU ID"
}The check applies to retail customers. The requirement on the TPP covers retail Users only, so a payment for a business customer may arrive without an Emirates ID and is not rejected for it.