Captures (v1.0.3 update ongoing)

Currently the following 4 Capture stage actionTypes are supported within the Accept Transactions API.

actionType definitions

Capture Request

In Card Not Present it is common to use two separate steps (actionType AUTH and actionType CAPTURE) to complete a Service Purchase and Service Refund. The AUTH actionType is typically used by the Merchant in a Purchase service to reserve the funds at the cardholder when the goods are bought in the webshop. The CAPTURE actionType is typically used when the goods are shipped to request the funds.

The requestor must send in the capture request to complete the transaction and receipt of money. In a capture request the following data elements may be present.

Request actionType CAPTURE

Captures should be repeated until a response is received. When a capture is repeated, it should have the same actionId as the original capture request so that Worldline can detect duplicates.

If you have not received a Capture response after 3 attempts, please contact Worldline FS support or your bank depending on the agreements in place.

Capture Response

In a capture response message, the following data elements can be present.

Response fields to CAPTURE actionType

Multiple Partial Captures (Capture_Split)

A CAPTURE can be split into multiple partial CAPTURES e.g. in case the goods are delivered at multiple intervals in time. Each partial CAPTURE must contain the sequenceNumber. By the last partial CAPTURE it is mandated to send in the sequenceCount of the number of Partial Captures.

Request actionType CAPTURE_SPLIT (multiple partial captures)

Authorization and Capture

In some cases such as with a Refund, the Merchant may want to request both Authorization and Capture steps at the same time.

The request must then include the actionType “AUTH_AND_CAPTURE”, and the other mandatory and conditional authorization fields described under actionType AUTH.

Request actionType AUTH_AND_CAPTURE fields

Disclaimer

The Open API specification is leading for integrations purposes. The Accept Transactions API documentation provides guidance on what is to be sent in for a particular transaction acceptance request (use case, action, brand, MCC, etc.).

The developer portal documentation does not provide a comprehensive set of rules and regulations on what request call body to send into the Accept Transactions API. To stay compliant and avoid data integrity issues, always consult the Card scheme processing rules. In addition, always consult your regulatory rules and regulations (for example consult the European Banking Authority websites for latest PSD II and SCA rules).

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.

WL FS Acquiring Merchant Contract hierarchy:

• Level 1: Acquirer (determined by the users access credentials)
• Level 2: Holding
• Level 3: Merchant (can be grouped)
• Level 4: Contract
• Level 5: Site (sub-Merchant, URL, Location)
• Level 6: Terminal

Merchant management calls

The WL FS merchant contract API enables retrieval and updating at all contract hierarchy levels. For third parties, contract updating is limited depending the generic user role (e.g. PSP, PayFac, Merchant) limitations agreed with the acquiring bank.

You can retrieve data by providing key parameters (e.g. contractId, siteId, terminalid), and other search criteria such as IBAN.

There are two types of GET METHOD Contract calls:

• GET calls to search (e.g. GET Holding List, GET Merchant List, GET Contract List, GET Site List, GET Terminal List) using one or more query parameters. Valid calls return a list with limited data.
• GET calls to retrieve a specific entity return part of a contract entity (e.g. holding, merchant, contract, site, terminal).

In addition to retrieval, there are several METHODs which allow for contract Updating of own merchant contract data:

1. Use POST call for adding a new contract entity (e.g. site, terminal).
2. Use PATCH calls to change an existing contract call entity (e.g. addresses).
3. Use DELETE calls to terminate (block) a contract call entity (e.g. site, terminal).

Parameters in bold are mandatory to complete a call.
To ensure best search call response time please use as many parameters as available.

Worldline Sandbox - Example set-up Payment Facilitator merchantId

Authorizations (v1.0.3)

Currently the following 6 Authorization stage actionTypes are supported within the Accept Transactions API.

actionType definitions

Key Topics Authorizations

CardholderVerificationMethod and 3DSecure

SCA Exemptions and Merchant Initiated Transactions

Tokenization

Optional Transaction References

Payment Facilitator

Authorization Response

Service Account_Verification

Authorization requests - Basic mandatory

Basic mandatory Card Not Present Authorization request message fields for actionTypes AUTH and PREAUTH are listed in table below.

Request actionType AUTH - Basic mandatory fields

Cardholder Verification Method and 3DSecure

The Accept Transactions API supports two types of Cardholder Verification Methods: CCV2 and 3DSecure.

According to European Banking Authority (EBA) Payment Service Directive (PSD) 2, Strong Customers Authentication (SCA) is mandated for cards issued within the EEA.

Standard Cardholder Verification Method in EEA is to use EMV 3DSecure for accepting card transactions.

Cardholder Verification Method CCV2 does not qualify as SCA.

Some types of transactions may be exempted from the EBA SCA rule.

Request actionType AUTH - Cardholder Verification Method and 3DSecure fields

SCA Exemptions and Merchant Initiated Transactions

According to EBA PSD2, Strong Customers Authentication is mandated for cards issued within the EEA.

Under SCA-rules exemptions are possible for e.g. low value payments or Merchant Initiated Transactions.

Request actionType AUTH - PSD2 SCA Exemptions, Merchant Initiated Transactions, Tokenization, Card-On-File Initiation

In case of SCA exemption, the Accept Transactions API authorization must include in the scaExemptionCause field for which exemptions/exclusion reason is applied.

For transactions in scope of the SCA rule, the issuer decides on the need for SCA. When an acquirer requests authorization without prior SCA, the issuer may decline indicating SCA is needed (response code 65: soft decline). For example, when the acquirer requests SCA exemption for Low Value Payment, the issuer may decline the authorization because the limit is reached of consecutive payments without SCA.

After a soft decline, the merchant should initiate a 3DS authentication request. In this authentication request the merchant should indicate that the SCA is mandated. After successful authentication, the merchant can send a second authorization request. The second authorization request is a new authorization request and not a follow-up on the first authorization request (i.e. the second request makes no reference to the first request).

Disclaimer: The explanation found on this developer portal about SCA and SCA exemptions is not a comprehensive set of rules. Always consult the Card scheme rules for detail on card processing according to SCA-rule and SCA exemptions. Consult the European Banking Authority (EBA) websites for latest PSD II and SCA rules.

Merchant Initiated Transactions

The Accept Transactions API can accept Merchant Initiated Transactions (MIT). MIT are payments initiated by the merchant without the interaction of the payer.

Such payments require that:

1. SCA is applied to the first transaction action mandating the Merchant to initiate payment(s) and
2. There is an agreement between the payer and the merchant for the provision of products or services and potential costs associated with these. Such payments can happen in the following cases:
   • Recurring Payments for fixed or variable amounts
   • Merchant funded installments
   • The final amount is higher than the amount used at authentication time. This can happen when additional charges are added to the initially agreed amount such as, a minibar in a hotel or fines with a rented car

Acquirers subject to PSD2 SCA are only allowed to apply Merchant-Initiated Transactions (MIT) when:

• The transaction is triggered by the merchant and the cardholder is typically off-session (off-session means the cardholder is no longer interacting with the merchant page or the merchant app), or
• The transaction is triggered by the merchant, as it could not have been triggered by the cardholder during checkout

Some examples:

• The final amount is not known during the checkout (for example, online groceries shopping)
• An event triggered the transaction after the checkout (for example, miscellaneous rental or service charges)
• The transaction is part of a recurring payment arrangement
• The transaction is broken down into different payments happening at different times (for example, installments, travel bookings, market places)

The field initiatorType should be used to indicate if the transaction is merchant initiated or cardholder initiated. If a cardholder initiated transaction is followed by a (series of) merchant initiated transactions, the field mitCause should be used to specify the type of MIT transactions for which the CIT transaction gives a mandate. The MIT-transactions must reference the CIT transaction with the field schemeTransactionId.

The mandatory field cardholderVerificationMethod should be set to "none" in case of a MIT-transaction.

Tokenization

The Accept Transactions API can accept the scheme token in field PAN and scheme dynamic cryptogram in field tavvData.

Card scheme network tokenization is the replacement of the cardholder’s primary account number (PAN) with an alternative number, referred to as a token.

Use of tokens reduces the risk of fraud in case of data breaches as the PANs are no longer stored. Tokens are used in various places such as wallets, but also by merchants who want to store the cardholders credentials (card-on-file). Tokens can be used in eCommerce transactions in the same way PANs are used. The number of digits of a Token is directly related to the number of digit of the PAN, e.g. a 16-digit token is created for a 16 digit PAN.

When used by merchants, tokens are unique to a merchant. To improve security, tokens are accompanied by a dynamic cryptogram (tavvData attribute in the Accept TRX API). Only the correct merchant can request a cryptogram associated with a unique token, and cryptograms may only be used once. The presence of the cryptogram in the authorization request helps the card scheme to verify that the transaction originated from the correct merchant.

Optional Transaction References

To facilitate tracking some additional PSP and merchant transaction references are available.

In case of a Refund the orginalTransactionId of the Purchase should be included to help connect the two transactions.

Request actionType AUTH – Optional transaction references

Payment Facilitator

In case of a Payment facilitator, the following acceptor fields are scheme mandated to be sent in for an authorization.

Request actionType AUTH - Payment Facilitator mandatory fields

Authorization request response

In an (pre-)authorization response message, the following data elements can be present.

Response fields request actionType AUTH and PREAUTH

Authorization Reversal

The Authorization follow-up actions AUTH_REVERSAL (full reservation amount) and AUTH_REVERSAL_PARTIAL (part reservation amount) are used to reverse the effect of the authorization and release the funds reserved with an authorization request.

After a transaction is captured, the authorization may no longer be reversed. Instead (e.g. customer returns goods) a refund should be used to credit the cardholder.

Cancellation

When a previously requested authorization is no longer needed use an authorization reversal request for the full amount. This is to ensure an accurate open-to-buy balance of the cardholder.

For an Authorization cancellation use the transactionId as identifier for the transaction lifecycle for which the requestor is trying to release the funds.

Technical reversal

When no response is received to an AUTH or PREAUTH action due to a technical reason (e.g. timeout), the requestor should send in a follow-up action to REVERSE (e.g. actions AUTH_REVERSAL) using the original actionType originalActionId (of e.g. original AUTH).

Request actionType AUTH_REVERSAL and AUTH_REVERSAL_PARTIAL

Pre-Authorization

The pre-authorization request is sent in using actionType PREAUTH, service Purchase, and the other mandatory & relevant conditional authorization fields described under actionType AUTH.

The actionType PREAUTH must be used when the transaction amount is not known at the time of authorization. Pre-authorizations are typically used in hotel and the car rental sector.

Depending on scheme rules for some brands (e.g. Maestro) pre-authorization should be used when the amount is known at authorization, but the transaction may possibly not be completed for other than technical reasons. For instance, the products ordered by the cardholder may turn out to be out-of-stock.

Extend Pre-Authorization period

For Mastercard Pre-Authorization period (default is 30 days) can be extended with 30 days using an actionType AUTH_INCREMENTAL with requestAmount set to "0". For VISA Pre-Authorization period (default is 30 days) can be extended using an actionType PREAUTH resubmission using MIT with correct mitCause.

Request actionType PREAUTH

(Pre-)Authorization incremental

The pre-authorization amount can be increased by sending in an follow-up request using the actionType AUTH_INCREMENTAL, the transactionId (lifecycle) from the initial PRE_AUTH request response, the additional requestAmount and the other mandatory fields of the AUTH actionType. For example, a hotel may need to increase the authorization amount due to minibar usage or a 1 day longer stay.

If the Purchase is later CAPTURED, the capture requestAmount must not exceed the accumulated authorization amount.

Extend Pre-Authorization period

For Mastercard Pre-Authorization period (default is 30 days) can be extended with 30 days using an actionType AUTH_INCREMENTAL with requestAmount set to "0". For VISA Pre-Authorization period (default is 30 days) can be extended using an actionType PREAUTH resubmission using MIT with correct mitCause.

Request actionType AUTH_INCREMENTAL

Authorization and Capture

In some cases such as with a Refund the Merchant may want to request both Authorization and Capture steps at the same time.

The request must then include the actionType “AUTH_AND_CAPTURE”, and the other mandatory and conditional authorization fields described under actionType AUTH.

Request actionType AUTH_AND_CAPTURE fields

Account Verification

The account verification service (or account status inquiry as it is called by Mastercard) can be used to check that the cardholders account is open and can be used for future transactions. The account verification has no financial impact, i.e. no funds are reserved (requestAmount is absent).

The merchant must send in an request with actionType “AUTH”, service “AccountVerification”, the “requestAmount” left out, and the other mandatory and conditional authorization fields described under actionType AUTH.

The account verification can be used in various situations but is also often used when not only the status of the account is checked but also the cardholder needs to be authenticated such as:

• To establish a recurring or bill payment relationship
• To store the cardholder’s credential on file for use in future transaction

Disclaimer

The Open API specification is leading for integrations purposes. The Accept Transactions API documentation provides guidance on what is to be sent in for a particular transaction acceptance request (use case, action, brand, MCC, etc.).

The developer portal documentation does not provide a comprehensive set of rules and regulations on what request call body to send into the Accept Transactions API. To stay compliant and avoid data integrity issues, always consult the Card scheme processing rules. In addition, always consult your regulatory rules and regulations (for example consult the European Banking Authority websites for latest PSD II and SCA rules).

Accept Transactions (v1.0.3)

This API enables you to Accept transactions for your Merchant customers.

Transactions are accepted via a host-to-host connection between the API user and Worldline FS API GateWay. The Worldline FS API GateWay is connected to the Worldline FS acceptance host, which in turn is connected to the Issuer network.

There is 1 POST Transaction request call and 1 POST Transaction request response field set.

How to use acceptance actions?

Each POST transaction request actionType is a partial on the full Transaction request field set. The POST Transaction request mandatory parameters depend on the actionType the user is requesting as explained in the specifications.

A valid POST transaction request must include:

1. the unique actionId in UUID format;
2. the minimum mandatory fields to perform a basic actionType (AUTH, CAPTURE etc.) for the service (e.g. Account Verification, Purchase, Refund);
3. if applicable, include Additional data (e.g. Card-On-File, MCC specifics such as Additional Merchant data and Airline Addendum..).

A follow-up action such as a CAPTURE must also include the transactionId (lifecycle) returned by the Worldline FS host in the approved initial authorization (AUTH and  PREAUTH actionType) request response. Exception is a technical reversal (e.g. timeout) as explained in actionType AUTH_REVERSAL where only the originalActionId is available.

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

For Purchase and Refund services available actions are:

• AUTH
• AUTH_REVERSAL
• CAPTURE
• AUTH_AND_CAPTURE
• CAPTURE_SPLIT (partial capture)

Actions under development are:

• PREAUTH
• AUTH_REVERSAL_PARTIAL
• AUTH_INCREMENTAL

Actions on the roadmap are:

• AUTH_UPDATE
• PAYOUT (OCT)

actionType definitions

Example transaction request actionType AUTH for Mastercard

{
  "actionType": "AUTH",
  "service": "Purchase",
  "identification": {
    "requestorId": "1157",
    "actionId": "e9bd7129-7377-4d1a-9c91-5abdfeaba145",
    "acquirerId": "315000001",
    "cardAcceptorId": "90100110"
  },
  "financial": {
    "requestAmount": {
      "amount": "23.32",
      "currency": "EUR"
    }
  },
  "circumstance": {
    "actionDateTime": "2022-07-28T13:06:12+02:00",
    "channel": "ECommerce"
  },
  "acceptor": {
    "merchantCategoryCode": "7999",
    "name": "Home Festival",
    "address": "Eendrachtslaan 315",
    "postalCode": "3526LB",
    "city": "Utrecht",
    "state": "NL",
    "countryCode": "NLD"
  },
  "card": {
    "cardNumber": "5413330089600010",
    "expiryDate": "2512"
  },
  "3DSecure": {
    "result": "Full",
    “dsTransactionId”: "4c754b56-c6c0-468b-bfc9-905ceab69618"
    “version”: "V2"
    “authenticationValue”: "lChDPlIS2WTc/PNfk0LoeYI/hYy="
    “dsEci”: "02"
    “subversion”: "2"
  }
}

Disclaimer

The Open API specification is leading for integrations purposes. The Accept Transactions API documentation provides guidance on what is to be sent in for a particular transaction acceptance request (use case, action, brand, MCC, etc.).

The developer portal documentation does not provide a comprehensive set of rules and regulations on what request call body to send into the Accept Transactions API. To stay compliant and avoid data integrity issues, always consult the Card scheme processing rules. In addition, always consult your regulatory rules and regulations (for example consult the European Banking Authority websites for latest PSD II and SCA rules).

The data model used in our system is represented as follows :

The different resources are described below :

Account ➔

Accounts manage monetary operations, balances and restrictions, and are typically assigned to account owners. An account owner is typically an individual, or a legal entity, who has signed a contract with an issuing institution, so a customer.

Accounts 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.

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, and could be used in several ways according to the purpose for which the address is used, as example for statement sending or card delivery.

Authorization ➔

Authorizations are request message from a connected scheme which are processed by our authorization server. Based on several business rules (e.g. card status, velocity limits check ...) the authorizations could either be accepted or declined.

Authorization Business Case ➔

An authorization business case can refer to one or several consecutive Authorizations (for example, a reservation in a hotel with a subsequent confirmation or a purchase with a subsequent cancellation).

Authorization Restriction ➔

The card usage can be restricted using multiple criteria, such as transaction type (ecom, ATM), acceptance domain (allowed regions), active start and end date.

Authorization Restriction Override ➔

Restrictions are either enabled or disabled by default and can be overridden.

Customer ➔

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

Contract ➔

Contract refers to the Customer contracts created in our solution. The contract is the link between cards, accounts and customer data. The contract inherits default value from Product with the possibility to override  some specific parameters, such as fees, terms and conditions, credit limit, card layout reference.

Card Contract ➔

A Card Contract represents a single card owner by a cardholder and is linked to a card profile which defines all allowed business rules (e.g. replacement, renewal) and card properties (e.g. chip data) required to create a card. Under a card contract the first card is created and all next cards in case of automatic renewals, card replacements.

Card ➔

A card is a payment mean that enables a customer to access funds or make purchases against a line of credit. Cards can have different technologies (EMV, Magnetic Stripe, Contactless), could be physical or virtual.

Order ➔

An order refers to card order and PIN mailer data extractions that are sent to card producer and PIN mailer editors respectively.

Operation ➔

Operations can be transactions received from clearing or internal generated operations ( e.g. fees, refund, chargeback...)  that are posted on accounts.

Temporary Credit Limit ➔

A temporary credit limit, that extends or reduces the account credit limit could be defined at account level. In this case, the value of the temporary limit override the content of the normal credit limit.

Velocity Limit ➔

The velocity limit is a restriction based on usage frequency and the total amount on the card account. 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 500€ per day on POS terminals in Europe.

Velocity Limit Override ➔

On account level the defaults can be overridden. Overriding can be timely restricted by providing an activation period.

The different resources are identified by corresponding references.

References can be internal, which means generated by our system and transmitted to the issuer.

WL supports also the usage of external references that means the bank provides us the value; this implies that the generation of this identifier follows rules shared by WL (unicity of the reference).

External references must be provided generally during the resource generation such as for:

• External contract reference during contract creation

• External card reference during card creation

• External account reference during account creation

Please find below a table illustrating the resources for which external reference is allowed.

A quick tour of Worldline Card Issuing

Worldline Card Issuing includes all the core features enabling to instantly issue cards and process payments : 

• Issue any type of card : debit, credit, pre-paid whatever its form physical/virtual,

• Authorize and process transaction efficiently thanks to a proven technology already processing more than 10 billions of transactions a year

• Launch a new product on international schemes but also on local ones, Wordline Card Issuing being GLOCAL ! 

• Embrace the wallet revolution by having the possibility to tokenize you card portfolio and make it compatible with mobile wallet providers

• Manage disputes and initiate chargeback to a merchant in line with the schemes’ rules and regulation.

Creating and managing your cards portfolio using Worldline Card Issuing will follow 4 main steps that can be easily done through our powerfull REST/json APIs.

Authentication

Worldline APIs require authentication on all endpoints and methods.

We currently support one Authentication scheme:

• Bearer Token (OAuth2 - Client Credentials)

Bearer Token

Bearer tokens are temporary security credentials that can be used to authorize 'third parties' (bearers) access to the Worldline API.

These tokens are created by calling the accesstoken endpoint.

Once created the token field must be used in the HTTP Authorization header using the Bearer scheme.

Example HTTPS request with a bearer token in Accept Transactions API

GET /v1.0/acquiring/transaction/acquirers/{acquirerId}/transactions HTTPS/1.1

Accept: application/json

Authorization: Bearer fsdfdsfdsfdsfs9857958hjiIsInR5cCI6IkpXVCJ9

Create Bearer Token - OAuth2 Client Credentials

The Client Credentials grant type is used by clients to obtain an access token outside of the context of a user.

The OAuth 2.0 client credentials grant flow permits an API (confidential client) to use its own credentials, instead of impersonating a user, to authenticate when calling another API.

Steps to obtain an Access token

Step 1: Construct a Basic Authentication header using the following values shared by Worldline team.

Step 2: Construct a valid HTTP Basic Authentication header as follows in pseudo-code.

const consumerKey = "jhfrjh881wtRxgregegegggeg";

const consumerSecret = "wfrregergjbD6rNxregregerg";

const authnValue = "Basic " + base64Encode(consumerKey + ":" + consumerSecret);

request.setHeader("Authorization", authnValue);

Step 3: Call the rest endpoint of Oauth2 client credentials to obtain the access token.

POST oauth/client_credential/accesstoken?grant_type=client_credentials HTTPS/1.1
Accept: application/json
Authorization: Basic jfvwrjfbrkfbrkbrglenglengelgnegnejwvfwejhf==

The call Response contains the Bearer Access token. Use this token to call the Actual resource.

Example POST call response - field access_token

{
    "refresh_token_expires_in": "0",
    "api_product_list": "[coffea]",
    "api_product_list_json": [
        "coffea"
    ],
    "organization_name": "$organization_name",
    "developer.email": "$Developermail",
    "token_type": "BearerToken",
    "issued_at": "1678146804722",
    "client_id": "jhfrjh881wtRxgregegegggeg",
    "access_token": "Knk9uvvoSALfzo3AGDADzGJ0Ayl1",
    "application_name": "4a319510-0793-4332-9627-452ae6a70c1d",
    "scope": "",
    "expires_in": "3599",
    "refresh_count": "0",
    "status": "approved"
}