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
Subscribe to