Cardinal Merchant Onboarding API
CardinalCommerce supports our re-seller engagements by supplying a Merchant Onboarding API that enables connectivity between the partner client's platform and Cardinal's Centinel platform. Implementation of the Cardinal Consumer Authentication (CCA) service requires all clients to utilize credentials that identify the merchant, transaction and you, as our partner.
Merchant registration (via the Onboarding API) is a function that creates a merchant account within our Centinel platform to prepare our mutual client for production readiness. The API not only creates new merchant accounts but also serves as a tool to allow partners to make specific updates to the client profile and to retrieve account details.
The functionality within the Onboarding API includes:
Merchant Creation
A new merchant profile, payment configurations, and transaction credentials will be created
API Key Creation
Create transaction credentials to be used with Cardinal Consumer Authentication
Merchant Acquirer Configurations
Create, Retrieve, Update, and Delete Acquirer configurations on a per merchant basis
Payer Authentication Configurations
Retrieve and Update configurations related to Cardinal Consumer Authentication on a per merchant basis
Connecting to the Onboarding API
The Merchant Onboarding API can connect to both our Staging (Test) and Production environments. The base domains used to connect to each of these environments are demonstrated below.
Environment | DNS |
---|---|
Staging (Test) | https://cardinalonboardingapistag.cardinalcommerce.com/CardinalOnboardingAPI |
Production | https://cardinalonboardingapi.cardinalcommerce.com/CardinalOnboardingAPI |
Rate Limiting
API requests to the Onboarding API are limited to 5 requests per second. This limit applies to all endpoints. When this rate is exceeded, you will receive the following response:
Response Code | 429 |
---|---|
Response Message | Too Many Requests |
Response Body | Request blocked, limit exceeded |
If you encounter this response, please wait an additional 5 seconds and retry your request.
Authentication
Access to the endpoints within the Merchant Onboarding API are permission based and enforced via use of an API Key specific to the environment. During your solution design, you will have received these credentials for both our Staging (Test) and Production environments. Use of these credentials within your solution design should be dynamic based on the environment.
If you have questions regarding your API Key values and environment configurations, please reach out to your Implementation Manager.
Request Format
Every endpoint requires a pre-defined format, using the API Key to establish a Signature to identify your request. This helps establish a consistent format for each endpoint that is compatible with the Cardinal security model.
To create the request object, the following items are needed:
ApiKey: The ApiKey will be given by Cardinal. This is how we identify who you are.
Identifier: This is the identifier that will be given to you by Cardinal. This works in conjunction with the ApiKey to generate the signature.
OrgUnitId: This tells the API which Processor ID to place the newly registered merchant under.
Partners may have multiple Processor IDs that segment business lines based on region, solutions, platforms, etc.
Algorithm: This value can be hard coded and removed from the constructor if wanted. The Algorithm can be either SHA-256/512.
TransactionId: A unique identifier for the request. Randomly generated value, alphanumeric between 5 and 55 characters.
Payload: This is the body of the request to the service. This request object will be serialized into JSON to be consumed by the API.
Signature: The API Key Signature is generated by concatenating the Unix Epoch Time in Milliseconds with the API Key, hashing the result, and then Base64 encoding the result.
These items/fields will be used to create the core request object used to communicate with the Onboarding API.
Request Field Definitions
Field Name | Description | Definition |
---|---|---|
Signature | A unique value used to identify and authenticate the request. | AN(255) |
Timestamp | Date/Time of the request |
OR Epoch Milliseconds e.g. |
OrgUnitId | Identifier that represents the Organization entity within the Cardinal system | AN(24) |
Algorithm | The algorithm used for the hashing within the Signatures | Supported Values:
|
Identifier | The unique value associated with your API Key. This will have been given to you during your solution design and will be consistent on each request. There is. a1:1 relationship between this value and your API Key. | AN(255) |
TransactionId | A unique identifier for the request. This is expected to be randomly generated. | AN(5-55) |
Payload | The payload will be the request object defined for each endpoint. See the below definitions for examples. | JSON/String |
Request Example
{
"Signature": "rv4nqWMEETWFhYQ7FCy+/l6eoVT2XydjOXXz+BC5jqg=",
"Timestamp": "2020-01-26T16:03:42.633Z",
"Identifier": "MerchantRegistration-Partner-Identifier",
"Algorithm": "SHA-256",
"TransactionId": "07643622",
"OrgUnitId": "55d256cfdb2b0f17304e9db8",
"Payload": "See Endpoint for Detail"
}
Generating a Signature Value
C# Code Sample
var bytesToHash = Encoding.UTF8.GetBytes(TimeStamp.GetUnixTime() + transactionId + apiKey);
string signature = Convert.ToBase64String(GetHashAlgorithm(Algorithm).ComputeHash(bytesToHash));
SHA-256 Example Values:
Timestamp: 2019-01-14T20:42:13.216Z
Milliseconds Since Epoch: 1547498533216
TransactionId: 07643622
ApiKey: 13f1fd1b-ab2d-4c1f-8e2c-ca61878f2a44
Signature: wpGKFbhcBl+8JLVXGP0QqBooK6dtLBv9bYtI15NXL1U=
SHA-512 Example Values:
Setting up the Merchant for Live Transactions
The Onboarding API enables you to make a single API call to create a new merchant, configure them for authentication, and receive their transaction credentials. Following completion of the Create Merchant API call, your new merchant will be ready to begin testing their Cardinal Consumer Authentication connectivity. Additional steps are required to configure the merchant for Live transactions. To complete these required steps, please work with with your Technical Account Manager to fully enable your newly created merchant(s).
Create Merchant
This is a synchronous API call which will create the merchant profile, create payment configurations, and transaction credentials (API Key).
Important: Please be sure to save the API Key as it is returned on Create Merchant. For security reasons, this will be the only time you have direct access into this value. There is no /Get endpoint to retrieve the API Key at a later time.
Endpoint - /V2/Merchant/Create
There are 4 primary objects to include in the Merchant Create call to fully set up your merchant: Centinel Merchant, Merchant Acquirer Configs, API Keys, Payer Auth Config (optional).
Merchant Acquirer Configs and Payer Auth Config should be nested under a parent CCA object when included in the request object. See the examples below for reference.
Object Definitions
Centinel Merchant
Object Name: CentinelMerchant
Field Name | Format Length | Required | Definition and Values | Example Values |
---|---|---|---|---|
Active | AN(5) | No |
Whether or not the merchant is able to transact. | TRUE |
CavvDataFormat | AN(6) | No | Optional - Defaults to Configuration value. Allowed Values: BASE64, HEX | BASE64 |
City | AN(50) | No | Merchant city | Mentor |
CountryCode | N(3) | Yes | ISO 3166 Country Code | 840 |
MerchantId | AN(50) | Yes | Identity defined for the merchant | 100_abc |
MerchantName | AN(40) | Yes | Name of the Merchant as assigned by the Acquirer. This value should be the same name used in the authorization message as defined in ISO 8583. No Special Characters allowed in this field | TestMerchant |
MerchantURL | AN(255) | Yes | Merchant URL Must be valid https URL | |
MerchantEmail | AN(254) | Yes | Email associated with the merchant account | |
Mode | AN(8) | No | Optional - Defaults to Configuration value. Allowed values:
| READONLY |
State | A(2) | No | State/Province the Merchant is incorporated Format: ISO 3166 | OH |
TestCaseGroup | AN(10) | Yes | Optional - Defaults to Configuration value. Recommended to pass CUSTOM. Allowed values:
| CUSTOM |
Timezone | AN(50) | No | Merchant time zone. | 11 |
TransactionPassword
NOTE: Use of TransactionPassword is in the process of being sunset. Please use API Signature when integrating to Cardinal service side endpoints. For more information, please refer to Cardinal (cmpi) Messages | API Key Usage | AN(50) | No | A password to secure and verify the transaction originated from the Merchant represented by the transaction details. The password value is configured in the Merchant profile. Min 5 to Max 50 characters. Requires the following:
| ABC123!@# |
Merchant Acquirer Configs
This will allow the partner to add the merchant's acquirer details that are required for the network directory server set-up.
Object Name: MerchantAcquirerConfigs
Field Name | Format Length | Required | Definition and Values | Example Values |
---|---|---|---|---|
AcquirerId | AN(30) | Yes | The Acquirer ID that the merchant is configured under in the acquirer's system, typically 6 digits | For Visa, this value will begin with a 4 (example: 4xxxxx) and be 6 digits For Mastercard, this value will begin with a 5 or a 2 (example 5xxxxx or 2xxxxx) and be 6 digits NOTE: For AMEX, this value will be longer than 6 digits |
AcquirerMerchantId | AN(35) | Yes | Merchant ID assigned by the Acquirer | Test Merchant |
CurrencyCode | AN(8) | Yes | 3 digit numeric (ISO 4217) or 'Default.' | |
PaymentInitiativeType | No max length | Yes | Values:
| VerifiedByVisa |
ThreeDSV1Disabled | N(1) | No | Disable 3DS1: The transaction will stop routing down to the 3DS1 path Values:
| 1 |
VMID | AN(35) | No (Only applicable for Visa) | Visa Merchant ID (VMID) | Provided by VerifiedByVisa |
AcquirerPassword | AN(8) | No NOTE: The AcquirerPassword is required for JCBJSecure requests. |
| 12345678 |
MCCCode | N(4) | Yes | Merchant category code (MCC) | Refer to EMV 3DS specification |
RequestorName | AN(40) | No NOTE: this value is required if you plan to run EMV 3DS transactions | This value is a Directory Server assigned 3DS Requestor Name value, each DS may provide a unique ID. |
|
RequestorID | AN(35) | No NOTE: this value is required if you plan to run EMV 3DS transactions | This value is a Directory Server assigned 3DS Requestor ID value, each DS may provide a unique ID. |
|
API Key
Object Name: APIKey
Field Name | Format Length | Required | Definition and Values | Example Values |
---|---|---|---|---|
ListOfGroups | AN(255) | Yes | List of Groups requested to add in the Merchant API Key. |
|
Payer Auth Config
The final object allows the partners to set up the merchant with their Payer Authentication Configurations. This step is only required if the partner wishes to set up the merchant with any custom configurations. Otherwise, Payer Authentication configurations will be set to default and this object will not be required.
The Merchant Onboarding API supports 143 different configurations for Payer Authentication. For a full listing of available fields, please reach out to your Solution Engineer.
Object name: PayerAuthConfig
2.0 Field Name | Centinel Field Name | Required | Definition and Values | Set As |
---|---|---|---|---|
Three DS 2.0 Enabled | ThreeDSV2 | Yes | Enable 3DS2: The transaction will be routed down to the 3DS2 path when DF information is available or when applicable fields are passed on the cmpi_lookup. If we miss any data of the data fields required for the 3DS2 data field we fall back to 1.0. Values: Default/On/Off | On |
ThreeDSV1Disabled | ThreeDSV1Disabled | No | Disable 3DS1: The transaction will stop routing down to the 3DS1 path Values: On/Off | On |
Merchant Category Code | CategoryCode | No | It is a default value passed if the Merchant doesn't specify one on the lookup. This field is passed in AReq and is an indicator of what type of goods the Merchant sells. | 1234 |
| ReturnStepUpUrl | Conditionally | It is a required value that needs to be passed by the merchant who wants to use Cardinal Cruise API integration | On |
| StepUpUrl | Conditionally | It is a required value that needs to be passed by the merchant who wants to use Cardinal Cruise API integration | Staging: https://centinelapistag.cardinalcommerce.com/V2/Cruise/StepUp Production: |
Request / Response Examples
Create Merchant Request
Create Merchant Response
Notification URL
For specific portions of the Create Merchant API call, you can opt to receive individual responses for each of the actions. These responses will be returned to a pre-configured Notification URL; the Notification URL is a fully qualified URL of the merchant webpage and should be returned to your designated Solution Engineer. The Notification URL will be used in the following scenarios:
Create Payer Authentication Configuration: Sends notification to the Configured URL after PayerAuthConfig is created.
Create Merchant Acquirer Configuration: Sends notification to the Configured URL after MerchantAcquirerConfig is created.
NOTE: A single Notification URL may be created for the two responses, or two separate URLs.
This step is optional, unless you require granular detail on the specifics of the merchant creation.
JWT
The notification sent to the Notification URL will be in the form of a JWT which will be signed with the your API Key.
Generic JWT - Stringified JWT Sample
Claim Name | Description |
---|---|
iat | Issued At - The epoch time in seconds of when the JWT was generated. |
iss | Issuer - An identifier for whom this JWT was issued for. This is used to map the shared secret API Key. |
exp | Expire At - |
jti | A guide value |
Payload | The JSON data object set to Notification URL. This object will change based on the type of notification. |
It is expected that you will respond with a Status of the Notification, to inform Cardinal of the receipt.
Expected Response from Notification URL to Merchant Onboarding API
Field | Description |
---|---|
StatusCode | Status code of the notification. We are expecting a status code of 0 if the notification is received. |
ErrorDescription | Description of Error. Set it to blank if there was no error or custom message can be sent. |
Notifications
/PayerAuthConfig/Create Notification
Example of /PayerAuthConfig/Create Notification:
Decoded Payload Data
Payload from Decoded Payload Data
Field | Description | Expected Value |
---|---|---|
ErrorNumber | Error number for the Create PayerAuthConfig request. | 0 |
ErrorDescription | Description of Error. |
|
Type | Type of request. | PayerAuthConfig |
Action | Action requested. | Create |
TransactionId | TransactionId sent during the merchant create request. |
|
Payload | Payload that was requested to create PayerAuthConfig. |
|
/MerchantAcquirerConfig/Create Notification
Example of /MerchantAcquirerConfig/Create Notification:
Decoded Payload Data
Payload from Decoded Payload Data
Field | Description | Expected Value |
---|---|---|
ErrorNumber | Error number for the Create MerchantAcquirerConfig request. | 0 |
ErrorDescription | Description of Error. |
|
Type | Type of request. | MerchantAcquirerConfig |
Action | Action requested. | Create |
TransactionId | TransactionId sent during the Create MerchantAcquirerConfig request. |
|
Payload | Payload that was requested to create MerchantAcquirerConfig. |
|
Table of Contents
- 1 Connecting to the Onboarding API
- 1.1 Rate Limiting
- 1.2 Authentication
- 1.3 Request Format
- 2 Setting up the Merchant for Live Transactions
- 2.1 Create Merchant
- 2.1.1 Object Definitions
- 2.1.1.1 Centinel Merchant
- 2.1.1.2 Merchant Acquirer Configs
- 2.1.1.3 API Key
- 2.1.1.4 Payer Auth Config
- 2.1.2 Request / Response Examples
- 2.1.1 Object Definitions
- 2.1 Create Merchant
- 3 Notification URL
Additional Information
EMV® is a registered trademark in the U.S. and other countries and an unregistered trademark elsewhere. The EMV trademark is owned by EMVCo, LLC