PaidBy (Open Banking)

1 1. Introduction
2 2. Create API Request
- 2.1 Sample JSON body for PaidBy
3 3. Receive API Request Response
- 3.1 Sample JSON Payment Response
4 4. Changing language
5 5. ISX Transaction Page (how to receive notifications)
6 6. Results Page
- 6.1 6.1. Final Events
- 6.2 6.2. Additional Events

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:

Create API Request.
Receive API Request Response.
ISX Transaction Page.
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/”.

Production Environment URL: https://gateway.isignthis.com/v1/authorization/
Stage Environment URL: https://stage-gateway.isignth.is/v1/authorization/

Complete the appropriate header information.

The API Header information is provided by the ISX merchant support team.

Field Name	Field Value

Field Name	Field Value
From	API Client Name
Authorization	Bearer API Token
Content-Type	application/json

Example:


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

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

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

"workflow":"Test_Workflow"

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

id":"Test_Merchant"

The API call consists of the following required fields to proceed with the payment:

first_name
last_name
email

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"
	},
	"transaction":{
		"id":"Test_ID",
		"amount":"100",
		"currency":"AUD",
		"reference":"Test_Ref"
	},
	"client":{
		"first_name":"Shana",
		"last_name":"Barrows",
		"email":"shana.barrows@isignthis.com"
	},
	"account":{
		"identifier":"Test_ID"
	}
}

In the “account” object - identifier is the customer ID that you assigned to your customer. Each “identifier” must be unique and paired with the customer for future transactions.

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 merchant support team.