Release Notes: REST API V2 - 2.8.1

REST API V2 - 2.8.1

  • Version 2.8.0 to 2.8.1
  • What's New
  • What's Changed
  • What's Deleted
  • What's Deprecated

What's New

Cancel close card contract

POST /issuers/{issuerId}/card-contracts/{cardContractReference}/cancel-close

The API allows to cancel card contract closing. The main input fields are:

  • The issuer ID
  • The card contract for which the cancel closure is requested: It can be provided by using the card contract reference or the issuer card contract external reference.

Cancel close card contract

POST /issuers/{issuerId}/card-contracts/external-card-contracts/{issuerCardContractExternalReference}/cancel-close

The API allows to cancel card contract closing. The main input fields are:

  • The issuer ID
  • The card contract for which the cancel closure is requested: It can be provided by using the card contract reference or the issuer card contract external reference.

Retrieve corporate contract by external contract ref

GET /issuers/{issuerId}/corporate-contracts/external-contracts/{issuerContractExternalReference}

This API allows retrieving a particular corporate contract from its reference or its issuer external reference. The API response contains contract information such as:

  • contract identifier with the contract reference and the issuer external contract reference if previously provided
  • product change information if any, such as its current status (scheduled, done, cancelled), new product, new contract if it exists
  • embedded fields if requested such as list of all customers or identifiers linked to this contract (e.g. contract owner, root account owner, cardholder(s)), card contracts, cards

Modify Corporate contract by ext ref

PATCH /issuers/{issuerId}/corporate-contracts/external-contracts/{issuerContractExternalReference}

The API allows to modify a corporate contract

Change paying account structure for a corporate contract

POST /issuers/{issuerId}/corporate-contracts/{contractReference}/change-paying-account

Change paying account structure for a corporate contract

POST /issuers/{issuerId}/corporate-contracts/external-contracts/{issuerContractExternalReference}/change-paying-account

The API allows to add an entity to a corporate contract identified by the Contract reference.

Modify Corporate contract

PATCH /issuers/{issuerId}/corporate-contracts/{contractReference}

The API allows to modify a corporate contract.

What's Changed

GET /issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/operations/{operationId}
Response:
  • Changed property data (object Operation)
    • Added property posDataCode (string)
    • Added property pointOfService (object)
    • Added property acquirerId (string)
    • Added property detailedFeeAmounts (array)
GET /issuers/{issuerId}/accounts/{accountReference}/operations/{operationId}
Response:
  • Changed property data (object Operation)
    • Added property posDataCode (string)
    • Added property pointOfService (object)
    • Added property acquirerId (string)
    • Added property detailedFeeAmounts (array)
POST /issuers/{issuerId}/cards/{cardReference}/create-emergency-card
Response:
  • Changed property data (object CreateEmergencyCardResponse)
    • Added property embossingName2ndLine (string)
POST /issuers/{issuerId}/cards/external-cards/{issuerCardExternalReference}/create-emergency-card
Response:
  • Changed property data (object CreateEmergencyCardResponse)
    • Added property embossingName2ndLine (string)
GET /issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}
Response:
  • Changed property data (object Account)
    • Added property defaultResetCreditLimit (string)
    • Added property lastImpactDate (string)
    • Added property coBrander (string)
    • Added property resetLimitBalance (object)
GET /issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/account-history
Response:
  • Changed property data (array)
    • Changed items (object AccountHistory)
      • Added property noOtbCheck (boolean)
      • Added property resetCreditLimit (boolean)
GET /issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/operations
Response:
  • Changed property data (array)
    • Changed items (object Operation)
      • Added property posDataCode (string)
      • Added property pointOfService (object)
      • Added property acquirerId (string)
      • Added property detailedFeeAmounts (array)
GET /issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/statements/last/operations
Response:
  • Changed property data (array)
    • Changed items (object Operation)
      • Added property posDataCode (string)
      • Added property pointOfService (object)
      • Added property acquirerId (string)
      • Added property detailedFeeAmounts (array)
GET /issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/statements/next/operations
Response:
  • Changed property data (array)
    • Changed items (object Operation)
      • Added property posDataCode (string)
      • Added property pointOfService (object)
      • Added property acquirerId (string)
      • Added property detailedFeeAmounts (array)
GET /issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/statements/{cycleClosureDate}/operations
Response:
  • Changed property data (array)
    • Changed items (object Operation)
      • Added property posDataCode (string)
      • Added property pointOfService (object)
      • Added property acquirerId (string)
      • Added property detailedFeeAmounts (array)
GET /issuers/{issuerId}/accounts/{accountReference}
Response:
  • Changed property data (object Account)
    • Added property defaultResetCreditLimit (string)
    • Added property lastImpactDate (string)
    • Added property coBrander (string)
    • Added property resetLimitBalance (object)
GET /issuers/{issuerId}/accounts/{accountReference}/account-history
Response:
  • Changed property data (array)
    • Changed items (object AccountHistory)
      • Added property noOtbCheck (boolean)
      • Added property resetCreditLimit (boolean)
GET /issuers/{issuerId}/accounts/{accountReference}/operations
Response:
  • Changed property data (array)
    • Changed items (object Operation)
      • Added property posDataCode (string)
      • Added property pointOfService (object)
      • Added property acquirerId (string)
      • Added property detailedFeeAmounts (array)
GET /issuers/{issuerId}/accounts/{accountReference}/statements/last/operations
Response:
  • Changed property data (array)
    • Changed items (object Operation)
      • Added property posDataCode (string)
      • Added property pointOfService (object)
      • Added property acquirerId (string)
      • Added property detailedFeeAmounts (array)
GET /issuers/{issuerId}/accounts/{accountReference}/statements/next/operations
Response:
  • Changed property data (array)
    • Changed items (object Operation)
      • Added property posDataCode (string)
      • Added property pointOfService (object)
      • Added property acquirerId (string)
      • Added property detailedFeeAmounts (array)
GET /issuers/{issuerId}/accounts/{accountReference}/statements/{cycleClosureDate}/operations
Response:
  • Changed property data (array)
    • Changed items (object Operation)
      • Added property posDataCode (string)
      • Added property pointOfService (object)
      • Added property acquirerId (string)
      • Added property detailedFeeAmounts (array)
GET /issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/contract
Response:
  • Changed property data (object Contract)
    • Added property coBrander (string)
    • Changed property accounts (array)
      • Changed items (object Account)
        • Added property defaultResetCreditLimit (string)
        • Added property lastImpactDate (string)
        • Added property coBrander (string)
        • Added property resetLimitBalance (object)
GET /issuers/{issuerId}/accounts/{accountReference}/contract
Response:
  • Changed property data (object Contract)
    • Added property coBrander (string)
    • Changed property accounts (array)
      • Changed items (object Account)
        • Added property defaultResetCreditLimit (string)
        • Added property lastImpactDate (string)
        • Added property coBrander (string)
        • Added property resetLimitBalance (object)
GET /issuers/{issuerId}/card-contracts/external-card-contracts/{issuerCardContractExternalReference}/contract
Response:
  • Changed property data (object Contract)
    • Added property coBrander (string)
    • Changed property accounts (array)
      • Changed items (object Account)
        • Added property defaultResetCreditLimit (string)
        • Added property lastImpactDate (string)
        • Added property coBrander (string)
        • Added property resetLimitBalance (object)
GET /issuers/{issuerId}/card-contracts/{cardContractReference}/contract
Response:
  • Changed property data (object Contract)
    • Added property coBrander (string)
    • Changed property accounts (array)
      • Changed items (object Account)
        • Added property defaultResetCreditLimit (string)
        • Added property lastImpactDate (string)
        • Added property coBrander (string)
        • Added property resetLimitBalance (object)
GET /issuers/{issuerId}/corporate-contracts/{contractReference}/corporate-employee-accounts/{accountReference}
Response:
  • Changed property data (object CorporateEmployeeAccountResponse)
    • Changed property account (object Account)
      • Added property defaultResetCreditLimit (string)
      • Added property lastImpactDate (string)
      • Added property coBrander (string)
      • Added property resetLimitBalance (object)
GET /issuers/{issuerId}/corporate-contracts/{contractReference}/corporate-employee-accounts/external-accounts/{issuerAccountExternalReference}
Response:
  • Changed property data (object CorporateEmployeeAccountResponse)
    • Changed property account (object Account)
      • Added property defaultResetCreditLimit (string)
      • Added property lastImpactDate (string)
      • Added property coBrander (string)
      • Added property resetLimitBalance (object)
GET /issuers/{issuerId}/corporate-contracts/external-contracts/{issuerContractExternalReference}/corporate-employee-accounts/external-accounts/{issuerAccountExternalReference}
Response:
  • Changed property data (object CorporateEmployeeAccountResponse)
    • Changed property account (object Account)
      • Added property defaultResetCreditLimit (string)
      • Added property lastImpactDate (string)
      • Added property coBrander (string)
      • Added property resetLimitBalance (object)
GET /issuers/{issuerId}/corporate-contracts/external-contracts/{issuerContractExternalReference}/corporate-employee-accounts/{accountReference}
Response:
  • Changed property data (object CorporateEmployeeAccountResponse)
    • Changed property account (object Account)
      • Added property defaultResetCreditLimit (string)
      • Added property lastImpactDate (string)
      • Added property coBrander (string)
      • Added property resetLimitBalance (object)
GET /issuers/{issuerId}/corporate-contracts/{contractReference}
Parameters:

Added: embed in query

Response:
  • Changed property data (object CorporateContract)
    • Added property statusDate (string)
    • Added property contractCompanies (array)
    • Added property productIdentifier (object)
    • Deleted property accounts (array)
    • Deleted property cardContractIdentifiers (array)
    • Deleted property cardContracts (array)
    • Changed property corporateContractEntities (array)
      • Changed items (object CorporateContractEntity)
        • Added property account (object)
    • Changed property corporateEmployeeAccounts (array)
      • Changed items (object CorporateEmployeeAccount)
        • Added property account (object)
        • Added property parentCompanyEntityExternalReference (string)
        • Added property cardContracts (array)
        • Added property contractFee (object)
        • Deleted property contractFees (object)
GET /issuers/{issuerId}/contracts/external-contracts/{issuerContractExternalReference}
Response:
  • Changed property data (object Contract)
    • Added property coBrander (string)
    • Changed property accounts (array)
      • Changed items (object Account)
        • Added property defaultResetCreditLimit (string)
        • Added property lastImpactDate (string)
        • Added property coBrander (string)
        • Added property resetLimitBalance (object)
GET /issuers/{issuerId}/contracts/external-contracts/{issuerContractExternalReference}/accounts
Response:
  • Changed property data (array)
    • Changed items (object Account)
      • Added property defaultResetCreditLimit (string)
      • Added property lastImpactDate (string)
      • Added property coBrander (string)
      • Added property resetLimitBalance (object)
GET /issuers/{issuerId}/contracts/{contractReference}
Response:
  • Changed property data (object Contract)
    • Added property coBrander (string)
    • Changed property accounts (array)
      • Changed items (object Account)
        • Added property defaultResetCreditLimit (string)
        • Added property lastImpactDate (string)
        • Added property coBrander (string)
        • Added property resetLimitBalance (object)
GET /issuers/{issuerId}/contracts/{contractReference}/accounts
Response:
  • Changed property data (array)
    • Changed items (object Account)
      • Added property defaultResetCreditLimit (string)
      • Added property lastImpactDate (string)
      • Added property coBrander (string)
      • Added property resetLimitBalance (object)
GET /issuers/{issuerId}/customers/external-customers/{issuerCustomerExternalReference}/accounts
Response:
  • Changed property data (array)
    • Changed items (object Account)
      • Added property defaultResetCreditLimit (string)
      • Added property lastImpactDate (string)
      • Added property coBrander (string)
      • Added property resetLimitBalance (object)
GET /issuers/{issuerId}/customers/{customerReference}/accounts
Response:
  • Changed property data (array)
    • Changed items (object Account)
      • Added property defaultResetCreditLimit (string)
      • Added property lastImpactDate (string)
      • Added property coBrander (string)
      • Added property resetLimitBalance (object)
GET /issuers/{issuerId}/companies/{customerReference}/corporate-contracts
Response:
  • Changed property data (array)
    • Changed items (object CorporateContract)
      • Added property statusDate (string)
      • Added property contractCompanies (array)
      • Added property productIdentifier (object)
      • Deleted property accounts (array)
      • Deleted property cardContractIdentifiers (array)
      • Deleted property cardContracts (array)
      • Changed property corporateContractEntities (array)
        • Changed items (object CorporateContractEntity)
          • Added property account (object)
      • Changed property corporateEmployeeAccounts (array)
        • Changed items (object CorporateEmployeeAccount)
          • Added property account (object)
          • Added property parentCompanyEntityExternalReference (string)
          • Added property cardContracts (array)
          • Added property contractFee (object)
          • Deleted property contractFees (object)
GET /issuers/{issuerId}/companies/external-customers/{issuerCustomerExternalReference}/corporate-contracts
Response:
  • Changed property data (array)
    • Changed items (object CorporateContract)
      • Added property statusDate (string)
      • Added property contractCompanies (array)
      • Added property productIdentifier (object)
      • Deleted property accounts (array)
      • Deleted property cardContractIdentifiers (array)
      • Deleted property cardContracts (array)
      • Changed property corporateContractEntities (array)
        • Changed items (object CorporateContractEntity)
          • Added property account (object)
      • Changed property corporateEmployeeAccounts (array)
        • Changed items (object CorporateEmployeeAccount)
          • Added property account (object)
          • Added property parentCompanyEntityExternalReference (string)
          • Added property cardContracts (array)
          • Added property contractFee (object)
          • Deleted property contractFees (object)
POST /issuers/{issuerId}/contracts/search
Response:
  • Changed property data (array)
    • Changed items (object Contract)
      • Added property coBrander (string)
      • Changed property accounts (array)
        • Changed items (object Account)
          • Added property defaultResetCreditLimit (string)
          • Added property lastImpactDate (string)
          • Added property coBrander (string)
          • Added property resetLimitBalance (object)
POST /issuers/{issuerId}/contracts/{contractReference}/change-product
Request body:
  • New optional properties:
    • productChangeTrigger
POST /issuers/{issuerId}/contracts/external-contracts/{issuerContractExternalReference}/change-product
Request body:
  • New optional properties:
    • productChangeTrigger
GET /issuers/{issuerId}/customers/external-customers/{issuerCustomerExternalReference}/contracts
Response:
  • Changed property data (array)
    • Changed items (object Contract)
      • Added property coBrander (string)
      • Changed property accounts (array)
        • Changed items (object Account)
          • Added property defaultResetCreditLimit (string)
          • Added property lastImpactDate (string)
          • Added property coBrander (string)
          • Added property resetLimitBalance (object)
GET /issuers/{issuerId}/customers/{customerReference}/contracts
Response:
  • Changed property data (array)
    • Changed items (object Contract)
      • Added property coBrander (string)
      • Changed property accounts (array)
        • Changed items (object Account)
          • Added property defaultResetCreditLimit (string)
          • Added property lastImpactDate (string)
          • Added property coBrander (string)
          • Added property resetLimitBalance (object)
POST /issuers/{issuerId}/contracts/create-consumer-contract
Request body:
  • Changed property contract (object CreateConsumerContractRequest.Contract)
    • Added property coBrander (string)

What's Deleted

Change paying account structure for a corporate contract

POST /issuers/{issuerId}/contracts/{contractReference}/change-paying-account

Change paying account structure for a corporate contract

POST /issuers/{issuerId}/contracts/external-contracts/{issuerContractExternalReference}/change-paying-account

What's Deprecated

 

No API deprecated.

Enable "on this page" menu on doc section
On

ob-obp-authorization-api

Authorisation API

API Reference

The following two steps have to be performed for each service to facilitate a secure connection between the Initiating Party and the Open Banking Service.

  1. Upload certificate
  2. Retrieve token

Upload certificate

The Initiating Party uploads his public certificate in the Back-office. 

Retrieve token

Endpoint: POST /token

This API retrieves the token which is used in the communication between the Initiating Party and the Open Banking Service. The Initiating Party is using his private key to sign the request. In the response he will receive an access token from the Open Banking Service. This token is used in all subsequent API calls towards the Open Banking Service.

Request

LocationNameTypeComments
Form data

grant_type

required

StringTo be set to ‘client_credentials’
Header

Authorization

required

String

The signature. It contains the header attributes 'app', 'client', 'id' and 'date' signed with the private key of the client.

The signature will be used to sign the authorisation request with the private key which corresponds to the certificate provided for the onboarding. 

Structure

Signature keyId=”<thumbprint of certificate>”, algorithm=”SHA256withRSA”, headers=”app client id date”, signature=”<signature>”

Example

Signature keyId=”58AF4EC5ADD4C4A3F28D3AEFF60656B2F2xxxxxx”, algorithm=”SHA256withRSA”, headers=”app client id date”, signature=”Abczym2rZF…r5qcvgmA==” 

Generating rules

The signature must be created over a String where app, client, id and date are concatenated with the following rules:

  • The keyId is the thumbprint of the certificate, viewed with the SHA1 algorithm.
  • Create the header field string by concatenating the lowercased header field name followed with an ASCII colon `:`, an ASCII space ` `, and the header field value. Leading and trailing optional whitespace (OWS) in the header field value MUST be omitted (as specified in RFC7230 [RFC7230], Section 3.2.4 [7]). If value is not the last value then append an ASCII newline `\n`.

More details can be found here: https://datatracker.ietf.org/doc/html/draft-cavage-http-signatures-12

Header

App

required

StringThe name of the service. Only IDEAL, AIS, PIS or PSU is allowed.
Header

Client

required

StringThe name of the client. This name is provided to the Initiating Party during onboarding. The name of the client is created by the Open Banking Service.
Header

Id

required

String

The combination of Initiating Party ID and sub Id. For example if Initiating Party ID is 433 and the sub ID is 5 the ID will be 433:5

IP=433, subId=5 -> 433:5

IP=434, no subId -> 434

Header

Date

required

Date

Should be filled with the current date.

The following date formats are supported:

1. EEE MMM dd HH:mm:ss zzz yyyy

2. ISO DATE: for example 2011-12-03T10:15:30+01:00

3. RFC 1123: for example Tue, 3 Jun 2008 11:05:30 GMT

Response

Mult.NameTypeComments
[1..1]access_tokenStringToken to be used in further API calls
[1..1]token_typeStringType of the token: Bearer
[1..1]expires_inIntegerExpiration time in seconds

Example: Authorisation

Request

curl -L -X POST 'https://localhost:8443/xs2a/routingservice/services/authorize/token?grant_type=client_credentials' \
-H 'App: IDEAL' \
-H 'Accept: application/json' \
-H 'Date: 2022-03-25T09:41:31.256Z' \
-H 'Authorization: Signature KeyID="8D0F688AD3E6C2D4D5FB99FE129F2A2E3B496AF7", algorithm="SHA256withRSA", headers="app client id date", signature= "kAIepMoo6CRTWz9CLUFcpZj8eNQTdjXq6V8+kdk/9M1GmVud2CVrP1NMNTEiXgKzBlFQQlhv1iaFhMVOLVq7u8aEV4eeoNxjTLDK+lk4zkjCBjeOyXtr32dtfjsvytlzhXw7KJizgOGd+m4Gh9xtSjY0I5QM/p+znKZsJCVKNSUUBZndAxIudsxy2Srp/yzexmvWpsoAvWIZzwtDS03h4PjGTGKloXz6KyC+/I+GSBjw9M3GATUMMVrrgTKoR8oI0Xcr9v7ZTr3KpT1d1/LrcxQ82o2kq0+4ECVoJdVRezr2oZRmZ5hTHTIHehMNkASnuDqzDaQxQvMInUTg8tFKGA=="' \
-H 'Id: 000784' \
-H 'Client: Worldline'

Response

Content-Type: application/json;charset=UTF-8
    ResponseCode: 200
    
    Headers: {X-Request-ID=23eeed2d-f163-43c5-94b1-eeadcbb393e3, MessageCreateDateTime=2022-03-25T09:41:31.819Z, Date=Fri, 25 Mar 2022 09:41:31 GMT, Content-Type=application/json;charset=UTF-8}
    Payload: {
    "access_token": "abb5468b4845dffff9cccd7c950e529",
    "token_type": "Bearer",
    "expires_in": 3600
}
Enable "on this page" menu on doc section
On

Contract

Contract

The contract is the subscription to a product by a customer. The contract inherits default values from its product, with the possibility to override some specific parameters such as fees, terms and conditions, credit limit, card layout reference.

Each Contract is identified by a unique “contractReference”, generated internally. It can optionally have an external reference “issuerContractExternalReference”, provided by the issuer, which must be unique for the issuer.

The below diagram presents different use cases covered by the API in the contract domain.

Contract APIs

Enable "on this page" menu on doc section
On

Handle Disputes

Manage dispute and optimize your card portfolio

step 4

 

Worldline Card Issuing provides to Issuer an interface tool to handle exceptions and manage claims. Additionally, Worldline offers with the Customer Service Management a comprehensive Dispute and Chargeback handling service. The service includes:

  • Chargeback handling

  • Compliance Case handling

  • (Pre)arbitration handling

Enable "on this page" menu on doc section
On

Corporate hierarchy, as a Bank employee

Corporate hierarchy: As a Bank employee, I want to

Set up Corporate credit cards hierarchy

"to come"

Set up Corporate debit card hierarchy

"to come"

Enable "on this page" menu on doc section
On

Token management, as a Customer

Token management: As a Customer, I want to

Enroll to wallet

Tokenisation API

"to come"

Enable "on this page" menu on doc section
On

Dispute, as a Customer

Dispute: As a Customer, I want to

Raise a dispute case for a transaction and add receipt as a proof

Create a dispute

Add document to a dispute folder

Enable "on this page" menu on doc section
On

Transactions, as a customer

Transactions: As a customer, I want to

See a list of all transactions on different level of Corporate account/s

List operations for an account

The issuer can provide the “amount due” model, the minimum amount and the % in case of partial payer

See the transaction details

Retrieve transaction details

See my statement

Retrieve last statement

Retrieve a given statement

See the operations for my next statement

List operations for next statement

Enable "on this page" menu on doc section
On
Subscribe to