Cardinal Merchant Onboarding API Reference
Merchant
Get
Endpoint - /V2/Merchant/Get
The Merchant you are intending to retrieve will be represented as the OrgUnitId on the core request. Note: no Payload is required for the request on this endpoint.
Get Merchant Request
{
"TransactionId": "44104676",
"Signature": "GCjvrRxb8FdfWl+/5tZ7mw7nEOzzIK48TFKoVBwgyWc=",
"Timestamp": "2020-02-01T20:14:57.484Z",
"Identifier": "CardinalOnboardingAPI-Test",
"Algorithm": "SHA-256",
"OrgUnitId": "5b6214bc2f3e7330d08ed35e"
} |
Get Merchant Response
{
"TransactionId": "44104676",
"ErrorNumber": 0,
"Message": "",
"Payload": {
"Merchant": {
"Active": true,
"CavvDataFormat": "BASE64",
"City": "Mentor",
"CountryCode": "840",
"MerchantId": "TM123456",
"MerchantURL": "https://www.merchanturl.com",
"Mode": "READONLY",
"State": "OH",
"TimeZone": "11",
"MerchantName": "TestMerchant"
}
}
} |
Update
Endpoint - /V2/Merchant/Update
Field Name | Format Length | Required | Definition and Values | Example Values |
|---|---|---|---|---|
Active | AN(5) | No | (True of False is expected) 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(10) | Yes | ISO 3166 Country Code | 840 |
ErrorDescription | AN(500) |
| (Only present in the response) Error description of the request. |
|
ErrorNumber | AN(20) |
| (Only present in the response) Error number for the request. '0' indicates that request was successful. |
|
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 |
MerchantEmail | AN(250) | Yes | Email associated with the merchant account | |
MerchantURL/WebsiteURL | AN(255) | Yes | Merchant URL - Must be valid https URL. | |
Mode | AN(8) | No | Optional - Defaults to Configuration value. Allowed values: OPEN, READONLY, LOCKED | 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. See https://cardinaldocs.atlassian.net/wiki/spaces/STAG/pages/1095925795 . | 11 |
Update Merchant Request
{
"TransactionId": "91171867",
"Signature": "snURHeZqgsVYSMnExmvyMW4RRmYqiFPDV+J5d8AJ6xs=",
"Timestamp": "2020-02-01T20:14:58.267Z",
"Identifier": "CardinalOnboardingAPI-Test",
"Algorithm": "SHA-256",
"OrgUnitId": "5b6214bc2f3e7330d08ed35e",
"Payload": {
"CentinelMerchant": {
"Active": true,
"CavvDataFormat": "BASE64",
"City": "Mentor",
"CountryCode": "840",
"MerchantId": "TM123456",
"MerchantURL": "https://www.merchanturl.com",
"State": "OH",
"TimeZone": "11",
"MerchantName": "TestMerchant",
"Mode": "READONLY"
}
}
} |
When sending in updated Merchant Details, the API requires that all configurations (current and updated) be sent in for the call to be updated successfully.
Update Merchant Response
Merchant Acquirer Config
Create
Endpoint - /V2/MerchantAcquirerConfig/Create
Field Name | Format Length | Required | Definition and Values | Example Values |
|---|---|---|---|---|
AcquirerId | AN(20) | Yes | The 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 assigned Acquirer Id. | Test Merchant |
CurrencyCode | AN(8) | Yes | 3 digit numeric (ISO 4217) or 'Default.' | See https://cardinaldocs.atlassian.net/wiki/spaces/STAG/pages/1095925779 |
PaymentInitiativeType | AN(30) | Yes | Values:
| ‘VerifiedByVisa’ or '1' |
AcquirerPassword | AN(100) | 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. |
|
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:
Merchants shouldn’t be sending values other than those mentioned above. | On |
Merchant Acquirer Create Request
Merchant Acquirer Create Response
Update
Endpoint - /V2/MerchantAcquirerConfig/Update
Field Name | Format Length | Required | Definition and Values | Example Values |
|---|---|---|---|---|
AcquirerId | AN(20) | Yes | The 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 assigned Acquirer Id. | UpdatedAcquirerMerchantId |
CurrencyCode | AN(8) | Yes | 3 digit numeric (ISO 4217) or 'Default.' | See https://cardinaldocs.atlassian.net/wiki/spaces/STAG/pages/1095925779 |
PaymentInitiativeType | AN(30) | Yes | Values:
| ‘VerifiedByVisa’ or '1' |
AcquirerPassword | AN(100) | 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. |
|
Merchant Acquirer Config Update Request
Merchant Acquirer Config Update Response
Delete
Endpoint - /V2/MerchantAcquirerConfig/Delete
Field Name | Format Length | Required | Definition and Values | Example Values |
|---|---|---|---|---|
AcquirerId | AN(20) | Yes | The 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 assigned Acquirer Id. | UpdatedAcquirerMerchantId |
CurrencyCode | AN(8) | Yes | 3 digit numeric (ISO 4217) or 'Default.' | See |
PaymentInitiativeType | AN(30) | Yes | Values:
| ‘VerifiedByVisa’ or '1' |
MCCCode | N(4) | Yes | Merchant category code (MCC) | Refer to EMV 3DS specification |
Delete Merchant Acquirer Config Request
Delete Merchant Acquirer Config Response
Get All
The Get All call allows you to retrieve details of the acquirer config loaded in our system.
Endpoint - /V2/MerchantAcquirerConfig/GetAll
Get All Merchant Acquirer Config Request
Get All Merchant Acquirer Config Response
Merchant Acquirer Config(Multiple Configs)
CreateAll
Endpoint - /V2/MerchantAcquirerConfig/CreateAll
Field Name | Format Length | Required | Definition and Values | Example Values |
|---|---|---|---|---|
AcquirerId | AN(20) | Yes | The 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 assigned Acquirer Id. | Test Merchant |
CurrencyCode | AN(8) | Yes | 3 digit numeric (ISO 4217) or 'Default.' | See |
PaymentInitiativeType | AN(30) | Yes | Values:
| ‘VerifiedByVisa’ or '1' |
AcquirerPassword | AN(100) | 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. |
|
Merchant Acquirer CreateAll Request
(Payload containing a List of MerchantAcquirerConfigs)
{ "Signature": "bRKinvmKaHZ9Irvf/cZ+fIs9jQ/QjKeeeqm/Q8xniko=", "Timestamp": "2020-02-01T20:14:59.600Z", "Identifier": "CardinalOnboardingAPI-New", "Algorithm": "SHA-256", "TransactionId": "78020875", "OrgUnitId": "5b6214c32f3e7330d08ed384", "Payload": { "MerchantAcquirerConfigs": [ { "AcquirerId": "444555", "AcquirerMerchantId": "12341234", "CurrencyCode": "Default", "PaymentInitiativeType": "VerifiedByVisa", "RequestorId": "NewVISA", "RequestorName": "NewVISA", "MCCCode": "1234" "ThreeDSV1Disabled": "1" "VMID": "12341234" }, { "AcquirerId": "555555", "AcquirerMerchantId": "12341234", "CurrencyCode": "Default", "PaymentInitiativeType": "MasterCard", "RequestorId": "NewMC", "RequestorName": "NewMC", "MCCCode": "1234" }, { "AcquirerId": "666555", "AcquirerMerchantId": "12341234", "CurrencyCode": "Default", "PaymentInitiativeType": "Diners", "RequestorId": "NewDINERS", "RequestorName": "NewDINERS", "MCCCode": "1234" } ] } } |
Merchant Acquirer CreateAll Response
{ "TransactionId": "73938297", "ErrorNumber": 0, "Payload": { "MerchantAcquirerConfigs": [ { "AcquirerId": "444555-1000", "ErrorNumber": 0, "Message": "Merchant Acquirer config created" }, { "AcquirerId": "555555-1000", "ErrorNumber": 0, "Message": "Merchant Acquirer config created" }, { "AcquirerId": "66666-1000", "ErrorNumber": 0, "Message": "Merchant Acquirer config created" } ] } } |
UpdateAll
Endpoint - /V2/MerchantAcquirerConfig/UpdateAll
Field Name | Format Length | Required | Definition and Values | Example Values |
|---|---|---|---|---|
AcquirerId | AN(20) | Yes | The 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 assigned Acquirer Id. | Test Merchant |
CurrencyCode | AN(8) | Yes | 3 digit numeric (ISO 4217) or 'Default.' | See |
PaymentInitiativeType | AN(30) | Yes | Values:
| ‘VerifiedByVisa’ or '1' |
AcquirerPassword | AN(100) | 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. |
|
Merchant Acquirer UpdateAll Request
{ "Signature": "ynRcqtPJITCbu9lPb+SosETgh5vEOM0uSeSbcG1+0lY=", "Timestamp": "2020-02-01T20:15:01.251Z", "Identifier": "CardinalOnboardingAPI-Test", "Algorithm": "SHA-256", "TransactionId": "79118695", "OrgUnitId": "5b6214c32f3e7330d08ed384", "Payload": { "MerchantAcquirerConfigs": [ { "AcquirerId": "444555", "AcquirerMerchantId": "UpdatedAcquirerMerchantId", "CurrencyCode": "Default", "PaymentInitiativeType": "VerifiedByVisa", "RequestorId": "TestVISA", "RequestorName": "TestVISA", "MCCCode": "1234" "ThreeDSV1Disabled": "1" "VMID": "12341234" }, { "AcquirerId": "555555", "AcquirerMerchantId": "UpdatedAcquirerMerchantId", "CurrencyCode": "Default", "PaymentInitiativeType": "MasterCard", "RequestorId": "TestMC", "RequestorName": "TestMC", "MCCCode": "1234" }, { "AcquirerId": "666555", "AcquirerMerchantId": "UpdatedAcquirerMerchantId", "CurrencyCode": "Default", "PaymentInitiativeType": "Diners", "RequestorId": "TestDINERS", "RequestorName": "TestDINERS", "MCCCode": "1234" } ] } } |
Merchant Acquirer UpdateAll Response
{ "TransactionId": "73938297", "ErrorNumber": 0, "Payload": { "MerchantAcquirerConfigs": [ { "AcquirerId": "444555-1000", "ErrorNumber": 0, "Message": "Merchant Acquirer config updated" }, { "AcquirerId": "555555-1000", "ErrorNumber": 0, "Message": "Merchant Acquirer config updated" }, { "AcquirerId": "66666-1000", "ErrorNumber": 0, "Message": "Merchant Acquirer config updated" } ] } } |
DeleteAll
Endpoint - /V2/MerchantAcquirerConfig/DeleteAll
Field Name | Format Length | Required | Definition and Values | Example Values |
|---|---|---|---|---|
AcquirerId | AN(20) | Yes | The 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 assigned Acquirer Id. | Test Merchant |
CurrencyCode | AN(8) | Yes | 3 digit numeric (ISO 4217) or 'Default.' | See |
PaymentInitiativeType | AN(30) | Yes | Values:
| ‘VerifiedByVisa’ or '1' |
AcquirerPassword | AN(100) | 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. |
|
Merchant Acquirer DeleteAll Request
{ "Signature": "ynRcqtPJITCbu9lPb+SosETgh5vEOM0uSeSbcG1+0lY=", "Timestamp": "2023-02-01T20:15:01.251Z", "Identifier": "CardinalDocs", "Algorithm": "SHA-256", "TransactionId": "79118695", "OrgUnitId": "5b6214c32f3e7330d08ed384", "Payload": { "MerchantAcquirerConfigs": [ { "AcquirerId": "444555-1000", "AcquirerMerchantId": "ABC123XYZ456", "AcquirerPassword": "", "CurrencyCode": "Default", "PaymentInitiativeType": "1" }, { "AcquirerId": "555555-1000", "AcquirerMerchantId": "ZXY123XYZ456", "AcquirerPassword": "", "CurrencyCode": "Default", "PaymentInitiativeType": "2" }, { "AcquirerId": "666666-1000", "AcquirerMerchantId": "ABC123XYZ456", "AcquirerPassword": "", "CurrencyCode": "Default", "PaymentInitiativeType": "3" } ] } } |
Merchant Acquirer DeleteAll Response
{ "TransactionId": "73938297", "ErrorNumber": 0, "Payload": { "MerchantAcquirerConfigs": [ { "AcquirerId": "444555-1000", "ErrorNumber": 0, "Message": "Merchant Acquirer config deleted" }, { "AcquirerId": "555555-1000", "ErrorNumber": 0, "Message": "Merchant Acquirer config deleted" }, { "AcquirerId": "66666-1000", "ErrorNumber": 0, "Message": "Merchant Acquirer config deleted" } ] } } |
Get All
The Get All call allows you to retrieve details of the acquirer config loaded in our system.
Endpoint - /V2/MerchantAcquirerConfig/GetAll
Get All Merchant Acquirer Config Request
Get All Merchant Acquirer Config Response
Payer Authentication Config
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.
Payer Auth Config Examples
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 |
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 |
Update
This call updates an existing merchant with the specified fields and their respective CentinelPayerAuthenticationConfigs. It can be used to update existing CentinelPayerAuthenticationConfigs for an existing merchant.
Endpoint - /V1/PayerAuthConfig/Update
Update Payer Auth Config Request
Update Payer Auth Config Response
Get
Endpoint - /V1/PayerAuthConfig/Get
Get Payer Auth Config Request
Get Payer Auth Config Response
Acquirers
Get All
Endpoint - /V2/Acquirers/GetAll
Possible Payload Values:
All
VerifiedByVisa
AmexSafeKey
ELO
DinersClubInternationalProtectBuy
MasterCardSecureCode
JCBJSecure
Maestro
CB
Pass "All" as the Payload field to return all valid Acquirer Ids. It is recommended to pass "All" for the first call in order to get the list of valid PaymentInitiativeTypes as well, which can then be used in any subsequent calls.
Get All Request
Get All Response
API Key
API Keys are the merchant's credentials to connect to Cardinal Consumer Authentication, consisting of the following two values:
API Key
API ID
Create
Endpoint - V1/APIKey/Create
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. |
|
Create API Key Request
Create APIKey Response