The goal of this API is to provide Issuers with a technical connection to update customer card
on file information by replacing old card details with new card details at the corresponding
data vault of the merchants selected by the Card Owner.
The Card Owner is the one pushing the request from the Issuer Application. Once the
Card Owner selects the merchants for which they wish the new card to be registered a request
should be generated and sent to Card Dynamics to launch the update process.
All the update requests will be processed and will get an asynchronous response with the
result of the update attempts as soon as those are available.
API SECURITY AND ENCRYPTION DETAILS
Before starting operations, the Issuer must get the identification and security keys to perform
all secured communications with the Issuer API.
There will be security measures applying only in LIVE environment:
- Setup of Allowed Domains. Issuer API will only accept calls from the Issuer’s
- Setup of Issuer’s Whitelisted IPs
Then to perform all encryption/decryption operations the Issuer needs:
- Issuer ID (provided by EPG example: 12345, Deprecated will be removed in future
- Secret Key (a password agreed between Issuer-EPG to perform AES, max 32 bit:
- X-API-KEY, security header value needed on some requests.
- Salt, key used on the signature providing security to Issuer API callbacks (example:
As an option the Issuer may require a username+password on the callback’s header to access
the Issuer’s side endpoint, this can be supported by Card Dynamics just by requesting this
All the picture listed fields details will be encrypted with AES/ECB algorithm using the MD5
secret key above explained.
An example of a merchant list is the following. The only necessary value is the cdMerchantId, the rest are optional to provide more information
"issuerMerchantName": "Spotify MX",
OUTPUT BODY SAMPLE
Here is an example of a Replacement Request, both encrypted and unencrypted.
The API will answer with a 200 OK code which means that it is listening and waiting for the asynchronous response with the result of the update attempt.
This field will not affect CD updates being processed, but it’s relevant in order to get accurate reporting
Name Description Schema
String used to check information integrity string
Change request identification in issuer integer
A JSON value representing the list of merchants where card has to be
New credit card expiration date string
(*) New CC number or NEW CC token, only one of these 2 fields should
be reported to represent the new card PAN.
Old credit card expiration date string
(*) Old CC number or Old CC token, only one of these 2 fields should
be reported to represent the old card PAN.
Replacement reason, possible values are: OP, OU, CO (check
ReplacementReason Values section at the end of the document)
The possible responses by the PSP are the following