A card contract represents a single card owned by a cardholder and is linked to a card profile which defines all allowed business rules (e.g., replacement, renewal) and card properties required to create a card (e.g., chip data).
Subsequent cards, created by automatic renewal or card replacement, are listed under the same card contract.
Each card contract is identified by a unique cardContract Reference, generated internally, and optionally by an external reference ”issuerCardContractExternalReference” provided by the issuer, which must be unique per issuer.
The below diagram illustrates the different use cases covered by this domain.
Retrieve card contract detail
The API allows the card contract details to be retrieved.
The main input fields are:
- The issuer ID
- The card contract for which the detail is requested: It can be provided by using the card contract reference or the issuer card contract external reference.
It is also possible to request some additional data by using the embedded fields.
In return, the interface provides the generic information (mainly master data) relevant to the card
API links
Below is an example where the request retrieves the card contract detail for:
- Card contract reference : 12342000000000374459
GET /api/v2/issuers/1234/card-contracts/12342000000000374459
Response data
"data":{
"issuerId":"1234",
"cardContractIdentifier":{
"cardContractReference":"12342000000000374459"
},
"cardTemplateReference":"T_1234_CARD_VISA_DEBIT_CLASSIC",
"cardTypeCode":"F",
"status":"ACTIVE",
"openingDate":"2022-12-05T13:13:43.165+00:00",
"activationDate":"2022-12-05T13:13:43.177+00:00",
"trustedAuthenticationReference":"123420221205141343905",
"newCardRenewalAllowed":true,
"issuerBranchCode":"NO_BRANCH",
"artwork":"DebitClassic",
"forcedEmbossingName":"KAISHNER",
"schemeDeclarationOptOut":false,
"principalSupplementaryCardIndicator":"SUPPLEMENTARY",
"productCategory":"DEBIT",
"productCategoryLabel":"IMMEDIATE_DEBIT_DEBIT",
"specificFields":{
"additionalProp1":"string",
"additionalProp3":"string",
"additionalProp2":"string"
},
"productIdentifier":{
"issuerProductExternalReference":"PDT_1234_VISA_DEBIT_CLASSIC",
"productReference":"PDT_1234_VISA_DEBIT_CLASSIC"
},
"cardHolderIdentifier":{
"customerReference":"CUS10000346489",
"issuerCustomerExternalReference":"HOME_ADDR_REF_PERSON-202212050001B"
},
"contractIdentifier":{
"contractReference":"4459f986-5242-4202-9ed5-f652573e9f63",
"issuerContractExternalReference":"CONTRACT-202212050001"
},
"cardProfileDescription":"P_1234_CARD_VISA_DEBIT_CLASSIC",
"cardProfileReference":"P_1234_CARD_VISA_DEBIT_CLASSIC"
}
}Retrieve cardholder for a card contract
The API allows the cardholder data linked to the card contract to be retrieved.
The main input fields are:
- The issuer ID
- The card contract for which the detail is requested: It can be provided by using the card contract reference or the issuer card contract external reference.
It is also possible to request some additional data by using the embedded fields.
In return, the interface provides the generic information of the customer.
API links
Below is an example where the request retrieves the cardholder for:
- Card contract reference : 12342000000000374459
GET /api/v2/issuers/1234/card-contracts/12342000000000374459/cardholder
Response data
"data":{
"issuerId":"1234",
"customerIdentifier":{
"customerReference":"CUS10000346489",
"issuerCustomerExternalReference":"HOME_ADDR_REF_PERSON-202212050001B"
},
"active":true,
"birthDate":"1979-02-20T00:00:00.000+00:00",
"birthPlace":"Lorch",
"commercialStatus":"Normal",
"courtesyTitle":"Frau",
"firstName":"Kristina",
"lastName":"KAISHNER",
"monthlySalary":"0",
"nationality":"DE",
"offlineRiskCategory":"Standard",
"onlineRiskCategory":"Standard",
"sex":"F"
}List cards for a card contract
The API allows all the cards of a card contract to be retrieved.
The main input fields are:
- The issuer ID
- The card contract for which the cards list is requested: It can be provided by using the card contract reference or the issuer card contract external reference.
In return, the interface provides the list of all the cards linked to the card contract. Each card is provided with additional information such as card status, expiry date, embossing line, blocking reason (if in blocked status).
API links
Below is an example where the request retrieves the cardholder for:
- Card contract reference : 12342000000000374459
GET /api/v2/issuers/1234/card-contracts/12342000000000374459/cardholder
Response data
{
"data":[
{
"issuerId":"1234",
"cardIdentifier":{
"cardReference":"2000000000374460"
},
"pan":"4546174862942386",
"maskedPan":"454617******2386",
"expiryDate":"1227",
"panSequenceNumber":"1",
"status":"BLOCKED",
"statusDate":"2022-12-05T16:16:19.514+00:00",
"embossingName":"KAISHNER",
"artwork":"DebitClassic",
"permanentlyBlocked":true,
"emergencyCard":false,
"emergencyCashAdvance":false,
"renewed":false,
"replaced":true,
"replacementReason":"LOST_STOLEN",
"blockingReason":"LOST",
"cardContractIdentifier":{
"cardContractReference":"12342000000000374459"
},
"isCardDigitalizationAllowed":false,
"panReference":"15001defb91548a045a2a67f1f5d944a0b7e",
"cardScheme":"VISA",
"virtual":false,
"techAndAppModelName":"M_1234_APPTEC_EMVT0VISA"
},
{
"issuerId":"1234",
"cardIdentifier":{
"cardReference":"2000000000374491",
"issuerCardExternalReference":"CARD-20221119"
},
"pan":"4546174672045636",
"maskedPan":"454617******5636",
"expiryDate":"1227",
"panSequenceNumber":"1",
"status":"ACTIVE",
"statusDate":"2022-12-05T16:27:57.533+00:00",
"embossingName":"KAISHNER",
"artwork":"DebitClassic",
"permanentlyBlocked":false,
"emergencyCard":false,
"emergencyCashAdvance":false,
"renewed":false,
"replaced":false,
"cardContractIdentifier":{
"cardContractReference":"12342000000000374459"
},
"isCardDigitalizationAllowed":false,
"panReference":"1500d015027a202e47b39d56e25aab9fcc1d",
"cardScheme":"VISA",
"virtual":false,
"techAndAppModelName":"M_1234_APPTEC_EMVT0VISA"
}
]
}Retrieve contract for a card contract
The API allows the contract detail of a card contract to be retrieved.
The main input fields requested by the API are:
- The issuer ID
- The card contract for which the contract information is requested: It can be provided by using the card contract reference or the issuer card contract external reference.
It is also possible to request some additional data, such as contract customers, accounts, legitimacy documents, by using the embedded fields.
In return, the interface provides the contract details.
API links
Below is an example where the request retrieves the cardholder for:
- Card contract reference : 12342000000000374459
Response data
{
"data":{
"issuerId":"1234",
"contractIdentifier":{
"contractReference":"4459f986-5242-4202-9ed5-f652573e9f63",
"issuerContractExternalReference":"CONTRACT-202212050001"
},
"issuerBranchCode":"NO_BRANCH",
"cardReleaseOrder":"AUTOMATIC",
"signatureDate":"2022-12-05T12:34:43.000+00:00",
"status":"SIGNED",
"statusDate":"2022-12-05T12:34:43.000+00:00",
"contractOwnerIdentifier":{
"customerReference":"CUS10000346472",
"issuerCustomerExternalReference":"PERSON-202212050001"
},
"productIdentifier":{
"issuerProductExternalReference":"PDT_1234_VISA_DEBIT_CLASSIC",
"productReference":"PDT_1234_VISA_DEBIT_CLASSIC"
},
"rootAccountIdentifier":{
"accountReference":"12346621070985963583",
"issuerAccountExternalReference":"ROOT_ACCOUNT-202212050001"
}
}
}Update card contract
The API allows a list of pre-defined parameters (attributes) of a card contract to be updated.
The main input fields are:
- The issuer ID
- The card contract for which updates are required: It can be provided by using the card contract reference or the issuer card contract external reference.
- Parameters to be updated
The card contract parameters can be retrieved using the Retrieve card Contract detail API.
The updated parameters should be consistent with the initial product configuration defined in the system (e.g., a change of model is accepted only if the provided model reference is allowed in the product definition).
A typical update for the card contract is the embossing name.
API links
Below is an example where the request updates the embossing name and the specific fields for:
- Card contract reference : 12342000000000374459
PATCH /api/v2/issuers/1234/card-contracts/12342000000000374459
Request data:
{
"forcedEmbossingName":"Kristina KAISHNER",
"specificFields":{
"additionalProp1":"A14587"
}
}Response data:
{
"responseMetadata":{
"correlationId":"74c91831-9f60-4f94-90eb-dffae27af2ed",
"statusMessage":"Executed successfully",
"statusCode":200,
"responseDateTime":"2022-12-19T11:20:02.972+0100",
"timeTakenMs":570
},
"data":{
"cardContractIdentifier":{
"cardContractReference":"12342000000000374459"
}
}
}Close card contract
The API allows a card contract to be closed.
The main input fields are:
- The issuer ID
- The card contract for which the closure is requested: It can be provided by using the card contract reference or the issuer card contract external reference.
- The parameters of the closure: reason, delay, date.
A card contract can be either closed immediately or in the future (either at the card expiry date or at another scheduled date).
When the card is terminated (when the closing date is reached):
- The card is immediately deactivated (next authorizations are declined).
- The card cannot be renewed or replaced anymore.
- Reimbursement of membership and account setup fees is possible if applicable
- The card account cannot be closed:
- before X days (e.g., to take into account the latest transactions)
- if there are ongoing disputes
- Once an account is closed, any incoming scheme transaction is automatically disputed.
API links
Cancel card contract closing
This API enables to cancel a card contract closing with a scheduled date in the future.
As a result, no closing date is planned anymore for the card contract.
API links
List card contracts
The API allows the list of card contracts to be retrieved which have the same card contract group reference.
The main input fields are:
- The issuer ID
- The group reference of the card contract for which the detail is requested
It is also possible to request some additional data by using the embedded fields.
In return, the interface provides the generic information (mainly master data) relevant to the card contract.
API links
Retrieve corporate contract for a card contract
The API allows the corporate contract detail of a card contract to be retrieved.
The main input fields requested by the API are:
- The issuer ID
- The card contract for which the corporate contract information is requested: It can be provided by using the card contract reference or the issuer card contract external reference.
It is also possible to request some additional data, such as list of corporate contract entities (limited to 100), list of all customers (limited to 100), list of all companies (limited to 100), list of corporate employee accounts (limited to 100), root account linked to this corporate contract, by using the embedded fields.
In return, the interface provides the corporate contract details.
API links