SMD API
Stock Market Data service provides a lot of APIs like :
If you want to test APIs, please contact us to get an authentication token
Merchant payments
Merchant payments
This API enables you to retrieve comprehensive payment data using specific criteria and periods of time.
-
Show payments data in your application of preference
-
The merchant payments are matched with PAID status transactions in the Transactions API for reconciliation purposes
-
Acquirers can allow third parties access to retrieve own merchant payments data
GET Merchant payments calls
Request parameters in bold on the Merchant payments API reference page are mandatory to complete a call.
To ensure best search call response time please use as many parameters as available.
There are two types of GET METHOD calls:
-
GET call to Search using one or more query parameters (e.g. paymentReference, merchantHierarchyId, merchantId, contractId and iban). Valid calls return a list of payment results
-
GET calls to retrieve a Specific entity (e.g. paymentId) – returns a particular payment result
Card lifecycle management
Worldline supports the whole card lifecycle.
Please find below an illustration of the possible transitions from one status to another
Activate a card
An issuer can activate a card on demand from Issuer Card External Reference or Card Reference only if the card is in CREATED status.
The issuer chooses the activation reason from the customised reasons previously configured.
As a result, the card is active in our system.
Note : The issuer can alternatively use one of the options offered by WL system to activate a card such as:
- Directly when the card is created
- or at first PIN based approved authorization
API links
Block a card
An issuer can block a card permanently (immediately or in the future) or block a card temporarily, depending on the configured blocking reason.
The card is in “CREATED” or “ACTIVE” status.
The issuer identifies the card with their own reference (Issuer Card External Reference) or with the reference generated by WL (Card Reference).
The issuer chooses the blocking reason among the reasons configured beforehand for him.
Several use cases are possible:
Use case 1: The issuer blocks a card permanently, in case of lost, stolen, not delivered, fraudulent activity, for example.
The issuer can provide:
- Transfer Effective Date – estimated date when the card was lost or stolen
- If the PIN is compromised
- If the card is lost or stolen:
- Lost Stolen Date
- If the card is lost:
- Loss Circumstances
As a result, next online authorizations are declined for the card.
If the card is permanently blocked, it can be notified to the scheme (card exceptions file sent to Stoplist network).
Use case 2: If the card has been compromised in a Common Point of Purchase (CPP), the issuer can schedule a permanent card blocking. (e.g., the cardholder is still allowed to use the card for PIN based transactions).
The issuer indicates that the card has been compromised in a Common Point of Purchase (cppFlag) and provides the delay to block the card in the future (scheduledCardBlockingDelay)
As a result:
- a permanent card blocking is scheduled for the card,
- authorizations are still accepted for the card.
The card is effectively blocked via batch process once the scheduled permanent card blocking date is reached.
Use case 3: The card is blocked temporarily in case of fraud suspicion by e.g. Issuer or Fraud system.
Fraud information as free text (fraud code) can be provided and can be used later (e.g. in dispute management in case there is a fraud declared on this card)
As a result, next online authorizations are declined for the card.
API links
POST /api/v2/issuers/{issuerId}/cards/{cardReference}/block
POST /api/v2/issuers/{issuerId}/cards/external-cards/{issuerCardExternalReference}/block
Example : Request for permanent blocking reason
- Issuer: 1234
- CardReference: 2000000000374460
- Blocking reason: LOST
POST /api/v2/issuers/1234/cards/2000000000374460/block
Request data
{
"blockingReason":"LOST",
"blockingReasonDetail":"LOST",
"comment":"comment",
"contactData":"contactData",
"customerRequestingBlockDate":"2022-10-14T08:14:08.493Z",
"fraudCode":"01",
"lastUsageDate":"2022-10-11T11:14:08.493Z",
"lastUsagePlace":"lastUsage",
"lossCircumstances":"lossCircumstances",
"lossCountry":"lossCountry",
"lossPlace":"lossPlace",
"lossReportedBy":"lossReportedBy",
"lossReportedVia":"lossReportedVia",
"lostStolenDate":"2022-10-11T11:14:08.493Z",
"noReplacementReason":"tempAddr",
"pinCompromised":true,
"transferEffectiveDate":"2022-10-14T08:14:08.493Z"
}Response data
"data":{
"cardIdentifier":{
"cardReference":"2000000000374460"
},
"status":"BLOCKED",
"blockingReason":"LOST",
"blockingReasonDetail":"LOST",
"cardBlockingDateTime":"2022-12-05T16:16:19.514+00:00"
}Unblock a card
An issuer can reactivate a temporarily blocked card.
The card is in temporary “Blocked” status.
The issuer identifies the card with their own reference (Issuer Card External Reference) or with the reference generated by WL (Card Reference)
The issuer chooses the unblocking reason from the reasons configured beforehand for him.
As a result, the card is active again.
An issuer cannot request the unblocking of a permanently blocked card.
API links
Block all cards with same PAN or same PAN reference
The API is similar to Block a card API but is applied to all cards having the same PAN or same PAN reference.
The API allows the permanent blocking (immediately or in the future), or temporary blocking, depending on the configured blocking reason, of all cards having the same PAN or same PAN reference.
Cards must be in “CREATED” or “ACTIVE” status.
The blocking reason is chosen from the reasons configured beforehand for the issuer
API links
Unblock all cards with same PAN or same PAN reference
The API is similar to Unblock a card API but is applied to all cards having the same PAN or same PAN reference.
The API allows the unblocking of all cards having the same PAN or same PAN reference.
Cards must be in temporary “Blocked” status.
The unblocking reason is chosen from the reasons configured beforehand for the issuer.
The Issuer cannot request this API for permanently blocked cards.
As a result, cards having the same PAN or same PAN reference are active again in our system.
API links
Deactivate a card
The API allows an active card, or a temporary blocked card, to be deactivated on demand, by using the Issuer Card External Reference or the Card Reference.
The deactivation reason is chosen from the reasons configured beforehand for the issuer.
As a result, the card is deactivated in our system.
This process is not reversible. New card authorizations are declined. If necessary, a request for a card replacement may be made by the issuer.
This API allows also to cancel a card in “Created” status, e.g., when the card production has failed.
API links
Replace a card
The API allows a card, that has not yet been replaced or renewed, to be replaced when the card is lost/stolen or damaged, or when the customer’s information has changed, by using the Issuer Card External Reference or the Card Reference.
The card contract must be ACTIVE and the card must not be in CREATED status.
The replacement reason is chosen from the reasons configured beforehand for the issuer.
Data that may need to be changed during replacement can be provided, such as: card data (e.g., embossing name), order data (e.g., card producer if several are allowed), customer data (e.g., name), PIN.
As a result, the new card is created, a card order and a PIN mailer order are created when applicable (physical card requested).
API links
POST /api/v2/issuers/{issuerId}/cards/{cardReference}/replace
POST /api/v2/issuers/{issuerId}/cards/external-cards/{issuerCardExternalReference}/replace
Example Replacement Request for LOST_STOLEN replacement reason
- Issuer: 1234
- CardReference: 2000000000374460
- replacement reason: LOST_STOLEN
POST /api/v2/issuers/1234/cards/2000000000374460/replace
Request data:
{
"waiveFee":false,
"replacementReason":"LOST_STOLEN",
"cardContract":{
"specificFields":{
"additionalProp1":"string",
"additionalProp2":"string",
"additionalProp3":"string"
},
"card":{
"issuerCardExternalReference":"CARD-20221119",
"cardOrder":{
"specificFields":{
"additionalProp1":"string",
"additionalProp2":"string",
"additionalProp3":"string"
},
"sendingMode":"Normal"
}
}
},
"overrideDistributionRules":false
}Response data:
"data":{
"card":{
"cardIdentifier":{
"cardReference":"2000000000374491",
"issuerCardExternalReference":"CARD-20221119"
},
"pan":"4546174672045636",
"maskedPan":"454617******2386",
"expiryDate":"1227",
"panSequenceNumber":"1",
"status":"ACTIVE",
"replacementFor":{
"cardReference":"2000000000374460"
},
"orders":[
{
"orderIdentifier":{
"orderReference":"202212052000000000374492"
},
"orderType":"CardOrder",
"currentInternalStatus":"ORDERABLE"
}
],
"panReference":"1500d015027a202e47b39d56e25aab9fcc1d"
},
"replacementForCardStatus":"BLOCKED",
"replacementReason":"LOST_STOLEN",
"cardReplacementDateTime":"2022-12-05T16:27:57.340+00:00"
}Block and replace a card
The API allows a card identified by the Issuer Card External Reference or the Card Reference to be blocked and replaced.
This API regroups Block a card and Replace a card APIs in a single request.
As result, the card is blocked and the new card is created.
If any error occurs while card blocking or card replacing, the card is neither blocked nor replaced.
API links
Payment Account to Account
General Contract Management
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
ob-p-ideal-debtor-preference
Get Preferences
Endpoint: Get /preferences/{Psuid}
This API can be used to retrieve the iDEAL preferences of a PSU. This will only work after an initial payment by this PSU was successfully completed.
-
The purple fields are applicable to IDEAL, those fields will be used towards the IDEAL Hub.
-
The orange fields are mandatory for an IDEAL payment.
More details about the fields can be found in the API reference.
Request
Response
Example:
Request (Signature-related fields "Digest" and "Signature" are conditionally mandatory):
Address: https://localhost:8443/xs2a/routingservice/services/ob/pis/v3/preferences/896587495-51254-85475893254
HttpMethod: GET
Headers: {Accept=application/json, AspspId=10002, Digest=SHA-256=47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=, X-Request-ID=08cc7007-f3c4-6586-4449-8dbf7a92740b, Authorization=Bearer 788b75b7ea27116c74d4a271404c5f49074fbc786ae67cf771a3a44a02a387d8, MessageCreateDateTime=2023-03-15T13:16:40.448Z, Signature=keyId="8D0F688AD3E6C2D4D5FB99FE129F2A2E3B496AF7",algorithm="SHA256withRSA",headers="digest x-request-id messagecreatedatetime (request-target)",signature="hjSmi6wuf/FTDyJ5W7F7QnzDj2X1KVjYuy5hbig+gF6JBhxBfJtZT4utnBgw6OG9dPyqB0EYHPJby786k+q44kl+pWMPJWAJjNHeXyNufNDENF3GGsRsnqBjwrNp9575vsIeimG34A6x47Ap1/01Nmsqk4NzGr0F0HAVyIbeX0Q9oKd6MJHBaswkv9nqaQTajIpmdesAA5D6eNTSfz4oBOCgk2FlJpUAdaAg9Nd1uZuXV+Jeug2coU+jc5FZUQXyZRaV7hiE5UtBIQVxpml6aydFZwCD6OaRJrGvluebVprYc1bqSsiMmS4Pk+qDJshSk5cWWhnp/bVsUFIIK+NU3g=="}
Response (Signature-related fields "Digest" and "Signature" are conditionally present):
ResponseCode: 200
Headers: {X-Request-ID=2db64c57-fc84-4998-a83c-aa33ff7fbd9b, MessageCreateDateTime=2023-03-15T13:16:40.898Z, Digest=SHA-256=bd7zfJ14uHY5YwvcXpqr78Df5jUpb0Z64styUET3afI=, Signature=keyId="3EBEF6033C00730D9C6DA05165A3CAA1F31036FB",algorithm="rsa-sha256",headers="messagecreatedatetime x-request-id digest",signature="kBpt9O2Auydz0398VFDf0M9lVWcGVI8CsNJbpvAcXxtmTnlO9cH2MlqZQqlMHGjDqcOMmjGeELaQLAft/R1p8HQoyIMJRxh9PtauyKTnHqLavLj6bJr4BoEUeQpE+xfXaR3tebVWz6zr+c7guHEqDjfNKaoKs5HjQIMm/qjKaptU7zkTCIiFsTWh0tmy/h+biI3MJzxqwpZcGdlOCgJ0LI1squZaQXmgA+AsC+uOomBgyhBMPRxMiFIyYPKnA3Ev+UL7UEm3F49B4d/AWYyO2E6B+9p470eA4Ippc4PHeBGvdNgX6zKERsDhCM8ZTmWlOeBh3i5QWvpJF/5Kv6qYHA==", Date=Wed, 15 Mar 2023 13:16:40 GMT}
Payload: {
"AspspName": "IssuerName",
"AspspLogoUrl": "https://checkout.company.com/login",
"DebtorAccountIdentification": "NL44RABO******6789"
}
ob-p-ideal-pis-api
The iDEAL payment api uses a subset of the available open banking API's. In this chapter only the api's needed for iDEAL payment initiation are described, furthermore the fields applicable to an iDEAL payment are marked purple (optional) and orange (mandatory).
Payment Status
Payments have different status depending on the actual state of processing:
- Open
- SettlementCompleted
- Cancelled
- Expired
- Error
In the following picture the possible iDEAL status are shown in an activity diagram:
Payment Initiation Endpoints
The base URL for the payment initiation service API is: /xs2a/routingservice/services/ob/pis/v3
POST Payments
Endpoint: POST /payments
This endpoint is used by the Initiating Party to set up payment initiation for an ASPSP.
- The purple fields are applicable to IDEAL, those fields will be used towards the IDEAL Hub.
- The orange fields are mandatory for an IDEAL payment.
More details about the fields can be found in the yaml specification.
|
Information During a prolonged period the Initiating Party is allowed to use the When the
|
Request (click to zoom)
Response (click to zoom)
Example: Standard iDEAL payment without Debtor token
Request (Signature-related fields "Digest" and "Signature" are conditionally mandatory):
Address: https://digitalroutingservice.awltest.de/xs2a/routingservice/services/ob/pis/v3/payments
HttpMethod: POST
Content-Type: application/json; charset=UTF-8
ExchangeId: b02d7597-3109-4291-86c3-a1d7faaee11c
Headers: {Accept=application/json, Digest=SHA-256=0P2tSst5wZ/1rBS+ZF5Pvp79klNUek7tetk0j9w+mNs=, X-Request-ID=fd3a9dae-5323-ea5a-5460-48857a264b9d, Authorization=Bearer 55aefa2dbd728d28dce18ef04e12e7014cde1e665901bc55ae0be044f114001e, MessageCreateDateTime=2023-12-29T16:38:45.770Z, Signature=keyId="39d8e82bb33e7e2a09cbcb3ef3eab351ee1c5e8f",algorithm="SHA256withRSA",headers="x-request-id (request-target) digest messagecreatedatetime",signature="a94S2WkCTBMdzx3nZrDcA61YkAsesjR9BjKkwvGLEmsCPyEUqk55zYHHE0rLVHwVD7YNchMZnEWFR3Vf63egGSTMPTD0xfmHZJua7Wz/VZVpmIkckCjfYiaQTilVImTcKeBIjhnkAd7MP2qQkr6bDtyQQ1zy1DGwDQgTlNVxOHbv+WcMKJxoQcFn5qLTvaq6fnat3a2Ka/jAUHRytAJ+5xWRT0tKq85LvjB10fho8gMgHQ+4q/0H2gmPhh9QYDwCawbBdgdDWb5HtX0qjhftO3iAb4G5HOlrqSBdTprYVDJmtqwh3YEekfy8KyHifiMMWiKVMrKohAcdvazlSMpKXA=="}
Payload: {
"PaymentProduct": ["IDEAL"],
"CommonPaymentData": {
"Amount": {
"Amount": "1.00"
},
"RemittanceInformation": "iDEAL Standard Flow Minimum fields",
"RemittanceInformationStructured": {
"Reference": "iDEALStandardFlow"
}
}
}
Response (Signature-related fields "Digest" and "Signature" are conditionally present):
ResponseCode: 201
Headers: X-Request-ID=d04820e1-d2da-4def-8def-13062b57d3a6, MessageCreateDateTime=2023-12-29T16:38:45.949Z, Digest=SHA-256=kyULomhnKJVz5IfrMDOWTs5ZpmBTKwjFrF6HO/LQG6s=, Signature=keyId="3EBEF6033C00730D9C6DA05165A3CAA1F31036FB",algorithm="rsa-sha256",headers="messagecreatedatetime x-request-id digest",signature="m//b5oj7D4Vuw5leONeJnlV6P2YvQEPs/fNq9WxE+HsS68iEICh3uMPPwhqv5JLh5UMDudZG0fY/YtvYx3GMUr5DqGaTxplUWW5+l8dV6JM94POvgOveJOPayCMAW0pWd55sbt/IvBJmc19+z6UKMJ5liNwrvYboxYQp3gb9iCeVyqkUPjjDZmo3EvQXV/6gcZAJCNwPy7vAKmGqiI57f/8EJQEZnwopTVMgn77JdpKht/dMw1oulCot4xaxmgcCwwWVxS951yqsNLxKhOnga4zHCe6anjr1F0qL0qZr85z1eDwVfwwAOiv7tGEzGaXszZnOAnsmwMNjktaVvFBPUQ==", Date=Fri, 29 Dec 2023 16:38:45 GMT, Content-Type=application/json;charset=UTF-8}
Payload: {
"CommonPaymentData": {
"ExpiryDateTimestamp": "2023-12-29T20:38:45.925Z",
"PaymentStatus": "Open",
"PaymentId": "142641",
"AspspPaymentId": "0001143558019460"
},
"Links": {
"RedirectUrl": {
"Href": "https://worldline.com"
},
"GetPaymentStatus": {
"Href": "https://digitalroutingservice.awltest.de/xs2a/routingservice/services/ob/pis/v3/payments/142641/status"
}
},
"UseWaitingScreen": false
}
Example: iDEAL Payment with Fast Checkout
Request (Signature-related fields "Digest" and "Signature" are conditionally mandatory):
Address: https://digitalroutingservice.awltest.de/xs2a/routingservice/services/ob/pis/v3/payments
HttpMethod: POST
Headers: {Accept=application/json, Digest=SHA-256=OCbJurWSWF7ltmMlP/kM4oT9C2p5ZEjh4Oh0hcGrzek=, X-Request-ID=8221d7a3-f41b-514f-bbc8-c39a744d145d, Authorization=Bearer 175a6d1c801969021f1071168661d617a17e3f8ba3824b7401491968644d2704, MessageCreateDateTime=2024-02-14T17:33:58.301Z, Signature=keyId="39d8e82bb33e7e2a09cbcb3ef3eab351ee1c5e8f",algorithm="SHA256withRSA",headers="x-request-id (request-target) digest messagecreatedatetime",signature="CAK3vtjrbVlYjtoi5nmor+hGvOTMHGRT4p+hXHU8MnLv5mJvtQRmQVbzujHENclCxTIyQjo01wy/ckBuYdFj1hyJfWW/JPJ0h1qCZX8/XBrI+IA89ZDqNvcd62wUHOcYeFMtIhcySk03Ln7YRjObIJ1g/ky/jB4/aA0UStAWOstc72YU8S2A+5JLy+lN7MzQoV2KNo3QzOyOzPZ9Ga6/2xdMnq7bG+uSBP9n07JljQPoqPr6onsX7UFSjYtind0kX+6wfH2XjQI2pFEhF1q8brL3ponnmQ053JJpp+dX68HFIuDSXn+O9CHL7HLY51xQIbDilPaocA1dPlPLeSsU+Q==", content-type=application/json; charset=UTF-8}
Payload: {
"PaymentProduct": ["IDEAL"],
"CommonPaymentData": {
"Amount": {
"Type": "Fixed",
"Amount": "24.50",
"AmountBreakdown": {
"OrderAmount": "20.50",
"ShippingCost": "4.00"
}
},
"RemittanceInformation": "iDEAL2.0 FastCheckout Flow",
"RemittanceInformationStructured": {
"Reference": "iDEALpurchase21"
}
},
"IDEALPayments": {
"FlowType": "FastCheckout",
"ExpectedCheckoutData": {
"DebtorContactDetails": {
"FirstName": true,
"LastName": true,
"PhoneNumber": true,
"Email": true
},
"ShippingAddress": true,
"BillingAddress": true
}
}
}
Response (Signature-related fields "Digest" and "Signature" are conditionally present):
ResponseCode: 201
Headers: {X-Request-ID=e3727e35-e3fd-4bb9-9c6c-1725da231527, MessageCreateDateTime=2024-02-14T17:33:58.939Z, Digest=SHA-256=16eS+f5lOwGtN05ukpGcKvDrKt2DR5QCNNsDQfLBe5c=, Signature=keyId="3EBEF6033C00730D9C6DA05165A3CAA1F31036FB",algorithm="rsa-sha256",headers="messagecreatedatetime x-request-id digest",signature="RcDMNd5jy/HiJ9s2QxmzwfKuXMTzT4Pk5lp8z0NhOG9fS1VrPVsEcq0u8Hm3C+6UwdPjGDekSC1kytvOm/gHSoZQTIEvpbh99w7yeBCzQNbIQNWr9Fnl4QyXgyrUfVgR889yEGntw+0esl0vu+LpFqi+0CI4rdu5vbzaqLz/oG00D9NC8W0PfEmj469XBevp3hDcnb6ieINmOVo4ZYu2ByaD3p6TC1vN+YYRqw6t/n+qZVjYG3DIhceTtiqsPvoucU7wYVRplqta7GyAK9RGevXzZfY6guiZrsDHl6mWhToKiQoS2YjGE6COF89oOeCfC5NXy4n+/fwKAhqmWBdPsQ==", Date=Wed, 14 Feb 2024 17:33:58 GMT, Content-Type=application/json;charset=UTF-8}
Payload: {
"CommonPaymentData": {
"ExpiryDateTimestamp": "2024-02-14T21:33:58.919Z",
"PaymentStatus": "Open",
"PaymentId": "174142",
"AspspPaymentId": "0001077680035886"
},
"Links": {
"RedirectUrl": {
"Href": "https://worldline.com"
},
"GetPaymentStatus": {
"Href": "https://routingservice.awltest.de/xs2a/routingservice/services/ob/pis/v3/payments/174142/status"
}
},
"UseWaitingScreen": false
}
GET Payment Status
Endpoint: GET /payments/{paymentId}/status
This endpoint is used to retrieve the status of a payment.
- The purple fields are applicable to IDEAL, those fields will be used towards the IDEAL Hub.
- The orange fields are mandatory for an IDEAL payment.
More details about the fields can be found in the yaml specification.
Request
Response (click to zoom)
Example: iDEAL payment status
Request (Signature-related fields "Digest" and "Signature" are conditionally mandatory):
Address: https://digitalroutingservice.awltest.de/xs2a/routingservice/services/ob/pis/v3/payments/143374/status
HttpMethod: GET
Headers: {Accept=application/json, Digest=SHA-256=47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=, X-Request-ID=aa9ec3e7-dc34-f625-2e97-e16644ea1e77, Authorization=Bearer 59519322f1f56db6bd1d23ac0e22cf5015088f085970fb9b461ff2684bc2e96a, MessageCreateDateTime=2024-01-08T12:55:34.630Z, Signature=keyId="39d8e82bb33e7e2a09cbcb3ef3eab351ee1c5e8f",algorithm="SHA256withRSA",headers="x-request-id (request-target) digest messagecreatedatetime",signature="W/6ViHZJ/x0/KM61H7mwCZQp2/3WPax5seqLpCby0BXwgpVoFrSmCu5oHF2pLS2AdHuTiE6qFsBnMkfeGMEDwtqCdY0GZVQGwZ6j9+6zjJHwm21xZ+BmXXH4puRgqxt7DSnOou3SkstzCblf4gSL8MqIyYu7n+eLQlWvjl57t7dNgX0sNTwJE/1GgU/ukDyUoJl4aO1n9ID8EnLDUpXunbZ+1pyCPGbfz5/pDMrJsKZ9l58tLxj7IneU+Mnai8UJEqrQ441ONgYCHF7KoDxu15XA+IY7DnwkA5u/+QN7IY5KpHG3zP19m7jiOimkI6lrqLAc2Ld4iehjNMGve7Ci7w=="}
Response (Signature-related fields "Digest" and "Signature" are conditionally present):
ResponseCode: 200
Headers: {X-Request-ID=3a3df5d3-fa9e-4fee-b9fd-067c23dc91fa, MessageCreateDateTime=2024-01-08T12:55:35.032Z, Digest=SHA-256=pV9HQh/XGpLmawhfj9d/hxYucKkOQCKV9BJ978PeW5k=, Signature=keyId="3EBEF6033C00730D9C6DA05165A3CAA1F31036FB",algorithm="rsa-sha256",headers="messagecreatedatetime x-request-id digest",signature="DMvxRTvhRG1kFAy0JPbBzdoRrXq5C9OUJHl6GMQkdNriG4SeuHGaFpdaDA6NgFw2+Ky/RBYiruL18ul+1ZvmdhlyhMaRqR0J7Jg/m9JMyu3wFunBVINysQ+2yj0ucXRMck/CoBW1mYwjDCGCN7xOofw2mZLV6PHjP9xHaDA855iPYE7HUaukB/qveA/S6B2qsjFxDs5AJh6VSWEoknA1+NJZCEX2VC23bnkMgy92qN6bZch5bL3462yFA/0uA75k9XH3O7+Jesl86tBU3kKATNk5n2//vun+Bg4NlSQjU21m6B+nOZT1M+TUkVzG0KWdByf6yFv/x0rp7hifnFZvjA==", Date=Mon, 08 Jan 2024 12:55:35 GMT, Content-Type=application/json;charset=UTF-8}
Payload: {
"PaymentProductUsed": "IDEAL",
"CommonPaymentData": {
"PaymentStatus": "SettlementCompleted",
"PaymentId": "143374",
"AspspPaymentId": "0001092688873027",
"AspspId": "10002",
"DebtorInformation": {
"Name": "Edsger Wybe Dijkstra - Callback",
"Agent": "ABNANL2AXXX",
"Account": {
"SchemeName": "IBAN",
"Identification": "NL44RABO0123456789"
}
}
}
}
ob-p-ideal-transaction-flow
In this chapter the transaction flows of two iDEAL payment types are described:
- Standard iDEAL payment
- Without profile recognition
- With profile recognition (based on debtor token)
- Fast Checkout iDEAL payment (based on browser cookie)
Additional requirements for the iDEAL payments are described in the chapter iDEAL requirements
Standard iDEAL Payment
An iDEAL transaction for a simple single payment is the basis of the iDEAL flow. The actual iDEAL transaction flow that the PSU follows, depends on where the iDEAL transaction is started at the Initiating Party (mobile app or browser, desktop browser) and where the payment authorization takes place at the ASPSP (mobile banking app, desktop browser, mobile browser). Next to this, it also depends on whether a PSU is already registered for iDEAL, and whether a registered PSU is recognized by the iDEAL Hub via a Debtor Token.
The full iDEAL transaction flow broadly follows the following steps:
-
Shopping Process: The PSU places an order at an Initiating Party and chooses iDEAL as payment method. If the Initiating Party makes use of Debtor Tokens, the Initiating Party shows the preferred ASPSP and IBAN of the recognized PSU alongside the iDEAL payment button.
-
Transaction Initiation: A transaction is created at the Open Banking Service using the Post /payments API, which responds with a redirect URL to the iDEAL payment page or the ASPSP directly.
-
Customer Recognition / ASPSP Selection: The PSU is redirected by the Initiating Party (or CPSP) to the iDEAL payment page, where he can choose an ASPSP or scan a QR code (depending on the web/app context). Alternatively, a recognized PSU (by means of browser cookie or debtor token) may be redirected directly to his preferred ASPSP or receive a push notification from his preferred ASPSP to authorize the iDEAL transaction (decoupled flow).
-
ASPSP Authorization: The PSU is presented with the transaction details at the ASPSP, where he authorizes the iDEAL transaction.
-
Transaction Confirmation & Return to Initiating Party: When the PSU authorizes the payment, a confirmation is sent by the ASPSP to the iDEAL Hub. If applicable, the PSU may be asked to register a profile with iDEAL. The iDEAL Hub informs the Open Banking Service of the payment status, who in turn informs the Initiating Party. In case the Initiating Party implemented the Post status API, they are informed of the payment status directly by the Open Banking Service. In case of a redirect flow, the PSU is ultimately redirected back to the Initiating Party.
Below are two example screen flows. The top one is using a mobile device throughout. The bottom one starts on a non-mobile device and switches to a mobile device for the ASPSP Authorization.
Figure 1 iDEAL transaction flow example on mobile
Figure 2 iDEAL transaction flow starts on non-mobile device (example)
For the initiation of an iDEAL payment two authentication flows are applicable; described in the table below.
|
Secure Customer Authentication (SCA) Approach |
Indicator in the Post /payments response |
Description |
|
Redirect |
RedirectUrl |
In the Redirect Approach the browser session of the PSU is redirected from the Initiating Party to the iDEAL Hub. The iDEAL Hub will ask the PSU which ASPSP he would like to use (this preference can be stored). The browser session is then redirected to the chosen ASPSP. The ASPSP provides all the pages required for authentication of the PSU and will then ask for authorization of the payment. After that the PSU is redirected back to the Initiating Party. |
|
Decoupled |
UseWaitingScreen = true AND RedirectUrl |
The decoupled flow can only occur if the 'HttpHeaderUserAgent' , 'PsuId' and 'UseDebtorToken = true' fields are provided in the Post /payments request. The Aspsp could then decide to use the decoupled flow, in that case the Post /payments response will have 'UseWaitingScreen = true' field. UseWaitingScreen is a boolean which is returned in the Post /payments response. If set to true it means the Initiating Party should display a waiting screen while the Aspsp is starting a decoupled flow with the PSU. The RedirectUrl is provided as backup. Currence set the following requirements for the waiting screen:
This page can be in the look and feel of the Initiating Party. |
Sequence diagrams
The sequence diagrams in this paragraph are examples of possible flows for standard iDEAL payments with and without profile recognition, they do not encompass all the possible flows.
In the diagrams below the sequence of requests is shown. The vertical green bars indicate which party is responsible for the session of the PSU. If a party has the session a screen can be displayed. Notice that in the iDEAL 2.0 flow the Initiating Party can receive a notification when the authorisation of the payment is finished on the ASPSP side. In order to receive this notification, the Initiating Party should implement the Post status API, so this can be called by the Open Banking Service. The initiating party also has the option to request the status by calling the Get /payments/status API of the Open Banking Service.
Redirect and no Debtor token
This is an example of an iDEAL payment where the PSU is not recognized by the iDEAL Hub.
Redirect with newly generated Debtor token
The iDEAL payment product has the option to store information about the PSU, such as the favorite bank and the IBAN. In order to use this functionality, the Initiating Party should set the field 'UseDebtorToken = true' in a Post /payments request towards the Open Banking Service. If a new debtor token is generated by the iDEAL Hub the Open Banking Service will return, next to the Status of the payment in Post /status, a PsuID in Post /debtorToken. This PsuID can then be used in subsequent iDEAL payments request for the same PSU (again with 'UseDebtorToken' set to true).
Redirect with existing Debtor token
The Open Banking Service also offers a separate API which can be used to retrieve the preferences of the PSU, the Get /preferences API.
In the sequence diagram below the Get /preferences api is the optional step in the beginning. This flow is using the Debtor Token to reduce the number of steps for the PSU to complete the payment (no ASPSP selection required in the iDEAL Hub).
Decoupled with existing Debtor token
This sequence diagram shows a possible decoupled flow, but is otherwise the same as the 'Redirect with existing debtor token' flow.
In a decoupled flow another device is used to authenticate and authorize the payment, this can be seen in the sequence diagram below by the fact that 2 sessions (green vertical bars) are active at the same time. The PSU doesn't leave the session with the Initiating Party, in the meantime a session is started on another device (for example a smartphone) which handles the interaction between the PSU and the ASPSP. The decoupled flow can potentially speed up the authentication process when bio-metrics are used in the ASPSP's app on the smartphone.
If the following fields are provided in the Post /payments request a decoupled flow can be initiated by the ASPSP:
- HttpHeaderUserAgent
- PsuId
- UseDebtorToken = true
In case of a decoupled flow the Post /payments response will have 'UseWaitingScreen = true' field.
Fast Checkout iDEAL Payment
An iDEAL payment with iDEAL Checkout allows a PSU to centrally manage his shipping, invoice and contact details in its iDEAL profile and provide these to an Initiating Party as part of the iDEAL payment.
In an iDEAL payment with iDEAL Checkout, a PSU is redirected to the iDEAL Payment Page. If the PSU is recognized by a cookie and an iDEAL profile is detected, the shipping address preferences are shown to him on the iDEAL payment page. The PSU then confirms its preferred contact details and shipping address on the iDEAL payment page, after which he proceeds with the transaction through either a redirect to the ASPSP, a QR code scan, or a push notification to its mobile banking app. After the PSU has authorized the payment at the ASPSP, he is redirected back to the Initiating Party. Upon authorization, the Initiating Party receives confirmation of the payment (similar to a regular iDEAL transaction), which will additionally include the chosen contact details and shipping address of the PSU.
Currently only Dutch shipping addresses are allowed for PSUs
Below an example screen flow of a Fast Checkout iDEAL Payment.
Initiating an iDEAL Checkout transaction with the Open Banking v3 API
An iDEAL Checkout transaction can be initiated by indicating this in the FlowType field of the Post /payments. A breakdown of the transaction amount needs to be added to this call, which will be shown to the PSU during the iDEAL Checkout transaction flow alongside its shipping details.
Initiating an iDEAL Checkout transaction
-
To mark a transaction as iDEAL Checkout, the field FlowType MUST be set to FastCheckout
-
To initiate an iDEAL Checkout transaction, the AmountBreakdown group MUST be included in the POST /payments call.
-
This group MUST include both an OrderAmount and a ShippingCost. If no shipping costs apply, the field must be filled with 0.
-
-
The sum of the OrderAmount and ShippingCost MUST be equal to the Amount field, which represents the total transaction amount to be payed by the PSU.
-
To specify the desired iDEAL Checkout data to be received, the ExpectedCheckoutData group can be set. Only those data fields that are set to true will be included in the callback.
In a iDEAL Checkout transaction, the response of the Post /payments call will always include a URL to the payment page in the Links.RedirectUrl field.
Shipping amount and shipping/invoice address restrictions
-
When initiating an iDEAL Checkout transaction, the Initiating Party MUST specify the desired iDEAL Checkout data to be received, which can be included in the payment initiation via the ExpectedCheckoutData group
-
The Initiating Party MUST comply with the General Data Protection Regulation (GDPR). The Initiating Party SHOULD only request the personal data which is needed to fullfill the agreement with the PSU;
-
-
The Initiating Party MUST provide both an OrderAmount and ShippingCost.
-
The PSU can only add Shipping and Invoice addresses in The Netherlands. Any other non-NL addresses are currently not allowed. Initiating Party's therefore can trust to receive only NL addresses.
-
It is (currently) not possible to dynamically define or alter the shipping amount based on the PSU’s chosen shipping address. The shipping amount can only be provided one time in the transaction initiation. The shipping amount can also be 0.
-
In case the PSU cannot or does not want to provide its iDEAL Checkout data, the transaction is canceled. This means that if an iDEAL Checkout transaction is initiated, a successful and payed transaction will always include the iDEAL Checkout data.
Selection/registration of iDEAL Checkout data by PSU
After initiating an iDEAL Checkout, the PSU is redirected to the iDEAL Payment Page. Here, the amount breakdown in order amount and shipping amount is shown, next to the regular payment details.
-
If the PSU is recognized by a browser cookie, the known shipping address preferences from its iDEAL profile are shown, in addition to the regular profile preferences. Note that only the data fields indicated in ExpectedCheckoutData will be shown to the PSU (this applies to all iDEAL Checkout flows).
-
Profile information presented will be partly masked and can only be fully shown if the PSU authenticates via its ASPSP.
-
If a registered PSU does not have any shipping address registered with its profile yet, it will first be asked to provide an address before continuing with the iDEAL Checkout transaction.
-
If the PSU is not recognized, it will first be asked whether the PSU has a registered iDEAL profile. In case of an existing profile, the PSU will be asked to select its ASPSP and is redirected to that ASPSP for authentication. After successful authentication, the PSU will return to the iDEAL payment page to view its (unmasked) profile and iDEAL Checkout data.
-
At any time during the iDEAL Checkout flow, the PSU may choose to change its preferred address for the transaction or add a new address. This is done on the iDEAL payment page.
-
If the PSU is not recognized and is a new PSU, the PSU is asked to register an iDEAL profile, including data for iDEAL Checkout.
Shipping data in transaction callback
After confirming the selected delivery details and preferred IBAN, the PSU is redirected to the ASPSP for authenticating and authorizing the payment. This is done at the ASPSP, similar to a regular transaction.
If the PSU was not registered with iDEAL yet, a registration flow was initiated at the iDEAL payment page.
After the PSU has confirmed the transaction payment at the ASPSP, the PSU’s iDEAL Checkout data (like shipping address) is added to the Post /status callback alongside the other payment details. The iDEAL Checkout data can be found in the DebtorInformation group. Note that only data fields that were indicated in the ExpectedCheckoutData will be included in the callback.
Sequence diagram
This iDEAL Fast Checkout flow is based on de the recognition of the PSU by the iDEAL 2.0 Hub based on a browser cookie. In the sequence diagram below the PSU is recognized. This flow will simplify the checkout screen of the Initiating Party; shipping, invoice and contact details are all handled by the iDEAL Hub. The shipping data is provided in the Post /status request or the Get /payments/status response after the payment was finalized at the ASPSP.
ob-p-ideal-security
The Ideal interface has a few additional security features regarding Digital Signatures on top of what is described in the Security page.
Digital Signatures, iDEAL specific
Signing requests for iDEAL by the Initiating Party
If signatures are enforced by the Initiating Party's Acquirer, the following headers will be mandatory in the API requests sent by the Initiating Party to the Open Banking Service:
- Signature
- Digest
The Signature header
The digital signing is done by applying the “Signature” scheme as described in https://datatracker.ietf.org/doc/html/draft-cavage-http-signatures-12. This is equivalent to the “Authorization” scheme (see Signing the authorization request) and the same procedure is followed to generate the signature and header parts but it uses the Signature header instead of the Authorization header.
In order to generate the signature string that is signed with a key, the Initiating Party must use the values of following HTTP header fields:
- Digest
- X-Request-ID
- MessageCreateDateTime
The headers used to generate the signature string also have to appear in the `headers` parameter of the Signature header, in the fixed order appearing below:
headers=”digest x-request-id messagecreatedatetime (request-target)”
To include the HTTP request target in the signature calculation, use the special `(request-target)` header field name. You can generate the header field value by concatenating the lowercased :method, an ASCII space, and the :path.
The (request-target) header field value to be used for the different APIs is:
|
API |
(request-target) header field value |
|
POST /payments |
post /xs2a/routingservice/services/ob/pis/v3/payments |
|
GET /payments/{paymentId}/status |
get /xs2a/routingservice/services/ob/pis/v3/payments/{{paymentId}}/status* |
|
GET /preferences/{Psuid} |
get /xs2a/routingservice/services/ob/pis/v3/preferences/{{psuId}}* |
*The placeholders {{paymentId}} and {{psuId}} must be substituted with the values as obtained within the respective flows.
The signature string is created by concatenating the lowercased header field names followed with an ASCII colon `:`, an ASCII space ` `, and the header field value. Leading and trailing optional whitespace (OWS) in the header field value MUST be omitted. If the value is not the last value, then an ASCII newline `\n` is appended.
Example: For the payment request with the following required headers
POST /payments HTTP/1.1> Digest: SHA-256=B/O1sG0L8+bEAqWF3aMZn3I0rx5YVi8r5cM6JHlTW7Q= X-Request-ID: 1aad5e0f-02d7-aefb-61e3-6f4d3322cf71 MessageCreateDateTime: 2023-03-15T10:07:26.264Z
The concatenated "Signature String" would be:
Digest: SHA-256=B/O1sG0L8+bEAqWF3aMZn3I0rx5YVi8r5cM6JHlTW7Q= X-Request-ID: 1aad5e0f-02d7-aefb-61e3-6f4d3322cf71 MessageCreateDateTime: 2023-03-15T10:07:26.264Z (request-target): post /xs2a/routingservice/services/ob/pis/v3/payments
The resulting signature parameter of the Signature header would be:
signature="N7kFLMMi/2R5hCd1gdO+GYhS70DOLMl+n8hborf42nFuu0HFjreoqU70gvxFWzgTPaWjdmNYY/7sOAUAQWudsM61Vc536XmaOGrrSxOINlH9l9QBk31xZMlJBf/+1+GtPb1BR26PYBjxKDMbN9W7PEVZLCDoObSnVLkvKbkLRWl0U8a39mDkUBu70Jw8yWusDU0g1OVN+5YRfENPNtC2ZnVD80gxih4JoFV6f4WCcX4HXVl229veFNO5joNQyUc7qOkXUGN2g0omgN4iJxVGnzEJ9BCrNe+vK9T25LC0fwSp/W6A9dDfuHQzMZgDJZZKpaX0Gg34i68etmi5oLrM3A=="
The algorithm parameter of the Signature header is fixed:
algorithm=”SHA256withRSA”
The ‘keyId’ parameter of the Signature header is the thumbprint of the used certificate, viewed with the SHA1 algorithm. The private key associated with `keyId` is used to generate a digital signature on the concatenated signature string applying the SHA256withRSA algorithm. The complete SIgnature header looks then like this:
Signature: Signature keyId=”DCAC7209573D506FC56095B8B23E8555A8F38B29”, algorithm=”SHA256withRSA”, headers=”digest x-request-id messagecreatedatetime (request-target)”, signature="N7kFLMMi/2R5hCd1gdO+GYhS70DOLMl+n8hborf42nFuu0HFjreoqU70gvxFWzgTPaWjdmNYY/7sOAUAQWudsM61Vc536XmaOGrrSxOINlH9l9QBk31xZMlJBf/+1+GtPb1BR26PYBjxKDMbN9W7PEVZLCDoObSnVLkvKbkLRWl0U8a39mDkUBu70Jw8yWusDU0g1OVN+5YRfENPNtC2ZnVD80gxih4JoFV6f4WCcX4HXVl229veFNO5joNQyUc7qOkXUGN2g0omgN4iJxVGnzEJ9BCrNe+vK9T25LC0fwSp/W6A9dDfuHQzMZgDJZZKpaX0Gg34i68etmi5oLrM3A=="
The Initiating Party must upload the used public certificate in the Back-office so that Open Banking Service is able to validate the signature. If the signature could be validated and the sender has a valid iDEAL subscription a successful response is returned.
The Digest header
Calculate the Digest header as follows:
-
Step1: Create a SHA-256 hash of the Payload
-
Note-1: if the output is hex-encoded, please make sure to convert it to binary data (convert the hex-encoded string to a byte array)
-
Note-2: payload formatting is important. If you generate the Digest by using an unformatted JSON payload, then please make sure that it matches with an unformatted request body used in the API request
-
-
Step 2: Base64-encode the SHA-256 hash
-
Step 3: Prepend 'SHA-256=' to the resulting base64-encoded value
Example: For the following payload:
{
"PaymentProduct": [
"IDEAL"
],
"CommonPaymentData":
"Amount":
"Type": "Fixed",
"Amount": "10.00",
"Currency": "EUR"
},
"RemittanceInformation": "Cookie",
"RemittanceInformationStructured":
"Reference": "iDEALpurchase21"
}
},
"IDEALPayments":
"UseDebtorToken": false,
"FlowType": "Standard"
}
}
Step 1: The SHA-256 hash of this request body is: "07f3b5b06d0bf3e6c402a585dda3199f7234af1e58562f2be5c33a2479535bb4" (Note: this is a hex-encoded representation)
Step 2: The base64-encoded hash (Note: hex to base64 encoding): "B/O1sG0L8+bEAqWF3aMZn3I0rx5YVi8r5cM6JHlTW7Q="
Step 3: The Digest header value: "SHA-256=B/O1sG0L8+bEAqWF3aMZn3I0rx5YVi8r5cM6JHlTW7Q="
Signing Requests to the Initiating Party (notification requests) and Responses sent to the Initiating Party
If signatures are enforced by the Initiating Party's Acquirer, the following headers will be present in the API requests and responses sent by the Open Banking Service to the Initiating Party:
- Digest
- Signature
The digital signing performed by the Open Banking Service is done by applying the same “Signature” scheme as described above.
A notification request or response from Open Banking Service to the Initiating Party may contain for example a header like:
Signature: keyId="2DOXXL7lNBNKJSMHKO2IBQC1", algorithm="SHA256withRSA", headers="digest x-request-id messagecreatedatetime (request-target)", signature="lulVhOhRwFs5G8+uGCh3BjJHBG540AyTCyaKhr9QE71YTtljxFt1b7i55C9QROw/zGt+iac3cBfGGRiTAfW4ta9Hn8+u7LvyfYHFcdxBhNj7T6dgrv+MLG6aI6hw/3Cwmkz/OwESBrQJzISWf8/0bgYNuXnuPf5r7BGMhHdhIr+RNxocW6wkSOEVQfOGYazy7YsoJhVEwNEt9gN++sw9HVfaxmwjl8MqxGNcLoVAgoGMcUOvNhjATA1MSzOj2cmw6kdi2yY2w7XiMuU9Tma0jQ3CGKhxIkD8Na2Vq1K2bs/n2DOxxL7lNbnKjsmhkO2ibQc1+RV3pXQJ1SDSI3EW/w=="
In order to ensure that the contents of the sent messages are correct and have not been altered during transmission or storage the Initiating Party can validate the received signature. For the validation of the signature, the Initiating Party can use the public certificate of the Open Banking Service which can be downloaded from the Back-office.
ob-p-ideal-requirements
The iDEAL scheme has some additional rules defined by Currence, the scheme owner.
Redirecting of PSU's
As a response to an iDEAL transaction initiation, the Initiating Party will receive a RedirectUrl, which is either an ASPSP URL (directing the PSU directly to the ASPSP domain) or a Payment Page URL (directing the PSU to the iDEAL Payment Page).
-
If redirected from a browser, the redirect to the ASPSP URL or iDEAL Payment page MUST be performed from the browser window where the PSU selected iDEAL as payment method. The complete page of the InItiating Party shall be replaced by the complete iDEAL Payment page.
-
Initiating Parties MUST NOT open the redirect to the iDEAL Payment page or ASPSP URL in a new browser window.
-
Initiating Parties MUST NOT present the iDEAL Payment page or ASPSP URL embedded within its own page, as this disallows recognition of a cookie.
-
-
If redirected from an Initiating Party app, the redirect MUST take place outside the app in the default browser of the PSU.
Initiating Parties MUST NOT redirect PSU's in a custom made in-app webview browser. Doing so will disallow for PSU's to be redirected to their mobile banking apps and will seriously breach privacy regulations.
Exceptions to the above are the use of SafariViewController for Apple iOS and Chrome Custom Tabs for Android. However be aware that these may not correspond to the PSU's default browsers, so that PSU recognition based on cookie might not work.
-
During the migration period to the updated iDEAL specifications, the Initiating Party is still allowed to share a preferred ASPSP (for example when the Initiating Party also stores this preference). This feature will be discontinued after the migration period ends.
Retrieving the Status of the transaction
-
If the Initiating Party has not yet received a confirmation of the payment status when the PSU opens the returnURL, the Initiating Party MUST retrieve the transaction status by calling the status API of the Open Banking Service.
-
The Initiating Party MUST inform the PSU of a success status of the transaction, so that the PSU is certain that the payment status was correctly received by the Initiating Party.
-
The Initiating Party MUST NOT poll the status and MUST adhere to the retry scheme, see Common API elements.
Presentation of Standard iDEAL payment on Initiating Party environment
There are some rules regarding the presentation of iDEAL on the Initiating Party's environment. The main purpose of these is to create a uniform user experience for PSU's whenever and wherever they pay with iDEAL.
-
The iDEAL payment option must be presented in the list of payment options in such a way that it receives at least the same amount of attention as other payment options.
-
The rules on presentation the iDEAL Payment button and the iDEAL logo can be found here: http://www.ideal.nl/en/payee/logos-banners/ .
-
In cases where the iDEAL logo cannot be displayed at the required size on a mobile device the mandatory free space of 15px around the logo may be reduced to accommodate the requirements of the mobile device.
-
Presentation of Fast Checkout iDEAL payment on Initiating Party environment
-
To indicate to PSUs that iDEAL Checkout is offered the Initiating Party MUST show the iDEAL Checkout logo. Logo’s can be found here: https://www.ideal.nl/bedrijven/logos/ . This logo may be accompanied by the term ‘Snel Bestellen’ to provide additional clarity on the flow the PSU will enter after selecting this option;
-
Before the PSU selects iDEAL Checkout, the applicable shipping costs MUST be communicated to the PSU, to prevent that the PSU is confronted with a higher amount in the iDEAL screens than expected;
-
The Initiating Party MUST confirm the datafields, received from Currence, to the PSU, preferably on the order confirmation screen.
Profile recognition via Debtor Tokens
For an enhanced user flow for returning PSU's, the Initiating Party may want to make use of Debtor Tokens. The Debtor Tokens allow the Initiating Party to present the PSU’s preferred IBAN within its Initiating Party Domain, and prevent a redirect to the iDEAL Payment Page.
If an Initiating Party wishes to make use of Debtor Tokens for its PSU's, the following applies:
-
The PSU MUST hold an account with the Initiating Party;
-
To retrieve the preferred ASPSP and (masked) IBAN of the PSU, the Initiating Party MUST provide a Debtor Token that uniquely identifies the PSU at the Initiating Party;
-
The Initiating Party MUST be able to recognize the PSU on a return visit;
-
The Initiating Party MUST retrieve and display the preferred ASPSP and masked IBAN of the PSU together with the iDEAL payment button;
-
The Initiating Party MUST only use Debtor Token that was received in the last transaction for that PSU
Please note that a Debtor Token can only be linked to one iDEAL profile.