PaidBy (Open Banking)

Overview

The merchant backend submits a PaidBy authorization request. A successful API response includes a redirect_url that the merchant frontend uses to open the hosted transaction page. Final payment status must be confirmed through notifications and transaction states.

Integration flow

The PaidBy Open Banking flow consists of 4 steps:

Create an API request.
Receive the API response.
Open the ISX transaction page.
Display the result page.

The merchant backend should create the API request because the request contains merchant credentials and configuration that must not be exposed in frontend code.

Merchant frontend
Sends checkout information
↓
Merchant backend
POST /v1/authorization/
↓
PaidBy API
Returns redirect_url
↓
Merchant backend
Returns redirect_url
↓
Merchant frontend
Opens hosted transaction page
↓
PaidBy transaction flow

Create an API request

POST /v1/authorization/

The API request consists of the HTTP method, URL, headers and JSON body. Different data may be included in the request, but the required objects and fields must be supplied for a successful transaction flow.

API endpoints

Environment	Method	API URL

Environment	Method	API URL
stage	POST	https://stage-gateway.isignth.is/v1/authorization/
production	POST	https://api.isxpay.com/gateway/service/v1/authorization/

Use the stage URL while developing and testing the integration. Use the production URL only after the merchant account and production configuration have been approved.

Request headers

The API header values are provided by the ISX relationship management team.

From: YOUR_API_CLIENT_NAME
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

Header	Value	Required	Description

Header	Value	Required	Description
`From`	`API client name`	Yes	Identifies the API client.
`Authorization`	`Bearer API_TOKEN`	Yes	Bearer token used to authenticate the request.
`Content-Type`	`application/json`	Yes	Indicates that the request body contains JSON.

The word Bearer must be included before the API token. Omitting it will cause an authentication error. Do not expose the From value or bearer token in frontend code.

Request objects

Object	Description	Required

Object	Description	Required
`workflow`	Workflow name supplied by the ISX relationship management team.	Yes
`merchant`	Information and configuration relating to the merchant.	Yes
`transaction`	Information about the payment transaction.	Yes
`client`	Information about the client making the payment.	Yes
`account`	Information identifying the client account.	Yes
`account_holder`	Information about the bank account to debit. Used for applicable EUR payments.	Conditional

Replace the example workflow and merchant values with those supplied for the merchant integration.

EUR request example

curl "https://stage-gateway.isignth.is/v1/authorization/" \
  --request POST \
  --header "From: YOUR_API_CLIENT_NAME" \
  --header "Authorization: Bearer YOUR_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "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"
    }
  }'

{
    "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 request example

curl "https://stage-gateway.isignth.is/v1/authorization/" \
  --request POST \
  --header "From: YOUR_API_CLIENT_NAME" \
  --header "Authorization: Bearer YOUR_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "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"
    }
  }'

{
    "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"
    }
  }

Request-field reference

Workflow

Field	Type	Required	Description

Field	Type	Required	Description
`workflow`	String	Yes	Workflow name supplied by the ISX relationship management team.

Merchant object

Field	Type	Required	Description

Field	Type	Required	Description
`id`	String	Yes	Merchant identifier supplied by the ISX relationship management team.
`transaction_webhook_url`	String	Yes	Merchant endpoint that receives transaction notifications.
`return_url`	String	Yes	URL to which the customer is returned after the hosted transaction flow.

Transaction object

Field	Type	Required	Description

Field	Type	Required	Description
`id`	String	Yes	Unique merchant transaction identifier.
`amount`	String	Yes	Transaction amount expressed in the lowest currency unit.
`currency`	String	Yes	Transaction currency. EUR and GBP are documented, depending on the merchant contract.
`reference`	String	Yes	Unique merchant transaction reference.

Both transaction.id and transaction.reference must be unique.

Payment amount	API value

Payment amount	API value
EUR 1.00	100
EUR 10.00	1000
GBP 25.50	2550

Client object

Field	Type	Required

Field	Type	Required
`first_name`	String	Yes
`last_name`	String	Yes
`email`	String	Yes
`gender`	String	No
`ip`	String	No
`mobile`	String	No
`title`	String	No
`middle_name`	String	No
`dob`	String	No
`citizen_country`	String	No
`birth_country`	String	No
`residential_address_street_number`	String	No
`residential_address_street`	String	No
`residential_address_secondary`	String	No
`residential_address_city`	String	No
`residential_address_subdivision`	String	No
`residential_address_postal_code`	String	No
`residential_address_country`	String	No

Account object

Field	Type	Required	Description

Field	Type	Required	Description
`identifier`	String	Yes	Customer identifier assigned by the merchant. Each identifier must be unique and paired with the customer for future transactions.

Account-holder object

The account_holder object contains information about the bank account to debit and applies to relevant EUR payment flows.

Field	Type	Required	Description

Field	Type	Required	Description
`name`	String	No	Name on the account.
`type`	String	No	Type of account.
`iban`	String	Conditional	IBAN of the account. Required when account_holder is included.
`bic`	String	Conditional	Bank identifier code.

When the account_holder object is supplied, iban becomes mandatory. Providing the customer IBAN may simplify the EUR customer experience by allowing the bank-selection screen to be skipped.

Receive the API response

After the POST request is sent, the PaidBy API returns information about the created transaction, including the hosted redirect_url. The merchant backend should validate the HTTP response and required response fields before returning the redirect URL to the frontend.

Response example

{
  "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://paidby.isxtech.com/landing/e6988b4a-ed1c-4104-9caf-af6bb8769756"
}

Following redirect_url opens the hosted transaction page.

Response-field reference

Field	Type	Description

Field	Type	Description
`id`	String	Unique response identification code.
`uid`	String	Unique response identification code.
`secret`	String	Transaction secret that can be used to validate ISX notifications.
`context_uid`	String	Context identifier associated with the transaction.
`mode`	String	Transaction mode detected by ISX.
`original_message`	Object	Information from the original transaction request.
`transactions`	String or collection	Transaction data returned by the API.
`state`	String	Current state of the transaction.
`compound_state`	String	Meaningful combined ISX transaction state.
`redirect_url`	String	Hosted URL used to continue the transaction flow.

Original-message fields

Field	Type	Description

Field	Type	Description
`merchant_id`	String	Merchant identifier from the request.
`transaction_id`	String	Merchant transaction ID from `transaction.id`.
`reference`	String	Merchant transaction reference.

Open the PaidBy transaction page

Use the redirect_url returned by the API response. Do not construct or hardcode a hosted transaction URL when a valid redirect_url has been returned.

{
  "id": "e6988b4a-ed1c-4104-9caf-af6bb8769756",
  "redirect_url": "https://paidby.isxtech.com/landing/e6988b4a-ed1c-4104-9caf-af6bb8769756"
}

Browser redirect.
New browser window.
Hosted iframe or dialog, where supported by the merchant integration.

Backend integration

Use the correct environment endpoint.
Add the assigned From header.
Add the assigned bearer token using Authorisation.
Send the documented request objects.
Ensure transaction.id and transaction.reference are unique.
Store the returned transaction identifiers and secret securely.
Return redirect_url to the frontend.
Receive and validate transaction notifications.
Confirm the final transaction state before fulfilling goods or services.

import express from "express";

const app = express();
app.use(express.json());

const PAIDBY_ENDPOINTS = {
  stage: "https://stage-gateway.isignth.is/v1/authorization/",
  production: "https://api.isxpay.com/gateway/service/v1/authorization/"
};

function getPaidByEndpoint() {
  return process.env.PAIDBY_ENVIRONMENT === "production"
    ? PAIDBY_ENDPOINTS.production
    : PAIDBY_ENDPOINTS.stage;
}

app.post("/api/create-paidby-transaction", async (req, res) => {
  const { transactionId, reference, amount, currency,
    firstName, lastName, email, accountIdentifier, accountHolder } = req.body;

  const requestBody = {
    workflow: process.env.PAIDBY_WORKFLOW,
    merchant: {
      id: process.env.PAIDBY_MERCHANT_ID,
      transaction_webhook_url: process.env.PAIDBY_WEBHOOK_URL,
      return_url: process.env.PAIDBY_RETURN_URL
    },
    client: { first_name: firstName, last_name: lastName, email },
    transaction: { id: transactionId, amount: String(amount), currency, reference },
    account: { identifier: accountIdentifier }
  };

  if (currency === "EUR" && accountHolder) {
    requestBody.account_holder = {
      name: accountHolder.name,
      type: accountHolder.type,
      iban: accountHolder.iban,
      bic: accountHolder.bic
    };
  }

  try {
    const response = await fetch(getPaidByEndpoint(), {
      method: "POST",
      headers: {
        From: process.env.PAIDBY_API_CLIENT_NAME,
        Authorization: `Bearer ${process.env.PAIDBY_API_TOKEN}`,
        "Content-Type": "application/json"
      },
      body: JSON.stringify(requestBody)
    });

    const data = await response.json();
    if (!response.ok || typeof data.redirect_url !== "string") {
      return res.status(502).json({ error: "Unable to create PaidBy transaction" });
    }

    return res.json({ id: data.id, uid: data.uid, redirect_url: data.redirect_url });
  } catch (error) {
    return res.status(500).json({ error: "Unexpected server error" });
  }
});

app.listen(3000);

PAIDBY_ENVIRONMENT=stage
PAIDBY_API_CLIENT_NAME=YOUR_API_CLIENT_NAME
PAIDBY_API_TOKEN=YOUR_API_TOKEN
PAIDBY_WORKFLOW=YOUR_WORKFLOW
PAIDBY_MERCHANT_ID=YOUR_MERCHANT_ID
PAIDBY_WEBHOOK_URL=https://merchant.example.com/webhooks/paidby
PAIDBY_RETURN_URL=https://merchant.example.com/payment/result

Frontend integration

Send the transaction information to the merchant backend.