Outbound Card API

Get Card Credentials

get

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.

Authorizations

OAuth2clientCredentialsRequired

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

Token URL:

Path parameters

issuerIdstring · min: 10 · max: 10Required

The id of the issuer

cardIdstring · min: 1 · max: 48Required

Unique identifier of the card.

Pattern: [A-Za-z0-9_-]{1,48}

Header parameters

x-correlation-idstring · min: 1 · max: 64Optional

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.

Pattern: [a-zA-Z0-9_\-\. ]{1,64}

AuthorizationstringOptional

Oauth Access Token (optional)

Example: 'Bearer: 2zzLJmBAtTNIU8nF8e8XbmDvaNGs'

Responses

200

application/json

encryptedDatastring · max: 8192Required

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

400

Bad Request

application/json

401

Authorization missing or invalid

application/json

403

Action forbidden (if card is not active, for example)

application/json

404

Resource not found (issuerId, cardId)

application/json

500

Internal Server Error

application/json

get

/cms/api/v1/issuers/{issuerId}/cards/{cardId}/credentials

GET /cms/api/v1/issuers/{issuerId}/cards/{cardId}/credentials HTTP/1.1
Host: YOUR_DOMAIN_NAME
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "encryptedData": "text"
}

Verify Card

post

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.

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Path parameters

issuerIdstring · min: 10 · max: 10Required

The id of the issuer

Header parameters

x-correlation-idstring · min: 1 · max: 64Optional

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.

Pattern: [a-zA-Z0-9_\-\. ]{1,64}

AuthorizationstringOptional

Oauth Access Token (optional)

Example: 'Bearer: 2zzLJmBAtTNIU8nF8e8XbmDvaNGs'

Body

encryptedDatastring · max: 8192Required

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

cardIdstring · min: 1 · max: 48Required

Unique identifier of the card.

Pattern: [A-Za-z0-9_-]{1,48}

cardBinstring · min: 6 · max: 6Required

The first 6 digits of the PAN

Responses

200

application/json

cardIdstring · min: 1 · max: 48Optional

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.

Pattern: [A-Za-z0-9_-]{1,48}

consumerIdstring · min: 1 · max: 64Optional

Unique identifier of the end user.

Must be provided only when the card verification is successful: verificationResults.card.invalid flag is false.

Pattern: [A-Za-z0-9_-]{1,64}

accountIdstring · min: 1 · max: 64Optional

Unique identifier of the account.

If not provided, the value from consumerId will be applied.

Pattern: [A-Za-z0-9_-]{1,64}

400

Bad Request

application/json

401

Authorization missing or invalid

application/json

403

Action forbidden

application/json

404

Resource not found

application/json

500

Internal Server Error

application/json

post

/cms/api/v1/issuers/{issuerId}/cards/credentials

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
    }
  }
}

Notify Card Operation (v1)

post

This request is used by D1 to notify the issuer backend about all operations done on a card.

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Path parameters

issuerIdstring · min: 10 · max: 10Required

The id of the issuer

cardIdstring · min: 1 · max: 48Required

Unique identifier of the card.

Pattern: [A-Za-z0-9_-]{1,48}

Header parameters

x-correlation-idstring · min: 1 · max: 64Optional

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.

Pattern: [a-zA-Z0-9_\-\. ]{1,64}

AuthorizationstringOptional

Oauth Access token (optional)

Example: 'Bearer 2zzLJmBAtTNIU8nF8e8XbmDvaNGs'

Body

The following object represent the account

operationIdstring · min: 1 · max: 64Required

Unique identifier of the operation

Pattern: [A-Za-z0-9_-]{1,64}

operationstring · enumRequired

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)

Possible values:

digitalCardIdsstring[]Optional

Unique identifier of the digital cards concerned by the operation.

statusstring · enumRequired

Status of the operation

Possible values:

Responses

204

Successful

400

Bad Request, Invalid request URI or header, or unsupported nonstandard parameter

application/json

401

The provided Authorization header is missing or invalid

404

Resource not found. Unknown issuerId or consumerId or accountId or cardId

application/json

500

Internal server error

application/json

post

/notifications/d1/v1/issuers/{issuerId}/cards/{cardId}/notifications

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"
}

No content

Notify 3-D Secure Card Operation

post

This request is used by D1 to notify the issuer backend about all 3-D Secure operations done on a card.

Path parameters

issuerIdstring · min: 10 · max: 10Required

The id of the issuer

cardIdstring · min: 1 · max: 48Required

Unique identifier of the card.

Pattern: [A-Za-z0-9_-]{1,48}

Header parameters

x-correlation-idstring · min: 1 · max: 64Optional

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.

Pattern: [a-zA-Z0-9_\-\. ]{1,64}

Body

Details about a 3-D Secure operation.

operationIdstring · min: 1 · max: 64Required

Unique identifier of the operation

Pattern: [A-Za-z0-9_-]{1,64}

operationstring · enumRequired

The operation type.

Possible values:

statusstring · enumRequired

Status of the operation

Possible values:

startTimestring · min: 1 · max: 64Required

The time the request has been processed. Format ISO 8601 YYYY-MM-DDThh:mm:ssTZD

Example: 2022-06-16T06:28:02.492Z

consumerIdstring · min: 1 · max: 64Optional

Unique identifier of the end user.

Pattern: [A-Za-z0-9_-]{1,64}

detailsone ofOptional

errorstringOptional

Human readable string representing the error, only present in case of operation failure

Responses

204

Successful

400

Bad Request, Invalid request URI or header, or unsupported nonstandard parameter

application/json

401

The provided Authorization header is missing or invalid

404

Resource not found. Unknown issuerId or consumerId or accountId or cardId

application/json

500

Internal server error

application/json

post

/notifications/d1/v1/issuers/{issuerId}/cards/{cardId}/3ds/notifications

POST /notifications/d1/v1/issuers/{issuerId}/cards/{cardId}/3ds/notifications HTTP/1.1
Host: YOUR_DOMAIN_NAME
Content-Type: application/json
Accept: */*
Content-Length: 712

{
  "operationId": "text",
  "operation": "3DS_FRICTIONLESS",
  "status": "SUCCESSFUL",
  "startTime": "2022-06-16T06:28:02.492Z",
  "consumerId": "text",
  "details": {
    "acsTransactionId": "text",
    "threeDSServerTransId": "text",
    "dsTransId": "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"
}

No content

Notify Card Operations (v2)

post

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.

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Path parameters

issuerIdstring · min: 10 · max: 10Required

The id of the issuer

Header parameters

x-correlation-idstring · min: 1 · max: 64Optional

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.

Pattern: [a-zA-Z0-9_\-\. ]{1,64}

AuthorizationstringOptional

Oauth Access token (optional)

Example: 'Bearer 2zzLJmBAtTNIU8nF8e8XbmDvaNGs'

Body

Responses

204

Successful

400

Bad Request, Invalid request URI or header, or unsupported non-standard parameter

application/json

401

The provided Authorization header is missing or invalid

application/json

500

Internal Server Error

application/json

post

/notifications/d1/v2/issuers/{issuerId}/cards

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"
    }
  ]
}

No content

PreviousOutbound NextModels

Last updated 10 days ago

Was this helpful?