Merchant management (old version)
The WL FS merchant contract API enables retrieval and updating at site & terminal level. Access to contract data is restricted to your acquirer and own merchant contract identifiers. For third parties, contract updating is limited depending on the generic user role (e.g. PSP, PayFac, Merchant) limitations agreed with the acquiring bank.
Version note:
Please be aware that these API interfaces may be changed and improved (e.g. addition of fields).
The "Try out" feature does not work at this time because the sandbox is being improved to support new functionality.
Accounts
Accounts are used to process operations, manage a balance in a dedicated currency, control the credit risk, perform transaction charging, calculate interest (credit or debit), generate an invoice (statement), process payments.
Three types of account working modes are being supported; Pay Later, Pay Now, Pay Before.
- Pay Later account working mode is used to implement classical credit card products like charge cards or revolving credit. Pay later accounts are settled by a cyclic closure process and typically produce an invoice (statement) with an amount due which can represent the full or partial statement balance. Credit or debit interest algorithms may apply.
- Pay Now account working mode is used for all types of debit cards. Such accounts are typically settled in short frequencies (e. g. daily) and produce debit orders, immediately forwarded to customers’ current accounts. Interest calculation never applies.
- Pay Before account working mode is used for the wide range of prepaid card products. The balance is always positive.
The below diagram presents different use cases covered by the API in the account domain.
ob-p-ideal-notification
The notification APIs described in this chapter needs to be implemented on the Initiating Party side, if the Initiating Party decides to use them. The Open Banking Service will post notifications to these endpoints. For the iDEAL product the post status notification is part of the product, a value-added service is not required (because the notification is part of the iDEAL scheme and the Open Banking Service doesn't have to-do additional polling).
POST Status
Endpoint: POST /status
This API will notify the initiating party about the status of the payment. More details about the fields can be found in the API reference.
Data model
Legend
| |
| Request (click to enlarge) | Response |
 |  |
Example: Notification for Standard iDEAL payment
Request (Signature-related fields "Digest" and "Signature" are conditionally present):
Address: https://checkout.company.com/transaction/webhook/91FA6EEC30844FAAB5/v3/notification/status
HttpMethod: POST
Headers: {Authorization=Bearer 123456789, X-Request-ID=c1452392-6c3f-4365-93f8-40558f61ac36, MessageCreateDateTime=2023-03-15T11:51:24.185+01:00, Digest=SHA-256=0hq1mKzxB1yyc6+hut2bEX7ps+nWyWb2pgQb6AhfhfM=, Signature=keyId="3EBEF6033C00730D9C6DA05165A3CAA1F31036FB",algorithm="rsa-sha256",headers="messagecreatedatetime x-request-id digest",signature="uYgovoK+ibAE7+MzJEKrApDUAgWfUv7RQK22zAxWHCdKCuG4d0HgqpDSqcGlKmP2IMFsC787zDU3oqKeeIIVXR72uZBiOnm0/84UL9e7LVDHDLQsRbfDnmvgX/4xQvdwROmyqh8kkcXTf/48zY0wo2n9iDspCbgTn1DEqAqtAlwunIpea8eYA3FQc+pV2px77wVP7l+9mTxexzLSmum61wWbqE4ESJn0K37gXY54229ZtCnNSlu9rsvjQ5xmDf1e6MvMLBOblXHIReN2t8IH85VGK7mpi8T7JeKb8rIG8qDbQ5TD3BmIS1+RspI95FldLCKLH91/KNrxsgPsrC2QgQ==", Content-Type=application/json}
Payload: {
"PaymentProductUsed" : "IDEAL",
"CommonPaymentData" : {
"GuaranteedAmount" : "10.00",
"PaymentStatus" : "SettlementCompleted",
"PaymentId" : "19928",
"AspspPaymentId" : "0001070883053837",
"AspspId" : "10002",
"DebtorInformation" : {
"Name" : "Edsger Wybe Dijkstra - Callback",
"Agent" : "ABNANL2AXXX",
"Account" : {
"SchemeName" : "IBAN",
"Identification" : "NL44RABO0123456789",
"Currency" : "EUR"
},
"UseWaitingScreen" : false
}
Response:
ResponseCode: 204
Example: Notification for iDEAL Payment with Fast Checkout
Request (Signature-related fields "Digest" and "Signature" are conditionally present):
Address: https://checkout.company.com/transaction/webhook/91FA6EEC30844FAAB5/v3/notification/status
HttpMethod: POST
Content-Type: application/json
Headers: {Authorization=Bearer 123456789, X-Request-ID=c1452392-6c3f-4365-93f8-40558f61ac36, MessageCreateDateTime=2023-03-15T11:51:24.185+01:00, Digest=SHA-256=0hq1mKzxB1yyc6+hut2bEX7ps+nWyWb2pgQb6AhfhfM=, Signature=keyId="3EBEF6033C00730D9C6DA05165A3CAA1F31036FB",algorithm="rsa-sha256",headers="messagecreatedatetime x-request-id digest",signature="uYgovoK+ibAE7+MzJEKrApDUAgWfUv7RQK22zAxWHCdKCuG4d0HgqpDSqcGlKmP2IMFsC787zDU3oqKeeIIVXR72uZBiOnm0/84UL9e7LVDHDLQsRbfDnmvgX/4xQvdwROmyqh8kkcXTf/48zY0wo2n9iDspCbgTn1DEqAqtAlwunIpea8eYA3FQc+pV2px77wVP7l+9mTxexzLSmum61wWbqE4ESJn0K37gXY54229ZtCnNSlu9rsvjQ5xmDf1e6MvMLBOblXHIReN2t8IH85VGK7mpi8T7JeKb8rIG8qDbQ5TD3BmIS1+RspI95FldLCKLH91/KNrxsgPsrC2QgQ==", Content-Type=application/json}
Payload: {
"PaymentProductUsed" : "IDEAL",
"CommonPaymentData" : {
"GuaranteedAmount" : "10.00",
"PaymentStatus" : "SettlementCompleted",
"PaymentId" : "19928",
"AspspPaymentId" : "0001070883053837",
"AspspId" : "RABONL2UXXX",
"DebtorInformation" : {
"Name" : "Edsger Wybe Dijkstra - Callback",
"Agent" : "ABNANL2AXXX",
"Account" : {
"SchemeName" : "IBAN",
"Identification" : "NL44RABO0123456789",
"Currency" : "EUR"
},
"ContactDetails" : {
"FirstName" : "Edsger",
"LastName" : "Dijkstra",
"PhoneNumber" : "+31612345678",
"Email" : "edsger@domain.nl"
},
"ShippingAddress" : {
"FirstName" : "Edsger",
"LastName" : "Dijkstra",
"PostCode" : "52066",
"Country" : "NL"
},
"BillingAddress" : {
"FirstName" : "Edsger",
"LastName" : "Dijkstra",
"PostCode" : "52066",
"Country" : "NL"
}
}
},
"UseWaitingScreen" : false
}
Response:
ResponseCode: 204
POST Debtor token
Endpoint: POST /debtorToken
This API will provide a debtor token update to the Initiating party. More details about the fields can be found in the API reference.
Data model
Legend
| |
| Request | Response |
 |  |
Example: Debtor Token Notification for Standard iDEAL payment
Request (Signature-related fields "Digest" and "Signature" are conditionally present):
Address: https://checkout.company.com/transaction/webhook/91FA6EEC30844FAAB5/v3/notification/status
HttpMethod: POST
Content-Type: application/json
Headers: {Authorization=Bearer 123456789, X-Request-ID=c1452392-6c3f-4365-93f8-40558f61ac36, MessageCreateDateTime=2023-03-15T11:51:24.185+01:00, Digest=SHA-256=0hq1mKzxB1yyc6+hut2bEX7ps+nWyWb2pgQb6AhfhfM=, Signature=keyId="3EBEF6033C00730D9C6DA05165A3CAA1F31036FB",algorithm="rsa-sha256",headers="messagecreatedatetime x-request-id digest",signature="uYgovoK+ibAE7+MzJEKrApDUAgWfUv7RQK22zAxWHCdKCuG4d0HgqpDSqcGlKmP2IMFsC787zDU3oqKeeIIVXR72uZBiOnm0/84UL9e7LVDHDLQsRbfDnmvgX/4xQvdwROmyqh8kkcXTf/48zY0wo2n9iDspCbgTn1DEqAqtAlwunIpea8eYA3FQc+pV2px77wVP7l+9mTxexzLSmum61wWbqE4ESJn0K37gXY54229ZtCnNSlu9rsvjQ5xmDf1e6MvMLBOblXHIReN2t8IH85VGK7mpi8T7JeKb8rIG8qDbQ5TD3BmIS1+RspI95FldLCKLH91/KNrxsgPsrC2QgQ==", Content-Type=application/json}
Payload: {
"PsuId": "TestOSZ",
"PaymentId": "12345",
"DebtorToken": "absjrfergd"
}
Response:
ResponseCode: 204
Event Stores
Our issuing solution is composed of several applications that pushes different types of events into one information repository.
Each Application can notify events toward this repository.
Event stores contains comments or business events that can be generated by the different applications (CMS, authorization server, customer service GUI,..) part of our solution.
Retrieve Event Stores
This API enables the list of events associated to a business reference type and a business reference value, for given period of time, to be retrieved.
A business reference type corresponds to a business domain like a CONTRACT, CARD, ACCOUNT whereas a business reference value can be typically a card, account, card contract reference.
The same event can be retrieved for different business reference types and business reference values. Event can be uniquely identified by its correlationId.
Currently, this API is mainly used to get the comments linked to a business reference value (e.g., a given card identifier).
API links
Search Event Stores
TThis API enables to retrieve the list of events associated to provided set of business reference types and a business reference values for given period of time.
A business reference types correspond to a business domain like a CONTRACT, CARD, ACCOUNT whereas a business reference values list for each provided type can be typically a card, account, card contract reference.
The same event can be retrieved for different business reference types and business reference values. Event can be uniquely identified by its correlationId.
Currently, this API is mainly used to get the comments linked to a business reference value (e.g., a given card identifier).
API links
Transactions doc
Transactions
This API enables you to retrieves comprehensive transaction data based on merchant payments, contract entity and on specific periods of time.
- Show transaction data in your application of preference
- Retrieve the transactions associated with merchant payment (paymentId) for reconciliation purposes
- Retrieve transaction fees generated by the Worldline FS Merchant Pricing Engine such as: Merchant Service Charge (Interchange++, Interchange+, Fixed fees), Interchange fees, Service fees, etc.
- Acquirers can allow third parties access to retrieve own transaction data
The illustration below shows examples of a happy flow (resulting in a paid transaction) from the POST Transaction in Accept Transactions API through the various transactionStates in the GET Transactions API.
Flow actions and transactionStates in APIs
GET Transactions calls
Request parameters in bold on the Transactions 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 3 GET Transactions API call field result sets:
1. Transaction calls - transactionResults (CNP update ongoing)
Retrieve the latest transactionState in the transactionResults for CNP & POS transactions.
The Back Office transactionStates are:
- Captured - host accept CAPTURE request
- Processed - sent to SCHEME for clearing
- Paid - merchant settlement payment instructions created
2. Authorization calls - actionResults (CNP API roadmap)
Retrieve latest acceptance actionResults using the following calls:
- GET transactionId (lifecycle)
- GET actionId
- GET authorizations using the merchant contract entity (e.g. merchant, site, terminal)
Both approved and declined Accept Transaction actionResults can be viewed using available identifiers.
All the following Accept Transaction API actionTypes are available in the actionResults.
- AUTH
- PREAUTH
- AUTH_INCREMENTAL
- AUTH_REVERSAL
- AUTH_REVERSAL_PARTIAL
- AUTH_AND_CAPTURE
- CAPTURE
- CAPTURE_SPLIT (multiple partial captures)
3. Transaction Lifecycle calls (API roadmap)
Retrieve the associated first/second presentment(s) data and the associated transaction data of the different stages in the dispute life cycle (presentment, re-presentment, chargeback, pre-arbitration, settlement, manual adjustment etc.)
Credit Instalment Management
Our solution supports credit instalment management allowing the Issuer to propose a number of credit instalment types to its customers. By using our credit instalment different plans, the Issuer can decide to grant a credit to its customers on a condition of its repayment at regular intervals over a specified period of time, until it is fully paid.
Retrieve A Credit Instalment Model Simulation
The "Request credit Instalment model simulation" API allows to simulate repayment schedule either by providing instalment model reference or instalment type (e.g. transaction, cash etc) and then customer can choose a desired instalment contract with the desired terms and repayment plan.
The mandatory input fields are:
- The issuer ID
- Credit amount requested by customer
- Reference of a credit instalment model or Instalment type
As a result system returns simulated information with 1 or more repayment plans containing such as:
- total amount due
- total interest amount
- fee amount (if relevant)
- each Instalment amount
- full repayment schedule
API links
Create A Credit Instalment Contract
The "Create credit Instalment contract" API allows to create a credit Instalment contract based on provided information.
The mandatory input fields are:
- The issuer ID
- Credit amount (allowed within the model range)
- External Reference of an active credit instalment model
- Receiving account reference which relates to the account credited. The account should not be closed.
- Paying account reference which is assigned for credit instalment repayment posting. The account shall not be closed.
The optional/conditional input fields:
- The customer for which the detail is requested: It can be provided by using the customer reference or the issuer customer external reference. Field is mandatory when channel is not 'SMS'.
- External Reference of an active credit instalment model
- Credit term which is allowed on the chosen instalment product. Default value is taken from instalment model, if credit term is not defined.
- First instalment date which shall be allowed on the chosen instalment product
- An external reference (MSISDN) can be provided to identify the Instalment credit contract to be credited (e.g. mobile phone number)
As a result Instalment contract is created with:
- Credit instalment reference
- Contract Status set as ‘Created’
- Contract date defined as the date of the creation
- Credit term (default value from the Instalment Model if not provided by issuer)
- First Instalment Date (default value from the Instalment Model if not provided by issuer)
- Total interest amount calculated
- Total contract amount calculated (credit amount plus total interest amount and total fee)
- Fee amount calculated
- Monthly Instalment amount calculated
- Repayment schedule calculated
If Instalment model reference is not provided, it will be derived from:
- card type taken from card or card contract identifier
- credit amount
Selected model must have the same currency and Channel Type as the one provided in the request.
If channel type is provided as 'SMS' then:
- provided Receiving account and Paying account must be the same
- MSISDN is mandatory
Restrictions can be applied to limit instalments per customer, per day etc.
API links
Update A Credit Instalment Contract
The "Update Credit Instalment contract" API allows to update different parameters of the contract: credit amount, Instalment term, first instalment date etc.
The mandatory input fields are:
- The issuer ID
- Credit Instalment Contract Reference
When the credit instalment contract is in "ACTIVE" status, system only allows to update "Paying Account Number”. No restrictions are applied for updating credit amount, even if the value is out of instalment model defined range.
API links
Cancel A Credit Instalment Contract
The "Cancel Credit Instalment contract" API allows issuer to cancel the Instalment contract before posting of the first instalment amount.
Contract status must be in "Created" status.
The mandatory input fields are:
- The issuer ID
- Credit Instalment Contract Reference
Upon receiving this request, the contract status will be changed from ‘Created’ to ‘Cancelled’.
API links
Activate A Credit Instalment Contract
The "Activate Credit Instalment contract" API allows issuer to request contract validation, once customer is signing the instalment contract.
The mandatory input fields are:
- The issuer ID
- Credit Instalment Contract Reference (can be 4 last digits if the MSISDN is provided)
Upon receiving this request, the contract status will be changed from ‘Created’ to ‘Active’.
An instalment account is created after the contract activation.
Upon instalment contract activation repayment plan is started.
API links
List Credit Instalment Contracts
The "List credit Instalment contracts" API allows to get the list of credit Instalment contracts for a given customer & issuer.
The mandatory input fields are:
- The issuer ID
- The customer for which the detail is requested: It can be provided by using the customer reference or the issuer customer external reference.
In return the interface provides list of credit instalment contracts (both closed and open) for a given customer with details such as: credit amount, interest rate, interest amount, repayment details, posting details on principal amount and interest, etc.
API links
Retrieve Credit Instalment Contract
The "Retrieve Credit Instalment contract" API allows to retrieve details for credit Instalment contract.
The mandatory input fields are:
- The issuer ID
- Credit Instalment Contract Reference
In return the interface provides details as: credit amount, interest rate, interest amount, repayment details, posting details on principal amount and interest, etc.
API links
Close All Credit Instalment Contracts For An Account
The "Close all credit Instalment contracts for an account" API allows to close all credit Instalment contracts for an account. All the Instalment contracts linked to paying account are closed.
The mandatory input fields are:
- The issuer ID
- Paying account reference
- Remaining credit instalment reimbursement option (issuer or paying account)
The remaining credit for the reimbursement contract can be repaid either by the issuer or customer from their paying account defined in the credit instalment contract.
Repayment amount can be posted with 2 possible options, if repayment posting type is defined in contract property "repayment posting type":
- Principal amount with Interest and Fee
- Principal amount with Interest
If property is not available, three different installment operations will be posted for PRINCIPAL, INTEREST and FEE.
As a result credit instalment contract is terminated.
API links
Terminate Credit Instalment Contract
The "Terminate Credit Instalment contract" API allows the issuer or the customer to terminate the credit Instalment contract.
The mandatory input fields are:
- The issuer ID
- Credit Instalment Contract Reference
- Remaining credit instalment reimbursement option (issuer or paying account)
The remaining credit for the reimbursement contract can be repaid either by the issuer or customer from their paying account defined in the credit instalment contract.
Repayment amount can be posted with 2 possible options, if repayment posting type is defined in contract property "repayment posting type":
- Principal amount with Interest and Fee
- Principal amount with Interest
If property is not available, three different instalment operations will be posted for PRINCIPAL, INTEREST and FEE.
As a result credit instalment contract is terminated.
API links
Early Repayment Of A Credit Instalment Contract
The "Early repayment of Credit Instalment contract" API allows to make an extra payment out of regular repayment plan.
The mandatory input fields are:
- The issuer ID
- Credit Instalment Contract Reference
- Repayment Amount
- Remaining credit instalment reimbursement option (issuer or paying account)
As a result the repayment plan is recalculated (number of instalment terms is reduced).
Repayment amount is posted with 2 possible options if repayment posting type is defined:
- Principal amount with Interest and Fee
- Principal amount with Interest
Otherwise three different installment operations will be posted for PRINCIPAL, INTEREST and FEE.
API links
Transactions description generic page
Transactions description
This API allows you to provide detailed transaction data to your merchant customers. The API enables you to retrieves comprehensive transaction data based on merchant payments, contract entity and on specific periods of time.
Accounts (Features For Pre-paid and Credit Cards)
Accounts are used to process operations, manage a balance in a dedicated currency, control the credit risk, perform transaction charging, calculate interest (credit or debit), generate an invoice (statement), process payments.
Three types of account working modes are being supported; Pay Later, Pay Now, Pay Before.
- Pay Later account working mode is used to implement classical credit card products like charge cards or revolving credit. Pay later accounts are settled by a cyclic closure process and typically produce an invoice (statement) with an amount due which can represent the full or partial statement balance. Credit or debit interest algorithms may apply.
- Pay Now account working mode is used for all types of debit cards. Such accounts are typically settled in short frequencies (e. g. daily) and produce debit orders, immediately forwarded to customers’ current accounts. Interest calculation never applies.
- Pay Before account working mode is used for the wide range of prepaid card products. The balance is always positive.
The below diagram presents different use cases covered by the API in the account domain.
Our issuing use cases
Customer
A customer is a person who has subscribed to services offered by the issuer
A customer can have multiple roles and can be:
- the owner of the contract
- the Cardholder,
- the owner of the account
Note that only relevant client information necessary for our processing, and customer communication on behalf of the issuer, is managed.
- Customer data (last name, first name, etc) related to a person or to a company
- Multiple addresses management
- including temporarily address management
- Address usage : card and PIN delivery, statement, client communication (letters, calls/ customer services
Several APIS are provided in order to manage the customer and their addresses as illustrated below:
