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.
1. 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	`yyyy-MM-dd'T'HH:mm:ss.fff'Z'` OR Epoch Milliseconds e.g. `1547498533216`
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: SHA-256 SHA-512
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	TRUE FALSE 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	https://example.com
MerchantEmail	AN(254)	Yes	Email associated with the merchant account	email@domain.com
Mode	AN(8)	No	Optional - Defaults to Configuration value. Allowed values: READONLY	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: CARDINAL CUSTOM MERCHANTACS	CUSTOM
Timezone	AN(50)	No	Merchant time zone. See Appendix B: Time Zones	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: At least 1 lower case character At least 1 upper case character At least 1 numeric character	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.'	See Appendix A: ISO Currency Code
PaymentInitiativeType	No max length	Yes	Values: VerifiedByVisa AmexSafeKey ELO DinersClubInternationalProtectBuy MasterCardSecureCode JCBJSecure Maestro CB EFTPOS UPI ITMX EFTPOS Mada	VerifiedByVisa
ThreeDSV1Disabled	N(1)	No	Disable 3DS1: The transaction will stop routing down to the 3DS1 path Values: 1 = Stops transactions from routing down 3DS 1.0 2 = Allows transactions to route down 3DS 1.0	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.	Cardinal Consumer Authentication

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: https://centinelapi.cardinalcommerce.com/V2/Cruise/StepUp

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: