Overview – Enrollment

Merchant API 2.0 new features allow merchants to set up specific promotions on Issuers APPs and receive high quality new registrations users seeking their services.

 

Merchants can receive a validated new registration and get new payment method from the Issuer sending the information (card or bank account).

 

No personal data will be kept in Card Dynamics, protecting end user’s information.

URI Scheme

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

Merchant API

Overview – Card Replacement

The goal of this API is to provide Merchants and PSPs with a technical connection to get update requests over customer cards information to replace old card details with new card details at the corresponding data vault of the merchants selected by the Card Owner. This merchant selection provided by the Card Owner will be sent to Card Dynamics from the Card Issuers or Banks.

This API is meant to be 100% available as we expect to receive calls from Card Dynamics with the update requests.

The Card Owner will push the request from any of the Issuer Applications, once the Card Owner select 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 and Card dynamics will push to this API the card updates.

The ultimate goal of all this is to be able to continue performing recurrent payments with the new card-on-file details, to do this the PSP/Merchant must provide a way to made the new card work using the old token on the merchant, depending on the case.

 

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 call the User is making.
For an Replacement Request The integrityCheck parameter will be composed by concatenating bold ocPan + ocExpDate + ncPan + ncExpDate 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.

All new Enrollment feature methods have integrity check parameters built exactly as the one defined above for Card Replacements.

 

Only the fields involved change on each method, in Enrollment objects integrity check is always composed using requestId + requestData combination

 

Enrollment

This method must be processed by a PCI actor willing to receive all the registration information including the payment method in a single call. Card Dynamics will POST to the Customer Enrollment URL provided the object defined below to attempt a new CustomerOneShotEnrollment Request.

One or more Customer Confirmation Requests may be required to perform the full enrollment.

Methods

Customer One Shot Enrollment Request

POST    Customer Enrollment URL

With this method the targeted Merchant will receive the request with all the necessary information to perform a full enrollment  with the personal and payment data included in the Request. 

CustomerOneShotEnrollmentRequestDTO:

As seen in the schema, every field carrying personal or payment information is encrypted for security reasons.

The registrationData object is a JSON array which contains all necessary fields to perform the EnrollmentRequest in the chosen merchant. Each field  is a pair of inputName => value.

These fields vary depending on the merchant.

RegistrationFormDTO:

The cardData object is a JSON array which contains the fields with the information of the credit or debit card which is going to be used as payment method in the chosen merchant.

Card DataDTO:

The bankData object is a JSON array which contains the fields with the information of bank account which is going to be used as payment method in the chosen merchant. The necessary parameters are the following:

BankDataDTO:

Request example
{
"enrollmentRequestId" : 724012,
"registrationData" : "{"email": "antoni.carbol@gmail.com","name":"Antonio","surname":"Carbonell","passwd":"Test0101"}",
"cardData":"{"pan":"5151238713368623", "expDate":"0325","cardHolder":"ANTONIO CARBONELLL","cvv":"231", "country":"ES","currency":"EUR"}",
"bankData" : null,
"integrityCheck":"c323437cda21a40386b67edc295d3d1ced369cffb24fecd75d",
"promoId":""
}
Response example
CustomerOneShotEnrollmentResponse
 

Customer One Shot Enrollment Response

Response to the CustomerOneShotEnrollmentRequest. In case not all required fields were sent in the Request, missing fields are indicated in the FieldsInError object. The parameters of the Response are the following:

The possible response codes are the following:

Merchant side will reply to the registration attempt with this object and HTTP codes as below. In case the User has been created and maybe the payment method registered, then response must be on a
HTTP 200:

 

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

  • 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 CustomerConfirmationRequest should be expected after this.

 

 

In case the User has been identified (was already registered in the Merchant) Response must be on a HTTP 409. HTTP 409 is a final KO and should reply with a message explaining the case.


In case the User could not be registered Response must be on a HTTP 400. HTTP 400 should be sent with fieldsInError value allowing new attempts from the issuer side, requesting the new value for the fields rejected/invalid during registration attempt. A new CustomerOneShotEnrollmentRequest is expected after this.


In case fieldsInError is null, HTTP 400 will mean CD Enrollment and card/bank registration statuses become FAILURE.


Any other HTTP code will mean CD Enrollment and card/bank registration statuses become FAILURE

Request example
CustomerOneShotEnrollmentRequest
Response example

{

 "message": "Introduzca el código de cuatro dígitos enviado al (+34)699121212",

"validationType": "CODE",

"fieldsInError": null

}

 
 

Customer Confirmation Request

POST    Customer Confirmation URL

This method must be processed by the PCI actor in case there is a confirmation required by the merchant (received in the previous CustomerOneShotEnrollmentResponse).
Card Dynamics will POST to the Customer Confirmation URL (new) providing the object defined below.

In case there is a confirmation code required by the merchant, it can be received either by phone or by email. This code is sent  in the CustomerConfirmationRequest as seen in the schema.

Request example

{

    "enrollmentRequestId": "00004c00-6bfa-43b7-8208-3c27fbf2c0b3",

    "validationType": "CODE",

    "code" : "1234"

Response example

CustomerConfirmationResponse

Customer Confirmation Response

POST    Customer Confirmation URL

This method must be processed by the PCI actor in case a CustomerConfirmationRequest has been previously sent.
Card Dynamics will POST to the Customer Confirmation URL (provided by the PCI actor) the object defined below.

Merchant will reply to the Confirmation Request with this object and HTTP codes as below.


In case the confirmation has been successfully performed Response must be on a HTTP 200:

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

  • 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 is expected after this.


In case the confirmation code input fails Response must be on a HTTP 400:

 

  • HTTP 400 + validationType = null means the full enrollment and payment method registration has FAILED. CD Enrollment and card/bank registration statuses will turn FAILURE

  • 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.

Request example
CustomerConfirmationRequest
Response example

{

    "validationType": null,

    "message": "OK"

}

 
 

Replacement

The goal of this API is to provide Merchants and PSPs with a technical connection to receive update requests over customer cards information to replace old card details with new card details at the corresponding data vault of the merchants selected by the Card Owner. This merchant selection provided by the Card Owner will represent a mandate to act on his behalf and execute the update.

The Card Owner will push the request, 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 and Card dynamics will push to this API the card updates. The general scheme of the operation looks like the following:

Card Dynamics will Push the Merchant Update Request with the ​required information to perform the replacement. The PSP or the Merchants will attempt to update the  credit card and will respond with the corresponding Status Code of the operation. Each Merchant will send an asynchronous notification when the operation is succesfully performed.

Methods

 

Merchant Update Request

POST    PSP/Merchant Update URL

Update request sent from Card Dynamics to the PSP or PCI Merchant, the URL has to be provided by them. The Body of this request is the following:

A notification will be sent by the PSP. The possible responses are the following:

If the response was an HTTP 200, the replacement operation is performed in all selected merchants. 

If the response wasn't an HTTP 200, the replacement operation ends, its status will be FAILURE.

After an HTTP 200, the replacement will be tried in each of the selected merchants, the high level flow of this operation can be viewed in the following schema:

Each merchant will send an asynchronous response to Card Dynamics when the replacement operation is finished: the Merchant Update Notification Result.

Request example
{
"cdUpdateId" :
25,
"integrityCheck" :
"95c6842e6149862e7e3 c65f559313f12b97ded9cb23eb10c5a4926bbf91f87b3",
"merchantPspId" :
100,
"ocPan" :
"4200000000000018",
"ocExpDate" :
"0119",
"ncPan" :
"4200000000000019",
"ncExpDate" :
"0121",
}
Response example
200 OK
This response has no body.
 
 

Merchant Update Notification Result

POST     /updateResult/updatenotification/result

Once the replacement request is processed, the PSP or the PCI merchant must receive a notification result for each merchant. Each of these notifications has the following parameters:

The possible respCodes are the following:

Request example

{
"cdUpdateId" :
25,
"message" :
null,
"pspUpdatedId" :
100,
"respCode" : "
200",
}

Response example
This response has no body.
 

Change log

 

Card Dynamics © - Legal Advice - GDPR