Merchant payments

Merchant payments

This API allows you to provide detailed payment data to your customers. The API retrieves comprehensive payment data using specific criteria and periods of time.

Benefits for you!

Puzzle

Complete

 

Provide your merchants with the details of every merchant payment.

loc

One location

 

Present the merchant payment data on one location.

graf

Own environment

 

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

Who can use the API?

acq

Acquirers

psp

PSPs

merch

Merchants

Why use it?

Currently the merchant can only retrieve this payment data via a separate merchant portal. This API enables you to use certain criteria (e.g. paymentId, paymentReference, merchantHierarchyId, merchantId, contractId and iban) to call payments data.

USE CASE

Provide specific payment data on demand to your customer

lamp

A merchant would like to know what amount is funded on a particular date. The Payments API allows the merchant to search for a particular payment to its bank account using different criteria such as paymentId, data, amount, iban etc.

PaymentAmount is reconciliated at an aggregated level as TransactionTotalAmount minus the different fees categories. Using the TransactionLink in a particular payment the merchant can quickly move to the associated transactions.

Are you looking for more information?

Transactions

Technical Description

#version 2.0.2 (30-08-2023)

-Add new v2.1 Id list call, returns a list of transactions instead of 0/1 transaction

  • /v2.1/acquirers/{acquirerId}/transactions/{transactionId}

    Note: In CNP the actionType CAPTURE_SPLIT can result in multiple cleared transactions with the same transactionId. In this unique case, please differentiate between transactions using the cleared transaction acquirerReferenceNumber and Capture request fields captureSequenceNumber, actionId.

-The status of the following v2.0 Id call has changed to deprecated, please use v2.1 call.

  • /v2.0/acquirers/{acquirerId}/transactions/{transactionId}

    Note: The above deprecated v2.0 call will remain available temporarily (up to 31-10-2024) allowing clients 6 months to migrate from current v2.0 Id call to v2.1.

-Changes to search call (/v2.0/acquirers/{acquirerId}/transactions)

  • Add query parameter actionId and pspReference
  • Rename query parameter merchantTransactionRefNo to merchantReference (old one still available but deprecated)

-Add 5 new fields in a transaction response: captureSequenceNumber, captureSequenceCount, schemeMerchantId, schemeTransactionId, paymentInitiationChannel

-Changes in TransactionIdentification (part of Transaction, Authorization and Lifecycle):

  • Rename field merchantTransactionReference to merchantReference (old field is deprecated, but still available up to 31-10-2024)
  • Add field actionId, pspReference, retrievalReferenceNumber

-Changes in ContractIdentification (part of Transaction, Authorization and Lifecycle)

  • Add field pspId

 

#version 2.0.1 (17-10-2022)

- Add 7 new fields to a transaction: result3ds, version3ds, cavv, xid, ucaf, mitCause, initiatorType

 

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.

Transactions

Transactions

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!

puz

Complete

 

Provide your merchants with the details of every merchant payment.

loc

One location

 

Present the merchant payment and the transactions on one location.

graph

Own environment

 

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

Who can use the API?

acq

Acquirers

psp

PSPs

merch

Merchants

Why use it?

Currently the merchant can only retrieve this transaction data via a separate merchant portal. This API enables you to use certain criteria (e.g. merchantId, transactionId and acquirerRefNo) to retrieve transactions data.

USE CASE

Provide specific transaction data on demand to your customer

lamp

A large department store uses multiple streams of data to track their customer purchases and to make specific offers as part of loyalty reward schemes. The merchant uses your application to import additional transaction data which can be used to improve the customer journey.

Reconciliation for (sub-)merchants

lamp

As a PSP you would like to show the transactions of a merchant payment in your own Merchant portal to (sub-)merchants.

In the Merchant Payments API you can search for and identify a merchant payment (payout) to your sub-merchant.

In the Transactions API you can search and retrieve the transactions that MATCH with the merchant payment (payout) to your sub-merchant.

The (sub-)merchant can retrieve the transaction data from your portal and use it to reconcile card transactions with the merchant payment (payout) for his/her own administration.

Note: If the (sub-)merchant wants an extract it may be more convenient to search for and retrieve a Reconciliation Statement from the Statements API.

Are you looking for more information?

Account Information Service API

Account Information Service API's

The APIs presented in this section can be used to access a PSU’s (Payment Service User) bank account, held with any reachable ASPSP. Retrieval of PSU’s account information is only allowed upon explicit consent of the account holder.
 

WL 1-Click Resources References

WL 1-Click Resources References

Resources Resource Reference
This reference act as a key for the resource
Issuer External Reference
This optional reference is used to ease API integration with clients
Issuer issuerId -
Product productReference issuerProductExternalReference
Customer customerReference issuerCustomerExternalReference
Address addressReference issuerAddressExternalReference
Contract contractReference issuerContractExternalReference
Card Contract cardContractReference issuerCardContractExternalReference
Card cardReference issuerCardExternalReference
Order orderReference -
Account accountReference issuerAccountExternalReference
Operation operationId -
Authorization transactionId -
Authorization Business Case businessCaseId -
Temporary Credit Limit temporaryCreditLimitReference -
Authorization Restriction authorizationRestrictionReference -
Authorization Restriction Override authorizationRestrictionOverrideReference -
Velocity Limit velocityLimitReference -
Velocity Limit Override velocityLimitOverrideReference -
Enable "on this page" menu on doc section
On

Velocity Limit Override

Velocity Limit Override

A default Velocity Limit could be override by Velocity Limit Overrides

The Velocity Limit Override can be done for a specific period using the attributes activationStartTime and activationEndTime

A Velocity Limit Override could change following attributes of the Velocity Limit

  • maximumAmount : Allowed maximum cumulated authorization amount
  • maximumAmountCheck : Switch indicating whether the cumulated authorization amount of the time period is compared to a maximum or not
  • maximumCount : Allowed maximum number of authorizations in the time period
  • maximumCountCheck : Switch indicating whether the number of authorizations in the time period is compared to a maximum or not

In our solution each Authorization Restriction Override is identified by an velocityLimitOverrideReference

It is possible to use this reference in order to 

  • Retrieve velocity limit override using the API GET /issuers/{issuerId}/accounts/{accountReference}/velocity-limits/{velocityLimitReference}/velocity-limit-overrides/{velocityLimitOverrideReference}
  • Update velocity limit override using the API PUT /issuers/{issuerId}/accounts/{accountReference}/velocity-limits/{velocityLimitReference}/velocity-limit-overrides/{velocityLimitOverrideReference}
  • Delete velocity limit override using the API DELETE /issuers/{issuerId}/accounts/{accountReference}/velocity-limits/{velocityLimitReference}/velocity-limit-overrides/{velocityLimitOverrideReference}

All the Velocity Limit Overrides which are applied on a Velocity Limit can be retrieved by the API that List velocity limit overrides for velocity limit GET /issuers/{issuerId}/accounts/{accountReference}/velocity-limits/{velocityLimitsReference}/velocity-limits-overrides/

Enable "on this page" menu on doc section
On

Velocity Limit

Velocity Limit

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

These rules are implemented with an initial customer specific Product setup and are set per default set as blocked or unblocked

The standard Velocity Limits are permanent and can be changed by creating some Velocity Limit Overrides

The standard Velocity Limits for Card Control are

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

Each standard Velocity Limits are set 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 Italy
  • ATM daily limit in the European Economic Area (w/o Italy)
  • ATM daily limit worldwide (w/o the EEA)

When an account is created, the default Velocity Limits defined on Product level are applied

In order to List velocity limits for account, the API GET /issuers/{issuerId}/accounts/{accountReference}/velocity-limits should be used by providing the issuerId of the Issuer and accountReference identifying the Account

In our solution each Velocity Limit is identified by an velocityLimitReference and it's possible to Retrieve velocity limit using GET /issuers/{issuerId}/accounts/{accountReference}/velocity-limits/{velocityLimitReference} API

Enable "on this page" menu on doc section
On

Authorization Restriction Override

Authorization Restriction Override

A default Authorization Restriction could be overwritten by Authorization Restriction Override.

The Authorization Restriction Override can also be done for a specific period using the attributes activationStartTime and activationEndTime

In order to Create authorization restriction overridethe API POST /issuers/{issuerId}/accounts/{accountReference}/authorization-restrictions/{authorizationRestrictionReference}/authorization-restriction-overrides should be used. The overrides is created based on an existing Authorization Restriction which authorizationRestrictionReference needs to be provided.

To block or unblock transactions – in other words to switch on/off a restriction – the attribute conditionCheck is taken into account.

In our solution each Authorization Restriction Override is identified by an authorizationRestrictionOverrideReference

It is possible to use this reference in order to 

  • Retrieve authorization restriction override using the API GET /issuers/{issuerId}/accounts/{accountReference}/authorization-restrictions/{authorizationRestrictionReference}/authorization-restriction-overrides/{authorizationRestrictionOverrideReference}
  • Update authorization restriction override using the API PUT /issuers/{issuerId}/accounts/{accountReference}/authorization-restrictions/{authorizationRestrictionReference}/authorization-restriction-overrides/{authorizationRestrictionOverrideReference} 
  • Delete authorization restriction override using the API DELETE /issuers/{issuerId}/accounts/{accountReference}/authorization-restrictions/{authorizationRestrictionReference}/authorization-restriction-overrides/{authorizationRestrictionOverrideReference}

All the Authorization Restriction Overrides which are applied on an Authorization Restriction can be retrieved by the API that List authorization restriction overrides for authorization restriction GET /issuers/{issuerId}/accounts/{accountReference}/authorization-restrictions/{authorizationRestrictionReference}/authorization-restriction-overrides/

 

Blocking countries

Card Control allows to block/unblock a single country or a list of countries.

The user needs to overwrite the existing default Authorization Restriction and use the conditionCheck attribute in combination with the conditionParameters attribute the country codes of the countries to be blocked.

For example, for an Authorization Restriction Override created with "conditionCheck":true, "conditionParameters":["004","008", "012"], authorizations from the countries Afghanistan (004), Albania (008) and Algeria (012) are declined.

Geo blocking

Geo Blocking is a functionality that allows the user to control for each Account whether a transaction from a region should be approved and processed or not.

The definition of the regions are part of customer Product setup and by default the following are setup :

  • Europe
  • North America
  • South America
  • Africa
  • Asia
  • Oceania
  • Antarctica 
  • European Economic Area

The user needs to override the existing default Authorization Restriction associated to one region and use the conditionCheck attribute in order to switch on/off the usage of the card in this region.

Blocking MCC

Merchant Category Code (MCC) Blocking is a functionality that allows to block a single MCC or a list of MCC.

The user needs to override the existing default Authorization Restriction and use the conditionCheck attribute in combination with the conditionParameters attribute the country codes of the countries to be blocked.

For example, for an Authorization Restriction Override created with "conditionCheck":true, "conditionParameters":["7995","7996"], authorizations from the following MCC are declined.

  • 7995 Betting (including Lottery Tickets, Casino Gaming Chips, Off - track Betting and Wagers)
  • 7996 Amusement Parks, Carnivals, Circuses, Fortune Tellers
Enable "on this page" menu on doc section
On

Authorization Restriction

Authorization Restriction

 

    The purpose of an Authorization Restriction is to allow or refuse a transaction on an Account based on given rules.

    These rules are implemented with an initial customer specific Product setup and are set per default set as blocked or unblocked

    The standard Authorization Restrictions are permanent and can be changed by creating some Authorization Restriction Overrides.

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

    • Channels like

      • ATM / cash
      • Card present (POS)
      • Card not present (eCommerce, telephone)
      • Card not present recurring
      • Contactless online (NFC online)
      • Magstripe
    • Single country, a list of single countries
    • Regions (Geo Blocking)
    • Merchant category codes (MCC Blocking)

    When an account is created, the default Authorization Restrictions defined on Product level are applied

    In order to List authorization restrictions for account, the API GET /issuers/{issuerId}/accounts/{accountReference}/authorization-restrictions should be used by providing the issuerId of the Issuer and accountReference identifying the Account

    Each Authorization Restriction is identified by an authorizationRestrictionReference and it's possible to Retrieve authorization restriction using GET /issuers/{issuerId}/accounts/{accountReference}/authorization-restrictions/{authorizationRestrictionReference} API

    Enable "on this page" menu on doc section
    On