Accepting Funds - PaidBy (Open Banking)
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.
This API doc describes PaidBy & the use of the Euro (EUR) & the Pound Sterling (GBP).
[PaidBy & the use of the Swedish Krona (SEK) through Zimpler]
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://api.isxpay.com/gateway/service/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 relationship management team.
|
Field Name |
Field Value |
|
From |
API Client Name |
|
Authorization |
Bearer API Token |
|
Content-Type |
application/json |
Example:
|
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 |
|
merchant |
Information about the merchant. |
Yes |
|
|
transaction |
Information about the transaction. |
Yes |
|
|
client |
Information about the client. |
Yes |
|
|
account |
Information about the account. |
Yes |
|
|
account_holder |
Object containing data about the bank account to debit. This is used for EUR payments only. |
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.
The https:// should be replaced with a suitable URL.
"id":"Test_Merchant"
"transaction_webhook_url":"https://..."
"return_url": "https://..."
The API call consists of the following fields to proceed with the payment in the client object:
|
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 |
|
|
Yes |
The API call consists of the following fields to proceed with the payment in the transaction object:
|
Field Name |
Required |
|
reference |
Yes1 |
|
amount2 |
Yes |
|
currency3 |
Yes |
|
id |
Yes1 |
1 The reference & id fields must be unique.
2 The amount field is expressed in the lowest currency unit (e.g., cent). For example, EUR 10.00 must be represented as 1000.
3 The currencies EUR & GBP can be used depending on the contract signed with ISX, which will also determine which account types are held. The currency field must be populated accordingly.
The API call consists of the following fields to proceed with the payment in the account_holder object:
|
Field Name |
Description |
Required |
|
name |
Name on the account |
No |
|
type |
Type of account |
No |
|
iban |
IBAN of the account |
Conditional. |
|
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. This is applicable only to EUR.
If the account_holder object is used, then the iban field becomes mandatory.
Refer to the JSON code entitled “Sample JSON body for PaidBy” for reference.
Sample JSON body for PaidBy
EUR
{
"workflow":"Test_Workflow",
"merchant":{
"id":"Test_Merchant",
"transaction_webhook_url":"https://...",
"return_url": "https://..."
},
"client":{
"first_name":"Shana",
"last_name":"Barrows",
"email":"shana.barrows@mail.com"
},
"transaction":{
"id":"Test_ID",
"amount":"100",
"currency":"EUR",
"reference":"Test_Ref"
},
"account_holder":{
"name":"Jane Smith",
"type":"business",
"iban":"DE89370400440532013000",
"bic":"COBADEFFXXX"
},
"account":{
"identifier":"Test_ID"
}
}
GBP
{
"workflow":"Test_Workflow",
"merchant":{
"id":"Test_Merchant",
"transaction_webhook_url":"https://...",
"return_url": "https://..."
},
"client":{
"first_name":"Shana",
"last_name":"Barrows",
"email":"shana.barrows@mail.com"
},
"transaction":{
"id":"Test_ID",
"amount":"100",
"currency":"GBP",
"reference":"Test_Ref"
},
"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 |
|
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
{
"id":"e6988b4a-ed1c-4104-9caf-af6bb8769756",
"uid":"e6988b4a-ed1c-4104-9caf-af6bb8769756",
"secret":"159173ee-6309-4806-b499-d2598a2ed21e",
"context_uid":"e6988b4a-ed1c-4104-9caf-af6bb8769756",
"mode":"registration",
"original_message":{
"merchant_id":"Test_Merchant",
"transaction_id":"Test_ID",
"reference":"Test_Ref"
},
"transactions":"[]",
"state":"PENDING",
"compound_state":"PENDING.VALIDATED_TRANSACTION",
"redirect_url":"https://verify.isignthis.com/landing/e6988b4a-ed1c-4104-9caf-af6bb8769756"
}
Following the redirect_url will lead to the transaction page.
If the API request response is unsuccessful an error will be shown.
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.
Example: www.test/landing/9ec923ef-3d70-410f-93c0-fe64df900353/fr
The available languages are:
|
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 must be stored, as this is required later to reconcile your transaction.
In the example below it is marked as: "provider_reference_code":"CT001-1659839".
{
"id":"653fd3fa-250a-4e56-81da-ea06c4888bee",
"uid":"653fd3fa-250a-4e56-81da-ea06c4888bee",
"secret":"37bbbc18-b0ca-4e68-815f-50d1a7dcc3bb",
"mode":"registration",
"recurring_transaction":false,
"original_message":{
"merchant_id":"ISX_Instant_tranfer",
"transaction_id":"Test411",
"reference":"Test601",
"account":{
"identifier":"Test697600",
"ext":{
}
}
},
"workflow_state":{
"capture":"NA",
"charge":"ACCEPTED",
"credit":"NA",
"3ds":"NA",
"piv":"NA",
"sca":"NA",
"docs":"NA",
"kyc":"NA"
},
"event":"transaction_accepted",
"state":"SUCCESS",
"compound_state":"SUCCESS.COMPLETE",
"identity":{
"id":"21143deb-8304-47ed-9daf-d7f21ab4d46a",
"uid":"21143deb-8304-47ed-9daf-d7f21ab4d46a",
"download_url":"https://api.isxpay.com/gateway/service/v1/identity/21143deb-8304-47ed-9daf-d7f21ab4d46a",
"ledger_lifetime_amount":"23200",
"ledger_lifetime_currency":"EUR",
"kyc_state":"NONE",
"created_at":"2022-06-20T09:31:51.004Z"
},
"response_code":"00",
"response_code_description":"Approved and completed successfully",
"screen_entities":[
],
"payment_provider_responses":[
{
"operation_type":"authorization-and-capture",
"operation_successful":true,
"provider_type":"bank_transfer",
"provider_name":"OpenBanking",
"request_currency":"EUR",
"reference_code":"452b35a3-7c05-4ff0-bd39-c47053867916",
"provider_reference_code":"P00122F9361FB944CAF8766E2E7A47D983F",
"response_id":"P00122F9361FB944CAF8766E2E7A47D983F",
"status_code":"Success",
"status_description":"OK",
"manual_reconciliation":false
},
{
"operation_type":"transaction-verification",
"operation_successful":true,
"provider_type":"bank_transfer",
"provider_name":"OpenBanking",
"request_currency":"EUR",
"reference_code":"P00122F9361FB944CAF8766E2E7A47D983F",
"status_code":"ACCEPTED",
"manual_reconciliation":true
},
{
"operation_successful":false,
"provider_name":"ISX",
"manual_reconciliation":false
},
{
"operation_successful":false,
"provider_name":"ISX",
"provider_reference_code":"CT001-1659839",
"manual_reconciliation":false
}
],
"payment_amount":{
"currency":"EUR",
"amount":1000
}
}
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 |
|
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 |
|
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.