Issuer API

The goal of this API is to provide Issuers with a technical connection with card on file merchants with to purposes:

 

1. Full enrollment: Issuers invite cardholders to register at an affiliated merchant from the secure environment of its issuer's app or web. The cardholder chooses to register at a merchant using the data the bank holds on them. Via the provided API, issuers send Card-Dynamics only and exclusively the required information to comply with the corresponding merchant registration form."

2. Replacement: Issuer send to Card-Dynamics cardholder old PAN details, new PAN details, and the merchants at which the cardholder wishes to update his payment details via API. Card-Dynamics sends those card details to the corresponding data vault of the selected merchants. Afterwards, the PSP looks after the merchant name and the old PAN number, replacing that PAN by the new one at that specific merchant. Finally, once the switch is done, a confirmation is provided to the issuer and consequently its cardholders. This merchant selection provided by the Card Owner will represent a mandate to act on his behalf and execute the update.

 

This API is meant to be 100% available and we expect to receive calls from the Issuer external applications (could be mobile, web based…etc.)

 

The Card Owner should be 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 replaced/registered. A request should be generated and sent to Card Dynamics to launch the 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.

 

There is no storage of personal or card data after the process. Only the card mask, which does not contain the complete number of the card is saved. It is also encrypted/masked so PANs are never exposed respecting PCI DSS. This mask is saved to manage claims and respond for audit trail purposes.

No personal data is ever processed given the lack of association between “Card Owner – Card details” information.

URI Scheme

Host: https://cd-proxy-service-stg.easypaymentgateway.com (Sandbox environment)
BasePath: /

API Security details

Communication on both sides will be secured by a TLS 1.2 protocol. All requests are idempotent. Any error related to these input parameters will result in a Bad Request 4XX with an error message.
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 environments:
 
  • Setup of Allowed Domains. Issuer API will only accept calls from the Issuer’s registered domains.
  • Setup of Issuer’s Whitelisted IPs.

Then to perform all encryption/decryption operations the Issuer needs:
  • X-API-KEY: Security header value needed on the requests.
  • Secret Key: Password agreed between Issuer and Card-Dynamics to perform AES encryption.
  • Salt: Key used on the signature providing security to Issuer API callbacks.

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 requesting this configuration.

All fields will be encrypted with AES/ECB algorithm using the secret key mentioned above.
An example of a simple encryption can be viewed in the following image:

Integrity Check

The integrityCheck parameter is composed by concatenating some of the Request values before being encrypted. Then this concatenation will be hashed using SHA256 and transformed to hexadecimal. So the Merchant/PSP can check whether the original values are not corrupted or hacked.
An example of the creation of an Integrity Check can be viewed in the following image.
The Integrity Check can vary depending on the request:
Enrollment Request Integrity Check:
Integrity Check = Hex(SHA256(registrationData + (cardData OR bankData)))
Replacement Request  Integrity Check:
Integrity Check = Hex(SHA256(ocPan + ocToken + ocExpDate + ncPan + ncToken + ncExpDate))

Callback Protection, Signature field 

In addition to the X-API-KEY sent on the header, signature field ensure the security to the MerchantChangeResponseDTO (async responses sent back to Issuers for each merchant in the list) 
Payload integrity will be validated using a SHA256 encryption of the fields within the payload and a salt value (provided by us) 
Signature = SHA256(salt + cdChangeRequestId + issuerChangeRequestId + cdMerchantId + issuerMerchantName + responseCode)
 
Salt example: 5Ggw7HcWsBuewd43N2Tp
Resulting payload: 

{

"cdChangeRequestId":920, "issuerChangeRequestId":1559546925282, "cdMerchantId":"35", "issuerMerchantName":"Uber", "responseCode":"000",

“signature”:“fd676168a35365fe2335d66ed7914b7784be5151cc16a999df833d56d5afd89a”

}

 

Full Enrollment

The Full Enrollment API provides users with a technical connection to register themselves in different merchants without having to do it manually in each one of them.

Directly from their bank app, the User will have access to exclusive offers to register himself in these merchants just by entering a password for each one. The rest of the data is provided by the bank, assuring data quality. 

Full enrollment flows

Methods

 

Available Enrollment Merchants Request

GET      enrollment/merchants

With this method the Issuer will request all the merchants available to push an Enrollment Request and get an array with all the details to render the promotions and registration forms of all the merchants available to receive new Registrations. 

The possible response codes are the following:

In case of receiving a 200 OK response, in the Body of the response there will be an array of the different Merchant definitions, the AvailableEnrollmentMerchantsDTO

AvailableEnrollmentMerchantsDTO parameters:

MerchantDetailsDTO:

MerchantFormDTO:

PromosDTO:

Request example
This request has no body
Response example: 
status: 200 ok
{
        "merchantType":
"Mobility",
        "merchants": [
            {
                "cdMerchantId":
66,
                "promotions":
"GLFyzF6YjNjL2TmAptPsOA==",
                "form":
"f[{"dataType":"text","inputName":"email","issuerFieldsName":"email","label":"Correo","maxSize":50,"minSize":4,"regexValidation":"^(\\D)+(\\w)*((\\.(\\w)+)?)+@(\\D)+(\\w)*((\\.(\\D)+(\\w)*)+)?(\\.)[a-z]{2,}$","toolTip":""},{"dataType":"password","inputName":"passwd","issuerFieldsName":"","label":"Contraseña","maxSize":20,"minSize":8,"regexValidation":"^([a-zA-Z0-9@*#]{8,20})$","toolTip":"La contraseña debe tener más de 8 caracteres"},{"dataType":"text","inputName":"name","issuerFieldsName":"name","label":"Nombre","maxSize":20,"minSize":1,"regexValidation":"^([a-zA-zÑñ\\s]{2,})$","toolTip":""},{"dataType":"text","inputName":"surname","issuerFieldsName":"surname","label":"Apellido","maxSize":20,"minSize":1,"regexValidation":"^([a-zA-zÑñ\\s]{2,})$","toolTip":""},{"dataType":"dropDown","dropDown":"+34,+1,+51,+52,+53,+54,+55,+56,+57,+58,+351","inputName":"phonePrefix","issuerFieldsName":"phone-prefix","label":"Prefijo","maxSize":4,"minSize":2,"regexValidation":"","toolTip":""},{"dataType":"number","inputName":"phoneNumber","issuerFieldsName":"phone-number","label":"Número móvil","maxSize":15,"minSize":9,"regexValidation":"","toolTip":""},{"dataType":"dropDown","dropDown":"MX,ES,CL","inputName":"addressCountry","issuerFieldsName":"address-country","label":"País","maxSize":2,"minSize":2,"regexValidation":"","toolTip":""}]"*,
                "merchantDetails":
"{"enrollmentTitle":"Disfruta del viaje","enrollmentShort":"¿Vas a algún sitio? Deja que Cabify te lleve.","merchantBrand":"Cabify","merchantDescription":"Cabify es una empresa española de ridesharing. Proporciona vehículos de alquiler a través de su aplicación móvil para teléfonos inteligentes.","merchantLogo":"http://d2e8pqed1httqt.cloudfront.net/cabify.png","merchantType":"Mobility","paymentMethod":1,"privacyPolicy":"https://cabify.com/spain/privacy_policy?hidden=true","androidStoreUrl":"https://play.google.com/store/apps/details?id=com.cabify.rider&hl=es","iOSStoreUrl":"https://itunes.apple.com/es/app/cabify-tu-chofer-privado/id476087442?mt=8","webUrl":"https://cabify.com/es/","termsConditions":"https://cabify.com/spain/terms?hidden=true"}"*
            }
        ]
    }
*Form  and merchantDetails will be propertly encrypted in the real request.
 

Customer One Shot Enrollment Request

POST     enrollment/register-with-payment

Issuer will POST all the registration information including the payment method in a single call. Card Dynamics will perform the Full Enrollment Attempt and will reply with the result or requesting confirmation required from merchants.

Customer One Shot Enrollment Request parameters:

RegistrationFormDTO: is a succession of inputName-value fields which are necessary to perform the full enrollment in a merchant. Ex: In the example request at the right.

CardDataDTO:

BankDataDTO:

Possible response codes:

CustomerOneShotEnrollmentResponseDTO: Enrollment request response body parameters:

Merchant side will reply to the registration attempt with this object and HTTP codes as above. In case everything is ok, then response must be on a HTTP 200, and there are 2 cases:

  1. HTTP 200 + validationType = null means the full enrollment and payment method registration has been successfully performed. CD Enrollment and card/bank registration statuses will be SUCCESS.

  2. HTTP 200 + validationType in (“CONFIRMATION”,”CODE”) means everything is progressing fine, but there is confirmation pending. CD Enrollment and card/bank registration statuses will be PENDING VALIDATION. A new CustomerConfirmationRequest is expected after this, within the merchant timeout frame.


In case the User could not be registered due to one or more field values, Response will be HTTP 400.
HTTP 400 should be sent with fieldsInError value allowing new attempts from the issuer side, requesting the new value for the fields that were rejected during the registration attempt.


The old registration attempt is in his final FAILED status and a new enrollmentId will be created with every new attempt.

Request example
{
"cdMerchantId" :
724012,
"registrationData" :
"{"email": "antonio.carbonell@gmail.com","name":"Antonio","surname":"Carbonell","passwd":"Test01"}"*,
"cardData" :
"{"pan":"5173430113367385" ,"expDate":"0625","cardHolder":"ANTONIO CARBONELL","cvv":"236","country":"ES","currency":"EUR"}"*,
"bankData" :
null,
"integrityCheck" :
"c95533935d5fc976bc33cb82c8b6843e76ec396508a3d777615707bf04620a93",
"promoId" :
""
}
*registrationData  and cardData/bankData will be propertly encrypted in the real request.
Response example
status: 200 ok

{

    "message": "Por favor, introduce el código de 4 dígitos enviado al 677418232",

    "validationType": "CODE",

    "enrollmentId": "81ab3fb7-9a05-445cbc9c-72c55309428d",

    "fieldsInError": null

}

fieldsInError example
{
"cdMerchantId" :
724012,
"registrationData" :
"{"email": "antonio.carbonell@gmail.com","name":"Antonio","surname":"Carbonell","passwd":"Test01"}"*,
"cardData" :
"{"pan":"5173430113367385" ,"expDate":"0625","cardHolder":"ANTONIO CARBONELL","cvv":"236","country":"ES","currency":"EUR"}"*,
"bankData" :
null,
"integrityCheck" :
"c95533935d5fc976bc33cb82c8b6843e76ec396508a3d777615707bf04620a93",
"promoId" :
""
}
*registrationData  and cardData/bankData will be propertly encrypted in the real request.
Response example

{

    "message": "Please, check the fields highlighted in red",

    "validationType": "null",

    "enrollmentId": "81ab3fb7-9a05-445cbc9c-72c55309428d",

    "fieldsInError": "[ “username”:”Choose another username, user007 is already taken.”,”email”:”The email provided already belong to another user.”,“national_ID”:”You National ID number is already registered in our system."]"

}

 

Customer Confirmation Request

POST     enrollment/confirmation

In case the Issuer gets the optional field validationType populated with “CONFIRMATION” or “CODE” from the One shot Enrollment Response or from a previous Customer Confirmation Response, Issuer must inform the end user and take the appropriate actions to reply with the CODE requested or with the OK confirmation from the end user about the email validation. A Confirmation must be send within the merchant predefined timeout (usually 5 min).

Customer Confirmation Request parameters:

The possible response codes are the following:

Response body:

In case the confirmation has been successfully performed, the Response must be on a HTTP 200 code.

 

  1. HTTP 200 + validationType = null means the full enrollment and payment method registration has been successfully performed. CD Enrollment and card/bank registration statuses are SUCCESS.

  2. HTTP 200 + validationType in (“CONFIRMATION”,”CODE”) means everything is progressing fine, but there is confirmation pending. CD Enrollment and card/bank registration statuses will stay in PENDING VALIDATION.


A new CustomerConfirmationRequest should be sent after this within the merchant’s timeout.
In case the confirmation code input fails, the Response is an HTTP 400 code.

  1. HTTP 400 + validationType = null means the full enrollment and payment method registration has FAILED. CD Enrollment and card/bank registration statuses are FAILED

  2. HTTP 400 + validationType in (“CONFIRMATION”,”CODE”) means the confirmation was NOT OK, but can be retried. CD Enrollment and card/bank registration statuses will stay in PENDING VALIDATION. A new CustomerConfirmationRequest should be sent after this within the merchant’s timeout.

Request example
{
"enrollmentId" :
81ab3fb7-9a05-445cbc9c-72c55309428d,
"validationType" :
"CODE",
"code" :
1234,
¡}
Response examples
status: 200 ok

{

    "message": "null",

    "validationType": "null",

    "enrollmentId": "81ab3fb7-9a05-445cbc9c-72c55309428d"

}

status: 200 ok

{

    "message": "Por favor, valida el email antonio@card-dynamics.com",

    "validationType": "CONFIRMATION",

    "enrollmentId": "81ab3fb7-9a05-445cbc9c-72c55309428d"

}

 

Replacement

The Replacement Method provides 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.
 

Methods

 
 

Card Dynamics Merchants Request

GET      /categorisation/issuer/export

Request to get all the Card Dynamics merchants for a specific Issuer and all the ones available having Issuer’s country. Will return both categorized and not categorized merchants. This Request has no Body, just the X-API-KEY in the Header. The possible response codes are the following

In case of receiving a 200 code, the response will be a JSON array of merchants where the replacement can be performed, called CardDynamicsMerchantsResponseDTO.

The fields of each merchant present in the list are explained in the following table:

Request example
This request has no body
Response example
[{"issuerId": null,
"issuerMerchantId":
null,
"issuerMerchantName":
null,
"issuerMerchantCountry":
null,
"cdMerchantId":
3,
"cdMerchantCountry":
"ES",
"cdMerchantBrandNames":
"",
"cdMerchantWebSite":
"",
"cdMerchantLogoUrl":
"https://url_logos/spotify.gif",
"cdSignedContract":
1
},
{"issuerId": 1021,
"issuerMerchantId":
"92",
"issuerMerchantName":
"Spotify MX",
"issuerMerchantCountry":
"MX",
"cdMerchantId":
4,
"cdMerchantCountry":
"MX",
"cdMerchantBrandNames":
"Spotify",
"cdMerchantWebSite": "www.spotify.com.mx",
"cdMerchantLogoUrl":
"https://url_logos/spotify.gif",
"cdSignedContract":
2
}
]

Change Request

POST   /changerequest/issuerrequest/change

This Request is used to process a change request from an Issuer. The X-API-KEY is present in the Header and the body has the following scheme:

Replacement Reason:

Possible response codes:

Request to Issuer’s endpoint with merchant change result containing this information in JSON format:

Request example
{
"issuerChangeRequestId" :
{{$timestamp}},
"replacementReason" :
"OP",
"ocPan" : "4200000000000018",
"ocExpDate" : "0119",
"ncPan" :
"4200000000000019",
"ncExpDate" :
"0121",
"integrityCheck" :
"95c6842e6149862e7e3c65f559313f12b97ded9cb23eb10c5a4926bbf91f87b3",

"merchantList" : "
[
{
"cdMerchantId": "21232",
},
{
"cdMerchantId": "69731"
}

}
Response example

{

"cdChangeRequestId":137895,

"issuerChangeRequestId":1599053948,

"cdMerchantId":"21232",

"responseCode":"000",

"signature":"c6779dd3d811ab28b8cf17fc770a7adbcb050d6cc57140803db743aef95a255c"}

 

Request Tokenization Operation

GET        /tokenization/new

Requests a new tokenization operation. This Request has no Body, just the X-API-KEY in the Header.

The possible response codes are the following:

If the request is succesfully processed, an operationId will be received in the response. This operationId will be necessary to keep track of the following tokenization request.

Tokenization scheme:

Request example
This request has no body
Response example
    {
        "operationId" :
"123e4567-e89b-12d3-a456-556642440000"
}
 

Issuer Merchants Import Request (Optional)

POST      /categorisation/issuer/import

With this method the Issuer can optionally push all the descriptors/unknown merchants to Card Dynamics so Card Dynamics can perform the categorization identifying the merchants inside the system to provide an updated connection. The X-API-KEY is sent in the Header and the body has the following schema:

The possible responses are the following

In the response the API informs of the number of inserted rows. This method will either insert all the merchants whic were sent in the request, or won't insert any merchants, no partial inserts can be performed.

Request example
Response example

{

"success": 1

}

[
{
"issuerMerchantId" :
"12345"
"issuerMerchantName" :
"name/descriptor"
"issuerMerchantCountry" :
"ES"
}
]

Execute Tokenization

POST         /tokenization/tokenize

Processes a tokenization request coming from the Issuer’s mobile App. The X-API-KEY is present in the Header and the body has the following scheme:

The possible response codes are the following:

Request example

{

"operationId" : "123e4567-e89b-12d3-a456-556642440000",  

  "pan" : "4940005077154636"

Response example
    {
        "token" :
"xxxxxyyyyyyyyxxxxxxyyyyyyxxxxxyyyyxxyyyyyyxxxxyyyy"
}

If the request is successfully processed, the response will include the token of the credit card whic will be used in all future operations to assure security during all processes.

 
 

Change log

 

Card Dynamics © - Legal Advice - GDPR