{ "openapi": "3.0.0", "info": { "title": "Outbound Card API", "version": "2.0", "description": "Notification API to be supported by the Banking system.\n - Notify card authorisations\n - Notify card status changes\n - notify Card operation (digitize) ", "contact": { "name": "Thales", "url": "https://www.thalesgroup.com/" } }, "servers": [ { "url": "https://YOUR_DOMAIN_NAME" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/notifications/d1/v2/issuers/{issuerId}/authorisations": { "parameters": [ { "$ref": "#/components/parameters/issuer-id-path" }, { "$ref": "#/components/parameters/x-correlation-id-output" } ], "post": { "summary": "Notify Card Authorisation Operations", "operationId": "notifyCardAuthorisations", "description": "This request is used by D1 to notify the system of the bank about one or several authorisation processed by D1.
\nThe number max of authorisation in the notification is defined at onboarding time with issuer.\nEach auhtorisation is linked to a given card id, and can contain a message dedicated for the final end-user.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "operations": { "type": "array", "items": { "$ref": "#/components/schemas/authorisationCard-operation-notification" } } } }, "examples": {} } }, "description": "" }, "responses": { "204": { "description": "Successful" }, "400": { "description": "Bad Request, Invalid request URI, header, paramters.
\nD1 will not retry the request until the issue is considered as resolved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorGeneric" } } } }, "401": { "description": "Unauthorized request.
\nD1 will not retry the request until the issue is considered as resolved. ", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorGeneric" } } } }, "403": { "description": "Forbidden action
\nD1 will not retry the request until the issue is considered as resolved.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorGeneric" } } } }, "404": { "description": "Ressource not found, Unknown issuerId
\nD1 will not retry the request until the issue is considered as resolved.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorGeneric" } } } }, "500": { "description": "Internal Server Error. D1 will retry the request later.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorGeneric" } } } }, "503": { "$ref": "#/components/responses/ServiceUnavailableError-outbound" } } } }, "/notifications/d1/v2/issuers/{issuerId}/cards": { "parameters": [ { "$ref": "#/components/parameters/issuer-id-path" }, { "$ref": "#/components/parameters/x-correlation-id-output" } ], "post": { "parameters": [ { "schema": { "type": "string", "example": "'Bearer 2zzLJmBAtTNIU8nF8e8XbmDvaNGs'" }, "in": "header", "name": "Authorization", "description": "Oauth Access token (optional)" } ], "summary": "Notify Card Operations", "operationId": "notifyCardOperations", "description": "This request is used by D1 to notify the system of the bank about any card status update.
\nThere is a retry mechanism in case the notification has not been sent.\nThus the bank system can use this notification to synchronize card status with their card repository.
\nThe number max of card status update in the notification is defined at onboarding time according to bank's system capability.
\nEach update is linked to a given card id, and can contain a message dedicated for the final end-user.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "operations": { "type": "array", "items": { "$ref": "#/components/schemas/CardStatus-operation-notification" } } } } } } }, "responses": { "204": { "description": "Successful" }, "400": { "description": "Bad Request, Invalid request URI, header, paramters.
\nD1 will not retry the request until the issue is considered as resolved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorGenericWithErrorCodeOutbound" } } } }, "401": { "description": "Unauthorized request.
\nD1 will not retry the request until the issue is considered as resolved. ", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorGenericWithErrorCodeOutbound" } } } }, "403": { "description": "Forbidden action
\nD1 will not retry the request until the issue is considered as resolved.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorGenericWithErrorCodeOutbound" } } } }, "404": { "description": "Ressource not found, Unknown issuerId
\nD1 will not retry the request until the issue is considered as resolved.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorGenericWithErrorCodeOutbound" } } } }, "500": { "description": "Internal Server Error. D1 will retry the request later.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorGenericWithErrorCodeOutbound" } } } }, "503": { "$ref": "#/components/responses/ServiceUnavailableError-outbound" } } } }, "/notifications/d1/v1/issuers/{issuerId}/cards/{cardId}/notifications": { "parameters": [ { "$ref": "#/components/parameters/issuer-id-path" }, { "$ref": "#/components/parameters/card-id-path" }, { "$ref": "#/components/parameters/x-correlation-id-output" } ], "post": { "description": "This request is used by D1 to notify the issuer backend about all operations done on a card.", "requestBody": { "content": { "application/json": { "schema": { "description": "The following object represent the account", "type": "object", "properties": { "operationId": { "$ref": "#/components/schemas/operationId" }, "operation": { "type": "string", "description": "The name of the operation done or ongoing on the card.
A DIGITIZE (meaning tokenize) operation can occur only on a virtual card or physical card, and means the card has been digitized (tokenized) (or it is in the process of being so)", "enum": [ "DIGITIZE" ] }, "digitalCardIds": { "type": "array", "description": "Unique identifier of the digital cards concerned by the operation.", "items": { "type": "string" } }, "status": { "type": "string", "description": "Status of the operation", "enum": [ "PENDING", "SUCCESSFUL", "FAILED" ] } }, "required": [ "operationId", "operation", "status" ] } } } }, "responses": { "204": { "description": "Successful" }, "400": { "description": "Bad Request, Invalid request URI or header, or unsupported nonstandard parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "401": { "description": "The provided Authorization header is missing or invalid" }, "404": { "description": "Resource not found. Unknown issuerId or consumerId or accountId or cardId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } } }, "summary": "Notify Card Operation (V1)", "operationId": "notify-card-operation", "parameters": [ { "schema": { "type": "string", "example": "'Bearer 2zzLJmBAtTNIU8nF8e8XbmDvaNGs'" }, "in": "header", "name": "Authorization", "description": "Oauth Access token (optional)" } ] } }, "/cms/api/v1/issuers/{issuerId}/cards/{cardId}/credentials": { "parameters": [ { "$ref": "#/components/parameters/issuer-id-path" }, { "$ref": "#/components/parameters/card-id-path" }, { "$ref": "#/components/parameters/x-correlation-id-output" } ], "get": { "summary": "Get Card Credentials", "operationId": "getCardCredentials", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "encryptedData": { "$ref": "#/components/schemas/encryptedDataForGetCardCredentials" } }, "required": [ "encryptedData" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "401": { "description": "Authorization missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "403": { "description": "Action forbidden (if card is not active, for example)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "404": { "description": "Resource not found (issuerId, cardId)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } } }, "description": "API used by D1 to call the CMS for retrieving the card credentials (PAN, expiry date, cardholder name and CVV) using a card identifier.
It can be used, for example, for displaying the card details to an end user who wants to perform an e-commerce transaction or for registering a 'legacy card' in the D1 system.", "parameters": [ { "schema": { "type": "string", "example": "'Bearer: 2zzLJmBAtTNIU8nF8e8XbmDvaNGs'" }, "in": "header", "name": "Authorization", "description": "Oauth Access Token (optional)" } ] } }, "/cms/api/v1/issuers/{issuerId}/cards/credentials": { "parameters": [ { "$ref": "#/components/parameters/issuer-id-path" }, { "$ref": "#/components/parameters/x-correlation-id-output" } ], "post": { "summary": "Verify Card", "operationId": "verifyCard", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "verificationResults" ], "properties": { "cardId": { "$ref": "#/components/schemas/cardId" }, "consumerId": { "type": "string", "description": "Unique identifier of the end user.\r\n\r\nMust be provided only when the card verification is successful: **verificationResults.card.invalid** flag is false.", "pattern": "[A-Za-z0-9_-]{1,64}", "minLength": 1, "maxLength": 24 }, "accountId": { "type": "string", "description": "Unique identifier of the account. \r\n\r\nNote: This parameter is deprecated, you can still send it but it will be ignored.", "pattern": "[A-Za-z0-9_-]{1,64}", "deprecated": true, "minLength": 1, "maxLength": 24 }, "verificationResults": { "$ref": "#/components/schemas/verificationResults" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "401": { "description": "Authorization missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "403": { "description": "Action forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } } }, "description": "When a tokenization request reaches D1, D1 can call your backend with this method to verify the status of the card for which the tokenization has been requested. This call will be done if the CVK used to compute the card CVV/DCVV has not been shared with D1 during the onboarding process.\n\nIt is expected that your backend verifies the consistency between the card information provided versus the card information known by the backend itself. As a minimum, you should check the following:\n- that the PAN is valid\n- if no expiration date is provided, that the card has not expired\n- if a CVV is provided, that it is valid\n\nIt is important that you provide a proper result response because D1 uses this result when making a decision regarding the tokenization request of the card.\n\nIf the card **is not already registered in D1, and if it has been configured during the on boarding to not reject an unknow card**.\nThen along with the card details, D1 provides a unique card reference : the cardId. You can, OPTIONALLY, override this value by providing your own card ID in the response. In this case, however, you must guarantee the uniqueness of the ID.\nIt is also required to provide a reference of the cardholder information (consumerId).\nIf D1 accepts the card verification, then the consumer and the card will be automatically registered in D1.\n\nIf the card **is not already registered in D1, and if it has been configured during the on boarding to reject an unknow card**. Then the tokenization flow will be stopped before calling your backend, and you will have to register the card using D1 register card API.\n", "parameters": [ { "schema": { "type": "string", "example": "'Bearer: 2zzLJmBAtTNIU8nF8e8XbmDvaNGs'" }, "in": "header", "name": "Authorization", "description": "Oauth Access Token (optional)" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "encryptedData": { "$ref": "#/components/schemas/encryptedDataForVerifyCard" }, "cardId": { "$ref": "#/components/schemas/cardId" }, "cardBin": { "type": "string", "minLength": 6, "maxLength": 6, "description": "The first 6 digits of the PAN" } }, "required": [ "encryptedData", "cardId", "cardBin" ] } } }, "description": "" } } } }, "components": { "schemas": { "encryptedDataForVerifyCard": { "type": "string", "title": "encryptedData (for Verify Card)", "maxLength": 8192, "description": "The encryptedData is the encrypted json (cf http://www.json.org/ ) representation of the card credentials.
This value is encrypted using the JWE encryption (please refer to the **[Encrypt sensitive data](../../../integrate-the-d1-api/encrypt-sensitive-data)** for more details)

Content

Once deciphered, the plaintext contains:\n\t\n|JSON field parameter name|description|MOC|Format|\n|-------|-------|-------|-------|\n|pan|The funding pan value.|M|string - up to 19 digits|\n|exp|The expiry date of the card.|M|string - 4 digits, following the format MMYY|\n|name|The card holder name.|O|string - up to 128 characters|\n|cvv|The CVV2 value of the funding card|O|string - 3 or 4 digits|" }, "encryptedDataForGetCardCredentials": { "type": "string", "title": "encryptedData (for Get Card Credentials)", "maxLength": 8192, "description": "The encryptedData is the encrypted json (cf http://www.json.org/ ) representation of the card credentials.
This value is encrypted using the JWE encryption (please refer to the **[Encrypt sensitive data](../../../integrate-the-d1-api/encrypt-sensitive-data)** for more details)

Content

Once deciphered, the plaintext contains:\n\t\n|JSON field parameter name|description|MOC|Format|\n|-------|-------|-------|-------|\n|pan|The funding pan value.|M|string - from 10 to 19 digits|\n|exp|The expiry date of the card.|M|string - 4 digits, following the format MMYY|\n|name|The card holder name.|O|string - up to 128 characters|\n|cvv|The CVV2 value of the funding card|M|string - 3 or 4 digits|" }, "verificationResults": { "title": "verificationResults", "type": "object", "description": "Rules verified by the issuer ", "properties": { "securityCode": { "type": "object", "properties": { "valid": { "type": "boolean" }, "verificationAttemptsExceeded": { "type": "boolean" } } }, "card": { "type": "object", "properties": { "lostOrStolen": { "type": "boolean" }, "expired": { "type": "boolean" }, "invalid": { "type": "boolean" }, "fraudSuspect": { "type": "boolean" } } } }, "required": [ "card" ] }, "error": { "title": "error", "type": "object", "x-examples": { "Example 1": { "error": "Exmaple of a generic error description" } }, "description": "An error occurred", "properties": { "error": { "type": "string", "description": "Detailed description of the error that occurred.\n" } } }, "CardStatus-operation-notification": { "type": "object", "required": [ "operationId", "operation", "status", "startTime", "cardId" ], "properties": { "operationId": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "[A-Za-z0-9_-]{1,64}", "description": "Unique identifier of the operation." }, "operation": { "type": "string", "enum": [ "CREATE", "REGISTER", "ACTIVATE", "SUSPEND", "RESUME", "DELETE", "DIGITIZE", "RENEW", "REPLACE", "PRODUCE", "STANDALONE_TRACKING", "CLICK_TO_PAY_ENROLMENT", "CLICK_TO_PAY_UPDATE", "CLICK_TO_PAY_OPTOUT", "UPDATE_ORDER" ], "description": "card status operation", "example": "RENEW" }, "status": { "type": "string", "enum": [ "PENDING", "SUCCESSFUL", "FAILED" ], "description": "The operation status", "example": "SUCCESSFUL" }, "startTime": { "type": "string", "description": "Time of the operation.", "minLength": 1, "maxLength": 64, "example": "2022-06-16T06:28:02.492Z" }, "endTime": { "type": "string", "description": "End time of the operation", "minLength": 1, "maxLength": 64, "example": "2022-06-16T09:28:12.492Z" }, "cardId": { "$ref": "#/components/schemas/cardId" }, "details": { "oneOf": [ { "$ref": "#/components/schemas/CardStatusDetails" }, { "$ref": "#/components/schemas/ProduceDetails" }, { "$ref": "#/components/schemas/DigitizeDetails" }, { "$ref": "#/components/schemas/pullOperation" }, { "$ref": "#/components/schemas/trackingOperation" } ] }, "message": { "type": "object", "properties": { "format": { "type": "string", "description": "Format of the message", "enum": [ "TEXT", "HTML" ] }, "title": { "type": "string", "description": "Title of the notification", "example": "Card Suspended" }, "content": { "type": "string", "description": "Message to be displayed", "example": "Your card has been suspended." } } }, "errorCode": { "type": "string", "description": "The type of the error", "example": "FIELD_INVALID_FORMAT" }, "error": { "type": "string", "description": "Provide more error details if possible.
For example name of the field with invalid format.", "example": "consumerId" } } }, "CardStatusDetails": { "type": "object", "title": "CREATE, REGISTER, ACTIVATE, SUSPEND, RESUME, DELETE, RENEW, REPLACE operations", "description": "Card Status Details", "properties": { "cardProductId": { "type": "string", "description": "Card Product identifier of the card" }, "cardState": { "$ref": "#/components/schemas/cardState" }, "reasonState": { "type": "string", "description": "Optional reason associated to the state of the card", "enum": [ "CLOSED_ACCOUNT", "CLOSED_CARD", "CARD_LOST", "CARD_FOUND", "CARD_STOLEN", "CARD_BROKEN", "CARD_NOT_RECEIVED", "FRAUD", "USER_DECISION", "ISSUER_DECISION", "CVV2_LOCKED", "EXPIRY_DATE_LOCKED", "PIN_LOCKED" ] }, "newCardId": { "type": "string", "description": "In case of card replacement, this field correspond to the cardId of the new card" }, "encryptedData": { "type": "string", "maxLength": 8192, "pattern": "^(?:[\\x20-\\x2D\\x2F-\\x7F]*\\.){4}(?:[\\x20-\\x2D\\x2F-\\x7F]*)$", "description": "Encrypted card information that can be provided in case of operation 'CREATE', 'REGISTER', 'RENEW' and 'REPLACE' (Receiver shall be configured accordingly during the onboarding)
\nIn case of 'REPLACE', this is the encrypted information of 'newCardId'
\nThe encryptedData is the encrypted json (cf http://www.json.org/) representation of the Card information.\nThis value is encrypted using the JWE encryption (please refer to the **[Encrypt sensitive data](../../../integrate-the-d1-api/encrypt-sensitive-data)** for more details)\n

Once deciphered, the plaintext contains a json structure with:\n|JSON field parameter name|description|MOC|Format|\n|-------|-------|-------|-------|\n|pan|The funding pan value.|M|string - up to 19 digits|\n|exp|The expiry date of the card.|M|string - 4 digits, following the format MMYY|" } } }, "ProduceDetails": { "type": "object", "title": "PRODUCE operation", "description": "The card production status notifcation details", "required": [ "status" ], "properties": { "status": { "$ref": "#/components/schemas/productionStatusInNotification" }, "reason": { "type": "string", "description": "Additional details in case of exception during data processing or card production", "example": "" }, "consumerId": { "type": "string", "description": "The consumer ID (card holder).", "example": "271b-6e47-8ec3-7f3f" }, "dueDate": { "type": "string", "format": "date", "example": "2023-01-21", "description": "The estimated card production date. It uses the format ```YYYY-MM-DD```." }, "productionSite": { "maxLength": 50, "minLength": 0, "type": "string", "description": "The factory where the card is produced.", "example": "Gemenos" }, "shipment": { "$ref": "#/components/schemas/shipment" }, "name": { "maxLength": 50, "minLength": 0, "description": "The card holder name printed on the card.\n", "type": "string", "example": "MR. JOHN SMITH" }, "maskedPan": { "maxLength": 19, "minLength": 12, "description": "The masked PAN value (Primary Account Number).\n", "type": "string", "example": "123456xxxxxx7890", "pattern": "^[0-9xX\\*]{12,19}$" }, "orderId": { "description": "The unique identifier of order used for card production.\n", "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$", "example": "9b95d70e-21fe-4c36-9368-ddd7fbd729e8" }, "packageId": { "description": "The unique identifier of the package used for card production.\n", "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$", "example": "be0b085c-ef03-4581-9e7b-50dbb2f08f43" }, "services": { "$ref": "#/components/schemas/services" }, "inputFileName": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Name of the input file in case of hybrid mode.", "example": "myInputFile_20240707.gz" }, "cardPackageDetails": { "$ref": "#/components/schemas/cardPackageDetails" }, "deliveryAddress": { "description": "The recipient's address.\n", "$ref": "#/components/schemas/addressInProduceNotification" } } }, "DigitizeDetails": { "title": "DIGITIZE operation", "type": "object", "description": "The card digitization details", "required": [ "tbd" ], "properties": { "deviceInformation": { "$ref": "#/components/schemas/deviceInformation" }, "digitalCardsDetails": { "type": "array", "minItems": 1, "maxItems": 2, "items": { "type": "object", "required": [ "generalInformation", "credentials" ], "properties": { "isPrimary": { "description": "Flag indicating whether the digital card was create by the primary TSP or not.", "type": "boolean", "default": true }, "generalInformation": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/digitalCardInformation" }, { "type": "object", "properties": { "digitalCardRequestorInformation": { "$ref": "#/components/schemas/digitalCardRequestorInformation" } } } ] }, "credentials": { "type": "string", "description": "The field is the json (cf http://www.json.org/ ) representation of the DIGITAL card.\nJWE encryption is used to secure the field (please refer to the [Encrypt sensitive data](../../../integrate-the-d1-api/encrypt-sensitive-data) for more details)\nDetails:\n\n{\n\n \"pan\":\"...\",\n \n \"exp\":\"...\"\n \n}\n\n\nThe PAN is Mandatory, up to 19 digits.\n\nThe expiry date in the format MMYY. It is not provided for UPI scheme.", "minLength": 1, "maxLength": 8196 } } } }, "eligibilityInformation": { "$ref": "#/components/schemas/eligibilityInformation" }, "digitizationInformation": { "$ref": "#/components/schemas/digitizationInformation" } } }, "digitalCardInformation": { "title": "digitalCardInformation", "type": "object", "description": "Provides information about the token. Note that this data is available only if the tokenization is successful or pending.", "properties": { "digitalCardId": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Unique identifier of the token specified by the TSP" }, "panSuffix": { "type": "string", "minLength": 4, "maxLength": 4, "description": "Last four digits of the token" }, "state": { "$ref": "#/components/schemas/digitalCardState" }, "type": { "$ref": "#/components/schemas/tokenType" }, "provisioningTime": { "type": "string", "maxLength": 32, "description": "The provisioning time of the token. Format ISO 8601 YYYY-MM-DDThh:mm:ssTZD" } }, "required": [ "digitalCardId", "panSuffix", "state" ] }, "pullOperation": { "title": "UPDATE_ORDER operation", "type": "object", "description": "The update order status notification details", "required": [ "pullType", "status" ], "properties": { "pullType": { "type": "string", "description": "The type of change to apply on the card order", "enum": [ "ACCELERATE", "ACCELERATE_AND_REDIRECT", "CANCEL", "REDIRECT" ] }, "status": { "$ref": "#/components/schemas/updateOrderStatus" }, "newDeliveryAddress": { "description": "The new delivery address", "$ref": "#/components/schemas/addressInPullNotification" } } }, "trackingOperation": { "type": "object", "title": "STANDALONE_TRACKING", "description": "The card tracking details", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "CARD_SHIPPED", "CARD_RETURNED" ], "example": "CARD_SHIPPED", "description": "The current status of card.\n\n- CARD_SHIPPED: The card has been picked up by the carrier.\n- CARD_RETURNED: The card has been returned back to sender and destroyed.\n" }, "trackingType": { "type": "string", "enum": [ "PRODUCTION", "SHIPMENT", "RETURN" ], "example": "PRODUCTION", "description": "The current status of card.\n\n- PRODUCTION: Track Card Production.\n- SHIPMENT: Track Card Production and Shipment.\n- RETURN: Track Card return.\n" }, "productionSite": { "maxLength": 50, "minLength": 0, "type": "string", "description": "The factory where the card is produced.", "example": "Gemenos" }, "shipment": { "$ref": "#/components/schemas/shipment" } } }, "authorisationCard-operation-notification": { "allOf": [ { "$ref": "#/components/schemas/authorisationCard-operation-model" }, { "type": "object", "required": [ "cardId" ], "properties": { "cardId": { "$ref": "#/components/schemas/cardId" }, "details": { "$ref": "#/components/schemas/authorisationCard-details" }, "message": { "$ref": "#/components/schemas/AuthorisationNotification-message" } } } ] }, "AuthorisationNotification-message": { "type": "object", "properties": { "format": { "type": "string", "description": "Format of the message", "enum": [ "TEXT", "HTML" ] }, "title": { "type": "string", "description": "Title of the notification", "example": "Approved Authorisation" }, "content": { "type": "string", "description": "Message to be displayed", "example": "Payment in AMAZONIA corp. of 100.00 EUR has been approved." } } }, "issuerId": { "maxLength": 10, "minLength": 10, "type": "string" }, "authorisationCard-operationId": { "type": "string", "minLength": 1, "maxLength": 12, "description": "Id corresponding to Retrieval Reference Number (ISO-8583 SID / Field No 37)." }, "authorisationCard-operation-model": { "type": "object", "required": [ "operationId", "operation", "status", "startTime" ], "properties": { "operationId": { "$ref": "#/components/schemas/authorisationCard-operationId" }, "operation": { "type": "string", "enum": [ "PURCHASE", "WITHDRAWAL", "REFUND", "PAYMENT", "OTHER" ], "description": "operation defines the auhtorisation type. Computed from processing code (ISO-8583 SID / Field No 3) transaction type (Postions 1-2).", "example": "PURCHASE" }, "status": { "type": "string", "enum": [ "APPROVED", "PARTIALLY_APPROVED", "REVERSED", "DECLINED" ], "description": "The operation status. Interpreted value of Action Code (ISO-8583 SID / Field No 39).", "example": "APPROVED" }, "startTime": { "type": "string", "description": "Transaction local date and time (ISO-8583 / Field No 12)
\nFormat ISO 8601 YYYY-MM-DDThh:mm:ssTZD", "minLength": 1, "maxLength": 64, "pattern": "^[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)$", "example": "2022-06-16T06:28:02.492Z" }, "errorCode": { "type": "string", "description": "error code , only present in case of DECLINED operation/authorisation", "enum": [ "INVALID_CARD_STATE", "INVALID_CARD_DATA", "CONTROL_FAIL", "VELOCITY_CHECK_FAIL", "BALANCE_CHECK_FAIL", "FRAUD_DETECTED", "TECHNICAL_ERROR", "ISSUER_ERROR", "DOMAIN_CONTROL_FAIL" ] } } }, "cardId": { "type": "string", "description": "Unique identifier of the card.", "minLength": 1, "maxLength": 48, "pattern": "^[A-Za-z0-9_-]{1,48}$" }, "currencyCode": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Currency Code in ISO 4217 alpha code format", "example": "EUR" }, "authorisationCardDetails-merchant": { "additionalProperties": false, "type": "object", "description": "merchant information as provided from Authorisation (ISO-8583 SID / Field No 42 & 43)", "required": [ "merchantId", "merchantNameAddress" ], "properties": { "merchantId": { "type": "string", "minLength": 1, "maxLength": 15, "description": "Card acceptor identification code (ISO-8583 SID / Field No 42)." }, "merchantNameAddress": { "type": "string", "minLength": 1, "maxLength": 40, "description": "Card acceptor name and address (ISO-8583 SID / Field No 43)." }, "merchantName": { "type": "string", "minLength": 1, "maxLength": 24, "description": "merchant accronym (positions 1-24) of Card acceptor name and address (ISO-8583 SID / Field No 43)." }, "city": { "type": "string", "minLength": 1, "maxLength": 13, "description": "merchant city (positions 25-37) of Card acceptor name and address (ISO-8583 SID / Field No 43)." }, "countryCode": { "type": "string", "description": "merchant country (positions 38-40) of Card acceptor name and address (ISO-8583 SID / Field No 43)
\nCountry code in ISO 3166-1 alpha-2.", "minLength": 2, "maxLength": 2, "pattern": "^[A-Z]{2}$", "example": "FR" }, "merchantType": { "type": "string", "description": "MCC / Merchant type (ISO-8583 SID / Field No 18). (not provided for an operation having a status=REVERSED)", "minLength": 4, "maxLength": 4, "pattern": "^[\\d]{4}$", "example": "5542" } } }, "digitalCardId": { "type": "string", "description": "Unique identifier of the digital card.", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "authorisationCardDetails-digitalCard": { "additionalProperties": false, "type": "object", "description": "Provided in case Authorisation with a digital card.
\nInformation extracted in Tag P55 (Token Data) from Additional Private Data (ISO-8583 SID / Field No 48)", "required": [ "digitalCardId", "digitalCardRequestorId" ], "properties": { "digitalCardId": { "$ref": "#/components/schemas/digitalCardId" }, "digitalCardRequestorId": { "type": "string", "description": "Digital Card requestor identifier. This is provided by the TSP itself.", "minLength": 11, "maxLength": 11 } } }, "authorisationCard-details": { "type": "object", "required": [ "isoMessageType", "transactionDate", "transmissionDate", "retrievalReferenceNumber", "stan", "internalStan", "actionCode", "amount", "currencyCode", "functionCode", "merchant" ], "properties": { "isoMessageType": { "type": "string", "description": "The ISO Message type of the request/advice sent by the switch.
Value '1100' represents an authorisation request.", "minLength": 4, "maxLength": 4, "pattern": "^[\\d]{4}$", "example": "1100" }, "transactionDate": { "type": "string", "description": "Transaction local date and time (ISO-8583 SID / Field No 12)
\nFormat ISO 8601 YYYY-MM-DDThh:mm:ssTZD", "minLength": 1, "maxLength": 64, "pattern": "^[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)$", "example": "2022-06-16T06:28:02.492Z" }, "transmissionDate": { "type": "string", "description": "Transmission date and time (ISO-8583 SID / Field No 7)
\nFormat ISO 8601 YYYY-MM-DDThh:mm:ssTZD", "minLength": 1, "maxLength": 64, "pattern": "^[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)$", "example": "2022-06-16T06:28:02.492Z" }, "retrievalReferenceNumber": { "type": "string", "minLength": 1, "maxLength": 12, "description": "Retrieval Reference Number (ISO-8583 SID / Field No 37).", "example": "230710891451" }, "stan": { "type": "string", "description": "System Trace Audit Number (ISO-8583 SID / Field No 11)", "minLength": 1, "maxLength": 6, "example": "891451" }, "internalStan": { "type": "string", "description": "The internal System Trace Audit Number generated by the solution.", "minLength": 1, "maxLength": 6, "example": "980588" }, "actionCode": { "type": "string", "minLength": 3, "maxLength": 3, "pattern": "^[\\d]{3}$", "description": "The none interpreted Action Code return by the authorisation host (ISO-8583 SID / Field No 39).
\nFor example '000' for APPROVED, '002' for PARTIAL APPROVE", "example": "000" }, "declinedReason": { "type": "string", "description": "The declined reason of the operation, present only is the authorisation has been DECLINED by Auhtorisation host.", "enum": [ "INVALID_CARD_STATE", "INVALID_CARD_DATA", "CONTROL_FAIL", "VELOCITY_CHECK_FAIL", "BALANCE_CHECK_FAIL", "FRAUD_DETECTED", "TECHNICAL_ERROR", "ISSUER_ERROR", "DOMAIN_CONTROL_FAIL" ] }, "declinedDetails": { "type": "string", "enum": [ "INVALID_CVV2", "INVALID_DCVV2", "INVALID_EXPIRY_DATE", "INVALID_RETRYABLE_DCVV2", "NO_ACTIVE_DCVV2", "CARD_DELETED", "CARD_EXPIRED", "CARD_REPLACED", "CARD_SUSPENDED", "CONTACTLESS_DISABLED", "CVV2_LOCKED", "EXPIRY_DATE_LOCKED", "PIN_LOCKED", "COUNTRY_NOT_ALLOWED", "CURRENCY_NOT_ALLOWED", "MAGSTRIPE_DISABLED", "MERCHANT_TYPE_NOT_ALLOWED", "ONLINE_PAYMENT_DISABLED", "WITHDRAWAL_DISABLED", "EMV_AUTHORIZATION_VERIFICATION_FAIL", "INVALID_PIN", "ABOVE_MAX_AMOUNT", "BELOW_MIN_AMOUNT", "MAX_AMOUNT_LIMIT_REACHED", "MAX_TRANSACTION_LIMIT_REACHED", "NOT_ENOUGH_FUND", "INVALID_MERCHANT", "SUSPECTED_FRAUD", "ACCOUNT_NOT_FOUND", "FUND_CHECK_FAILED", "TECHNICAL_ERROR" ], "description": "Additional details for declined Reason if available. In table below you will find the possible details for each declined reason\n| Declined reason | possible declined details |\n| -------------------- | ------------------------|\n| INVALID_CARD_DATA | INVALID_CVV2
INVALID_DCVV2
INVALID_EXPIRY_DATE
INVALID_RETRYABLE_DCVV2
NO_ACTIVE_DCVV2 |\n| INVALID_CARD_STATE | CARD_DELETED
CARD_EXPIRED
CARD_REPLACED
CARD_SUSPENDED
CONTACTLESS_DISABLED
CVV2_LOCKED
EXPIRY_DATE_LOCKED
PIN_LOCKED |\n| DOMAIN_CONTROL_FAIL | CONTACTLESS_DISABLED
COUNTRY_NOT_ALLOWED
CURRENCY_NOT_ALLOWED
MAGSTRIPE_DISABLED
MERCHANT_TYPE_NOT_ALLOWED
ONLINE_PAYMENT_DISABLED
WITHDRAWAL_DISABLED |\n| CONTROL_FAIL | EMV_AUTHORIZATION_VERIFICATION_FAIL
INVALID_PIN |\n| VELOCITY_CHECK_FAIL | ABOVE_MAX_AMOUNT
BELOW_MIN_AMOUNT
MAX_AMOUNT_LIMIT_REACHED
MAX_TRANSACTION_LIMIT_REACHED |\n| BALANCE_CHECK_FAIL | NOT_ENOUGH_FUND |\n| FRAUD_DETECTED | INVALID_MERCHANT
SUSPECTED_FRAUD |\n| ISSUER_ERROR | ACCOUNT_NOT_FOUND
FUND_CHECK_FAILED |" }, "amount": { "type": "number", "minimum": 0, "maximum": 999999999999, "description": "The nominal transaction amount value (ISO-8583 SID / Field No 04).
\nValue without decimal separator, use the currency exponent to determine the number of decimal.
\nFor example, an amount in euro of €21 is returned 2100.", "example": 2100 }, "currencyCode": { "$ref": "#/components/schemas/currencyCode" }, "billingAmount": { "type": "number", "minimum": 0, "maximum": 999999999999, "description": "The billing amount value from Authorisation (ISO-8583 SID / Field No 06)
\nValue without decimal separator, use the currency exponent to determine the number of decimal.
\nFor example, an amount in euro of €21 is returned 2100.", "example": 2100 }, "billingCurrencyCode": { "$ref": "#/components/schemas/currencyCode" }, "conversionRate": { "type": "number", "description": "Cardholder billing exchange rate from Auhtorization (ISO-8583 SID / Field No 10)
Or used by the solution during conversion.", "minimum": 0, "maximum": 9999999, "example": 1.092479 }, "replacementAmount": { "type": "number", "minimum": 0, "maximum": 999999999999, "description": "The replacement amount value from Authorisation (ISO-8583 SID / Field No 30)
\nValue without decimal separator, use the currency exponent to determine the number of decimal.
\nFor example, an amount in euro of €21 is returned 2100.", "example": 2100 }, "replacementCurrencyCode": { "$ref": "#/components/schemas/currencyCode" }, "accountNumber": { "type": "string", "maxLength": 24, "description": "Account number used when posting with Core Banking System" }, "standInProcessing": { "type": "boolean", "description": "Specify if STAND-In processing has been used or not by D1 Authorisation host.\n - true if the authorization has been approvded on behalf of the Core Banking System (STAND-IN processing)\n - false if financial authorization has been approved by the Core Banking system.", "example": false }, "functionCode": { "type": "string", "description": "Function code (ISO-8583 SID - Field No 24)", "minLength": 3, "maxLength": 3, "pattern": "^[\\d]{3}$", "example": "100" }, "messageReasonCode": { "type": "string", "description": "Function code (ISO-8583 SID - Field No 25)", "minLength": 4, "maxLength": 4, "pattern": "^[\\d]{4}$", "example": "1002" }, "cardPresent": { "type": "boolean", "description": "Point of service data code (ISO-8583 SID / Field No 22) Card Present indicator (Postion 06).", "example": false }, "cardDataInputMode": { "type": "string", "description": "Point of service data code (ISO-8583 SID / Field No 22) Card Data Input Mode (Postion 07).
See ISO-8583 SID for the list of possible values.", "minLength": 1, "maxLength": 1, "example": "1" }, "initiatingParty": { "type": "string", "enum": [ "CARDHOLDER", "MERCHANT" ], "description": "Merchant or Cardholder initiated transaction
TAG P64 in Additional private data (ISO-8583 SID / Field No 48) Initating-Party (Postion 04)." }, "acquirerCountryCode": { "type": "string", "description": "Acquiring institution country code (ISO-8583 SID / Field No 19).
\nCountry code in ISO 3166-1 alpha-2.", "minLength": 2, "maxLength": 2, "pattern": "^[A-Z]{2}$", "example": "FR" }, "merchant": { "$ref": "#/components/schemas/authorisationCardDetails-merchant" }, "digitalCard": { "$ref": "#/components/schemas/authorisationCardDetails-digitalCard" } } }, "errorGeneric": { "additionalProperties": false, "type": "object", "description": "Generic error returned by the APIs.", "properties": { "errorCode": { "type": "string", "description": "The type of the error", "example": "FIELD_INVALID_FORMAT" }, "error": { "type": "string", "description": "Provide more error details if possible.
For example name of the field with invalid format.
This field is for troubleshooting purposes only, it can change at any time so MUST NOT be parsed, and is not supposed to be human readable so CANNOT be displayed to end users.", "example": "consumerId" } } }, "cardState": { "type": "string", "description": "the state of the card", "enum": [ "INACTIVE", "ACTIVE", "SUSPENDED", "DELETED", "REPLACED" ], "example": "ACTIVE" }, "productionStatusInNotification": { "type": "string", "enum": [ "CARD_PROD_REQUESTED", "DATA_PREPARED", "CARD_PROD_READY", "CARD_PROD_ONGOING", "CARD_PROD_DONE", "CARD_SHIPPED", "CARD_PROD_CANCELED", "CARD_PROD_ONHOLD", "DATA_EXCEPTION", "CARD_PROD_EXCEPTION" ], "example": "CARD_SHIPPED", "description": "The current status of card production.\n\n|status code | description |\n|---------------------------|-------------------------------------------------------------------------------------------------------------------|\n|CARD_PROD_REQUESTED
*(full api only)* | Card production has been requested via the D1 APIs. |\n|DATA_PREPARED
*(full api only)* | The data required for production has been successfully prepared. | \n|DATA_EXCEPTION
*(full api only)* | Data preparation has failed for some reason. |\n|CARD_PROD_READY | The data has arrived at the Personalization Center; the card is ready to be produced. |\n|CARD_PROD_ONGOING | Card production has started. |\n|CARD_PROD_DONE
*(instant issuance only)* | The card has been successfully produced. |\n|CARD_SHIPPED | The card has been shipped.|\n|CARD_PROD_CANCELED | Card production has been canceled by the issuer. |\n|CARD_PROD_ONHOLD | Card production has been put on hold. |\n|CARD_PROD_EXCEPTION
*(instant issuance only)* | Card production failed for some reason. |\n" }, "lastCheckpoint": { "type": "object", "description": "The tracking information of the last checkpoint", "properties": { "checkpointTime": { "type": "string", "description": "The date and time of the checkpoint event, provided by the carrier. It is in the format ```YYYY-MM-DDThh:mm:ssZ``` for the timezone of the checkpoint.", "format": "date-time", "example": "2023-01-21T17:32:28Z" }, "city": { "minLength": 1, "type": "string", "description": "The city info provided by carrier.", "example": "New York" }, "countryName": { "type": "string", "description": "The country/Region name of the checkpoint, may also contain other location information.", "example": "United States" }, "message": { "type": "string", "description": "The checkpoint message.", "example": "Package delivered" } } }, "shipment": { "type": "object", "properties": { "pickupDate": { "type": "string", "description": "The date and time the shipment was picked up by the carrier. It is in the format ```YYYY-MM-DDThh:mm:ssZ``` for the timezone where the pickup occured.", "format": "date-time", "example": "2023-01-21T17:32:28Z" }, "carrier": { "type": "string", "description": "Unique carrier code.\n\n|Carrier Code|Carrier Name|\n|----|----|\n|chronopost-france|Chronopost France|\n|dhl|DHL Express|\n|fedex|FedEx®|\n|la-poste-colissimo|La Poste|AvailableForPickup|\n|spain-correos-es|Correos de España|\n|ups|UPS|\n|usps|USPS| |\n", "example": "fedex" }, "trackingNumber": { "type": "string", "pattern": "^[A-Za-z0-9 _\\-\\.\\/]{1,64}$", "description": "The tracking number.", "example": "61293150000079650811" }, "status": { "maxLength": 50, "minLength": 0, "type": "string", "enum": [ "INFO_RECEIVED", "IN_TRANSIT", "OUT_FOR_DELIVERY", "FAILED_ATTEMPT", "DELIVERED", "AVAILABLE_FOR_PICKUP", "EXCEPTION", "EXPIRED", "PENDING" ], "description": "Current status of tracking.\n\n|status code | description |\n|---------------------------|-------------------------------------------------------------------------------------------------------------------|\n|INFO_RECEIVED | Carrier has received request from shipper and is about to pick up the shipment. |\n|IN_TRANSIT | Carrier has accepted or picked up shipment from shipper. The shipment is on the way. |\n|OUT_FOR_DELIVERY | Carrier is about to deliver the shipment, or it is ready to pickup. |\n|FAILED_ATTEMPT | Carrier attempted to deliver but failed, and usually leaves a notice and will try to deliver again. |\n|DELIVERED | The shipment was delivered successfully. |\n|AVAILABLE_FOR_PICKUP | The package arrived at a pickup point near you and is available for pickup. |\n|EXCEPTION | Custom hold, undelivered, returned shipment to sender or any shipping exceptions. |\n|EXPIRED | Shipment has no tracking information for 30 days since added. |\n|PENDING | Tracking information not available yet. | |\n", "example": "DELIVERED" }, "message": { "minLength": 1, "type": "string", "description": "Normalized tracking message.\n\n|Message|Description|Shipment Status|\n|----|----|----|\n|DELIVERED|Shipment delivered successfully|DELIVERED|\n|Picked up by the customer|Package picked up by the customer|DELIVERED|\n|Sign by customer|Package delivered to and signed by the customer|DELIVERED|\n|Delivered and received cash on delivery|Package delivered to the customer and cash collected on delivery|DELIVERED|\n|Available for pickup|The package arrived at a pickup point near you and is available for pickup|AVAILABLE_FOR_PICKUP|\n|EXCEPTION|Delivery of the package failed due to some shipping exception|EXCEPTION|\n|Customer moved|Delivery of the package failed as the customer relocated|EXCEPTION|\n|Customer refused delivery|Delivery of the package failed as the recipient refused to take the package due to some reason|EXCEPTION|\n|Delayed (Customs clearance)|Package delayed due to some issues during the customs clearance|EXCEPTION|\n|Delayed (External factors)|Package delayed due to some unforeseen reasons|EXCEPTION|\n|Held for payment|The package being held due to pending payment from the customer's end|EXCEPTION|\n|Incorrect Address|Package not delivered due to incorrect recipient address|EXCEPTION|\n|Pick up missed|Package available for the pickup but not collected by the customer|EXCEPTION|\n|Rejected by carrier|Package rejected by the carrier due to noncompliance with its guidelines|EXCEPTION|\n|Returning to sender|The package is on its way back to the sender|EXCEPTION|\n|Returned to sender|The return package has been successfully received by the sender|EXCEPTION|\n|Shipment damage|Shipment damaged|EXCEPTION|\n|Shipment lost|Delivery of the package failed as it got lost|EXCEPTION|\n|Failed Attempt|The delivery of the package failed due to some reason. Courier usually leaves a notice and will try to deliver again|FAILED_ATTEMPT|\n|Addressee not available|Recipient not available at the given address|FAILED_ATTEMPT|\n|Business Closed|Business is closed at the time of delivery|FAILED_ATTEMPT|\n|In Transit|Shipment on the way|IN_TRANSIT|\n|Acceptance scan|Shipment accepted by the carrier|IN_TRANSIT|\n|Arrival scan|Shipment arrived at a hub or sorting center|IN_TRANSIT|\n|Arrived at the destination country/region|International shipment arrived at the destination country/region|IN_TRANSIT|\n|Customs clearance completed|Customs clearance completed|IN_TRANSIT|\n|Customs clearance started|Package handed over to customs for clearance|IN_TRANSIT|\n|Departure Scan|Package departed from the facility|IN_TRANSIT|\n|Problem resolved|Problem resolved and shipment in transit|IN_TRANSIT|\n|Forwarded to a different delivery address|Shipment forwarded to a different delivery address|IN_TRANSIT|\n|Info Received|The carrier received a request from the shipper and is about to pick up the shipment|INFO_RECEIVED|\n|Out for Delivery|The package is out for delivery|OUT_FOR_DELIVERY|\n|Customer contacted|The customer is contacted before the final delivery|OUT_FOR_DELIVERY|\n|Delivery appointment scheduled|A delivery appointment is scheduled|OUT_FOR_DELIVERY|\n|PENDING|No information available on the carrier website or the tracking number is yet to be tracked|PENDING|\n|Carrier account not connected|It represents the shipments are pending due to no connection with carrier accounts|PENDING|\n|Label created, no updates yet|The order has been processed/packaged, but not scanned at a shipping location yet|PENDING|\n|Wrong carrier|There is no tracking info available because the carrier is wrong|PENDING|\n|No recent updates|There have been no new tracking updates in the last 120 days|PENDING|\n|Unrecognized carrier|AfterShip can’t track this type of shipment as the carrier is unrecognized.|PENDING|\n|Expired|No tracking information of the shipment, from the last 30 days|EXPIRED|\n", "example": "Picked up by the customer" }, "trackingUrl": { "type": "string", "description": "Official tracking URL of the carrier (if any).", "example": "https://www.fedex.com/apps/fedextrack/?tracknumbers=61293150000079650811&cntry_code=US" }, "redirectUrl": { "type": "string", "description": "Delivery instructions (delivery date or address) can be modified by visiting the link if supported by the carrier.", "example": "https://www.fedex.com/apps/fedextrack/?action=track&tracknumbers=61293150000079650811&cntry_code=US" }, "estimatedDeliveryDate": { "type": "string", "description": "'The estimated delivery date provided by the carrier. It is in the format ```YYYY-MM-DDThh:mm:ssZ``` for the recipent's timezone.'", "format": "date-time", "example": "2023-01-21T17:32:28Z" }, "lastUpdatedAt": { "type": "string", "description": "The date and time the shipment was updated. It is in the format ```YYYY-MM-DDThh:mm:ssZ``` for the timezone GMT+0.", "format": "date-time", "example": "2023-01-21T17:32:28Z" }, "deliveryDate": { "type": "string", "description": "'The date and time the shipment was delivered. It is in the format ```YYYY-MM-DDThh:mm:ssZ``` for the recipent's timezone.'", "format": "date-time", "example": "2023-01-21T17:32:28Z" }, "signedBy": { "type": "string", "description": "Signed by information for delivered shipment.", "example": "Steve Young" }, "failedDeliveryAttempts": { "type": "string", "description": "Number of failed attempts courier tried to deliver the card.", "example": "2" }, "lastCheckpoint": { "$ref": "#/components/schemas/lastCheckpoint" } } }, "cardProductId": { "type": "string", "description": "Unique identifier of the type of card ( defined during the onboarding of D1)", "minLength": 1, "maxLength": 48, "pattern": "^[A-Za-z0-9_-]{1,48}$" }, "services": { "required": [ "issuance", "delivery" ], "properties": { "cardProductId": { "$ref": "#/components/schemas/cardProductId" }, "issuance": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-zA-Z0-9_-\\s]{1,64}$", "description": "The type of issuance.\n
\n|Attribute|Description|\n|-------|-------|\n|CREATION|Issuance of a brand-new card to a user|\n|RENEWAL|An existing card reaches its expiration date and needs to be replaced with a new one for continued use|\n|REPLACEMENT|An existing card needs to be reissued due to loss, theft, or damage.|\n", "example": "RENEWAL" }, "priority": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-zA-Z0-9_-\\s]{1,64}$", "description": "The level of priority agreed for the card production (defined during the onboarding of D1).\n", "example": "P1" }, "delivery": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-zA-Z0-9_-\\s]{1,64}$", "description": "The shipment method (defined during the onboarding of D1).\n", "example": "DHL" }, "packaging": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-zA-Z0-9_-\\s]{1,64}$", "example": "welcome_pack_red", "default": "NO_PACK", "description": "Unique identifier of the packaging (defined during the onboarding of D1).\n" }, "cardCarrier": { "type": "string", "minLength": 1, "maxLength": 64, "default": "NO_CARRIER", "pattern": "^[a-zA-Z0-9_-\\s]{1,64}$", "description": "Unique identifier of the card carrier (defined during the onboarding of D1).\n" } } }, "cardPackageDetails": { "type": "object", "properties": { "plastic": { "type": "string", "description": "Reference of the plastic used for the card\n", "minLength": 2, "maxLength": 40, "example": "CardRef1" }, "artworkId": { "type": "string", "description": "Reference of the artwork printed on the card\n", "minLength": 2, "maxLength": 40, "example": "CardRef1" }, "cardCarrier": { "type": "string", "description": "Reference of the card carrier used for the card\n", "minLength": 2, "maxLength": 100, "example": "17609320 Carrier A4 white 100g Thales" }, "envelope": { "type": "string", "description": "Reference of the envelope used for the card\n", "minLength": 2, "maxLength": 100, "example": "ENV BLANCHE 115X229mm FEN 45X100X2520 CART1000" }, "package": { "type": "string", "minLength": 2, "maxLength": 100, "description": "Reference of the package used for the card\n" }, "cardActivationLabel": { "type": "string", "minLength": 2, "maxLength": 100, "description": "Reference of the activation label used for the card\n" }, "inserts": { "type": "array", "minItems": 0, "maxItems": 10, "items": { "type": "string" }, "description": "List of inserts\n" } } }, "addressInProduceNotification": { "type": "object", "required": [ "line1", "zipCode", "city", "countryCode" ], "properties": { "companyName": { "type": "string", "description": "The name of the company.", "minLength": 1, "maxLength": 64, "pattern": "^[\\p{L}\\p{N}\\p{M} ,.'_#;:\\/-]{1,64}$", "example": "Thales" }, "line1": { "type": "string", "description": "The first line of the address.", "minLength": 1, "maxLength": 64, "pattern": "^[\\p{L}\\p{N}\\p{M} ,.'_#;:\\/-]{1,64}$", "example": "Street #1" }, "line2": { "type": "string", "description": "The second line of the address.", "minLength": 1, "maxLength": 64, "pattern": "^[\\p{L}\\p{N}\\p{M} ,.'_#;:\\/-]{1,64}$", "example": "Street #2" }, "line3": { "type": "string", "description": "The third line of the address.", "minLength": 1, "maxLength": 64, "pattern": "^[\\p{L}\\p{N}\\p{M} ,.'_#;:\\/-]{1,64}$", "example": "Street #3" }, "city": { "type": "string", "description": "The city name.", "minLength": 1, "maxLength": 32, "pattern": "^[\\p{L}\\p{N}\\p{M} ,.'_#;:\\/-]{1,32}$", "example": "London" }, "state": { "type": "string", "description": "The state.", "minLength": 1, "maxLength": 30, "pattern": "^[\\p{L}\\p{N}\\p{M} ,.'_#;:\\/-]{1,30}$" }, "zipCode": { "type": "string", "description": "The zip Code.", "minLength": 1, "maxLength": 10, "pattern": "^[0-9A-Z- ]{1,10}$", "example": "WC2N 5DU" }, "countryCode": { "type": "string", "description": "The country code, based on ISO 639-1 alpha-2 format", "minLength": 2, "maxLength": 2, "pattern": "^[A-Z]{2}$", "example": "GB" } } }, "deviceInformation": { "title": "deviceInformation", "additionalProperties": false, "type": "object", "description": "Provides details about the device that has been used for the card digitization.\nNote that this data is available only if the check eligbility has passed with success.\nData availability dependes on the requestor.", "properties": { "deviceId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Identifier of the token storage." }, "digitalCardStorageType": { "type": "string", "maxLength": 32, "description": "Type of the token sorage location. Following values are possible:\n- HCE\n- SPAY_PHONE\n- SPAY_TABLET\n- SPAY_WATCH\n- SPAY_TV\n- IPHONE\n- IWATCH\n- IPAD\n- MAC_BOOK\n- ANDROID_PHONE\n- ANDROID_TABLET\n- ANDROID_WATCH\n- MOBILE_PHONE\n- TABLET\n- WATCH\n- MOBILE_PHONE_OR_TABLET\n- BRACELET\n- UNKNOWN" }, "manufacturer": { "type": "string", "minLength": 1, "maxLength": 32, "description": "Device manufacturer name" }, "brand": { "type": "string", "minLength": 1, "maxLength": 32, "description": "Device brand" }, "model": { "type": "string", "minLength": 1, "maxLength": 32, "description": "Device model" }, "osVersion": { "type": "string", "minLength": 1, "maxLength": 16, "description": "Device OS version" }, "firmwareVersion": { "type": "string", "description": "Device firmware version", "minLength": 1, "maxLength": 32 }, "phoneNumber": { "type": "string", "description": "Device phone number", "minLength": 1, "maxLength": 20 }, "fourLastDigitPhoneNumber": { "type": "string", "description": "", "minLength": 1, "maxLength": 4 }, "deviceName": { "type": "string", "maxLength": 128, "description": "Device name set by the consumer" }, "deviceParentId": { "type": "string", "description": "ID of parent device. Applies to wearable", "minLength": 1, "maxLength": 64 }, "language": { "type": "string", "description": "Language set on the device in ISO 639-3", "minLength": 1, "maxLength": 3 }, "serialNumber": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Device serial number" }, "timeZone": { "type": "string", "description": "Device time zone abbreviation. Example: PST, GMT, etc...", "minLength": 1, "maxLength": 32 }, "timeZoneSetting": { "type": "string", "maxLength": 32, "description": "Who has set the timezone.\nPossible values:\n- NETWORK_SET\n- CONSUMER_SET" }, "simSerialNumber": { "type": "string", "description": "Secure Element serial number", "minLength": 1, "maxLength": 24 }, "IMEI": { "type": "string", "minLength": 1, "maxLength": 32 }, "networkOperator": { "type": "string", "description": "Network operator name.", "maxLength": 32 }, "networkType": { "type": "string", "description": "Network type. Can be:\n- CELLULAR\n- WIFI", "maxLength": 16 } }, "required": [ "deviceId" ] }, "digitalCardState": { "type": "string", "description": "the state of the digital card (token)", "enum": [ "ACTIVE", "INACTIVE", "DELETED", "DEPLOYMENT_ONGOING", "PENDING_ACTIVATION" ], "example": "ACTIVE", "title": "digitalCardState" }, "tokenType": { "type": "string", "maxLength": 16, "description": "The type of the token. Following values are supported:\n- SE\n- HCE\n- COF\n- ECOM\n- QRC" }, "digitalCardRequestorInformation": { "title": "digitalCardRequestorInformation", "additionalProperties": false, "type": "object", "description": "Provides details about the digital card requestor.", "properties": { "id": { "type": "string", "description": "Digital Card requestor identifier. This is provided by the TSP itself.", "minLength": 11, "maxLength": 11 }, "walletId": { "type": "string", "description": "MasterCard ONLY. Wallet Application identifier", "maxLength": 32 }, "name": { "type": "string", "maxLength": 256, "description": "Wallet or Merchant human readable name" }, "tspId": { "type": "string", "maxLength": 11, "minLength": 11, "description": "VISA only. Identifiers of the couple Token Requestor - Token Service Provider" }, "originalDigitalCardRequestorId": { "type": "string", "description": "Applies only to VISA in case of token for token provisioning", "minLength": 11, "maxLength": 11 } } }, "eligibilityInformation": { "type": "object", "description": "Provides details about the eligibility check operation", "properties": { "cardBIN": { "type": "string", "minLength": 6, "maxLength": 6 }, "eligible": { "type": "boolean" }, "cardProduct": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "name": { "type": "string", "minLength": 1, "maxLength": 256 } } } }, "required": [ "cardBIN", "eligible" ] }, "result": { "title": "result", "type": "object", "properties": { "result": { "type": "string", "enum": [ "YES", "NO", "NOT_APPLICABLE" ] } } }, "issuerVerifications": { "title": "issuerVerifications", "type": "object", "properties": { "cardIsExpired": { "$ref": "#/components/schemas/result" }, "cardIsLostOrStolen": { "$ref": "#/components/schemas/result" }, "wrongCVV": { "$ref": "#/components/schemas/result" }, "fraudSuspect": { "$ref": "#/components/schemas/result" }, "cardIsInvalid": { "$ref": "#/components/schemas/result" } }, "required": [ "cardIsExpired", "cardIsLostOrStolen", "wrongCVV", "fraudSuspect", "cardIsInvalid" ] }, "captureMethodIncompatible": { "title": "captureMethodIncompatible", "type": "object", "properties": { "result": { "type": "string", "enum": [ "YES", "NO", "NOT_APPLICABLE" ] } }, "description": "If the capture method of the card details is NOT one of the following:\n- BANK_APP (card details from the Banking App)\n- TOKEN (card details derived by the TSP from an existing digital card)\n- ON-FILE (card details from a card stored on file)\n\nthen the absence of CVV is unexpected, the result will be YES" }, "digitalCardTypeIncompatible": { "title": "digitalCardTypeIncompatible", "type": "object", "properties": { "result": { "type": "string", "enum": [ "YES", "NO", "NOT_APPLICABLE" ] } }, "description": "If the digital card type required is NOT one of the following:\n- COF (card on file)\n- ECOM (e-Commerce)\n\nthen the absence of CVV is unexpected, the result will be YES" }, "CVVNotProvided": { "title": "CVVNotProvided", "type": "object", "description": "If CVV has not been provided by the digital card requestor, then D1 verifies if this is incompatible with either the card capture method used or the digital card type requested.", "properties": { "incompatibleWithCaptureMethod": { "$ref": "#/components/schemas/captureMethodIncompatible" }, "incompatibleWithDigitalCardType": { "$ref": "#/components/schemas/digitalCardTypeIncompatible" } }, "required": [ "incompatibleWithCaptureMethod", "incompatibleWithDigitalCardType" ] }, "decisionEngineVerifications": { "title": "decisionEngineVerifications", "type": "object", "properties": { "tooManyDigitizationRequests": { "$ref": "#/components/schemas/result" }, "tooManyCVVVerificationFailed": { "$ref": "#/components/schemas/result" }, "walletPhoneNumberNotMatchingConsumerPhoneNumber": { "$ref": "#/components/schemas/result" }, "digitizationCountExceededOnSameFPAN": { "$ref": "#/components/schemas/result" }, "digitizationCountExceededOnSameDevice": { "$ref": "#/components/schemas/result" }, "cardIsExpired": { "$ref": "#/components/schemas/result" }, "cardIsInvalid": { "$ref": "#/components/schemas/result" }, "wrongCVV": { "$ref": "#/components/schemas/result" }, "CVVNotProvided": { "$ref": "#/components/schemas/CVVNotProvided" } }, "required": [ "tooManyDigitizationRequests", "tooManyCVVVerificationFailed", "walletPhoneNumberNotMatchingConsumerPhoneNumber", "digitizationCountExceededOnSameFPAN", "digitizationCountExceededOnSameDevice", "cardIsExpired", "cardIsInvalid", "wrongCVV", "CVVNotProvided" ] }, "walletRecommendation": { "type": "string", "description": "Wallet/Digital Card Requestor colour recommended during the card tokenization request\n\nPlease note that in certain situations a recommendation might be not provided by the wallet.", "enum": [ "NOT_APPLICABLE", "GREEN", "YELLOW", "ORANGE", "RED" ] }, "digitalCardRequestorAssessment": { "title": "digitalCardRequestorAssessment", "type": "object", "x-examples": { "Example 1": { "averageScore": "3", "deviceScore": "3", "accountScore": "NOT_APPLICABLE", "recommendation": "YELLOW", "reasonCodesRecommendation": "01", "reasonCodesRecommendationDescription": [ { "01": "User Wallet Account ID too new relative to launch" } ], "verificationCodes": [ "TR_ACCOUNT_SCORE_NOT_AVAILABLE" ] } }, "required": [ "averageScore", "deviceScore", "accountScore", "recommendation" ], "properties": { "averageScore": { "type": "string", "description": "Average scoring from the digital card requestor. Following values are possible:\n\nNOT_APPLICABLE (score is based on data from digital card requestor. If the data is not available, average can't be computed).\n1\n2\n3\n4\n5" }, "deviceScore": { "type": "string", "description": "Following values are possible:\n\nNOT_APPLICABLE (score is based on data from digital card requestor. If the data is not available, score can't be provided).\n1\n2\n3\n4\n5" }, "accountScore": { "type": "string", "description": "Wallet Provider account scoring, low values means high risk.\nFollowing values are possible:\n\nNOT_APPLICABLE (score is based on data from digital card requestor. If the data is not available, score can't be provided).\n\n1 2 3 4 5" }, "recommendation": { "$ref": "#/components/schemas/walletRecommendation" }, "reasonCodesRecommendationDescription": { "type": "array", "description": "This field shall allow to list the received Wallet Reason Code Recommendation(s).Values are mapped to more user friendly descriptions. The full list of mapped codes is available here: https://docs.payments.thalescloud.io/implement-tokenization/card-tokenization-request/processing-the-decision/decision-engine/data-validation-codes/wallet-reason-codes", "uniqueItems": true, "items": { "type": "object" } } } }, "idAndVMethods": { "additionalProperties": false, "type": "object", "properties": { "supported": { "type": "array", "items": { "type": "string" } }, "selected": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The following values are possible:\n- OTP_BY_SMS\n- OTP_BY_EMAIL\n- BANK_APP\n- CUSTOMER_SERVICE" } } }, "digitizationInformation": { "type": "object", "description": "Provides details about the tokenization (digitization) operation whatever the result is (that is, successful, pending or cancelled)", "title": "digitizationInformation", "properties": { "digitizationChecks": { "type": "object", "required": [ "issuerVerifications", "decisionEngineVerifications", "digitalCardRequestorAssessment" ], "properties": { "issuerVerifications": { "$ref": "#/components/schemas/issuerVerifications" }, "decisionEngineVerifications": { "$ref": "#/components/schemas/decisionEngineVerifications" }, "digitalCardRequestorAssessment": { "$ref": "#/components/schemas/digitalCardRequestorAssessment" }, "verificationCodes": { "type": "array", "maxItems": 100, "description": "D1 Verification codes generated by the decision engine during rule evaluation. Following values are possible:\n\t \n|value |description| \n|-----------|----------------------------------| \n|TR_RECOMMENDATION_NOT_AVAILABLE|wallet recommendation is missing|\n|TR_DEVICE_SCORE_NOT_AVAILABLE|device scoring is missing|\n|TR_ACCOUNT_SCORE_NOT_AVAILABLE|account scoring is missing|", "items": { "type": "string" } }, "matchedRule": { "type": "object", "description": "Decision Engine rule triggerig the final decision.\r\n\r\nApplicable only to Decision Engine Version V2", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "Unique identifier of the matching rule." }, "name": { "type": "string", "description": "Name of the matching rule." }, "scenario": { "type": "object", "description": "The actual matching scenario ", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "Unique identifier of the matched scenario." }, "name": { "type": "string", "description": "Name of the matched scenario." } } } } } } }, "digitizationResult": { "type": "object", "required": [ "flow" ], "properties": { "flow": { "type": "string", "description": "Tokenization Decision Engine assessment result.\nFollowing values are possible:\n- RED (DECLINE)\n- GREEN (APPROVE)\n- YELLOW (STEP-UP)", "minLength": 1, "maxLength": 64, "enum": [ "RED", "YELLOW", "GREEN" ] }, "score": { "type": "string", "minLength": 1, "maxLength": 1, "pattern": "[1-5]{1,1}$", "description": "This is the final score the decision engine has computed considering all the verifications and the scoring from the requestor and/or TSP.\nScore goes from 1 (low trust) to 5 (high trust)." }, "idAndVMethods": { "$ref": "#/components/schemas/idAndVMethods" }, "digitizationDecisionTimestamp": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The time when the digitization decision has been sent to the TSP.\nThis parameter can be used by the Issuer to manage the notifications to cardholder in case of PENDING status of digitize operation.\nFormat ISO 8601 YYYY-MM-DDThh:mm:ssTZD\n" } } } }, "required": [ "digitizationChecks", "digitizationResult" ] }, "updateOrderStatus": { "type": "string", "enum": [ "PULL_SUCCESSFUL", "PULL_FAILED" ], "example": "PULL_SUCCESSFUL", "description": "The status of pull request.\n\n|status code | description |\n|---------------------------|-------------------------------------------------------------------------------------------------------------------|\n|PULL_SUCCESSFUL | The pull request was successfully processed. |\n|PULL_FAILED | The pull request processing failed. |\n| \n" }, "addressCommonFields": { "type": "object", "required": [ "lastName", "line1", "zipCode", "city", "countryCode" ], "properties": { "title": { "type": "string", "description": "The title.", "minLength": 1, "maxLength": 40, "pattern": "^[\\p{L}\\p{N}\\p{M} ,.'_#;:\\/-]{1,40}$", "example": "Mr." }, "firstName": { "type": "string", "description": "The first name.", "minLength": 1, "maxLength": 40, "pattern": "^[\\p{L}\\p{N}\\p{M} ,.'_#;:\\/-]{1,40}$", "example": "John" }, "lastName": { "type": "string", "description": "The last name.", "minLength": 1, "maxLength": 40, "pattern": "^[\\p{L}\\p{N}\\p{M} ,.'_#;:\\/-]{1,40}$", "example": "Smith" }, "companyName": { "type": "string", "description": "The name of the company.", "minLength": 1, "maxLength": 64, "pattern": "^[\\p{L}\\p{N}\\p{M} ,.'_#;:\\/-]{1,64}$", "example": "Thales" }, "line1": { "type": "string", "description": "The first line of the address.", "minLength": 1, "maxLength": 64, "pattern": "^[\\p{L}\\p{N}\\p{M} ,.'_#;:\\/-]{1,64}$", "example": "Street #1" }, "line2": { "type": "string", "description": "The second line of the address.", "minLength": 1, "maxLength": 64, "pattern": "^[\\p{L}\\p{N}\\p{M} ,.'_#;:\\/-]{1,64}$", "example": "Street #2" }, "line3": { "type": "string", "description": "The third line of the address.", "minLength": 1, "maxLength": 64, "pattern": "^[\\p{L}\\p{N}\\p{M} ,.'_#;:\\/-]{1,64}$", "example": "Street #3" }, "city": { "type": "string", "description": "The city name.", "minLength": 1, "maxLength": 32, "pattern": "^[\\p{L}\\p{N}\\p{M} ,.'_#;:\\/-]{1,32}$", "example": "London" }, "state": { "type": "string", "description": "The state.", "minLength": 1, "maxLength": 30, "pattern": "^[\\p{L}\\p{N}\\p{M} ,.'_#;:\\/-]{1,30}$" }, "zipCode": { "type": "string", "description": "The zip Code.", "minLength": 1, "maxLength": 10, "pattern": "^[0-9A-Z- ]{1,10}$", "example": "WC2N 5DU" }, "countryCode": { "type": "string", "description": "The country code, based on ISO 639-1 alpha-2 format", "minLength": 2, "maxLength": 2, "pattern": "^[A-Z]{2}$", "example": "GB" }, "email": { "type": "string", "description": "The email, used for card shipment contact purpose.", "minLength": 1, "maxLength": 255, "pattern": "^[a-zA-Z0-9_+&*-]+(?:\\.[a-zA-Z0-9_+&*-]+)*@(?:[a-zA-Z0-9-]+\\.)+[a-zA-Z]{2,15}$", "example": "john.doe@dummymail.com" } } }, "addressInPullNotification": { "allOf": [ { "$ref": "#/components/schemas/addressCommonFields" } ] }, "errorGenericWithErrorCodeOutbound": { "additionalProperties": false, "type": "object", "description": "Generic error returned by the APIs.", "properties": { "errorCode": { "type": "string", "description": "The type of the error", "example": "FIELD_INVALID_FORMAT" }, "error": { "type": "string", "description": "Provide more error details if possible.
For example name of the field with invalid format.", "example": "consumerId" } } }, "operationId": { "type": "string", "description": "Unique identifier of the operation", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]{1,64}$" } }, "responses": { "ServiceUnavailableError-outbound": { "description": "The service is temporarily unavailable. D1 will retry the request later." } }, "securitySchemes": { "bearerAuth": { "type": "http", "description": "A JWT generated by the [Get Authorization Token API](oauth2-api).
The server checks the validity of the provided token to control access to this protected resource. Please refer to [Get OAuth 2.0 access token](../../../integrate-the-d1-api/get-oauth-2.0-access-token) for more details on the flow and on how to get this JWT.", "scheme": "bearer", "bearerFormat": "JWT" } }, "parameters": { "issuer-id-path": { "description": "The id of the issuer", "in": "path", "name": "issuerId", "required": true, "schema": { "$ref": "#/components/schemas/issuerId" } }, "x-correlation-id-output": { "description": "Random identifier which can be used to correlate the different API calls done as part of a single use-case. This identifier will be the one primarily used for troubleshooting.\n\nThere is no strong guarantee of the uniqueness of this identifier, so please refrain from using it for other purpose than logging and troubleshooting.", "in": "header", "name": "x-correlation-id", "schema": { "type": "string" } }, "card-id-path": { "description": "The id of the card", "in": "path", "name": "cardId", "required": true, "schema": { "$ref": "#/components/schemas/cardId" } } } } }