Integrate D1 Notifications

Events and notifications

Each D1 service (Tokenization, physical card issuance, transaction control, and more) generates internal events. D1 Notification captures these events and turns them into notifications for your issuer backend and issuer application.

D1 Notification event flow (from D1 events to issuer backend and issuer application notifications).

Examples of events:

• Card digitization

• Card suspension or resumption

• Payment authorization

• Physical card issuance status update

D1 can use these events to:

• Send a backend notification to your issuer backend over REST

• Send an in-app notification to your issuer application

Whether a notification is sent is configurable per issuer. You can also define rule criteria based on the event type and the fields in the notification payload.

Example: send an in-app notification when an authorization is declined due to insufficient funds.

Use notifications either:

• Programmatically, to react to an event (for example, update card status in your CMS).

• As end-user messaging, shown in the issuer application or used by customer support.

D1 Notification can generate human-readable messages using message templates (backend and in-app). For in-app notifications, you can also build your own message using metadata provided in the notification payload.

Retry mechanism (backend notifications only)

D1 Notification supports retries for backend notifications sent over REST.

If the issuer backend responds with an HTTP 5xx, D1 Notification keeps the notification and retries after a delay.

Retry delay and retry count are configured during D1 onboarding. If you do not configure retries, D1 does not retry deliveries.

Configure bulk delivery (backend notifications only)

D1 Notification supports bulk delivery for backend notifications. Bulk delivery groups multiple notifications into a single REST request. This reduces request volume to the issuer backend.

Bulk delivery is enabled or disabled during D1 onboarding.

• If enabled, you define the maximum number of notifications per request. D1 Notification supports up to 100 notifications in one request. D1 Notification groups notifications of the same event type until it reaches this limit. If the limit is not reached in time, D1 Notification still sends the batch to avoid excessive delays.

• If disabled, D1 Notification sends one REST request per notification. In this mode, the payload does not include an operations array:

The authorisationCard-operation-model object

Attributes

operationIdstring · min: 1 · max: 12Required

Id corresponding to Retrieval Reference Number (ISO-8583 SID / Field No 37).

operationstring · enumRequired

operation defines the auhtorisation type. Computed from processing code (ISO-8583 SID / Field No 3) transaction type (Postions 1-2).

Example: PURCHASEPossible values:

statusstring · enumRequired

The operation status. Interpreted value of Action Code (ISO-8583 SID / Field No 39).

Example: APPROVEDPossible values:

startTimestring · min: 1 · max: 64Required

Transaction local date and time (ISO-8583 / Field No 12)
Format ISO 8601 YYYY-MM-DDThh:mm:ssTZD

Example: 2022-06-16T06:28:02.492ZPattern: ^[0-9]{4}-((0[13578]|1[02])-(0[1-9]|[12][0-9]|3[01])|(0[469]|11)-(0[1-9]|[12][0-9]|30)|02-(0[1-9]|[12][0-9]))T([0-1][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9](\.[0-9]{3}Z|\.[0-9]{2}([\+\-](0[1-9]|1[0-2])):00)$

errorCodestring · enumOptional

error code , only present in case of DECLINED operation/authorisation

Possible values:

The authorisationCard-operation-model object

{
  "operationId": "text",
  "operation": "PURCHASE",
  "status": "APPROVED",
  "startTime": "2022-06-16T06:28:02.492Z",
  "errorCode": "INVALID_CARD_STATE"
}

Configure notification rules

During D1 onboarding, you define a set of notification rules for the issuer.

You configure:

• Which event types to receive

• Where to deliver notifications (issuer application and/or issuer backend)

• Optional filters to send notifications only when conditions match

1

Select event types

Select which notification event types you want to receive. Each event type has a specific payload structure.

Event types and payload structures:

Notification event Type	Description	Data structure (see the payload returned in case of 200)
Authorisation	Emitted each time an authorization is performed	Structure
CardCreation	Card lifecycle. Emitted each time a card is created by D1	Structure
CardRegistration	Card lifecycle. Emitted each time a card is registered in D1	Structure
CardSuspension	Card lifecycle. Emitted each time a card status is set to suspended	Structure
CardResumption	Card lifecycle. Emitted each time a card status is set to resumed	Structure
CardReplacement	Card lifecycle. Emitted each time a card is replaced	Structure
CardDeletion	Card lifecycle. Emitted each time a card status is set to deleted	Structure
Produce	Physical card issuance. Emitted each time a personalization status changes	Structure

2

Select delivery channels

For each selected event type, choose one or more delivery channels.

Available channels:

Notification distribution service	Description
InAppNotification	Send the notification to the issuer application
BackendNotification	Send the notification to the issuer backend over REST

3

Add optional filters

Optionally define conditions to filter notifications. Filters depend on the notification event type.

Authorization notifications

Additional conditions

By default, D1 Notification produces one notification per authorization. You can add conditions during D1 onboarding to filter which authorizations generate notifications.

Examples:

• Only receive APPROVED authorizations

• Only receive DECLINED authorizations due to the reason INVALID_CARD_STATE

• Only receive PURCHASE and APPROVED authorizations

You can filter on any attribute in the notification payload. See the structure.

Metadata (in-app notifications only)

For in-app notifications, you can define metadata. D1 Notification sends this metadata to the issuer application so it can build a user-facing message for the end user.

Examples:

• operation : the authorization type (PURCHASE, WITHDRAWAL, REFUND...)

• status : the authorization status (APPROVED, DECLINED...)

• declinedReason : in case of authorization DECLINED, the reason (INVALID_CARD_STATE, DOMAIN_CONTROL_FAIL...)

You can expose metadata for any attribute in the notification payload. See the structure.

Message template

You can define a user-facing message per condition. Templates use Mustache syntax.

Examples:

• On the condition 'Only receive APPROVED authorizations', an additional message can be Payment in {{details.merchantName}} has been approved

Will generate the message:

"Payment in ZMARKET has been approved."

• On the condition 'Only receive DECLINED authorizations due to the reason INVALID_CARD_STATE', an additional message can be Payment in {{details.merchantName}} has been declined because your card state is invalid. Additional details :{{details.declinedDetails}}

Will generate the message:

"Payment in ZMARKET has been declined because your card state is invalid. Additional details : CARD_SUSPENDED"

You can reference any attribute from the notification payload. See the structure.

D1 supports multi-language templates. You set a default language and optional additional languages. D1 selects the best match for the end user.

Card lifecycle notifications

Additional conditions

By default, D1 Notification produces one notification per card status change. You can add conditions during D1 onboarding to filter which status changes generate notifications.

Examples:

• Only receive a card SUSPENDED notification when the reason of suspension is CARD_STOLEN

• Only receive a card RESUMED notification when the reason of suspension is ISSUER_DECISION

You can filter on any attribute in the notification payload. See the structure.

Metadata (in-app notifications only)

For in-app notifications, you can define metadata. D1 Notification sends this metadata to the issuer application so it can build a user-facing message for the end user.

Examples:

• cardState : the card status (ACTIVE, SUSPENDED, DELETED...)

• reasonState : the reason of the card status change (ISSUER_DECISION, USER_DECISION, CARD_STOLEN...)

You can expose metadata for any attribute in the notification payload. See the structure.

Message template

You can define a user-facing message per condition. Templates use Mustache syntax.

Examples:

• On the condition 'Only receive a card SUSPENDED notification when the reason of suspension is CARD_STOLEN', an additional message can be Your card has been suspended. Additional details : card stolen

Will generate the message:

"Your card has been suspended. Additional details : card stolen"

• On the condition 'Only receive a card RESUMED notification', an additional message can be Your card has been resumed. Additional details on the reason : {{details.reasonState}}

Will generate the message:

"Your card has been resumed. Additional details on the reason : USER_DECISION"

You can reference any attribute from the notification payload. See the structure.

D1 supports multi-language templates. You set a default language and optional additional languages. D1 selects the best match for the end user.