Create A Consumer Contract
The Create Consumer Contract API allows the creation of a new consumer contract and its first card, either with physical support (plastic) or not (virtual card). The issuer can provide a list of new customers or the references to existing customers in Worldline system.
As a result, the contract is created:
- with the status set to ‘Signed’
- with the account hierarchy (root and card account) and its status set to active
- with the card and its status set to created or active, depending on the card product configuration
- with the card order to produce the physical card, and the pin mailer order if required.
Pre-conditions:
- The correlation ID, if provided by the issuer, must be unique. In case of re-use of a correlation ID from an existing contract, the system will return the data from the existing contract (e.g., if the API call returns a "time-out“ response, the same correlation ID can be provided to retrieve contract data from WL system for further checks).
- An active consumer product exists with a physical or pure virtual card.
The API response returns the different identifiers related to the contracts, such as the contract itself, contract owner, account owner, add-on, card contract, card and cardholder. Each identifier is composed of the Worldline internal reference and, optionally, the external reference if provided by the issuer in the request.
The references are used to: retrieve/update/close contracts, list accounts for a contract, retrieve the contract owner for a contract, retrieve/update legitimacy documents, etc..
Additional information for credit card when creating the contract
- it is possible to provide a customized credit limit amount value (e.g. after credit scoring)
- it is possible to provide SEPA mandate data to send a direct debit note to the debtor’s bank to repay the cyclic due amount
- it is possible to provide an insurance package (in order to calculate insurance fees) and to activate it (insuranceEventCode)
Additional information for prepaid card when creating the contract
- the credit limit amount is equal to 0 and cannot be changed during contract lifetime
- it is possible to provide SEPA mandate data to send a direct debit note to the debtor’s bank in case offline transactions have to be repaid (note that our system can put on hold such offline transactions that lead the prepaid account to a debit position, waiting for payment by the customer)
API links
Below is an example where the data for customer creation is provided in the request:
POST /api/v2/issuers/1234/contracts/create-consumer-contract
Request data
"data":{
" ""customers":" "[
" "{
"/* Comment":"here is provided the customer required to create this contract. This customer is the contract owner (see above contractOwnerRequestCorrelationId"": "92"). Then it is also the account owner of the account “issuerAccountExternalReference":" ""ROOT_ACCOUNT-202212050001""and also the cardholder of the card by automatic inheritance. */
""addresses":" "[
" "{
"addressLabel":" ""MAIN_POSTAL_ADDRESS",
" ""addressType":" ""POSTAL_MAIL",
" ""issuerAddressExternalReference":" ""ADDRESS-202212050001",
" ""postalAddress":" "{
" ""line1":" ""Belziger 70",
" ""line2":" ""Test line2",
" ""townName":" ""BERLIN",
" ""country":" ""DE"" "
}" "
}" "
],
" ""birthDate":" ""1970-10-22T00:00Z",
" ""birthPlace":" ""London",
" ""courtesyTitle":" ""Mr",
" ""firstName":" ""John",
" ""issuerCustomerExternalReference":" ""PERSON-202212050001",
" ""lastName":" ""SMITH",
" ""commercialStatus":" ""Normal",
" ""onlineRiskCategory":" ""Standard",
" ""offlineRiskCategory":" ""Standard",
" ""requestCorrelationId":" ""92",
"/* is used in the rest of the message to assign this new customer as e.g. contract owner",
"account owner",
"cardholder) */
""sex":" ""M",
" ""nationality":" ""DE"" "
}"/* Another new customer can be provided if contract owner and account owner or cardholder are not the same */
"
]" ""contract":" "{
" ""accountHierarchy":" "{
" ""accounts":" "[
" "{
" ""accountTemplateReference":" ""T_1234_ACC_ROOT_VISA_DEBIT_CLASSIC",
" ""bic":" ""XXXDEBB",
" ""iban":" ""DE02500105174128973163",
" ""issuerAccountExternalReference":" ""ROOT_ACCOUNT-202212050001"" "
},
" "{
" ""accountTemplateReference":" ""T_1234_ACC_CHILD_VISA_DEBIT_CLASSIC",
" ""bic":" ""XXXDEBB",
" ""iban":" ""DE02500105174128973163",
" ""issuerAccountExternalReference":" ""CHILD_ACCOUNT-202212050001"" "
}" "
]" "
},
" ""cardContracts":" "[
" "{
" ""card":" "{
" ""cardOrder":" "{
" ""sendingMode":" ""Normal"" "
},
" ""issuerCardExternalReference":" ""CARD-202212050001"" "
},
" ""cardTemplateReference":" ""T_1234_CARD_VISA_DEBIT_CLASSIC",
" ""forcedEmbossingName":" ""SMITH JOHN",
" ""forcedEmbossingName2ndLine":" ""STEVEN",
" ""issuerCardContractExternalReference":" ""CARD_CONTRACT-202212050001"" "
}" "
],
" ""cardReleaseOrder":" ""AUTOMATIC",
" ""contractOwnerRequestCorrelationId":" ""92",
/* the new customer provided in the list of customers above and identiied by correlationId as “92” is assigned to contract owner role */
"issuerContractExternalReference":" ""CONTRACT-202212050001",
" ""issuerProductExternalReference":" ""PDT_1234_VISA_DEBIT_CLASSIC",
" ""issuerBranchCode":" ""NO_BRANCH"" "
}
}Response data
"data":{
" ""contract":" "{
" ""contractIdentifier":" "{
" ""contractReference":" ""4459f986-5242-4202-9ed5-f652573e9f63",
" ""issuerContractExternalReference":" ""CONTRACT-202212050001"" "
},
" ""status":" ""SIGNED",
" ""creationDate":" ""2022-12-05T12:34:43.770+00:00",
" ""signatureDate":" ""2022-12-05T12:34:43.758+00:00",
" ""issuerBranchCode":" ""NO_BRANCH",
" ""cardReleaseOrder":" ""AUTOMATIC",
" ""productIdentifier":" "{
" ""issuerProductExternalReference":" ""PDT_1234_VISA_DEBIT_CLASSIC",
" ""productReference":" ""PDT_1234_VISA_DEBIT_CLASSIC"" "
},
" ""contractOwnerIdentifier":" "{
" ""customerReference":" ""CUS10000346472",
" ""issuerCustomerExternalReference":" ""PERSON-202212050001"" "
},
" ""accounts":" "[
" "{
"accountIdentifier":" "{
" ""accountReference":" ""12348505533653587133",
" ""issuerAccountExternalReference":" ""CHILD_ACCOUNT-202212050001"" "
},
" ""root":" false",
" ""status":" ""ACTIVE",
" ""accountOwnerIdentifier":" "{
" ""customerReference":" ""CUS10000346472",
" ""issuerCustomerExternalReference":" ""PERSON-202212050001"" "
},
" ""accountGuarantorIdentifier":" "{
" ""customerReference":" ""CUS10000346472",
" ""issuerCustomerExternalReference":" ""PERSON-202212050001"" "
}" "
},
" "{
"accountIdentifier":" "{
" ""accountReference":" ""12346621070985963583",
" ""issuerAccountExternalReference":" ""ROOT_ACCOUNT-202212050001"" "
},
" ""root":" true",
" ""status":" ""ACTIVE",
" ""accountOwnerIdentifier":" "{
" ""customerReference":" ""CUS10000346472",
" ""issuerCustomerExternalReference":" ""PERSON-202212050001"" "
},
" ""accountGuarantorIdentifier":" "{
" ""customerReference":" ""CUS10000346472",
" ""issuerCustomerExternalReference":" ""PERSON-202212050001"" "
}" "
}" "
],
" ""cardContracts":" "[
" "{
" ""cardContractIdentifier":" "{
" ""cardContractReference":" ""12342000000000374437",
" ""issuerCardContractExternalReference":" ""CARD_CONTRACT-202212050001"" "
},
" ""cardHolderIdentifier":" "{
" ""customerReference":" ""CUS10000346472",
" ""issuerCustomerExternalReference":" ""PERSON-202212050001"" "
},
" ""status":" ""ACTIVE",
" ""principalSupplementaryCardIndicator":" ""PRINCIPAL",
" ""card":" "{
" ""cardIdentifier":" "{
" ""cardReference":" ""2000000000374438",
" ""issuerCardExternalReference":" ""CARD-202212050001"" "
},
" ""pan":" ""4546177060616413",
" ""maskedPan":" ""454617******6413",
" ""expiryDate":" ""1227",
" ""panSequenceNumber":" ""1",
" ""status":" ""ACTIVE",
" ""orders":" "[
" "{
" ""orderIdentifier":" "{
" ""orderReference":" ""202212052000000000374439"" "
},
" ""orderType":" ""CardOrder",
" ""currentInternalStatus":" ""ORDERABLE"" "
}" "
],
" ""panReference":" ""1500fc52cb34fa714bf3bd94c9421d38c79c"" "
},
" ""relatedAccounts":" "[
" "{
" ""relation":" ""DEFAULT",
" ""accountIdentifier":" "{
" ""accountReference":" ""12348505533653587133",
" ""issuerAccountExternalReference":" ""CHILD_ACCOUNT-202212050001"" "
}" "
}" "
]" "
}" "
]" "
},
" ""customers":" "[
" "{
" ""customerIdentifier":" "{
" ""customerReference":" ""CUS10000346472",
" ""issuerCustomerExternalReference":" ""PERSON-202212050001"" "
},
" ""courtesyTitle":" ""Mr",
" ""lastName":" ""SMITH",
" ""firstName":" ""John",
" ""addresses":" "[
" "{
" ""addressIdentifier":" "{
" ""addressReference":" ""ADDREF_MAIN_POSTAL_ADDRESS_1000000000385897",
" ""issuerAddressExternalReference":" ""ADDRESS-202212050001"" "
},
" ""addressLabel":" ""MAIN_POSTAL_ADDRESS",
" ""addressType":" ""POSTAL_MAIL"" "
}" "
]" "
}" "
]" "
}
}
}Search Contracts By IBAN
By providing an IBAN, this API can search and return all contracts for which at least one account in the account hierarchy matches the IBAN criteria.
The API input parameters allow:
- limiting the list of returned cards per card contract to either the latest card only or all previous cards
- enriching the response with additional data relative to the accounts, the card contracts, the cards and the customers by using embedded fields
The API response contains all matched contracts. For each returned contract the information provided includes:
- the contract identifier, and the external contract reference if originally provided
- product change information, such as current status, new product, new contract - if it exists
- embedded fields, if requested, such as the list of all customers or identifiers linked to this contract (e.g. contract owner, root account owner, cardholder(s)), card contracts, cards
Retrieve Contract
This API allows the retrieval of a particular contract from its reference or its issuer external reference.
The API response contains contract information, such as:
- contract identifier with the contract reference and the issuer external contract reference if previously provided
- product change information, such as its current status (scheduled, done, cancelled), new product, new contract - if it exists
- embedded fields, if requested, such as the list of all customers or identifiers linked to this contract (e.g., contract owner, root account owner, cardholder(s)), card contracts, cards
API links
GET /api/v2/issuers/{issuerId}/contracts/{contractReference}
GET /api/v2/issuers/{issuerId}/contracts/external-contracts/{issuerContractExternalReference}
Below an example of a request for:
- The contract: 4459f986-5242-4202-9ed5-f652573e9f63
- The issuer: 1234
GET /api/v2/issuers/1234/contracts/4459f986-5242-4202-9ed5-f652573e9f63
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"" "
}" "
}Below a second example of a request for:
- The contract: 1e9802ae-68db-467b-8610-ae59f0d37291
- The issuer: 1234
With requested embedded field: cardContracts
In the response, the 3 card contracts are provided.
GET /api/v2/issuers/1234/contracts/1e9802ae-68db-467b-8610-ae59f0d37291?embed=cardContracts
Response data
"data":{
" ""issuerId":" ""1234",
" ""contractIdentifier":" "{
" ""contractReference":" ""1e9802ae-68db-467b-8610-ae59f0d37291",
" ""issuerContractExternalReference":" ""CONTRACT-202212130001"" "
},
" ""issuerBranchCode":" ""NO_BRANCH",
" ""cardReleaseOrder":" ""AUTOMATIC",
" ""numberOfFreeCardsPrimaryCardImpacted":" false",
" ""signatureDate":" ""2022-12-13T14:40:21.000+00:00",
" ""status":" ""SIGNED",
" ""statusDate":" ""2022-12-13T14:40:21.000+00:00",
" ""cardContracts":" "[
" "{
" ""issuerId":" ""1234",
" ""cardContractIdentifier":" "{
" ""cardContractReference":" ""12342000000000380697"" "
},
" ""cardTemplateReference":" ""T_1234_CARD_VISA_DEBIT_CLASSIC",
" ""cardTypeCode":" ""F",
" ""status":" ""ACTIVE",
" ""openingDate":" ""2022-12-13T15:25:57.710+00:00",
" ""activationDate":" ""2022-12-13T15:25:57.730+00:00",
" ""trustedAuthenticationReference":" ""123420221213162557294",
" ""newCardRenewalAllowed":" true",
" ""issuerBranchCode":" ""NO_BRANCH",
" ""artwork":" ""DebitClassic",
" ""forcedEmbossingName":" ""BOUBOU",
" ""schemeDeclarationOptOut":" false",
" ""principalSupplementaryCardIndicator":" ""SUPPLEMENTARY",
" ""productCategory":" ""DEBIT",
" ""productCategoryLabel":" ""IMMEDIATE_DEBIT_DEBIT",
" ""productIdentifier":" "{
" ""issuerProductExternalReference":" ""PDT_1234_VISA_DEBIT_CLASSIC",
" ""productReference":" ""PDT_1234_VISA_DEBIT_CLASSIC"" "
},
" ""cardHolderIdentifier":" "{
" ""customerReference":" ""CUS10000351532",
" ""issuerCustomerExternalReference":" "" PERSON-202212130001B"" "
},
" ""vipFlag":" false",
" ""contractIdentifier":" "{
" ""contractReference":" ""1e9802ae-68db-467b-8610-ae59f0d37291",
" ""issuerContractExternalReference":" ""CONTRACT-202212130001"" "
},
" ""cardProfileDescription":" ""P_1234_CARD_VISA_DEBIT_CLASSIC",
" ""cardProfileReference":" ""P_1234_CARD_VISA_DEBIT_CLASSIC"" "
},
" "{
" ""issuerId":" ""1234",
" ""cardContractIdentifier":" "{
" ""cardContractReference":" ""12342000000000380694",
" ""issuerCardContractExternalReference":" ""CARD_CONTRACT-202212130001"" "
},
" ""cardTemplateReference":" ""T_1234_CARD_VISA_DEBIT_CLASSIC",
" ""cardTypeCode":" ""F",
" ""status":" ""ACTIVE",
" ""openingDate":" ""2022-12-13T14:40:21.527+00:00",
" ""activationDate":" ""2022-12-13T14:40:21.527+00:00",
" ""trustedAuthenticationReference":" ""123420221213154021607",
" ""newCardRenewalAllowed":" true",
" ""issuerBranchCode":" ""NO_BRANCH",
" ""artwork":" ""DebitClassic",
" ""forcedEmbossingName":" ""BOUBOU*TEST BOUBOU EMBOSS2",
" ""schemeDeclarationOptOut":" false",
" ""principalSupplementaryCardIndicator":" ""PRINCIPAL",
" ""productCategory":" ""DEBIT",
" ""productCategoryLabel":" ""IMMEDIATE_DEBIT_DEBIT",
" ""productIdentifier":" "{
" ""issuerProductExternalReference":" ""PDT_1234_VISA_DEBIT_CLASSIC",
" ""productReference":" ""PDT_1234_VISA_DEBIT_CLASSIC"" "
},
" ""cardHolderIdentifier":" "{
" ""customerReference":" ""CUS10000351531",
" ""issuerCustomerExternalReference":" ""PERSON-202212130001"" "
},
" ""vipFlag":" false",
" ""contractIdentifier":" "{
" ""contractReference":" ""1e9802ae-68db-467b-8610-ae59f0d37291",
" ""issuerContractExternalReference":" ""CONTRACT-202212130001"" "
},
" ""cardProfileDescription":" ""P_1234_CARD_VISA_DEBIT_CLASSIC",
" ""cardProfileReference":" ""P_1234_CARD_VISA_DEBIT_CLASSIC"" "
},
" "{
" ""issuerId":" ""1234",
" ""cardContractIdentifier":" "{
" ""cardContractReference":" ""12342000000000380700"" "
},
" ""cardTemplateReference":" ""T_1234_CARD_VISA_DEBIT_CLASSIC",
" ""cardTypeCode":" ""F",
" ""status":" ""ACTIVE",
" ""openingDate":" ""2022-12-13T16:54:15.002+00:00",
" ""activationDate":" ""2022-12-13T16:54:15.112+00:00",
" ""trustedAuthenticationReference":" ""123420221213175415246",
" ""newCardRenewalAllowed":" true",
" ""issuerBranchCode":" ""NO_BRANCH",
" ""artwork":" ""DebitClassic",
" ""forcedEmbossingName":" ""BOUBOU",
" ""schemeDeclarationOptOut":" false",
" ""principalSupplementaryCardIndicator":" ""SUPPLEMENTARY",
" ""productCategory":" ""DEBIT",
" ""productCategoryLabel":" ""IMMEDIATE_DEBIT_DEBIT",
" ""productIdentifier":" "{
" ""issuerProductExternalReference":" ""PDT_1234_VISA_DEBIT_CLASSIC",
" ""productReference":" ""PDT_1234_VISA_DEBIT_CLASSIC"" "
},
" ""cardHolderIdentifier":" "{
" ""customerReference":" ""CUS10000351533",
" ""issuerCustomerExternalReference":" ""PERSON-202212130001C"" "
},
" ""vipFlag":" false",
" ""contractIdentifier":" "{
" ""contractReference":" ""1e9802ae-68db-467b-8610-ae59f0d37291",
" ""issuerContractExternalReference":" ""CONTRACT-202212130001"" "
},
" ""cardProfileDescription":" ""P_1234_CARD_VISA_DEBIT_CLASSIC",
" ""cardProfileReference":" ""P_1234_CARD_VISA_DEBIT_CLASSIC"" "
}" "
],
" ""contractOwnerIdentifier":" "{
" ""customerReference":" ""CUS10000351531",
" ""issuerCustomerExternalReference":" ""PERSON-202212130001"" "
},
" ""productIdentifier":" "{
" ""issuerProductExternalReference":" ""PDT_1234_VISA_DEBIT_CLASSIC",
" ""productReference":" ""PDT_1234_VISA_DEBIT_CLASSIC"" "
},
" ""rootAccountIdentifier":" "{
" ""accountReference":" ""12343652199237560111",
" ""issuerAccountExternalReference":" ""ROOT_ACCOUNT-202212130001"" "
}" "
}
}Update Addresses Of All Contract Members
This API is used to update all members of a given contract with same provided address (including address usages).
E.g., for Contract A, contract owner, cardholders 1 and 2 are updated simultaneously with the same Main postal address data.
API links
POST /api/v2/issuers/1234/contracts/1e9802ae-68db-467b-8610-ae59f0d37291/update-all-customers-addresses
Request data
{
" ""addresses":" "[
" "{
" ""addressLabel":" ""MAIN_POSTAL_ADDRESS",
" ""addressType":" ""POSTAL_MAIL",
" ""postalAddress":" "{
" ""line1":" ""50 AVENUE LAMARTINE",
" ""line3":" ""string",
" ""line4":" ""string",
" ""line5":" ""string",
" ""buildingNumber":" ""50",
" ""streetName":" ""AVENUE LAMARTINE",
" ""postCode":" ""75010",
" ""townName":" ""PARIS",
" ""country":" ""FR"" "
},
" ""startDate":" ""2022-12-13T16:37:26.625Z"" "
}" "
]
}Response data
"data":" "{
{
" ""contractIdentifier":" "{
" ""contractReference":" ""1e9802ae-68db-467b-8610-ae59f0d37291",
" ""issuerContractExternalReference":" ""CONTRACT-202212130001"" "
},
" ""customers":" "[
" "{
" ""customerIdentifier":" "{
" ""customerReference":" ""CUS10000351531",
" ""issuerCustomerExternalReference":" ""PERSON-202212130001"" "
},
" ""addresses":" "[
" "{
" ""addressIdentifier":" "{
" ""addressReference":" ""ADDREF_MAIN_POSTAL_ADDRESS_1000000000392073"" "
},
" ""addressLabel":" ""MAIN_POSTAL_ADDRESS",
" ""addressType":" ""POSTAL_MAIL"" "
}" "
]" "
},
" "{
" ""customerIdentifier":" "{
" ""customerReference":" ""CUS10000351532",
" ""issuerCustomerExternalReference":" ""HOME_ADDR_REF_PERSON-202212130001B"" "
},
" ""addresses":" "[
" "{
" ""addressIdentifier":" "{
" ""addressReference":" ""ADDREF_MAIN_POSTAL_ADDRESS_1000000000392074"" "
},
" ""addressLabel":" ""MAIN_POSTAL_ADDRESS",
" ""addressType":" ""POSTAL_MAIL"" "
}" "
]" "
}" "
]" "
}
}Add Card To An Existing Contract
This API allows an issuer to add a new card (debit, credit, prepaid, either physical or virtual), a new account to an existing contract, together or independently, from a product extension among those allowed by the product used to instantiate the contract.
This product extension is usually composed of both card and account products, but can be composed of a card or several cards only, or of one or several accounts only or combination of both cards and accounts. It leads to create a new card and a new card account within the contract (multiple contents of product extensions can be configured depending on issuer's needs).
The new card account is in most of the cases attached to the root account of the hierarchy (default behaviour) but the issuer can provide its parent account if it is not the root (complex account hierarchy with more than 2 account levels).
The issuer shall provide required data for each account and card contract/card if required (depends on product extension configuration).
The issuer can provide:
- a list of new customers or the references to existing customers in Worldline system
- the legitimacy document(s) per customer
- different membership fee and account setup fee (contract fees) if needed per account
The issuer can choose to receive in response for the extended/updated contract new resources created only or all resources (e.g. already existing accounts, card contracts, cards).
The API response returns the extended contract with information related to account(s), card contract(s) and card(s) (limited to newly created account(s) and card contract(s)/card(s) if requested).
Add Cards and Accounts Request
API links
Below, an example of a request to add a card to:
- The existing contract: 1e9802ae-68db-467b-8610-ae59f0d37291
- Issuer: 1234
- for a new customer (Helen BOUBOU)
With the parameter “newResourcesOnly” set to true, only the created card and account are provided back.
POST /api/v2/issuers/1234/contracts/1e9802ae-68db-467b-8610-ae59f0d37291/add-cards-accounts?newResourcesOnly=true
Request data
{
" ""customers":" "[
" "{
" ""requestCorrelationId":" ""117",
" ""issuerCustomerExternalReference":" ""PERSON-202212130001C",
" ""active":" true",
" ""courtesyTitle":" ""Frau",
" ""lastName":" ""BOUBOU",
" ""firstName":" ""Helen",
" ""birthDate":" ""1989-12-20T00:00:00.000Z",
" ""birthPlace":" ""Lorch",
" ""sex":" ""F",
" ""nationality":" ""DE",
" ""onlineRiskCategory":"Standard",
" ""offlineRiskCategory":"Standard",
" ""commercialStatus":"Normal",
" ""addresses":" "[
" "{
" ""issuerAddressExternalReference":" ""HOME_ADDR_REF_PERSON-202212130001C",
" ""addressLabel":" ""MAIN_POSTAL_ADDRESS",
" ""addressType":" ""POSTAL_MAIL",
" ""postalAddress":" "{
" ""country":" ""DE",
" ""line1"" ":" ""HUBERTUSANLAGE 25"" "
}" "
}"
"
]" "
}" "
],
" ""issuerProductExtensionExternalReference":" ""PDT_1234_EXT_VISA_DEBIT_CLASSIC",
" ""accountHierarchy":" "{
" ""accounts":" "[
" "{
" ""accountTemplateReference":" ""T_1234_ACC_CHILD_VISA_DEBIT_CLASSIC",
" ""issuerAccountExternalReference":" ""CHILD_ACCOUNT-202212130001C",
" ""iban":" ""DE02500105174128973163",
" ""accountOwnerRequestCorrelationId":" ""117"" "
}" "
]" "
},
" ""cardContracts":" "[
" "{
" ""card":" "{
" ""cardOrder":" "{
" ""sendingMode":" ""Normal"" "
}" "
},
" ""cardTemplateReference":" ""T_1234_CARD_VISA_DEBIT_CLASSIC",
" ""principalSupplementaryCardIndicator":" ""SUPPLEMENTARY",
" ""forcedEmbossingName":" ""BOUBOU"" "
}" "
]
}Response data
{
" ""responseMetadata":" "{
" ""correlationId":" ""d4f2ceeb-7e1e-483d-af01-38e630a8e343",
" ""statusMessage":" ""Executed successfully",
" ""statusCode": 200,
" ""responseDateTime":" ""2022-12-13T17:54:15.838+0100",
" ""timeTakenMs": 1174
},
" ""data":" "{
" ""contract":" "{
" ""contractIdentifier":" "{
" ""contractReference":" ""1e9802ae-68db-467b-8610-ae59f0d37291",
" ""issuerContractExternalReference":" ""CONTRACT-202212130001"" "
},
" ""status":" ""SIGNED",
" ""creationDate":" ""2022-12-13T14:40:21.036+00:00",
" ""signatureDate":" ""2022-12-13T14:40:21.000+00:00",
" ""issuerBranchCode":" ""NO_BRANCH",
" ""cardReleaseOrder":" ""AUTOMATIC",
" ""productIdentifier":" "{
" ""issuerProductExternalReference":" ""PDT_1234_VISA_DEBIT_CLASSIC",
" ""productReference":" ""PDT_1234_VISA_DEBIT_CLASSIC"" "
},
" ""contractOwnerIdentifier":" "{
" ""customerReference":" ""CUS10000351531",
" ""issuerCustomerExternalReference":" ""PERSON-202212130001"" "
},
" ""accounts":" "[
" "{
" ""accountIdentifier":" "{
" ""accountReference":" ""12341542264159267791",
" ""issuerAccountExternalReference":" ""CHILD_ACCOUNT-202212130001C"" "
},
" ""root":" false",
" ""status":" ""ACTIVE",
" ""accountOwnerIdentifier":" "{
" ""customerReference":" ""CUS10000351533",
" ""issuerCustomerExternalReference":" ""PERSON-202212130001C"" "
},
" ""accountGuarantorIdentifier":" "{
" ""customerReference":" ""CUS10000351531",
" ""issuerCustomerExternalReference":" ""PERSON-202212130001"" "
}" "
}" "
],
" ""cardContracts":" "[
" "{
" ""cardContractIdentifier":" "{
" ""cardContractReference":" ""12342000000000380700"" "
},
" ""cardHolderIdentifier":" "{
" ""customerReference":" ""CUS10000351533",
" ""issuerCustomerExternalReference":" ""PERSON-202212130001C"" "
},
" ""status":" ""ACTIVE",
" ""principalSupplementaryCardIndicator":" ""SUPPLEMENTARY",
" ""card":" "{
" ""cardIdentifier":" "{
" ""cardReference":" ""2000000000380701"" "
},
" ""pan":" ""4546176812235324",
" ""maskedPan":" ""454617******5324",
" ""expiryDate":" ""1227",
" ""panSequenceNumber":" ""1",
" ""status":" ""ACTIVE",
" ""orders":" "[
" "{
" ""orderIdentifier":" "{
" ""orderReference":" ""202212132000000000380702"" "
},
" ""orderType":" ""CardOrder",
" ""currentInternalStatus":" ""ORDERABLE"" "
}" "
],
" ""panReference":" ""15007c193f2d588f4b8b991ab24537ebe001"" "
},
" ""relatedAccounts":" "[
" "{
" ""relation":" ""DEFAULT",
" ""accountIdentifier":" "{
" ""accountReference":" ""12341542264159267791",
" ""issuerAccountExternalReference":" ""CHILD_ACCOUNT-202212130001C"" "
}" "
}" "
]" "
}" "
]" "
},
" ""customers":" "[
" "{
" ""customerIdentifier":" "{
" ""customerReference":" ""CUS10000351533",
" ""issuerCustomerExternalReference":" ""PERSON-202212130001C"" "
},
" ""courtesyTitle":" ""Frau",
" ""lastName":" ""BOUBOU",
" ""firstName":" ""Helen",
" ""addresses":" "[
" "{
" ""addressIdentifier":" "{
" ""addressReference":" ""ADDREF_MAIN_POSTAL_ADDRESS_1000000000392075",
" ""issuerAddressExternalReference":" ""HOME_ADDR_REF_PERSON-202212130001C"" "
},
" ""addressLabel":" ""MAIN_POSTAL_ADDRESS",
" ""addressType":" ""POSTAL_MAIL"" "
}" "
]" "
}" "
]" "
}
}Update Contract
The API allows to update certain data of an existing consumer contract, identified by the Issuer Contract external reference or the Contract reference.
- allowed advertisement channels (flags)
- allowed data analysis
- the issuer branch code (e.g. bank agency in charge of this contract)
- allowed delivery channel for possible letters
- if the membership fee should be reimbursed when a card contract is closed
- how many cards should free of membership fee and/or account setup fee
- if the primary card should be considered as the first to be free for membership/account setup fees or if only additional cards should be considered
- if both membership and account setup fees should be waived during contract lifecycle (can be changed at any moment)
- the membership fee anniversary date can be changed
- pass-through data can be updated (specificFields)
- content
As a result, the contract is immediately updated with provided data in our system.
Add Cards and Accounts Request
API links
Below an example of request where the advertisement flags, the delivery channels for correspondence and the branch code are updated for the:
- contract reference: 1e9802ae-68db-467b-8610-ae59f0d37291
- Issuer: 1234
PATCH /api/v2/issuers/1234/contracts/1e9802ae-68db-467b-8610-ae59f0d37291
Request data
{
" ""advertisementFlags":" "{
" ""general":" true",
" ""email":" false",
" ""letter":" false",
" ""phone":" false",
" ""statement":" true",
" ""sms":" false
"
},
" ""issuerBranchCode":" ""NO_BRANCH",
" ""dataAnalysisFlags":" "{
" ""person":" false",
" ""paymentTransaction":" false",
" ""exchangeThirdParties":" false
"
},
" ""deliveryChannel":" "{
" ""contractLetterType":" ""LETTER",
" ""disputeLetterType":" ""LETTER",
" ""statementType":" ""WEB"" "
}
}Response data
{
" ""responseMetadata":" "{
" ""correlationId":" ""25eb44b4-7ff7-41fe-a253-0c2b7519f380",
" ""statusMessage":" ""Executed successfully",
" ""statusCode": 200,
" ""responseDateTime":" ""2022-12-14T18:11:53.053+0100",
" ""timeTakenMs": 229
},
" ""data":" "{
" ""contractIdentifier":" "{
" ""contractReference":" ""1e9802ae-68db-467b-8610-ae59f0d37291",
" ""issuerContractExternalReference":" ""CONTRACT-202212130001"" "
}" "
}
}List Accounts For A Contract
The API allows the list of accounts for a contract, identified by the Issuer Contract external reference or the Contract reference, to be retrieved.
API links
Below an example of request for:
- The contract reference: 1e9802ae-68db-467b-8610-ae59f0d37291
- The issuer: 1234
The response includes 4 accounts: 1 root account and 3 card accounts.
GET /api/v2/issuers/1234/contracts/1e9802ae-68db-467b-8610-ae59f0d37291/accounts
Response data
{
" ""data":" "[
" "{
" ""issuerId":" ""1234",
" ""accountIdentifier":" "{
" ""accountReference":" ""12341542264159267791",
" ""issuerAccountExternalReference":" ""CHILD_ACCOUNT-202212130001C"" "
},
" ""root":" false",
" ""accountBalance":" "{
" ""value": 0,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""status":" ""ACTIVE",
" ""statusDate":" ""2022-12-13T16:54:14.000+00:00",
" ""exclusiveCurrency":" false",
" ""activationDate":" ""2022-12-13T16:54:14.000+00:00",
" ""iban":" ""DE02500105174128973163",
" ""name":" ""T_1234_ACC_CHILD_VISA_DEBIT_CLASSIC",
" ""workingCurrencyCode":" ""EUR",
" ""originalWorkingMode":" ""PAY_NOW",
" ""workingMode":" ""PAY_NOW",
" ""subscriptionSwitch":" false",
" ""toBeSwitched":" false",
" ""accountHierarchyReference":" ""12343652199237560111",
" ""noGraceOnTheFirstCycle":" false",
" ""productIdentifier":" "{
" ""issuerProductExternalReference":" ""PDT_1234_VISA_DEBIT_CLASSIC",
" ""productReference":" ""PDT_1234_VISA_DEBIT_CLASSIC"" "
},
" ""accountProfileReference":" ""P_1234_ACC_CHILD",
" ""closureCalendar":" ""C_1234_CLOSURE_DEFAULT",
" ""overlimitContribution":" ""0.0",
" ""spareChangeSaving":" false",
" ""rootAccountIdentifier":" "{
" ""accountReference":" ""12343652199237560111",
" ""issuerAccountExternalReference":" ""ROOT_ACCOUNT-202212130001"" "
},
" ""parentAccountIdentifier":" "{
" ""accountReference":" ""12343652199237560111",
" ""issuerAccountExternalReference":" ""ROOT_ACCOUNT-202212130001"" "
},
" ""payingAccountIdentifier":" "{
" ""accountReference":" ""12341542264159267791",
" ""issuerAccountExternalReference":" ""CHILD_ACCOUNT-202212130001C"" "
},
" ""accountOwnerIdentifier":" "{
" ""customerReference":" ""CUS10000351533",
" ""issuerCustomerExternalReference":" ""PERSON-202212130001C"" "
},
" ""accountGuarantorIdentifier":" "{
" ""customerReference":" ""CUS10000351533",
" ""issuerCustomerExternalReference":" ""PERSON-202212130001C"" "
},
" ""contractIdentifier":" "{
" ""contractReference":" ""1e9802ae-68db-467b-8610-ae59f0d37291",
" ""issuerContractExternalReference":" ""CONTRACT-202212130001"" "
},
" ""delinquent":" false",
" ""noOtbCheck":" false",
" ""noParentNotification":" false",
" ""contractType":" ""CONSUMER",
" ""hierarchyOutgoingCreditTransferFeature":" "{
" ""periodicOct":" false",
" ""octOnContractTerminationAllowed":" false",
" ""octOnAccountTerminationAllowed":" false",
" ""octOnDemandAllowed":" false
"
}" "
},
" "{
" ""issuerId":" ""1234",
" ""accountIdentifier":" "{
" ""accountReference":" ""12343652199237560111",
" ""issuerAccountExternalReference":" ""ROOT_ACCOUNT-202212130001"" "
},
" ""root":" true",
" ""accountBalance":" "{
" ""value": 0,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""bic":" ""INGDEBB",
" ""status":" ""ACTIVE",
" ""statusDate":" ""2022-12-13T14:40:21.000+00:00",
" ""exclusiveCurrency":" false",
" ""activationDate":" ""2022-12-13T14:40:21.000+00:00",
" ""iban":" ""DE02500105174128973163",
" ""name":" ""T_1234_ACC_ROOT_VISA_DEBIT_CLASSIC",
" ""workingCurrencyCode":" ""EUR",
" ""originalWorkingMode":" ""PAY_NOW",
" ""workingMode":" ""PAY_NOW",
" ""subscriptionSwitch":" false",
" ""toBeSwitched":" false",
" ""accountHierarchyReference":" ""12343652199237560111",
" ""originalPaymentMode":" ""CARDHOLDER_DETERMINED",
" ""noGraceOnTheFirstCycle":" false",
" ""amountDueCalculationLevel":" ""COMPONENT_LEVEL",
" ""productIdentifier":" "{
" ""issuerProductExternalReference":" ""PDT_1234_VISA_DEBIT_CLASSIC",
" ""productReference":" ""PDT_1234_VISA_DEBIT_CLASSIC"" "
},
" ""accountProfileReference":" ""P_1234_ACC_ROOT",
" ""accountTemplateReference":" ""T_1234_ACC_ROOT_VISA_DEBIT_CLASSIC",
" ""closureCalendar":" ""C_1234_CLOSURE_DEFAULT",
" ""overlimitContribution":" ""0.0",
" ""spareChangeSaving":" false",
" ""rootAccountIdentifier":" "{
" ""accountReference":" ""12343652199237560111",
" ""issuerAccountExternalReference":" ""ROOT_ACCOUNT-202212130001"" "
},
" ""payingAccountIdentifier":" "{
" ""accountReference":" ""12343652199237560111",
" ""issuerAccountExternalReference":" ""ROOT_ACCOUNT-202212130001"" "
},
" ""accountOwnerIdentifier":" "{
" ""customerReference":" ""CUS10000351533",
" ""issuerCustomerExternalReference":" ""PERSON-202212130001C"" "
},
" ""accountGuarantorIdentifier":" "{
" ""customerReference":" ""CUS10000351533",
" ""issuerCustomerExternalReference":" ""PERSON-202212130001C"" "
},
" ""contractIdentifier":" "{
" ""contractReference":" ""1e9802ae-68db-467b-8610-ae59f0d37291",
" ""issuerContractExternalReference":" ""CONTRACT-202212130001"" "
},
" ""delinquent":" false",
" ""noOtbCheck":" false",
" ""noParentNotification":" false",
" ""contractType":" ""CONSUMER",
" ""hierarchyOutgoingCreditTransferFeature":" "{
" ""periodicOct":" false",
" ""octOnContractTerminationAllowed":" false",
" ""octOnAccountTerminationAllowed":" false",
" ""octOnDemandAllowed":" false
"
}" "
},
" "{
" ""issuerId":" ""1234",
" ""accountIdentifier":" "{
" ""accountReference":" ""12344689712869894759",
" ""issuerAccountExternalReference":" ""CHILD_ACCOUNT-202212130001B"" "
},
" ""root":" false",
" ""accountBalance":" "{
" ""value": 0,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""status":" ""ACTIVE",
" ""statusDate":" ""2022-12-13T15:25:57.000+00:00",
" ""exclusiveCurrency":" false",
" ""activationDate":" ""2022-12-13T15:25:57.000+00:00",
" ""iban":" ""DE02500105174128973163",
" ""name":" ""T_1234_ACC_CHILD_VISA_DEBIT_CLASSIC",
" ""workingCurrencyCode":" ""EUR",
" ""originalWorkingMode":" ""PAY_NOW",
" ""workingMode":" ""PAY_NOW",
" ""subscriptionSwitch":" false",
" ""toBeSwitched":" false",
" ""accountHierarchyReference":" ""12343652199237560111",
" ""noGraceOnTheFirstCycle":" false",
" ""productIdentifier":" "{
" ""issuerProductExternalReference":" ""PDT_1234_VISA_DEBIT_CLASSIC",
" ""productReference":" ""PDT_1234_VISA_DEBIT_CLASSIC"" "
},
" ""accountProfileReference":" ""P_1234_ACC_CHILD",
" ""closureCalendar":" ""C_1234_CLOSURE_DEFAULT",
" ""overlimitContribution":" ""0.0",
" ""spareChangeSaving":" false",
" ""rootAccountIdentifier":" "{
" ""accountReference":" ""12343652199237560111",
" ""issuerAccountExternalReference":" ""ROOT_ACCOUNT-202212130001"" "
},
" ""parentAccountIdentifier":" "{
" ""accountReference":" ""12343652199237560111",
" ""issuerAccountExternalReference":" ""ROOT_ACCOUNT-202212130001"" "
},
" ""payingAccountIdentifier":" "{
" ""accountReference":" ""12344689712869894759",
" ""issuerAccountExternalReference":" ""CHILD_ACCOUNT-202212130001B"" "
},
" ""accountOwnerIdentifier":" "{
" ""customerReference":" ""CUS10000351532",
" ""issuerCustomerExternalReference":" ""HOME_ADDR_REF_PERSON-202212130001B"" "
},
" ""accountGuarantorIdentifier":" "{
" ""customerReference":" ""CUS10000351533",
" ""issuerCustomerExternalReference":" ""PERSON-202212130001C"" "
},
" ""contractIdentifier":" "{
" ""contractReference":" ""1e9802ae-68db-467b-8610-ae59f0d37291",
" ""issuerContractExternalReference":" ""CONTRACT-202212130001"" "
},
" ""delinquent":" false",
" ""noOtbCheck":" false",
" ""noParentNotification":" false",
" ""contractType":" ""CONSUMER",
" ""hierarchyOutgoingCreditTransferFeature":" "{
" ""periodicOct":" false",
" ""octOnContractTerminationAllowed":" false",
" ""octOnAccountTerminationAllowed":" false",
" ""octOnDemandAllowed":" false
"
}" "
},
" "{
" ""issuerId":" ""1234",
" ""accountIdentifier":" "{
" ""accountReference":" ""12343686269046574979",
" ""issuerAccountExternalReference":" ""CHILD_ACCOUNT-202212130001"" "
},
" ""root":" false",
" ""accountBalance":" "{
" ""value": 0,
" ""exponent": 2,
" ""isoCode":" ""EUR"" "
},
" ""bic":" ""INGDEBB",
" ""status":" ""ACTIVE",
" ""statusDate":" ""2022-12-13T14:40:21.000+00:00",
" ""exclusiveCurrency":" false",
" ""activationDate":" ""2022-12-13T14:40:21.000+00:00",
" ""iban":" ""DE02500105174128973163",
" ""name":" ""T_1234_ACC_CHILD_VISA_DEBIT_CLASSIC",
" ""workingCurrencyCode":" ""EUR",
" ""originalWorkingMode":" ""PAY_NOW",
" ""workingMode":" ""PAY_NOW",
" ""subscriptionSwitch":" false",
" ""toBeSwitched":" false",
" ""accountHierarchyReference":" ""12343652199237560111",
" ""originalPaymentMode":" ""CARDHOLDER_DETERMINED",
" ""noGraceOnTheFirstCycle":" false",
" ""amountDueCalculationLevel":" ""COMPONENT_LEVEL",
" ""productIdentifier":" "{
" ""issuerProductExternalReference":" ""PDT_1234_VISA_DEBIT_CLASSIC",
" ""productReference":" ""PDT_1234_VISA_DEBIT_CLASSIC"" "
},
" ""accountProfileReference":" ""P_1234_ACC_CHILD",
" ""accountTemplateReference":" ""T_1234_ACC_CHILD_VISA_DEBIT_CLASSIC",
" ""closureCalendar":" ""C_1234_CLOSURE_DEFAULT",
" ""overlimitContribution":" ""0.0",
" ""spareChangeSaving":" false",
" ""rootAccountIdentifier":" "{
" ""accountReference":" ""12343652199237560111",
" ""issuerAccountExternalReference":" ""ROOT_ACCOUNT-202212130001"" "
},
" ""parentAccountIdentifier":" "{
" ""accountReference":" ""12343652199237560111",
" ""issuerAccountExternalReference":" ""ROOT_ACCOUNT-202212130001"" "
},
" ""payingAccountIdentifier":" "{
" ""accountReference":" ""12343686269046574979",
" ""issuerAccountExternalReference":" ""CHILD_ACCOUNT-202212130001"" "
},
" ""accountOwnerIdentifier":" "{
" ""customerReference":" ""CUS10000351531",
" ""issuerCustomerExternalReference":" ""PERSON-202212130001"" "
},
" ""accountGuarantorIdentifier":" "{
" ""customerReference":" ""CUS10000351533",
" ""issuerCustomerExternalReference":" ""PERSON-202212130001C"" "
},
" ""contractIdentifier":" "{
" ""contractReference":" ""1e9802ae-68db-467b-8610-ae59f0d37291",
" ""issuerContractExternalReference":" ""CONTRACT-202212130001"" "
},
" ""delinquent":" false",
" ""noOtbCheck":" false",
" ""noParentNotification":" false",
" ""contractType":" ""CONSUMER",
" ""hierarchyOutgoingCreditTransferFeature":" "{
" ""periodicOct":" false",
" ""octOnContractTerminationAllowed":" false",
" ""octOnAccountTerminationAllowed":" false",
" ""octOnDemandAllowed":" false
"
}" "
}" "
]
}List Card Contracts For A Contract
List Card Contracts For A Contract
API links
Below an example of request for:
- The contract reference: 1e9802ae-68db-467b-8610-ae59f0d37291
- The issuer: 1234
The response gives 3 card contracts.
GET /api/v2/issuers/1234/contracts/1e9802ae-68db-467b-8610-ae59f0d37291/card-contracts
Response data
{
"data":" "[
" "{
" ""issuerId":" ""1234",
" ""cardContractIdentifier":" "{
" ""cardContractReference":" ""12342000000000380697"" "
},
" ""cardTemplateReference":" ""T_1234_CARD_VISA_DEBIT_CLASSIC",
" ""cardTypeCode":" ""F",
" ""status":" ""ACTIVE",
" ""openingDate":" ""2022-12-13T15:25:57.710+00:00",
" ""activationDate":" ""2022-12-13T15:25:57.730+00:00",
" ""trustedAuthenticationReference":" ""123420221213162557294",
" ""newCardRenewalAllowed":" true",
" ""issuerBranchCode":" ""NO_BRANCH",
" ""artwork":" ""DebitClassic",
" ""forcedEmbossingName":" ""BOUBOU",
" ""schemeDeclarationOptOut":" false",
" ""principalSupplementaryCardIndicator":" ""SUPPLEMENTARY",
" ""productCategory":" ""DEBIT",
" ""productCategoryLabel":" ""IMMEDIATE_DEBIT_DEBIT",
" ""productIdentifier":" "{
" ""issuerProductExternalReference":" ""PDT_1234_VISA_DEBIT_CLASSIC",
" ""productReference":" ""PDT_1234_VISA_DEBIT_CLASSIC"" "
},
" ""cardHolderIdentifier":" "{
" ""customerReference":" ""CUS10000351532",
" ""issuerCustomerExternalReference":" ""HOME_ADDR_REF_PERSON-202212130001B"" "
},
" ""vipFlag":" false",
" ""contractIdentifier":" "{
" ""contractReference":" ""1e9802ae-68db-467b-8610-ae59f0d37291",
" ""issuerContractExternalReference":" ""CONTRACT-202212130001"" "
},
" ""cardProfileDescription":" ""P_1234_CARD_VISA_DEBIT_CLASSIC",
" ""cardProfileReference":" ""P_1234_CARD_VISA_DEBIT_CLASSIC"" "
},
" "{
" ""issuerId":" ""1234",
" ""cardContractIdentifier":" "{
" ""cardContractReference":" ""12342000000000380694",
" ""issuerCardContractExternalReference":" ""CARD_CONTRACT-202212130001"" "
},
" ""cardTemplateReference":" ""T_1234_CARD_VISA_DEBIT_CLASSIC",
" ""cardTypeCode":" ""F",
" ""status":" ""ACTIVE",
" ""openingDate":" ""2022-12-13T14:40:21.527+00:00",
" ""activationDate":" ""2022-12-13T14:40:21.527+00:00",
" ""trustedAuthenticationReference":" ""123420221213154021607",
" ""newCardRenewalAllowed":" true",
" ""issuerBranchCode":" ""NO_BRANCH",
" ""artwork":" ""DebitClassic",
" ""forcedEmbossingName":" ""BOUBOU*TEST BOUBOU EMBOSS2",
" ""schemeDeclarationOptOut":" false",
" ""principalSupplementaryCardIndicator":" ""SUPPLEMENTARY",
" ""productCategory":" ""DEBIT",
" ""productCategoryLabel":" ""IMMEDIATE_DEBIT_DEBIT",
" ""productIdentifier":" "{
" ""issuerProductExternalReference":" ""PDT_1234_VISA_DEBIT_CLASSIC",
" ""productReference":" ""PDT_1234_VISA_DEBIT_CLASSIC"" "
},
" ""cardHolderIdentifier":" "{
" ""customerReference":" ""CUS10000351531",
" ""issuerCustomerExternalReference":" ""PERSON-202212130001"" "
},
" ""contractIdentifier":" "{
" ""contractReference":" ""1e9802ae-68db-467b-8610-ae59f0d37291",
" ""issuerContractExternalReference":" ""CONTRACT-202212130001"" "
},
" ""cardProfileDescription":" ""P_1234_CARD_VISA_DEBIT_CLASSIC",
" ""cardProfileReference":" ""P_1234_CARD_VISA_DEBIT_CLASSIC"" "
},
" "{
" ""issuerId":" ""1234",
" ""cardContractIdentifier":" "{
" ""cardContractReference":" ""12342000000000380700"" "
},
" ""cardTemplateReference":" ""T_1234_CARD_VISA_DEBIT_CLASSIC",
" ""cardTypeCode":" ""F",
" ""status":" ""ACTIVE",
" ""openingDate":" ""2022-12-13T16:54:15.002+00:00",
" ""activationDate":" ""2022-12-13T16:54:15.112+00:00",
" ""trustedAuthenticationReference":" ""123420221213175415246",
" ""newCardRenewalAllowed":" true",
" ""issuerBranchCode":" ""NO_BRANCH",
" ""artwork":" ""DebitClassic",
" ""forcedEmbossingName":" ""BOUBOU",
" ""schemeDeclarationOptOut":" false",
" ""principalSupplementaryCardIndicator":" ""PRINCIPAL",
" ""productCategory":" ""DEBIT",
" ""productCategoryLabel":" ""IMMEDIATE_DEBIT_DEBIT",
" ""productIdentifier":" "{
" ""issuerProductExternalReference":" ""PDT_1234_VISA_DEBIT_CLASSIC",
" ""productReference":" ""PDT_1234_VISA_DEBIT_CLASSIC"" "
},
" ""cardHolderIdentifier":" "{
" ""customerReference":" ""CUS10000351533",
" ""issuerCustomerExternalReference":" ""PERSON-202212130001C"" "
},
" ""contractIdentifier":" "{
" ""contractReference":" ""1e9802ae-68db-467b-8610-ae59f0d37291",
" ""issuerContractExternalReference":" ""CONTRACT-202212130001"" "
},
" ""cardProfileDescription":" ""P_1234_CARD_VISA_DEBIT_CLASSIC",
" ""cardProfileReference":" ""P_1234_CARD_VISA_DEBIT_CLASSIC"" "
}" "
]
}Suspend A Contract
The API allows a contract, identified by the Issuer Contract external reference or the Contract reference, to be suspended.
It is possible to indicate whether membership/account setup fees must be partially reimbursed with the contract suspension.
The contract suspension has the following effects:
- the contract closure is scheduled according to a delay configurable at issuer level
- Immediate temporary card blocking
- Renewal and replacement of all cards blocking
- Account Setup Fee and Membership Fee are suppressed.
- An Outgoing Credit Transfer (OCT) is automatically generated if the account has a credit balance.
API links
Cancel A Contract Suspension
As long as the closure date is not reached, contract suspension can be removed.
The contract suspension cancellation has the following effects:
- The scheduled contract closure date is removed
- Renewal is unblocked
- Replacement is unblocked
- Cards linked to the contract are unblocked
The API allows a contract suspension process to be cancelled.
The contract is identified by the Issuer Contract external reference or the Contract reference.
API links
Close Contract
The API allows a contract, identified by the Issuer Contract external reference or the Contract reference, to be closed.
The contract can be closed immediately, scheduled to be closed at a date provided by the issuer or set to be closed at the card expiry date.
As a result:
- For immediate closure: the contract is closed, the cards within the contract are deactivated (next authorizations are declined), the closure is triggered for the accounts.
- For scheduled closure: the contract is not changed until the closing date is reached. Once the closing date is reached, the contract is closed, the cards within the contract are deactivated, the closure is triggered for the accounts.
API links
POST /api/V2/issuers/{issuerId}/contracts/{contractReference}/close
POST /api/V2/issuers/{issuerId}/contracts/external-contracts/{issuerContractExternalReference}/close
Below an example of request with a scheduled closure date:
- contract reference: 4459f986-5242-4202-9ed5-f652573e9f63
- issuer: 1234
POST api/v2/issuers/1234/contracts/4459f986-5242-4202-9ed5-f652573e9f63/close
Request data
{
" ""closingComment":" ""closingContract",
" ""closingDate":" ""2023-04-30T02:31:44.650Z",
" ""closingReason":" ""EXPIRED",
" ""closureDelayType":" ""SCHEDULED"
}Response data
{
" ""responseMetadata":" "{
" ""correlationId":" ""65aa7f43-b3d2-4160-927e-95801efad125",
" ""statusMessage":" ""Executed successfully",
" ""statusCode": 200,
" ""responseDateTime":" ""2023-02-02T15:52:38.281+0100",
" ""timeTakenMs": 450
},
" ""data":" "{
" ""contract":" "{
" ""contractIdentifier":" "{
" ""contractReference":" ""4459f986-5242-4202-9ed5-f652573e9f63",
" ""issuerContractExternalReference":" ""CONTRACT-202212050001"" "
},
" ""status":" ""SIGNED",
" ""closingDate":" ""2023-04-30T02:31:44.650+00:00",
" ""accounts":" "[
" "{
" ""accountIdentifier":" "{
" ""accountReference":" ""65008505533653587133",
" ""issuerAccountExternalReference":" ""CHILD_ACCOUNT-202212050001"" "
},
" ""root":" false",
" ""status":" ""ACTIVE"" "
},
" "{
" ""accountIdentifier":" "{
" ""accountReference":" ""65006621070985963583",
" ""issuerAccountExternalReference":" ""ROOT_ACCOUNT-202212050001"" "
},
" ""root":" true",
" ""status":" ""ACTIVE"" "
},
" "{
" ""accountIdentifier":" "{
" ""accountReference":" ""65009389899134164294",
" ""issuerAccountExternalReference":" ""CHILD_ACCOUNT-202212050001B"" "
},
" ""root":" false",
" ""status":" ""ACTIVE"" "
}" "
],
" ""cardContracts":" "[
" "{
" ""cardContractIdentifier":" "{
" ""cardContractReference":" ""65002000000000374459"" "
},
" ""status":" ""ACTIVE",
" ""cards":" "[
" "{
" ""cardIdentifier":" "{
" ""cardReference":" ""2000000000374460"" "
},
" ""maskedPan":" ""454617******2386",
" ""expiryDate":" ""1227",
" ""panSequenceNumber":" ""1",
" ""status":" ""BLOCKED"" "
}" "
]" "
},
" "{
" ""cardContractIdentifier":" "{
" ""cardContractReference":" ""65002000000000374437"" "
},
" ""status":" ""ACTIVE",
" ""cards":" "[
" "{
" ""cardIdentifier":" "{
" ""cardReference":" ""2000000000374438",
" ""issuerCardExternalReference":" ""CARD-202212050001"" "
},
" ""maskedPan":" ""454617******6413",
" ""expiryDate":" ""1227",
" ""panSequenceNumber":" ""1",
" ""status":" ""ACTIVE"" "
}" "
]" "
}" "
]" "
}" "
}
}Cancel A Contract Closing
This API enables to cancel a contract closing with a scheduled date in the future.
The contract identifier is provided in input.
As a result, no closing date is planned anymore for the contract.
API links
Below an example of request with a scheduled closure date:
- contract reference: 4459f986-5242-4202-9ed5-f652573e9f63
- issuer: 1234
POST /api/v2/issuers/1234/contracts/4459f986-5242-4202-9ed5-f652573e9f63/cancel-close
Response data
{
" ""responseMetadata":" "{
" ""correlationId":" ""3e657247-7ff1-4a1c-b590-6180fb10f353",
" ""statusMessage":" ""Executed successfully",
" ""statusCode": 200,
" ""responseDateTime":" ""2023-02-02T16:35:32.795+0100",
" ""timeTakenMs": 81
},
" ""data":" "{
" ""contractIdentifier":" "{
" ""contractReference":" ""4459f986-5242-4202-9ed5-f652573e9f63",
" ""issuerContractExternalReference":" ""CONTRACT-202212050001"" "
}" "
}
}List Contract Fees For A Contract
The API allows the list of contract fees linked to a contract, identified by the Issuer Contract external reference or the Contract reference, to be retrieved.
In response, the model references are provided for each account part of the contract.
API links
Here, an example of request for:
- The contract reference: 1f798c05-f18b-4e6d-9ce3-017d6de43b92
- The issuer: 1234
The response gives membership fee model applied to the card account “12349288360035054578”.
GET /api/v2/issuers/1234/contracts/1f798c05-f18b-4e6d-9ce3-017d6de43b92/contract-fees
Response data
{
" ""data":" "[
" "{
" ""accountIdentifier":" "{
" ""accountReference":" ""12344084403017969976",
" ""issuerAccountExternalReference":" ""ROOT_ACCOUNT-202212160001"" "
}" "
},
" "{
" ""accountIdentifier":" "{
" ""accountReference":" ""12349288360035054578",
" ""issuerAccountExternalReference":" ""CHILD_ACCOUNT-202212160001"" "
},
" ""selectedModels":" "[
" "{
" ""reference":" ""M_1234_ACCSETUPFEE_GOLD_41",
" ""type":" ""ACCOUNT_SETUP_FEE"" "
},
" "{
" ""reference":" ""M_1234_MEMBERSHIPFEE_GOLD_41",
" ""type":" ""MEMBERSHIP_FEE"" "
}" "
]" "
}" "
]
}Update Contract Fees For A Given Contract And Card Account
This API enables the contract fees (Membership fee and account set-up fee) to be updated for a given contract and given card account in the contract.
This is done by providing in input the new model reference and the type to be used.
This model has to be configured previously for the product.
API links
Here, an example of request for:
- The contract reference: 1f798c05-f18b-4e6d-9ce3-017d6de43b92
- The issuer: 1234
- The account 12349288360035054578
The response updates the membership fee model applied to the card account “12349288360035054578”.
PATCH /api/v2/issuers/1234/contracts/1f798c05-f18b-4e6d-9ce3-017d6de43b92/contract-fees/12349288360035054578
Request data
{
" ""selectedModels":" "[
" "{
" ""reference":" ""M_1234_MEMBERSHIPFEE_GOLD_21",
" ""type":" ""MEMBERSHIP_FEE"" "
}" "
]
}Response data
{
" ""responseMetadata":" "{
" ""correlationId":" ""29a7a912-b795-4cc1-a831-7d872128015a",
" ""statusMessage":" ""Executed successfully",
" ""statusCode": 200,
" ""responseDateTime":" ""2022-12-16T17:28:18.502+0100",
" ""timeTakenMs": 317
},
" ""data":" "{
" ""accountIdentifier":" "{
" ""accountReference":" ""12349288360035054578",
" ""issuerAccountExternalReference":" ""CHILD_ACCOUNT-202212160001"" "
}" "
}
}Retrieve Contract Owner A Contract
This API allows the contract owner for a contract identified by the Issuer Contract external reference or the Contract reference, to be retrieved.
API links
Here, an example of request for:
- The contract reference: 1e9802ae-68db-467b-8610-ae59f0d37291
- The issuer: 1234
GET /api/v2/issuers/1234/contracts/1e9802ae-68db-467b-8610-ae59f0d37291/contract-owner
Response data
{
" ""data":" "{
" ""issuerId":" ""1234",
" ""customerIdentifier":" "{
" ""customerReference":" ""CUS10000351533",
" ""issuerCustomerExternalReference":" ""PERSON-202212130001C"" "
},
" ""active":" true",
" ""birthDate":" ""1989-12-20T00:00:00.000+00:00",
" ""birthPlace":" ""Lorch",
" ""commercialStatus":" ""Normal",
" ""courtesyTitle":" ""Frau",
" ""firstName":" ""Helen",
" ""lastName":" ""BOUBOU",
" ""monthlySalary":" ""0",
" ""nationality":" ""DE",
" ""offlineRiskCategory":" ""Standard",
" ""onlineRiskCategory":" ""Standard",
" ""sex":" ""F"" "
}
}Switch Between Principal And Supplementary Cards
The API is used to change the contract owner of the main card by a cardholder of an additional card belonging to the same contract.
The API requires in input:
- the Issuer ID
- the contract reference
- the cardholder reference (future contract owner and future cardholder of the main card)
- the card contract reference (optional - in case the cardholder has several card contracts in different contracts)
In return, the list of all changes is provided at contract level and card contracts level (old main card and new main card.
API links
Below an example of the switch request for
- Contract reference: 1e9802ae-68db-467b-8610-ae59f0d37291
- Customer reference: CUS10000351533
POST /api/v2/issuers/1234/contracts/1e9802ae-68db-467b-8610-ae59f0d37291/switch-principal-card
Request data
{
"cardHolderIdentifier": {
"customerReference": "CUS10000351533"
}
}
Response data
{
" ""responseMetadata":" "{
" ""correlationId":" ""adae8262-0114-4221-8bd4-305be87e2f89",
" ""statusMessage":" ""Executed successfully",
" ""statusCode": 200,
" ""responseDateTime":" ""2022-12-14T12:49:33.884+0100",
" ""timeTakenMs": 1138
},
" ""data":" "{
" ""contract":" "{
" ""contractIdentifier":" "{
" ""contractReference":" ""1e9802ae-68db-467b-8610-ae59f0d37291",
" ""issuerContractExternalReference":" ""CONTRACT-202212130001"" "
},
" ""contractOwnerIdentifier":" "{
" ""customerReference":" ""CUS10000351533",
" ""issuerCustomerExternalReference":" ""PERSON-202212130001C"" "
},
" ""cardContracts":" "[
" "{
" ""cardContractIdentifier":" "{
" ""cardContractReference":" ""12342000000000380700"" "
},
" ""principalSupplementaryCardIndicator":" ""PRINCIPAL"" "
},
" "{
" ""cardContractIdentifier":" "{
" ""cardContractReference":" ""12342000000000380694",
" ""issuerCardContractExternalReference":" ""CARD_CONTRACT-202212130001"" "
},
" ""principalSupplementaryCardIndicator":" ""SUPPLEMENTARY"" "
}" "
]" "
}" "
}
}List Legitimacy Documents For A Contract
Legitimacy documents correspond to documents that prove the identity of a customer (pass ID, national card ID)
The document type, The document ID, the expiry date of the document, its issuing date can be stored in our system.
This API is used to get the customers legitimacy documents of a contract.
The input parameters are:
- the contract reference for which information is requested: It can be provided by using the contract reference or the issuer external contract reference.
API links
Below an example of request for:
- The contract reference: 1e9802ae-68db-467b-8610-ae59f0d37291
For this contract, there are 2 customers. The response gives the legitimacy documents for each of them.
GET /api/v2/issuers/1234/contracts/1e9802ae-68db-467b-8610-ae59f0d37291/legitimacy-documents
Response data
{
{
" ""data":" "[
" "{
" ""legitimacyDocumentType":" ""Passport",
" ""legitimacyDocumentId":" ""7845128",
" ""legitimacyDocumentDate":" ""2020-07-25T00:00:00.000+00:00",
" ""legitimacyDocumentExpiryDate":" ""2020-07-25T00:00:00.000+00:00",
" ""legitimated":" true",
" ""customerIdentifier":" "{
" ""customerReference":" ""CUS10000351532",
" ""issuerCustomerExternalReference":" ""PERSON-202212130001B"" "
}" "
},
" "{
" ""legitimacyDocumentType":" ""Passport",
" ""legitimacyDocumentId":" ""9512345",
" ""legitimacyDocumentDate":" ""2016-10-13T00:00:00.000+00:00",
" ""legitimacyDocumentExpiryDate":" ""2026-10-13T00:00:00.000+00:00",
" ""legitimated":" true",
" ""customerIdentifier":" "{
" ""customerReference":" ""CUS10000351531",
" ""issuerCustomerExternalReference":" ""PERSON-202212130001"" "
}" "
}" "
]
}- The contract reference: 1e9802ae-68db-467b-8610-ae59f0d37291
Update Legitimacy Document Of A Contract Customer
This API is used to update the customers legitimacy documents of a contract.
The input parameters are:
- the contract and the customer identifier for which information must be updated. They can be provided by using the internal references or the issuer external references:
- contract reference and customer reference or
- issuer contract external reference and issuer customer external reference
API links
Below an example of request for:
- the contract reference: 1e9802ae-68db-467b-8610-ae59f0d37291
- the customer reference: CUS10000351531
POST /api/v2/issuers/1234/contracts/1e9802ae-68db-467b-8610-ae59f0d37291/legitimacy-documents/CUS10000351531
Request data
{
"legitimacyDocumentType": "Passport",
"legitimacyDocumentId": "9512345",
"legitimacyDocumentDate": "2016-10-13T00:00:00.000Z",
"legitimacyDocumentExpiryDate": "2026-10-13T00:00:00.000Z",
"legitimated": true
}Response data
{
"responseMetadata":{
"correlationId":"351096b5-98ce-409b-b01d-daa77ff6f5be",
"statusMessage":"Executed successfully",
"statusCode":200,
"responseDateTime":"2022-12-13T16:35:02.551+0100",
"timeTakenMs":148
},
"data":{
"legitimacyDocumentType":"Passport",
"legitimacyDocumentId":"9512345",
"legitimacyDocumentDate":"2016-10-13T00:00:00.000+00:00",
"legitimacyDocumentExpiryDate":"2026-10-13T00:00:00.000+00:00",
"legitimated":true
}
}Sign A Contract
The API allows to:
- sign a contract, identified by the Issuer Contract external reference or the Contract reference (the contract must be in "awaiting signature" status)
- request to activate all cards within this contract simultaneously
As a result:
- the contract is signed
- the accounts within the contract are activated
- the cards within the contract are activated if requested
- the contract can be updated
API links