Card control

Read more about Card control

Card Control enables the cardholder to manage his card in real-time. Cards can be managed via the banking app or online banking through our APIs

The cardholder knows best his habits and preferences for card usage. Card Control allows him/her to customize a card in different aspects. Some examples: set card limits on different channels – in-store/online/contactless payments, cash withdrawals at ATM. As well it is possible to block chosen payment channels or certain merchant categories (e.g., casinos, liquor store, etc.). Geographical reach can also be controlled: countries can be blocked or enabled for card payments. All the mentioned features can be set for a specific period of time. Altogether, a variety of features and its combination provide a detailed customization.

Thanks to a comprehensive customization, Card Control becomes a first step towards risk mitigation. Through spending limit management, country and merchant category blocks, spend notifications, etc. the cardholder gets alert about fraudulent activities and can prevent it. Next to this, extensive card self-management options lead to fewer disputes and a lower number of calls to the customer care center.

The cardholder loses a physical card. He/she opens the banking app and blocks the cards easily.

A new card is issued instantly. The cardholder customizes it by setting spending limits, blocking some merchants and activating notifications?

The cardholder is getting ready for a trip. Before travelling, he/she activates payments by his/her card in specifi countries.

How it works ?

Card Control allows the cardholder to personalize his card overriding the issuer specific standard settings. The customization is achieved by updating and overriding cards authorization restrictions and velocity limits.

Each authorization restriction override is based on an existing authorization restriction. First step is to retrieve the authorizationRestrictionReference through the list of existing authorization restriction by calling the API List of authorization restriction for account. Second step is to modify the authorization restriction using the API Create authorization restriction override. The override created could be then updated using the appropriate API.

Similar process applies to velocity limits. A default velocity limit could be overwritten by Velocity limit overrides API that allows to modify number and amount of authorizations allowed for a specific time period. The override created could be then updated and deleted using the appropriate API.

Merchant management (old version)

Technical Description

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.

View Documentation

Read more about Merchant management (old version)

Accounts

Read more about Accounts

Accounts (Features For All Card Types)

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

Read more about ob-p-ideal-notification

Notification API

for iDEAL 2.0

API Reference

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

Orange fields: mandatory for an iDEAL payment
Purple fields: conditionally mandatory for an IDEAL payment

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

Orange fields: mandatory for an iDEAL payment
Purple fields: conditionally mandatory for an IDEAL payment

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

Read more about Event Stores

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

GET api/v2/issuers/{issuerId}/businessRefType/{businessRefType}/businessRefValue/{businessRefValue}/event-stores

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

POST api/v2/issuers/{issuerId}/event-stores/search

Transactions doc

Read more about Transactions doc

API reference Accept transactions doc Merchant payments 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

Read more about Credit Instalment Management

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

POST/api/v2/issuers/{issuerId}/credit-instalments/simulate

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

POST/api/v2/issuers/{issuerId}/credit-instalments/

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

POST /api/v2 /issuers/{issuerId}/credit-instalments/{creditInstalmentReference}

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

POST /api/v2/issuers/{issuerId}/credit-instalments/{creditInstalmentReference}/cancel

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

POST/api/v2/issuers/{issuerId}/credit-instalments/{creditInstalmentReference}/activate

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

GET /api/v2/issuers/{issuerId}/credit-instalments/

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

GET /api/v2/issuers/{issuerId}/credit-instalments/{creditInstalmentReference}

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

POST /api/v2/issuers/{issuerId}/credit-instalments/terminate-all

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

POST /api/v2 /issuers/{issuerId}/credit-instalments/{creditInstalmentReference}/terminate

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

POST /api/v2 /issuers/{issuerId}/credit-instalments/{creditInstalmentReference}/repay

Transactions description generic page

Read more about 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.

Benefits for you!

Complete

Provide your merchants with the details of every merchant payment.

" "

One location

Present the merchant payment and the transactions on one location.

" "

Own environment

Present transaction data in your own app or portal based on your own client data.

" "

Accounts (Features For Pre-paid and Credit Cards)

Read more about Accounts (Features For Pre-paid and Credit Cards)

Accounts (Features For Pre-paid and Credit Cards)

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.