Outbound Card API
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.
OAUTH activation for outbound endpoints is optional part of D1 Tenant configuration (Refresh URL, Token URL, Credentials, Scope) A CMS entity wishing to opt for OAUTH scheme needs to support an endpoint (Token URL) from which the access token can be retrieved. This endpoint shall support HTTP POST Client Credentials grant requests in x-www-form-urlencoded content type as specified here: https://datatracker.ietf.org/doc/html/rfc6749#section-4.4.2
The id of the issuer
Unique identifier of the card.
[A-Za-z0-9_-]{1,48}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.
There is no strong guarantee of the uniqueness of this identifier, so please refrain from using it for purposes other than logging and troubleshooting.
[a-zA-Z0-9_\-\. ]{1,64}Oauth Access Token (optional)
'Bearer: 2zzLJmBAtTNIU8nF8e8XbmDvaNGs'OK
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 Sensitive Information Encryption for more details)
Content
Once deciphered, the plaintext contains:
| JSON field parameter name | description | MOC | Format |
|---|---|---|---|
| pan | The funding pan value. | M | string - from 10 to 19 digits |
| exp | The expiry date of the card. | M | string - 4 digits, following the format MMYY |
| name | The card holder name. | O | string - up to 128 characters |
| cvv | The CVV2 value of the funding card | M | string - 3 or 4 digits |
| auxiliaryPan | The auxiliary funding pan value.It shall be provided when cobadge is supported and if the card has an auxiliary pan. | C | string - up to 19 digits |
| auxiliaryExp | The auxiliary expiry date of the card.It shall be provided when cobadge is supported and if the card has an auxiliary pan. | C | string - 4 digits, following the format MMYY |
| customSuffix | last 4 digits of the display pan which is different than the actual funding pan | O | string - 4 digits |
Bad Request
Authorization missing or invalid
Action forbidden (if card is not active, for example)
Resource not found (issuerId, cardId)
Internal Server Error
GET /cms/api/v1/issuers/{issuerId}/cards/{cardId}/credentials HTTP/1.1
Host: YOUR_DOMAIN_NAME
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*
{
"encryptedData": "text"
}When a tokenization request reaches D1, D1 calls the CMS (Card Management System) with this method to verify the status of card for which the tokenization has been requested.
It is expected that the CMS verifies the consistency between the card information provided versus the card information known by the CMS itself. As a minimum, the CMS should check the following:
that the PAN number is valid
if no expiration date is provided, that the card has not expired
if a CVV is provided, that it is valid
It is important that the CMS provides a proper result response because D1 uses this result when making a decision regarding the tokenization request of the card.
Along with the card details, D1 provides a unique card reference, cardId. The CMS can, OPTIONALLY, override this value by providing its own card ID in the response. In this case, however, CMS must guarantee the uniqueness of the ID.
It is required to provide a reference of the cardholder information (consumerId). This reference will be used by the D1 to request the cardholder contacts details to the Core Banking system.
OAUTH activation for outbound endpoints is optional part of D1 Tenant configuration (Refresh URL, Token URL, Credentials, Scope) A CMS entity wishing to opt for OAUTH scheme needs to support an endpoint (Token URL) from which the access token can be retrieved. This endpoint shall support HTTP POST Client Credentials grant requests in x-www-form-urlencoded content type as specified here: https://datatracker.ietf.org/doc/html/rfc6749#section-4.4.2
The id of the issuer
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.
There is no strong guarantee of the uniqueness of this identifier, so please refrain from using it for purposes other than logging and troubleshooting.
[a-zA-Z0-9_\-\. ]{1,64}Oauth Access Token (optional)
'Bearer: 2zzLJmBAtTNIU8nF8e8XbmDvaNGs'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 Sensitive Information Encryption for more details)
Content
Once deciphered, the plaintext contains:
| JSON field parameter name | description | MOC | Format |
|---|---|---|---|
| pan | The funding pan value. | M | string - from 10 to 19 digits |
| exp | The expiry date of the card. | M | string - 4 digits, following the format MMYY |
| name | The card holder name. | O | string - up to 128 characters |
| cvv | The CVV2 value of the funding card | O | string - 3 or 4 digits |
Unique identifier of the card.
[A-Za-z0-9_-]{1,48}The first 6 digits of the PAN
OK
Unique identifier of the card.
OPTIONAL. In case CMS has already its own card identifier and prefers to use it in place of the one provided.
[A-Za-z0-9_-]{1,48}Unique identifier of the end user.
Must be provided only when the card verification is successful:
verificationResults.card.invalid=false AND verificationResults.card.lostOrStolen=false AND verificationResults.card.expired=false AND verificationResults.card.fraudSuspect=false
[A-Za-z0-9_-]{1,64}Unique identifier of the account.
If not provided, the value from consumerId will be applied.
[A-Za-z0-9_-]{1,64}Bad Request
Authorization missing or invalid
Action forbidden
Resource not found
Internal Server Error
POST /cms/api/v1/issuers/{issuerId}/cards/credentials HTTP/1.1
Host: YOUR_DOMAIN_NAME
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 57
{
"encryptedData": "text",
"cardId": "text",
"cardBin": "text"
}{
"cardId": "text",
"consumerId": "text",
"accountId": "text",
"verificationResults": {
"securityCode": {
"valid": true,
"verificationAttemptsExceeded": true
},
"card": {
"lostOrStolen": true,
"expired": true,
"invalid": true,
"fraudSuspect": true
}
}
}This request is used by D1 to notify the issuer backend about all operations done on a card.
OAUTH activation for outbound endpoints is optional part of D1 Tenant configuration (Refresh URL, Token URL, Credentials, Scope) A CMS entity wishing to opt for OAUTH scheme needs to support an endpoint (Token URL) from which the access token can be retrieved. This endpoint shall support HTTP POST Client Credentials grant requests in x-www-form-urlencoded content type as specified here: https://datatracker.ietf.org/doc/html/rfc6749#section-4.4.2
The id of the issuer
Unique identifier of the card.
[A-Za-z0-9_-]{1,48}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.
There is no strong guarantee of the uniqueness of this identifier, so please refrain from using it for purposes other than logging and troubleshooting.
[a-zA-Z0-9_\-\. ]{1,64}Oauth Access token (optional)
'Bearer 2zzLJmBAtTNIU8nF8e8XbmDvaNGs'The following object represent the account
Unique identifier of the operation
[A-Za-z0-9_-]{1,64}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)
Unique identifier of the digital cards concerned by the operation.
Status of the operation
Successful
Sin contenido
Bad Request, Invalid request URI or header, or unsupported nonstandard parameter
The provided Authorization header is missing or invalid
Resource not found. Unknown issuerId or consumerId or accountId or cardId
Internal server error
POST /notifications/d1/v1/issuers/{issuerId}/cards/{cardId}/notifications HTTP/1.1
Host: YOUR_DOMAIN_NAME
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 90
{
"operationId": "text",
"operation": "DIGITIZE",
"digitalCardIds": [
"text"
],
"status": "PENDING"
}Sin contenido
This request is used by D1 to notify the issuer backend about all 3-D Secure operations done on a card.
The id of the issuer
Unique identifier of the card.
[A-Za-z0-9_-]{1,48}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.
There is no strong guarantee of the uniqueness of this identifier, so please refrain from using it for purposes other than logging and troubleshooting.
[a-zA-Z0-9_\-\. ]{1,64}Details about a 3-D Secure operation.
Unique identifier of the operation
[A-Za-z0-9_-]{1,64}The operation type.
Status of the operation
The time the request has been processed. Format ISO 8601 YYYY-MM-DDThh:mm:ssTZD
2022-06-16T06:28:02.492ZUnique identifier of the end user.
[A-Za-z0-9_-]{1,64}Human readable string representing the error, only present in case of operation failure
Successful
Sin contenido
Bad Request, Invalid request URI or header, or unsupported nonstandard parameter
The provided Authorization header is missing or invalid
Resource not found. Unknown issuerId or consumerId or accountId or cardId
Internal server error
POST /notifications/d1/v1/issuers/{issuerId}/cards/{cardId}/3ds/notifications HTTP/1.1
Host: YOUR_DOMAIN_NAME
Content-Type: application/json
Accept: */*
Content-Length: 718
{
"operationId": "text",
"operation": "3DS_FRICTIONLESS",
"status": "SUCCESSFUL",
"startTime": "2022-06-16T06:28:02.492Z",
"consumerId": "text",
"details": {
"acsTransactionId": "text",
"threeDSServerTransId": "text",
"dsTransactionId": "text",
"purchase": {
"merchantName": "text",
"merchantType": "text",
"amount": "text",
"currencyCode": "text",
"merchantId": "text",
"countryCode": "text",
"merchantUrl": "https://example.com"
},
"acquirer": {
"bin": "text",
"countryCode": "text"
},
"device": {
"deviceChannel": "01",
"appInstanceId": "text",
"authnType": "BIOMETRIC"
},
"eci": "text",
"authenticationMethod": "02",
"transStatus": "Y",
"transStatusReason": "text",
"rba": {
"evaluatedRule": [],
"selectedRule": [],
"appliedExemption": []
},
"protocolVersion": "text"
},
"error": "text"
}Sin contenido
This request is used by D1 to notify the system of the bank about any card operation update. There is a retry mechanism in case the notification has not been sent. Thus the bank system can use this notification to synchronize card operation status with their card repository. The number max of card operation in the notification is defined at onboarding time according to bank's system capability. Each operation is linked to a given cardId, and can contain a message decidicated for the final end-user.
OAUTH activation for outbound endpoints is optional part of D1 Tenant configuration (Refresh URL, Token URL, Credentials, Scope) A CMS entity wishing to opt for OAUTH scheme needs to support an endpoint (Token URL) from which the access token can be retrieved. This endpoint shall support HTTP POST Client Credentials grant requests in x-www-form-urlencoded content type as specified here: https://datatracker.ietf.org/doc/html/rfc6749#section-4.4.2
The id of the issuer
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.
There is no strong guarantee of the uniqueness of this identifier, so please refrain from using it for purposes other than logging and troubleshooting.
[a-zA-Z0-9_\-\. ]{1,64}Oauth Access token (optional)
'Bearer 2zzLJmBAtTNIU8nF8e8XbmDvaNGs'Successful
Sin contenido
Bad Request, Invalid request URI or header, or unsupported non-standard parameter
The provided Authorization header is missing or invalid
Internal Server Error
POST /notifications/d1/v2/issuers/{issuerId}/cards HTTP/1.1
Host: YOUR_DOMAIN_NAME
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 1882
{
"operations": [
{
"operationId": "text",
"operation": "PRODUCE",
"status": "SUCCESSFUL",
"startTime": "2022-06-16T06:28:02.492Z",
"endTime": "2022-06-16T09:28:12.492Z",
"cardId": "text",
"details": {
"status": "CARD_SHIPPED",
"reason": "",
"consumerId": "271b-6e47-8ec3-7f3f",
"issuerRequestId": "01c5a05e-e197-11ec-8fea-0242ac120002",
"dueDate": "2023-01-21",
"productionSite": "Gemenos",
"name": "MR. JOHN SMITH",
"maskedPan": "123456xxxxxx7890",
"orderId": "9b95d70e-21fe-4c36-9368-ddd7fbd729e8",
"packageId": "be0b085c-ef03-4581-9e7b-50dbb2f08f43",
"shipment": {
"pickupDate": "2023-01-21T17:32:28Z",
"carrier": "fedex",
"trackingNumber": "61293150000079650811",
"status": "DELIVERED",
"message": "Picked up by the customer",
"trackingUrl": "https://www.fedex.com/apps/fedextrack/?tracknumbers=61293150000079650811&cntry_code=US",
"redirectUrl": "https://www.fedex.com/apps/fedextrack/?action=track&tracknumbers=61293150000079650811&cntry_code=US",
"estimatedDeliveryDate": "2023-01-21T17:32:28Z",
"lastUpdatedAt": "2023-01-21T17:32:28Z",
"deliveryDate": "2023-01-21T17:32:28Z",
"signedBy": "Steve Young",
"failedDeliveryAttempts": "2",
"lastCheckpoint": {
"checkpointTime": "2023-01-21T17:32:28Z",
"city": "New York",
"countryName": "United States",
"message": "Package delivered"
}
},
"services": {
"cardProductId": "text",
"issuance": "RENEWAL",
"priority": "P1",
"delivery": "DHL",
"packaging": "welcome_pack_red",
"cardCarrier": "NO_CARRIER"
},
"inputFileName": "myInputFile_20240707.gz",
"cardPackageDetails": {
"plastic": "CardRef1",
"artworkId": "CardRef1",
"cardCarrier": "17609320 Carrier A4 white 100g Thales",
"envelope": "ENV BLANCHE 115X229mm FEN 45X100X2520 CART1000",
"package": "text",
"cardActivationLabel": "text",
"inserts": [
"text"
]
},
"deliveryAddress": {
"companyName": "Thales",
"line1": "Street #1",
"line2": "Street #2",
"line3": "Street #3",
"city": "London",
"state": "text",
"zipCode": "WC2N 5DU",
"countryCode": "GB"
}
},
"errorCode": "FIELD_INVALID_FORMAT",
"error": "cardId"
}
]
}Sin contenido
Última actualización
¿Te fue útil?