Developer Portal Resource User Guide (delete)

Resource Description

Issuer


Issuer Product


Contract

Contract refers to the consumer and corporate contracts created in OPC (Offers, Products & Contracts) service using the provided product as template for the structure and default values. Products are built from Account and Card Templates, Profiles and Add-on services.


Contract Saving Measures

Saving measures are activated and deactivated on a contract for risk management purposes. They are used to close online services through authorization methods, lower Online Limits, update authorization methods with immediate payment mode to set the Force Account Check, switch account card payment from deferred to immediate payment mode, forbid cards delivery, block EMV Card Applications, put under control EMV Card Applications, deactivate Contactless Cards.


Card Contract

A card contract can be created for a card holder or as an anonymous contract. When creating a card from a card contract, a number of parameters are calculated based on the settings in the card profile, the selected models and the card contract.


 

Card

A card let cardholders access funds in checking or savings accounts or make purchases against a line of credit. Card types are being defined by a card schemes and a brand (e. g. Visa Classic Card, Visa Gold Card, MasterCard Standard, MasterCard Gold).


Card Order

An order refers to Card Order and PIN Mailer data extractions that are sent to Card Producer and PIN Mailer Editors respectively.


Customer

A customer is a person (individual) or a company who has subscribed to services offered by the issuer.


Customer Address

A customer Address is the generic term for postal address, email address or phone number. 

Addresses can be of two types; Personal Address or Company Address.

Addresses could get multiple usages describe which address is used and in which service. These usages are defined in the corresponding service; Account Service (Statement Sending, Invoice Sending) and Card Service (Virtual Card Sending, Card Delivery, PIN mailer Delivery, Activation Mode Delivery).


Account

Accounts are independent from any payment mean. They are used to process operations, manage a balance in a dedicated currency,  control the credit risk, perform transaction charging, calculate interests (credit or debit), generate an invoice (statement), process payments. Three types of accounts working modes are being supported; Pay Before, Pay Now, Pay Later.

Accounts are linked to form a hierarchy in order to set up multi-purpose products (mixture of debit and credit accounts), represent organizations (families or corporate structures), set up multi-currency accounts. Credit risk verifications can be expanded across the hierarchy. Consolidated invoicing and payment management is done on top level account for accounts lower in the hierarchy.


Account Authorization Restrictions 

The purpose of a restriction is to allow or refuse a transaction based on given rules. These rules are
implemented with an initial customer specific setup in Worldline Pay Front Office. Like this, a set of customer
specific standard restrictions can be implemented. The standard restrictions are permanently, but can be
changed, i.e. overwritten by using the Card Control API.
The approval and the refusal of transactions are managed by turning on or off - or by blocking or unblocking -
the concerned standard restriction.


The standard restrictions for Card Control are to block or unblock of :

  • cards temporarily or permanently
  • channels like
    • ATM / cash
    • card present (POS)
    • card not present (eCommerce, telephone)
    • card not present recurring
    • contactless online (NFC online)
    • magstripe
  • a single country, a list of single countries
  • regions (Geo Blocking)
  • merchant category codes (MCC Blocking)

It is also possible setup a mix of restrictions in WLP-FO, e.g. block or unblock ATMs in South Africa.

Each of these standard restrictions is per default set as blocked or unblocked, depending on the customer’s
need.


Each of the listed standard restrictions can be blocked or unblocked by calling the appropriate web service of
the Worldline Premium Gateway API. If the user e.g. blocks a card by using the appropriate web service, the
card is blocked immediately and without an end date.


Account Authorization Velocity Limits

The purpose of a velocity limit is to limit a transaction in terms of amount and frequency, e.g. it might be
allowed to withdraw 2,500€ per day on POS terminals in Europe.
The velocity limits are implemented with an initial customer specific setup in Worldline Pay Front Office. Like
this, a set of customer specific standard velocity limits can be implemented. The standard velocity limits are
permanently, but can be changed, i.e. overwritten by using the Card Control API.
The standard velocity limits for Card Control are

  • Cash (ATM, branch, POS)
  • eCommerce
  • POS
  • NFC

Depending on the customer’s need, each of the standard velocity limits is set per default with

  • a minimum amount and a flag, if this amount should be checked
  • a maximum amount and a flag, if this amount should be checked
  • a maximum counter and a flag, if this amount should be checked

A default velocity limit can further be combined with a country or a region, e.g.

  • ATM daily limit in the Netherlands
  • ATM daily limit in the Europeen Economic Area (w/o the Netherlands)
  • ATM daily limit worldwide (w/o the EEA)

Account Authorizations

Authorizations are approvals from a card issuer that the cardholder has sufficient funds to cover the cost of the transaction.


Account Credit Limit

Credit limits are applicable to Pay Later account types. A credit limit is the maximum amount of money an account owner can borrow. An account will typically have a single overall credit limit that restricts the total amount of unsettled activity permitted against the account.


Account Credit Installement Contract


Account Operations

Operations are posted on accounts, It could be clearing transactions, internal fees and interests, refund and redebits from Dispute management.


Account Statements


Dispute

Dispute cycle management provides the full life cycle management and organization of disputed transactions. A transaction can be disputed for a number of different reasons, such as when a cardholder detects that the transaction has been executed twice, when he does not recognize the transaction on his statement, or when services for the transaction were not delivered.

test

Enable "on this page" menu on doc section
On

Instant Issuing

Instant Issuing

Issue and activate virtual cards instantly. This will allow the cardholder to start using cards straight after opening an account or in a card replacement event, such as stolen or lost card.

A virtual card is fully compliant and can be used for shopping online. As well it can be tokenized and enrolled into ApplePay, GooglePay or other xPay wallets, and used in-store.

Choosing Worldline Card Issuing – a fully digital card issuing solution – eliminates card waiting time for your cardholders and allows you to cut costs on physical card production and shipping.

bullhorn

The customer installs a mobile app. After digital self enrollment and authentification, a virtual card can be requested

euro

Virtual card is issued and pushed to the app with all relevant data : PAN, the expiry date, etc.

consumer

The cardholder can use a new card immediately for shopping online or enroll it into Google Pay/ Apple Pay/XPay and use it in-store

How it works

 

Ask for contract & card creation using createConsumerContract API, the card manager will create the contract,  the account hierarchy, the cardholder and the first card according to the configured templates. The response to the createConsumerContract call will contain data regarding the Contract, the Account and the Card. Second step is to use the relevant card reference received for activateCard API call, the card activation instruction will be forwarded to all relevant applications (ie card manager, authorization system… ), from now on the card is ready to be used.

About us

About us

As Europe’s leading payment service provider, Worldline Financial Services combines long-standing proven expertise in traditional mass payment systems (issuing, acquiring, intra- and interbank payment processing) and innovative e-commerce and mobile payment solutions. We provide Europe’s most extensive end-to-end service portfolio both for payments and card transactions and offer cross-border availability of value-added services for banks, financial institutions and corporates.

Our company was created by a merger between Worldline’s Financial Processing & Software Licensing activities in France, Benelux and Germany and Equens, both prominent experts in the cards and payments industry. Building on more than 50 years of experience and proven track records, we can ensure that you are entrusting your payment services into knowledgeable hands.

We invest extensively in the industrialization of our platforms to support excellent operation of critical payment infrastructures. We also invest in new and innovative solutions, such as instant payment initiatives, contactless and m-payment solutions for banks (e.g. wallets and card analytics) and digital identity services. Undertaking ambitious R&D activities, we accelerate your time-to-market and digital transformation, allowing you to cater for the shifting needs and increasing demands of your customers.

Our unparalleled European footprint allows us to achieve economies of scale and benefit from synergies, making us a cost-efficient and competitive business partner for seamless, secure and efficient payment solutions.
Lower your costs and improve your service with our industry-leading processing platforms, full European market coverage, and client-focused services. With our distinctive, leading position in the market, you can rely on us. Sound solutions, solid results.

Enable "on this page" menu on doc section
On

Merchant management

Technical Description

The WL FS Merchant Contract API enables retrieval and updating at all contract hierarchy levels. 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.

 

Production release of Merchant Contract API version 2.0.4 was on 18-11-2024.

#version 2.0.4 (15-07-2024)

- Add field visaEnablerVerificationValue to existing calls:

  • GET /acquiring/contract/v2.0/acquirers/{acquirerId}/sites/{cardAcceptorId}
  • GET /acquiring/contract/v2.0/acquirers/{acquirerId}/contracts/{contractId}/sites/{siteId}
  • PATCH /acquiring/contract/v2.0/acquirers/{acquirerId}/contracts/{contractId}/sites/{siteId}
  • POST /acquiring/contract/v2.0/acquirers/{acquirerId}/contracts/{contractId}/sites
  • GET /acquiring/contract/v2.0/acquirers/{acquirerId}/sites/{cardAcceptorId}/terminals/{terminalId}
  • GET /acquiring/contract/v2.0/acquirers/{acquirerId}/contracts/{contractId}/sites/{siteId}/terminals/{terminalId}
  • PATCH /acquiring/contract/v2.0/acquirers/{acquirerId}/contracts/{contractId}/sites/{siteId}/terminals/{terminalId}
  • POST /acquiring/contract/v2.0/acquirers/{acquirerId}/contracts/{contractId}/sites/{siteId}/terminals

- Add header field includeTerminated to all GET calls

- Add field commencementDate to responses of the following calls:

  • GET /acquiring/contract/v2.0/acquirers/{acquirerId}/contracts
  • GET /acquiring/contract/v2.0/acquirers/{acquirerId}/sites
  • GET /acquiring/contract/v2.0/acquirers/{acquirerId}/terminals

 

#version 2.0.3 (21-02-2024)

- Add field visaMerchantVolumeIndicator to existing calls:

  • POST /acquiring/contract/v2.0/acquirers/{acquirerId}/merchants
  • GET /acquiring/contract/v2.0/acquirers/{acquirerId}/merchants/{merchantId}
  • PATCH /acquiring/contract/v2.0/acquirers/{acquirerId}/merchants/{merchantId}

- Add fields matTransactionLimitContactless and matCardholderVerificationLimit to existing calls:

  • GET /acquiring/contract/v2.0/acquirers/{acquirerId}/contracts/{contractId}/brands
  • PATCH /acquiring/contract/v2.0/acquirers/{acquirerId}/contracts/{contractId}/brands
  • GET /acquiring/contract/v2.0/acquirers/{acquirerId}/sites/{siteId}/brands
  • PATCH /acquiring/contract/v2.0/acquirers/{acquirerId}/sites/{siteId}/brands
  • GET /acquiring/contract/v2.0/acquirers/{acquirerId}/sites/{siteId}/terminals/{terminalId}/brands
  • PATCH /acquiring/contract/v2.0/acquirers/{acquirerId}/sites/{siteId}/terminals/{terminalId}/brands

 

#version 2.0.2 (28-06-2023)

- New Calls based on cardAcceptorId:

  • POST /acquiring/contract/v2.0/acquirers/{acquirerId}/sites
  • GET /acquiring/contract/v2.0/acquirers/{acquirerId}/sites/{cardAcceptorId}
  • DELETE /acquiring/contract/v2.0/acquirers/{acquirerId}/sites/{cardAcceptorId}
  • PATCH /acquiring/contract/v2.0/acquirers/{acquirerId}/sites/{cardAcceptorId}
  • GET /acquiring/contract/v2.0/acquirers/{acquirerId}/sites/{cardAcceptorId}/addresses
  • PATCH /acquiring/contract/v2.0/acquirers/{acquirerId}/sites/{cardAcceptorId}/addresses
  • POST /acquiring/contract/v2.0/acquirers/{acquirerId}/sites/{cardAcceptorId}/terminals
  • GET /acquiring/contract/v2.0/acquirers/{acquirerId}/sites/{cardAcceptorId}/terminals/{terminalId}
  • DELETE /acquiring/contract/v2.0/acquirers/{acquirerId}/sites/{cardAcceptorId}/terminals/{terminalId}
  • PATCH /acquiring/contract/v2.0/acquirers/{acquirerId}/sites/{cardAcceptorId}/terminals/{terminalId}
  • GET /acquiring/contract/v2.0/acquirers/{acquirerId}/sites/{cardAcceptorId}/terminals/{terminalId}/addresses

- New Call:

  • POST /acquiring/contract/v2.0/acquirers/{acquirerId}/contracts/{contractId}/currencies

- Add optional contractId to SITE entity in post body

  • POST /acquiring/contract/v2.0/acquirers/{acquirerId}/sites
  • POST /acquiring/contract/v2.0/acquirers/{acquirerId}/contracts/{contractId}/sites

-Add field paymentFacilitatorName to existing calls:

  • POST /acquiring/contract/v2.0/acquirers/{acquirerId}/merchants
  • GET /acquiring/contract/v2.0/acquirers/{acquirerId}/merchants/{merchantId}
  • PATCH /acquiring/contract/v2.0/acquirers/{acquirerId}/merchants/{merchantId}

 

#version 2.0.1 (02-12-2022)

- New Calls:

  • POST /acquiring/contract/v2.0/acquirers/{acquirerId}/holdings
  • PATCH /acquiring/contract/v2.0/acquirers/{acquirerId}/holdings/{holdingId}
  • DELETE /acquiring/contract/v2.0/acquirers/{acquirerId}/holdings/{holdingId}
  • GET /acquiring/contract/v2.0/acquirers/{acquirerId}/terminals/{terminalId}/checknumbers/{checkNumber}

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.

Merchant management

Merchant management

Worldline FS Merchant Management module offers full and final merchant settlement based on Worldline FS: scheme clearing, scheme settlement files, merchant pricing engine, and merchant configuration as stored in the merchant contract system.

As trusted partner, Worldline FS manages the contract data of its clients’ customers.

  • Show merchant contract data in your application of preference.

  • Manage your own merchant contracts in real-time at all contract hierarchy levels in the merchant contract system.

  • Acquirers can allow third parties access to retrieve own merchant contract data and allow limited updating of own merchant contracts.

Benefits for you!

duim

Improve user experience

 

Provide this data in your application of preference to optimize your customer's journey.

man

Eliminate manual work

 

No need to log into the (separate) merchant portal anymore. Your customers can access the data in the application of preference

contr

Easy access to real-time merchant contract data

 

Access your customer data in your own infrastructural environment.

Who can use the API?

acq

Acquirers

 

psp

PSPs

Why use it?

Currently the merchant can only retrieve contract data via a separate merchant portal. This API enables you to present the contract data in one place. You can use specific contract management information (e.g. merchantId, contractId) to call other Worldline FS APIs.

USE CASE

Provide customers all relevant contract data in one place

lamp

Imagine that – being a client of Worldline FS – you can now show all relevant Worldline FS merchant contract information in your own application. Moreover, you can combine this data with your own contract data to provide the client with all his contract data in one place.

Update your (sub-)merchant contract data

lmp

 

As a PSP you need to update the contact details for a (sub-)merchant. With this API - being a third party customer of Worldline FS - you can update the contract details (e.g. move terminal between sites or change contact phone number) on demand ensuring they are up-to-date. This helps you ensure a speedy service to your customers and lowers costs by reducing acquirer support calls.

How it works for a PSP

Step 1

  1. Your (sub-)merchant logs in to your app or merchant portal and selects “View contract data”

  2. Your (sub-)merchant selects the data he/she would like to see

  3. Site is the contract hierarchy level of your (sub-)merchant (URL or location)

Step 2

  1. Your app/merchant portal transfers the request to Worldline FS by using GET address at siteId call

  2. The Worldline FS API returns the requested data in JSON format

  3. Your app/merchant portal reformats and presents it to your (sub-)merchant

Step 3

  1. Your merchant checks his/her information and selects "Edit" to update his/her contact details

  2. He/she updates his contact phone number and selects "Save"

  3. The contact details are sent by you via a PATCH address at siteId call to WL FS updating the details in the merchant contract database real-time

Are you looking for more information?

Where do I give feedback, report a bug, or request a change to an API?

We like to hear from you. Please use the contact form to let us know what you think of our APIs, to report a bug, or submit your request. We will get back to you straight away!

I need some help, where do I get support?

You have come to the right place for help. Search our FAQ for your question. Does this not answer your question? Please use our contact form at the bottom of the page and submit your question.

Where can I find documentation for development?

Each API has its own dedicated documentation page. On this page you’ll be able to see how the documentation work. Swagger is used to publish the documentation of the API. On each specific API page, a link to the documentation of that API is provided.

How am I notified when changes are made to the APIs?

When you are onboarded and have the API(s) in production that you want to use for your application, we make sure that you will be informed with all the information about the changes or updates and with a clear guideline how to proceed.

What types of APIs does equensWorldline offer?

We currently offer APIs for the business line Merchant payments. Browse our API pages to see all the APIs we currently offer. All APIs in our developer portal are REST APIs. On every business line page, we also demonstrate you our future APIs that we foresee to be developed in the near futur