PaidBy (Open Banking)

PBB_banner.png

1. Introduction

Open banking is the secure sharing of financial data between financial institutions, such as ISX.

Before open banking became available, consumer financial data was controlled solely by big banks.

Now, consumers are able to access, and manage, their financial data across our platforms — resulting in a smoother, more personalised experience in the process.

This benefits our customers, who end up paying lower costs whilst enjoying improved technology and customer service.

Different data can be included in the API request but there are some specific objects that are required for a successful authentication process.

In our case the workflow of the ISX Money Instant bank transfer solution consists of four steps:

  1. Create API Request.

  2. Receive API Request Response.

  3. ISX Transaction Page.

  4. Result Page.


2. Create API Request

The API request consists of four steps: Method, URL, Header, and Body.

Request Method: POST

The API is accessed from the Request URL.

This is a combination of our URL and the addition of the following text at the end of the URL: “/v1/authorization/”.

Complete the appropriate header information.

The API Header information is provided by the ISX relationship management team.

Field Name

Field Value

Field Name

Field Value

From

API Client Name

Authorization

Bearer API Token

Content-Type

application/json

Example:

Field Name

Field Value

Field Name

Field Value

From

Test_APIClient

Authorization

Bearer TEXnkvZCtFucXebHYwrYLIGbkhjygvBTbxWELCCnCQJTKsx6bYNh5fOjEE

Content-Type

application/json

The word Bearer must be present in the API token or else an error will result.

To generate the “Transaction API call”, the following API Objects are required.

Each object has a number of specific attributes.

Below you can view each object name, description and whether it’s required or not.

Also, the glossary column has a link that directs you to detailed information about each object, including examples.

Object Name

Description

Required

Glossary

Object Name

Description

Required

Glossary

merchant

Information of the merchant

Yes

Merchant object

transaction

Information of the transaction

Yes

Transaction object

client

Information of the client

Yes

Client object

account

Information of the account

Yes

Account object

account_holder

Object containing data about the bank account being verified

Conditional

 

In the API body request, add the “workflow” name provided and replace “id” in the “merchant” object with the ones provided by the ISX relationship management team.

“Test_Workflow” text (below) should be replaced with the “workflow” name provided by the ISX relationship management team.

"workflow":"Test_Workflow"

“Test_Merchant” text (below) should be replaced with the “merchant_id” provided by the ISX relationship management team.

id":"Test_Merchant"

The API call consists of the following fields to proceed with the payment in the “client“ object:

Field Name

Required

Field Name

Required

gender

No

ip

No

residential_address_postal_code

No

mobile

No

last_name

Yes

title

No

middle_name

No

citizen_country

No

birth_country

No

residential_address_secondary

No

residential_address_country

No

residential_address_subdivision

No

dob

No

residential_address_street_number

No

residential_address_city

No

residential_address_street

No

first_name

Yes

email

Yes

The API call consists of the following fields to proceed with the payment in the “transaction“ object:

Field Name

Required

Field Name

Required

reference

Yes

amount

Yes

currency

Yes

id

Yes

The API call consists of the following fields to proceed with the payment in the “account_holder“ object:

Field Name

Description

Required

Field Name

Description

Required

name

Name on the account

No

type

Type of account

No

iban

IBAN of the account

Conditional. Required for BIC lookup for account selection.

bic

Bank identifier code

Conditional

Even though the “iban“ field is optional, we strongly suggest completing this field as it will make processing easier in the long run.

By providing the customer IBAN, the end user experience will be simplified because the “Bank Selection” screen will be skipped. So, this eliminates a customer's need to scroll for, or search for, or preselect their bank.

Refer to the JSON code entitled “Sample JSON body for PaidBy” for reference.

Sample JSON body for PaidBy

{ "workflow":"Test_Workflow", "merchant":{ "id":"Test_Merchant" }, "client":{ "first_name":"Shana", "last_name":"Barrows", "email":"shana.barrows@isignthis.com" }, "transaction":{ "id":"Test_ID", "amount":"100", "currency":"AUD", "reference":"Test_Ref" }, "account_holder":{ "name":"Jane Smith", "type":"business", "iban":"DE89370400440532013000", "bic":"COBADEFFXXX" }, "account":{ "identifier":"Test_ID" } }

3. Receive API Request Response

Once the POST is sent, a response message will be received.

Field

Type

Description

Field

Type

Description

id/uid

String

Unique response identification code.

secret

String

Transaction secret code that can be used to validate ISX notifications.

mode

String

The transaction mode detected by ISX.

original_message

Object

Information about your transaction request.

state

String

Information about the state of the transaction.

compound_state

String

The ISX meaningful state of the transaction.

redirect_url

String

The redirect URL.

Sample JSON Payment Response

Following the redirect_url will lead to the transaction page.


4. Changing language

If you wish to change the language, add an extra parameter in the redirect URL that you receive in your response.

Add the relevant code of the language at the trailing end of the URL.

The available languages are:

Code

Language

Code

Language

da

Danish

de

German

en

English

es

Spanish

fr

French

ja

Japanese

no

Norwegian

se

Swedish


5. ISX Transaction Page (how to receive notifications)

Once the ISX transaction page is opened, the customer maybe prompted to insert additional information (depending on the settings that requested), once completed, proceed with the transaction.

For each unsuccessful transaction a customer makes, an appropriate event notification will be provided to your webhook.

Refer to Notifications and Transaction Events & States for more information.

Additionally for an successful transaction, when the flow is completed, we include an additional object in the “payment_provider_responses” containing a “provider_reference_code” this needs to be stored, as this is required later to reconcile your transaction.

In the example below it is marked as: “provider_reference_code”:“CT001-1659839”.


6. Results Page

Depending on which page you have decided to show, either the ISX results page or your own page.

This will be displayed to the customer with the appropriate message.

Refer to Transaction Events & States for more information on all transaction events and states.

The following two tables list all return URL events related specifically to PaidBy:

6.1. Final Events

Event

Description

Event

Description

transaction_accepted

The transaction has been accepted and is being validated.

transaction_declined

The transaction has been declined.

transaction_expired

The transaction request has expired.

transaction_cancelled

The transaction has been cancelled.

6.2. Additional Events

Event

Description

Event

Description

payment_success

Payment was successful (Note: this is not a final state).

risk_auto_rejected

The transaction has been automatically rejected due to risk rules.

unexpected_error

An unexpected error occurred and the transaction has been halted.

If any issues arise, contact the ISX relationship management team.


 

© ISX Financial EU PLC 2024. All rights reserved.