Weavr
Powered by Redocly

Weavr Embedded Payment Run API (v1)

Download OpenAPI specification:Download

License: private

Weavr Payment Run Plug-in API provides a simple and flexible way for Embedders to add payment execution capabilities in their application.

By integrating Weavr Payment Run plug-in API in your application, you can embed banking and payment capabilities within your app to boost productivity for your users in a seamless experience.

Authentication

Each request to the API must include an api_key that represents your account. You can obtain an API Key by registering for a Embedder account here.

Almost all endpoints require a secondary authentication token auth_token that represents the user for whom the request is being executed.

Postman Collection

To help you get started with your integration, you can download the Postman collection here. The collection includes the steps you’ll need to follow to integrate Embedded Payment Run within your app.

The collection makes use of environment variables to pre-fill details associated with your Sandbox account, such as your account’s API Key. You can download your Sandbox Account environment file from the Sandbox Portal.

Tokens

Acquire auth token

Authenticate a user with the email and password that they provided when registering.

Given that the user credentials are correct, this returns a token that can then be used to authorise other secured operations. In case the password is expired, a temporary token is returned, which can be used solely for updating the password.

The token returned is valid for 5 minutes from last activity.

SecurityapiKey
Request
Request Body schema: application/json
required
email
required
string <email>

E-mail Address of the user

required
object

The user's password or passcode used to log in a user. Passwords must be:

  • between 8 and 30 characters
  • include a lowercase character
  • include an uppercase character
  • include a digit and a special character
  • different from any of the 5 last such passwords used.

For non-PCI compliant integrations, the password submitted must be tokenised.

Responses
200

OK

400

Bad Request Error - Your request is invalid.

401

Unauthorized - Your credentials or access token are invalid.

403

Forbidden - Access to the requested resource or action is forbidden.

409

The user's password has expired. Use the returned temporary token to update their password via the '/passwords/update' endpoint.

429

Too many requests.

500

Internal Server Error - There is a problem with the server. Please try again later.

503

Service Unavailable - We're temporarily offline for maintenance. Please try again later.

default

Error

post/v1/login_with_password
Request samples
application/json
{
  • "email": "user@example.com",
  • "password": {
    }
}
Response samples
application/json
{
  • "token": "string",
  • "tokenType": "AUTH",
  • "identity": {
    },
  • "credentials": {
    }
}

Logout

Logs out the user and terminates the session identified by the auth_token in the Authorization Header.

SecurityapiKey and authToken
Responses
204

Success - No Content.

400

Bad Request Error - Your request is invalid.

401

Unauthorized - Your credentials or access token are invalid.

403

Forbidden - Access to the requested resource or action is forbidden.

429

Too many requests.

500

Internal Server Error - There is a problem with the server. Please try again later.

503

Service Unavailable - We're temporarily offline for maintenance. Please try again later.

default

Error

post/v1/logout
Response samples
application/json
{
  • "message": "string",
  • "syntaxErrors": {
    }
}

Passwords

Create a password

Create a new password for the user identified by the user_id path parameter.

SecurityapiKey
Request
path Parameters
user_id
required
string^[0-9]+$

The unique identifier for the user.

Example: 110747174434373672
Request Body schema: application/json
required
required
object

The user's password or passcode used to log in a user. Passwords must be:

  • between 8 and 30 characters
  • include a lowercase character
  • include an uppercase character
  • include a digit and a special character
  • different from any of the 5 last such passwords used.

For non-PCI compliant integrations, the password submitted must be tokenised.

Responses
200

OK

400

Bad Request Error - Your request is invalid.

401

Unauthorized - Your credentials or access token are invalid.

403

Forbidden - Access to the requested resource or action is forbidden.

404

Not found - The requested resource couldn't be found.

409

Conflict

429

Too many requests.

500

Internal Server Error - There is a problem with the server. Please try again later.

503

Service Unavailable - We're temporarily offline for maintenance. Please try again later.

default

Error

post/v1/password/{user_id}
Request samples
application/json
{
  • "password": {
    }
}
Response samples
application/json
{
  • "passwordInfo": {
    },
  • "token": "string"
}

Update a password

Update the password for the logged-in user.

SecurityapiKey and authToken
Request
Request Body schema: application/json
required
required
object

The user's password or passcode used to log in a user. Passwords must be:

  • between 8 and 30 characters
  • include a lowercase character
  • include an uppercase character
  • include a digit and a special character
  • different from any of the 5 last such passwords used.

For non-PCI compliant integrations, the password submitted must be tokenised.

required
object

The user's password or passcode used to log in a user. Passwords must be:

  • between 8 and 30 characters
  • include a lowercase character
  • include an uppercase character
  • include a digit and a special character
  • different from any of the 5 last such passwords used.

For non-PCI compliant integrations, the password submitted must be tokenised.

Responses
200

OK

400

Bad Request Error - Your request is invalid.

401

Unauthorized - Your credentials or access token are invalid.

403

Forbidden - Access to the requested resource or action is forbidden.

409

Conflict

429

Too many requests.

500

Internal Server Error - There is a problem with the server. Please try again later.

503

Service Unavailable - We're temporarily offline for maintenance. Please try again later.

default

Error

post/v1/passwords/update
Request samples
application/json
{
  • "oldPassword": {
    },
  • "newPassword": {
    }
}
Response samples
application/json
{
  • "passwordInfo": {
    },
  • "token": "string"
}

Validate a password

Check that a password adheres to all complexity checks.

SecurityapiKey
Request
Request Body schema: application/json
required
required
object

The user's password or passcode used to log in a user. Passwords must be:

  • between 8 and 30 characters
  • include a lowercase character
  • include an uppercase character
  • include a digit and a special character
  • different from any of the 5 last such passwords used.

For non-PCI compliant integrations, the password submitted must be tokenised.

Responses
204

Success - No Content.

400

Bad Request Error - Your request is invalid.

401

Unauthorized - Your credentials or access token are invalid.

403

Forbidden - Access to the requested resource or action is forbidden.

409

Conflict

429

Too many requests.

500

Internal Server Error - There is a problem with the server. Please try again later.

503

Service Unavailable - We're temporarily offline for maintenance. Please try again later.

default

Error

post/v1/passwords/validate
Request samples
application/json
{
  • "password": {
    }
}
Response samples
application/json
{
  • "message": "string",
  • "syntaxErrors": {
    }
}

Initiate lost password process

Initiate the lost password process.

If the email address provided is associated with an active user, an email will be sent, containing a URL that redirects the user to change their password. The URL contains request parameters for all of the parameters required to change the password for the user via the /passwords/lost_password/resume POST endpoint.

SecurityapiKey
Request
Request Body schema: application/json
required
email
required
string <email>

E-mail Address of the user

Responses
204

Success - No Content.

400

Bad Request Error - Your request is invalid.

401

Unauthorized - Your credentials or access token are invalid.

403

Forbidden - Access to the requested resource or action is forbidden.

409

Conflict

429

Too many requests.

500

Internal Server Error - There is a problem with the server. Please try again later.

503

Service Unavailable - We're temporarily offline for maintenance. Please try again later.

default

Error

post/v1/passwords/lost_password/start
Request samples
application/json
{
  • "email": "user@example.com"
}
Response samples
application/json
{
  • "message": "string",
  • "syntaxErrors": {
    }
}

Resume lost password process

This is the second and final step in updating the password of a user who forgot their password.

SecurityapiKey
Request
Request Body schema: application/json
required
nonce
required
string = 6 characters ^[0-9]*$

A randomly generated one-time use code.

email
required
string <email>

E-mail Address of the user

required
object

The user's password or passcode used to log in a user. Passwords must be:

  • between 8 and 30 characters
  • include a lowercase character
  • include an uppercase character
  • include a digit and a special character
  • different from any of the 5 last such passwords used.

For non-PCI compliant integrations, the password submitted must be tokenised.

Responses
200

OK

400

Bad Request Error - Your request is invalid.

401

Unauthorized - Your credentials or access token are invalid.

403

Forbidden - Access to the requested resource or action is forbidden.

409

Conflict

429

Too many requests.

500

Internal Server Error - There is a problem with the server. Please try again later.

503

Service Unavailable - We're temporarily offline for maintenance. Please try again later.

default

Error

post/v1/passwords/lost_password/resume
Request samples
application/json
{
  • "nonce": "string",
  • "email": "user@example.com",
  • "newPassword": {
    }
}
Response samples
application/json
{
  • "token": "string"
}

Additional Factors

Enrol a user device for authentication using one-time passwords

This is the first step in enrolling the logged-in user's mobile device, where a one-time password is sent to the device.

Note that on the Sandbox Environment, text messages are not sent and the one-time-password is always "123456".

SecurityapiKey and authToken
Request
path Parameters
channel
required
string

The unique identifier for the channel.

Value: "SMS"
Responses
204

Success - No Content.

400

Bad Request Error - Your request is invalid.

401

Unauthorized - Your credentials or access token are invalid.

403

Forbidden - Access to the requested resource or action is forbidden.

404

Not found - The requested resource couldn't be found.

409

Conflict

429

Too many requests.

500

Internal Server Error - There is a problem with the server. Please try again later.

503

Service Unavailable - We're temporarily offline for maintenance. Please try again later.

default

Error

post/v1/authentication_factors/otp/{channel}
Response samples
application/json
{
  • "message": "string",
  • "syntaxErrors": {
    }
}

Verify enrolment of a user device for authentication using one-time passwords

The second step in enrolling the logged-in user (root or authorised user) to use one-time-passwords to enable verification of transactions.

Note that on the Sandbox Environment, text messages are not sent and the verificationCode is always set to "123456".

SecurityapiKey and authToken
Request
path Parameters
channel
required
string

The unique identifier for the channel.

Value: "SMS"
Request Body schema: application/json
required
verificationCode
required
string = 6 characters ^[0-9]*$

The code received by the user on the device.

Responses
204

Success - No Content.

400

Bad Request Error - Your request is invalid.

401

Unauthorized - Your credentials or access token are invalid.

403

Forbidden - Access to the requested resource or action is forbidden.

404

Not found - The requested resource couldn't be found.

409

Conflict

429

Too many requests.

500

Internal Server Error - There is a problem with the server. Please try again later.

503

Service Unavailable - We're temporarily offline for maintenance. Please try again later.

default

Error

post/v1/authentication_factors/otp/{channel}/verify
Request samples
application/json
{
  • "verificationCode": "string"
}
Response samples
application/json
{
  • "message": "string",
  • "syntaxErrors": {
    }
}

Step up

Issue a one-time password that can be used to step-up a token

Initiates the step-up token process by sending an SMS with an one-time-password to a device belonging to the logged-in user that was previously enrolled through /authentication_factors/otp/{channel} endpoint.

This process is required for endpoints that require a step-up token to complete the call.

Note that on the Sandbox Environment, text messages are not sent and the one-time-password is always "123456".

SecurityapiKey and authToken
Request
path Parameters
channel
required
string

The unique identifier for the channel.

Value: "SMS"
Responses
204

Success - No Content.

400

Bad Request Error - Your request is invalid.

401

Unauthorized - Your credentials or access token are invalid.

403

Forbidden - Access to the requested resource or action is forbidden.

404

Not found - The requested resource couldn't be found.

409

Conflict

500

Internal Server Error - There is a problem with the server. Please try again later.

503

Service Unavailable - We're temporarily offline for maintenance. Please try again later.

default

Error

post/v1/stepup/challenges/otp/{channel}
Response samples
application/json
{
  • "message": "string",
  • "syntaxErrors": {
    }
}

Verify a step-up token using a one-time password

Completes the verification process for a step up token.

Note that on the Sandbox Environment, text messages are not sent and the verificationCode is always "123456".

SecurityapiKey and authToken
Request
path Parameters
channel
required
string

The unique identifier for the channel.

Value: "SMS"
Request Body schema: application/json
required
verificationCode
required
string = 6 characters ^[0-9]*$

The code received by the user on the device.

Responses
204

Success - No Content.

400

Bad Request Error - Your request is invalid.

401

Unauthorized - Your credentials or access token are invalid.

403

Forbidden - Access to the requested resource or action is forbidden.

404

Not found - The requested resource couldn't be found.

409

Conflict

500

Internal Server Error - There is a problem with the server. Please try again later.

503

Service Unavailable - We're temporarily offline for maintenance. Please try again later.

default

Error

post/v1/stepup/challenges/otp/{channel}/verify
Request samples
application/json
{
  • "verificationCode": "string"
}
Response samples
application/json
{
  • "message": "string",
  • "syntaxErrors": {
    }
}

Buyers

Buyers are identities representing a business

Once on-boarded, Buyers can create payment runs and pay their suppliers in your application.

Create a buyer

Buyers are identities representing a business. Once on-boarded, Buyers can create and manage their own instruments via your plugin.

The information provided must be accurate and will be passed on for KYB verification with our partner.

SecurityapiKey
Request
Request Body schema: application/json
required
tag
string <= 50 characters ^[a-zA-Z0-9_-]+$

The tag field is a custom field that can be used to search and filter.

required
object

The admin user needs to be a director or a legal representative of the buyer that is being onboarded - this user cannot be deactivated.

Admin users need to verify their email address and mobile number, as well as complete KYC as part of the Buyer's due diligence process.

required
object

The details associated with the company being on-boarded. The details provided need to match exactly with the details provided during KYB.

acceptedTerms
required
boolean

Must be set to true to indicate that the buyer admin user has accepted the terms and conditions.

ipAddress
required
string [ 5 .. 45 ] characters

The IP address of the buyer user doing the registration.

baseCurrency
required
string = 3 characters

The currency expressed in ISO-4217 code.

Value: "GBP"
supportedCurrencies
required
Array of strings
Items Value: "GBP"
Responses
200

Success

400

Bad Request Error - Your request is invalid.

401

Unauthorized - Your credentials or access token are invalid.

403

Forbidden - Access to the requested resource or action is forbidden.

409

Conflict

429

Too many requests.

500

Internal Server Error - There is a problem with the server. Please try again later.

503

Service Unavailable - We're temporarily offline for maintenance. Please try again later.

default

Error

post/v1/buyers
Request samples
application/json
{
  • "tag": "string",
  • "adminUser": {
    },
  • "company": {
    },
  • "acceptedTerms": true,
  • "ipAddress": "string",
  • "baseCurrency": "GBP",
  • "supportedCurrencies": [
    ]
}
Response samples
application/json
{
  • "id": "string",
  • "tag": "string",
  • "adminUser": {
    },
  • "company": {
    },
  • "acceptedTerms": true,
  • "baseCurrency": "GBP",
  • "supportedCurrencies": [
    ],
  • "creationTimestamp": 0
}

Get buyer details

Retrieve the details of the buyer that the logged-in user belongs to.

Required user role: ADMIN

SecurityapiKey and authToken
Responses
200

Success

400

Bad Request Error - Your request is invalid.

401

Unauthorized - Your credentials or access token are invalid.

403

Forbidden - Access to the requested resource or action is forbidden.

429

Too many requests.

500

Internal Server Error - There is a problem with the server. Please try again later.

503

Service Unavailable - We're temporarily offline for maintenance. Please try again later.

default

Error

get/v1/buyers
Response samples
application/json
{
  • "id": "string",
  • "tag": "string",
  • "adminUser": {
    },
  • "company": {
    },
  • "acceptedTerms": true,
  • "baseCurrency": "GBP",
  • "supportedCurrencies": [
    ],
  • "creationTimestamp": 0,
  • "ipAddress": "string"
}

Update a buyer

Update the details of the buyer that the logged-in user belongs to.

The following Buyer details are verified during due diligence (KYB) and cannot be updated via the API once the Buyer has been verified:

  • Admin User Name
  • Admin User Surname
  • Admin User Email
  • Admin User Mobile Country Code
  • Admin User Mobile Number
  • Admin Date of Birth
  • Company Business Address

If these details need to be changed after due diligence is completed, please contact Customer Support to restart the Due Diligence process.

Required user role: ADMIN

SecurityapiKey and authToken
Request
Request Body schema: application/json
required
tag
string <= 50 characters ^[a-zA-Z0-9_-]+$

The tag field is a custom field that can be used to search and filter.

object

The details associated with the company. The details provided need to match exactly with the details provided during KYB.

object

The legal representative of the buyer. Admin users can invite and manage the buyer's authorised users.

baseCurrency
string = 3 characters

The currency expressed in ISO-4217 code.

Value: "GBP"
resetMobileCounter
boolean
Responses
201

Created

400

Bad Request Error - Your request is invalid.

401

Unauthorized - Your credentials or access token are invalid.

403

Forbidden - Access to the requested resource or action is forbidden.

409

Conflict

429

Too many requests.

500

Internal Server Error - There is a problem with the server. Please try again later.

503

Service Unavailable - We're temporarily offline for maintenance. Please try again later.

default

Error

patch/v1/buyers
Request samples
application/json
{
  • "tag": "string",
  • "company": {
    },
  • "adminUser": {
    },
  • "baseCurrency": "GBP",
  • "resetMobileCounter": true
}
Response samples
application/json
{
  • "id": "string",
  • "tag": "string",
  • "adminUser": {
    },
  • "company": {
    },
  • "acceptedTerms": true,
  • "baseCurrency": "GBP",
  • "supportedCurrencies": [
    ],
  • "creationTimestamp": 0
}

Start admin user email verification

The first step in verifying a admin user's email. The admin user whose email address is to be verified is sent an email containing a randomly generated code.

This code must then be provided in the buyerAdminUserEmailVerify operation to verify the admin user's email address.

Note that on the Sandbox Environment, the verificationCode is always set to "123456".

SecurityapiKey
Request
Request Body schema: application/json
required
email
required
string <email>

E-mail Address of the user

Responses
204

Success - No Content.

400

Bad Request Error - Your request is invalid.

401

Unauthorized - Your credentials or access token are invalid.

403

Forbidden - Access to the requested resource or action is forbidden.

409

Conflict

429

Too many requests.

500

Internal Server Error - There is a problem with the server. Please try again later.

503

Service Unavailable - We're temporarily offline for maintenance. Please try again later.

default

Error

post/v1/buyers/verification/email/send
Request samples
application/json
{
  • "email": "user@example.com"
}
Response samples
application/json
{
  • "message": "string",
  • "syntaxErrors": {
    }
}

Verify admin user email

The second step in verifying the admin user's email. The randomly generated code sent to the admin user via email, using the buyerAdminUserEmailVerificationCodeSend operation, is submitted here to verify the admin user's email.

This is needed as part of the verification process for basic due diligence.

Note that on the Sandbox Environment, the verificationCode is always set to "123456".

SecurityapiKey
Request
Request Body schema: application/json
required
email
required
string <email>

E-mail Address of the user

verificationCode
required
string = 6 characters ^[0-9]+$

A randomly generated one-time use code used to verify the user's email address or mobile number.

Responses
204

Success - No Content.

400

Bad Request Error - Your request is invalid.

401

Unauthorized - Your credentials or access token are invalid.

403

Forbidden - Access to the requested resource or action is forbidden.

409

Conflict

429

Too many requests.

500

Internal Server Error - There is a problem with the server. Please try again later.

503

Service Unavailable - We're temporarily offline for maintenance. Please try again later.

default

Error

post/v1/buyers/verification/email/verify
Request samples
application/json
{
  • "email": "user@example.com",
  • "verificationCode": "string"
}
Response samples
application/json
{
  • "message": "string",
  • "syntaxErrors": {
    }
}

Start buyer KYB

Buyers need to complete due diligence (KYB) before they can create payment runs and pay their suppliers.

This operation initiates the due diligence process for the buyer that the logged-in user belongs to.

Due Diligence is handled by a KYB provider - you will need to embed the KYB UI Component in your application so that the buyer will be able to perform the KYB process.

To initialise the KYB UI Component, you need a reference that is given you in the response of this operation.

Required user role: ADMIN

SecurityapiKey and authToken
Responses
200

Success

400

Bad Request Error - Your request is invalid.

401

Unauthorized - Your credentials or access token are invalid.

403

Forbidden - Access to the requested resource or action is forbidden.

409

Conflict

429

Too many requests.

500

Internal Server Error - There is a problem with the server. Please try again later.

503

Service Unavailable - We're temporarily offline for maintenance. Please try again later.

default

Error

post/v1/buyers/kyb
Response samples
application/json
{
  • "reference": "string"
}

Get buyer KYB status

Returns the KYB status for the buyer that the logged-in user belongs to.

Required user role: ADMIN

SecurityapiKey and authToken
Responses
200

Success

400

Bad Request Error - Your request is invalid.

401

Unauthorized - Your credentials or access token are invalid.

403

Forbidden - Access to the requested resource or action is forbidden.

429

Too many requests.

500

Internal Server Error - There is a problem with the server. Please try again later.

503

Service Unavailable - We're temporarily offline for maintenance. Please try again later.

default

Error

get/v1/buyers/kyb
Response samples
application/json
{
  • "kybStatus": "NOT_STARTED",
  • "ongoingKybStatus": "NOT_STARTED"
}

Buyer Authorised Users

Buyers can invite authorised users to access their account. Once on-boarded, authorised users can transact on behalf of the identity they are on-boarded with.

Authorised users are typically employees who have access to company's banking accounts.

Note that /users endpoints are to be used only for performing operations related to authorised users - getting or updating the details of admin users is to be done via /buyers endpoints.

Create a user

Creates a user that belongs to the buyer that the logged-in user belongs to.

Once on-boarded, users have access and manage the buyer's payment runs.

Users are assigned roles which limits the level of access they have and what they can do on behalf of the buyer.

Required user role: ADMIN

SecurityapiKey and authToken
Request
Request Body schema: application/json
required
name
required
string [ 1 .. 20 ] characters

The first name of the user.

surname
required
string [ 1 .. 20 ] characters

The last name of the user.

email
required
string <email>

E-mail Address of the user

object

Mobile number of the user

object

Date of birth of the authorised user.

roles
required
Array of strings non-empty

Roles define the level of access assigned to the user.

  • CREATOR: Users assigned this role can create, view and update payment runs.
  • CONTROLLER: Users assigned this role can view and link their company's bank accounts as well as fund payment runs.
Items Enum: "CREATOR" "CONTROLLER"
Responses
200

Success

400

Bad Request Error - Your request is invalid.

401

Unauthorized - Your credentials or access token are invalid.

403

Forbidden - Access to the requested resource or action is forbidden.

409

Conflict

429

Too many requests.

500

Internal Server Error - There is a problem with the server. Please try again later.

503

Service Unavailable - We're temporarily offline for maintenance. Please try again later.

default

Error

post/v1/users
Request samples
application/json
{
  • "name": "string",
  • "surname": "string",
  • "email": "user@example.com",
  • "mobile": {
    },
  • "dateOfBirth": {
    },
  • "roles": [
    ]
}
Response samples
application/json
{
  • "id": "string",
  • "buyerId": "string",
  • "name": "string",
  • "surname": "string",
  • "email": "user@example.com",
  • "mobile": {
    },
  • "active": true,
  • "dateOfBirth": {
    },
  • "roles": [
    ]
}

Get all users

Fetches all authorised users associated with the buyer that the logged-in user belongs to.

Required user role: ADMIN

SecurityapiKey and authToken
Request
query Parameters
offset
integer <int32> >= 0
Default: 0

The offset value for paging, indicating the initial item number to be returned from the data set satisfying the given criteria. Leave out to fetch the first page of results.

limit
integer <int32> [ 1 .. 100 ]
Default: 100

The limit of the results for paging, starting at the offset. Limit is always capped at 100.

active
boolean

Filter for active or deactivated users. Leave out to fetch all users.

email
string <email>

Filter for users with the specified email address.

Responses
200

Success

400

Bad Request Error - Your request is invalid.

401

Unauthorized - Your credentials or access token are invalid.

403

Forbidden - Access to the requested resource or action is forbidden.

429

Too many requests.

500

Internal Server Error - There is a problem with the server. Please try again later.

503

Service Unavailable - We're temporarily offline for maintenance. Please try again later.

default

Error

get/v1/users
Response samples
application/json
{
  • "users": [
    ],
  • "count": 0,
  • "responseCount": 0
}

Get a user

Retrieves the user identified by the user_id path parameter.

Required user role: ADMIN

SecurityapiKey and authToken
Request
path Parameters
user_id
required
string^[0-9]+$

The unique identifier for the user.

Example: 110747174434373672
Responses
200

Success

400

Bad Request Error - Your request is invalid.

401

Unauthorized - Your credentials or access token are invalid.

403

Forbidden - Access to the requested resource or action is forbidden.

404

Not found - The requested resource couldn't be found.

429

Too many requests.

500

Internal Server Error - There is a problem with the server. Please try again later.

503

Service Unavailable - We're temporarily offline for maintenance. Please try again later.

default

Error

get/v1/users/{user_id}
Response samples
application/json
{
  • "id": "string",
  • "buyerId": "string",
  • "name": "string",
  • "surname": "string",
  • "email": "user@example.com",
  • "mobile": {
    },
  • "active": true,
  • "dateOfBirth": {
    },
  • "roles": [
    ]
}

Update a user

Update the details of a user identified by the user_id in the the path parameter.

Only the fields that are specified in the request body will be updated. All other fields will remain unchanged.

When patching a mobile number, the new mobile number should be enrolled for Additional Factors.

Required user role: ADMIN

SecurityapiKey and authToken
Request
path Parameters
user_id
required
string^[0-9]+$

The unique identifier for the user.

Example: 110747174434373672
Request Body schema: application/json
required
name
string <= 20 characters

The first name of the user.

surname
string <= 20 characters

The last name of the user.

email
string <email>

E-mail Address of the user

object

Mobile number of the user

object

Date of birth of the authorised user.

roles
Array of strings non-empty

Roles define the level of access assigned to the user.

  • CREATOR: Users assigned this role can create, view and update payment runs.
  • CONTROLLER: Users assigned this role can view and link their company's bank accounts as well as fund payment runs.
Items Enum: "CREATOR" "CONTROLLER"
Responses
200

Success

400

Bad Request Error - Your request is invalid.

401

Unauthorized - Your credentials or access token are invalid.

403

Forbidden - Access to the requested resource or action is forbidden.

404

Not found - The requested resource couldn't be found.

409

Conflict

429

Too many requests.

500

Internal Server Error - There is a problem with the server. Please try again later.

503

Service Unavailable - We're temporarily offline for maintenance. Please try again later.

default

Error

patch/v1/users/{user_id}
Request samples
application/json
{
  • "name": "string",
  • "surname": "string",
  • "email": "user@example.com",
  • "mobile": {
    },
  • "dateOfBirth": {
    },
  • "roles": [
    ]
}
Response samples
application/json
{
  • "id": "string",
  • "buyerId": "string",
  • "name": "string",
  • "surname": "string",
  • "email": "user@example.com",
  • "mobile": {
    },
  • "active": true,
  • "dateOfBirth": {
    },
  • "roles": [
    ]
}

Activate a user

Activate the user identified by the user_id path parameter.

By default, any new users created will be automatically activated. This operation needs to be used only if the user was previously de-activated using the userDeactivate operation, or if the user was de-activated automatically after multiple incorrect login attempts.

Required user role: ADMIN

SecurityapiKey and authToken
Request
path Parameters
user_id
required
string^[0-9]+$

The unique identifier for the user.

Example: 110747174434373672
Responses
204

Success - No Content.

400

Bad Request Error - Your request is invalid.

401

Unauthorized - Your credentials or access token are invalid.

403

Forbidden - Access to the requested resource or action is forbidden.

404

Not found - The requested resource couldn't be found.

429

Too many requests.

500

Internal Server Error - There is a problem with the server. Please try again later.

503

Service Unavailable - We're temporarily offline for maintenance. Please try again later.

default

Error

post/v1/users/{user_id}/activate
Response samples
application/json
{
  • "message": "string",
  • "syntaxErrors": {
    }
}

Deactivate a user

De-activate the user identified by the user_id path parameter.

Deactivated users cannot log in or execute any operations with their credentials.

This operations is not final and a user can be re-activated using the userActivate operation. Note that another active user would need to log in so as to re-activate the de-activated user.

Required user role: ADMIN

SecurityapiKey and authToken
Request
path Parameters
user_id
required
string^[0-9]+$

The unique identifier for the user.

Example: 110747174434373672
Responses
204

Success - No Content.

400

Bad Request Error - Your request is invalid.

401

Unauthorized - Your credentials or access token are invalid.

403

Forbidden - Access to the requested resource or action is forbidden.

404

Not found - The requested resource couldn't be found.

429

Too many requests.

500

Internal Server Error - There is a problem with the server. Please try again later.

503

Service Unavailable - We're temporarily offline for maintenance. Please try again later.

default

Error

post/v1/users/{user_id}/deactivate
Response samples
application/json
{
  • "message": "string",
  • "syntaxErrors": {
    }
}

Send a user invite

Once a user is created using the userCreate operation, the user needs to setup his/her password.

An invitation needs to be sent to the user in order to be able to set up the password for the first time. The invitation email, which remains valid for 1 month, will contain a URL having all information required to setup the password via the userInviteConsume.

Required user role: ADMIN

SecurityapiKey and authToken
Request
path Parameters
user_id
required
string^[0-9]+$

The unique identifier for the user.

Example: 110747174434373672
Responses
204

Success - No Content.

400

Bad Request Error - Your request is invalid.

401

Unauthorized - Your credentials or access token are invalid.

403

Forbidden - Access to the requested resource or action is forbidden.

404

Not found - The requested resource couldn't be found.

409

Conflict

429

Too many requests.

500

Internal Server Error - There is a problem with the server. Please try again later.

503

Service Unavailable - We're temporarily offline for maintenance. Please try again later.

default

Error

post/v1/users/{user_id}/invite
Response samples
application/json
{
  • "message": "string",
  • "syntaxErrors": {
    }
}

Validate a user invite

Check if a user's invite is still valid. This operation is useful to avoid having the user fill in a form only to be held by a validation issue (eg. expired invite).

SecurityapiKey
Request
path Parameters
user_id
required
string^[0-9]+$

The unique identifier for the user.

Example: 110747174434373672
Request Body schema: application/json
required
inviteCode
required
string = 6 characters ^[0-9]*$

A randomly generated one-time use code.

Responses
204

Success - No Content.

400

Bad Request Error - Your request is invalid.

401

Unauthorized - Your credentials or access token are invalid.

403

Forbidden - Access to the requested resource or action is forbidden.

404

Not found - The requested resource couldn't be found.

409

Conflict

429

Too many requests.

500

Internal Server Error - There is a problem with the server. Please try again later.

503

Service Unavailable - We're temporarily offline for maintenance. Please try again later.

default

Error

post/v1/users/{user_id}/invite/validate
Request samples
application/json
{
  • "inviteCode": "string"
}
Response samples
application/json
{
  • "message": "string",
  • "syntaxErrors": {
    }
}

Consume a user invite

Consumes an invitation previously sent to the user via userInviteSend. This is needed so that the invited user sets up the password.

Note that on the Sandbox Environment, the inviteCode is always set to "123456".

SecurityapiKey
Request
path Parameters
user_id
required
string^[0-9]+$

The unique identifier for the user.

Example: 110747174434373672
Request Body schema: application/json
required
inviteCode
required
string = 6 characters ^[0-9]*$

A randomly generated one-time use code.

required
object

The user's password or passcode used to log in a user. Passwords must be:

  • between 8 and 30 characters
  • include a lowercase character
  • include an uppercase character
  • include a digit and a special character
  • different from any of the 5 last such passwords used.

For non-PCI compliant integrations, the password submitted must be tokenised.

Responses
200

Success

400

Bad Request Error - Your request is invalid.

401

Unauthorized - Your credentials or access token are invalid.

403

Forbidden - Access to the requested resource or action is forbidden.

404

Not found - The requested resource couldn't be found.

409

Conflict

429

Too many requests.

500

Internal Server Error - There is a problem with the server. Please try again later.

503

Service Unavailable - We're temporarily offline for maintenance. Please try again later.

default

Error

post/v1/users/{user_id}/invite/consume
Request samples
application/json
{
  • "inviteCode": "string",
  • "password": {
    }
}
Response samples
application/json
{
  • "token": "string"
}

Send an email verification code to the authorised user

The first step in verifying an authorised user's email. The authorised user whose email address is to be verified is sent an email containing a randomly generated code.

This code must then be provided in the authorisedUserEmailVerify operation to verify the authorised user's email address.

Note that on the Sandbox Environment, the verificationCode is always set to "123456".

SecurityapiKey
Request
Request Body schema: application/json
required
email
required
string <email>

E-mail Address of the user

Responses
204

Success - No Content.

400

Bad Request Error - Your request is invalid.

401

Unauthorized - Your credentials or access token are invalid.

403

Forbidden - Access to the requested resource or action is forbidden.

409

Conflict

429

Too many requests.

500

Internal Server Error - There is a problem with the server. Please try again later.

503

Service Unavailable - We're temporarily offline for maintenance. Please try again later.

default

Error

post/v1/users/verification/email/send
Request samples
application/json
{
  • "email": "user@example.com"
}
Response samples
application/json
{
  • "message": "string",
  • "syntaxErrors": {
    }
}

Verify email of the authorised user

The second step in verifying the authorised user's email. The randomly generated code sent to the authorised user via email, using the authorisedUserEmailVerificationCodeSend operation, is submitted here to verify the authorised user's email.

This is needed as part of the verification process for basic due diligence.

Note that on the Sandbox Environment, the verificationCode is always set to "123456".

SecurityapiKey
Request
Request Body schema: application/json
required
email
required
string <email>

E-mail Address of the user

verificationCode
required
string = 6 characters ^[0-9]+$

A randomly generated one-time use code used to verify the user's email address or mobile number.

Responses
204

Success - No Content.

400

Bad Request Error - Your request is invalid.

401

Unauthorized - Your credentials or access token are invalid.

403

Forbidden - Access to the requested resource or action is forbidden.

409

Conflict

429

Too many requests.

500

Internal Server Error - There is a problem with the server. Please try again later.

503

Service Unavailable - We're temporarily offline for maintenance. Please try again later.

default

Error

post/v1/users/verification/email/verify
Request samples
application/json
{
  • "email": "user@example.com",
  • "verificationCode": "string"
}
Response samples
application/json
{
  • "message": "string",
  • "syntaxErrors": {
    }
}

Payment runs

A Payment run contains a list of supplier payments. A Payment run can be

  • created by a user with a CREATOR role
  • confirmed by a user with a CONTROLLER role
  • funded by a user with a CONTROLLER role

Note that the Controller user must have their mobile device enrolled to SCA.

Before a payment run can be executed, it must be funded. Users with the CONTROLLER role must link their company's bank account(s) that are represented as Linked Accounts, which than can be used as the funding source for a payment run.

Depending on the bank's constraints it may not be possible to deposit the total amount of funds required for a payment run, in which case the payment run will be automatically split into funding groups. All funding groups must be funded and executed for the payment run to be marked as completed.

Note that even if the payment is created successfully, you still need to check its status in order to determine if it is completed orfailed.

Create a payment run

Create a new payment run containing a list of outstanding supplier payments.

Required user role: CREATOR

SecurityapiKey and authToken
Request
Request Body schema: application/json
paymentRunRef
string

A unique identifier by which you identify the payment run with on your system.

tag
string <= 50 characters ^[a-zA-Z0-9_-]+$

The tag field is a custom field that can be used to search and filter.

description
string

The long form description of the payment run

required
Array of objects (Payment) [ 1 .. 1000 ] items

The list of payments associated with the payment run

Responses
200

OK

400

Bad Request Error - Your request is invalid.

401

Unauthorized - Your credentials or access token are invalid.

403

Forbidden - Access to the requested resource or action is forbidden.

409

Conflict

429

Too many requests.

500

Internal Server Error - There is a problem with the server. Please try again later.

503

Service Unavailable - We're temporarily offline for maintenance. Please try again later.

default

Error

post/v1/payment_runs
Request samples
application/json
{
  • "paymentRunRef": "94fddfb2-297d-423d-9157-4200b7beb834",
  • "tag": "string",
  • "description": "September payment run 01",
  • "payments": [
    ]
}
Response samples
application/json
{
  • "id": "string",
  • "paymentRunRef": "94fddfb2-297d-423d-9157-4200b7beb834",
  • "tag": "string",
  • "description": "September payment run 01",
  • "createdBy": "110747174434373672",
  • "status": "PENDING_CONFIRMATION",
  • "statusReason": "string",
  • "payments": [
    ],
  • "createdAt": "2019-08-24T14:15:22Z"
}

Get payment runs

Retrieve the list of payment runs belonging to the buyer that the logged-in user belongs to.

Required user roles: CONTROLLER OR CREATOR

SecurityapiKey and authToken
Request
query Parameters
limit
integer <int32> [ 1 .. 100 ]
Default: 100

The limit of the results for paging, starting at the offset. Limit is always capped at 100.

offset
integer <int32> >= 0
Default: 0

The offset value for paging, indicating the initial item number to be returned from the data set satisfying the given criteria. Leave out to fetch the first page of results.

tag
Array of strings unique

Filter by tag. The exact tag must be provided, as wildcards are not supported. Leave out to fetch all entries.

Responses
200

OK

400

Bad Request Error - Your request is invalid.

401

Unauthorized - Your credentials or access token are invalid.

403

Forbidden - Access to the requested resource or action is forbidden.

429

Too many requests.

500

Internal Server Error - There is a problem with the server. Please try again later.

503

Service Unavailable - We're temporarily offline for maintenance. Please try again later.

default

Error

get/v1/payment_runs
Response samples
application/json
{
  • "count": 10,
  • "responseCount": 100,
  • "paymentRuns": [
    ]
}

Get a payment run

Retrieve a payment run belonging to the buyer that the logged-in user belongs to.

Required user roles: CONTROLLER OR CREATOR

SecurityapiKey and authToken
Request
path Parameters
payment_run_id
required
string^[0-9a-fA-F]{24}$

The unique identifier of the payment run.

Responses
200

OK

400

Bad Request Error - Your request is invalid.

401

Unauthorized - Your credentials or access token are invalid.

403

Forbidden - Access to the requested resource or action is forbidden.

404

Not found - The requested resource couldn't be found.

429

Too many requests.

500

Internal Server Error - There is a problem with the server. Please try again later.

503

Service Unavailable - We're temporarily offline for maintenance. Please try again later.

default

Error

get/v1/payment_runs/{payment_run_id}
Response samples
application/json
{
  • "id": "string",
  • "paymentRunRef": "94fddfb2-297d-423d-9157-4200b7beb834",
  • "tag": "string",
  • "description": "September payment run 01",
  • "createdBy": "110747174434373672",
  • "status": "PENDING_CONFIRMATION",
  • "statusReason": "string",
  • "payments": [
    ],
  • "createdAt": "2019-08-24T14:15:22Z"
}

Confirm a payment run

Confirm that a payment run can be executed.

Required user role: CONTROLLER

SecurityapiKey and authToken
Request
path Parameters
payment_run_id
required
string^[0-9a-fA-F]{24}$

The unique identifier of the payment run.

Responses
204

Success - No Content.

400

Bad Request Error - Your request is invalid.

401

Unauthorized - Your credentials or access token are invalid.

403

Forbidden - Access to the requested resource or action is forbidden.

404

Not found - The requested resource couldn't be found.

409

Conflict

500

Internal Server Error - There is a problem with the server. Please try again later.

503

Service Unavailable - We're temporarily offline for maintenance. Please try again later.

default

Error

post/v1/payment_runs/{payment_run_id}/confirm
Response samples
application/json
{
  • "message": "string",
  • "syntaxErrors": {
    }
}

Get a payment run funding instructions

Start the the funding process of a payment run.

Specify the funding source of the payment run by providing an id to an already linked account.

Depending on the maximum payment amount constraints imposed by the bank that is providing the account, the payment run may be split in 2 or more groups. Note that you'll need to complete a funding process for each instruction returned.

Required user role: CONTROLLER

SecurityapiKey and authToken
Request
path Parameters
payment_run_id
required
string^[0-9a-fA-F]{24}$

The unique identifier of the payment run.

query Parameters
linkedAccountIds
required
Array of strings unique

The unique identifier of the linked account, that is to be used as the funding source for the payment run.

Note that only one linked account per currency is supported.

Example: linkedAccountIds=652d25b73541d8084a88a38d
Responses
200

OK

400

Bad Request Error - Your request is invalid.

401

Unauthorized - Your credentials or access token are invalid.

403

Forbidden - Access to the requested resource or action is forbidden.

404

Not found - The requested resource couldn't be found.

409

Conflict

429

Too many requests.

500

Internal Server Error - There is a problem with the server. Please try again later.

503

Service Unavailable - We're temporarily offline for maintenance. Please try again later.

default

Error

get/v1/payment_runs/{payment_run_id}/fund
Response samples
application/json
{
  • "count": 10,
  • "responseCount": 100,
  • "fundingInstructions": [
    ]
}

Cancel a payment run

Cancel a payment run.

Note that only payment runs which haven't started executing and whose status is PENDING_CONFIRMATION can be cancelled.

Required user roles: CONTROLLER OR CREATOR

SecurityapiKey and authToken
Request
path Parameters
payment_run_id
required
string^[0-9a-fA-F]{24}$

The unique identifier of the payment run.

Responses
204

Success - No Content.

400

Bad Request Error - Your request is invalid.

401

Unauthorized - Your credentials or access token are invalid.

403

Forbidden - Access to the requested resource or action is forbidden.

404

Not found - The requested resource couldn't be found.

409

Conflict

429

Too many requests.

500

Internal Server Error - There is a problem with the server. Please try again later.

503

Service Unavailable - We're temporarily offline for maintenance. Please try again later.

default

Error

post/v1/payment_runs/{payment_run_id}/cancel
Response samples
application/json
{
  • "message": "string",
  • "syntaxErrors": {
    }
}

Linked Accounts

Linked accounts represent bank accounts that the buyer has with other banks. Once set up, they are used to fund payment runs.

Get Linked accounts

Retrieves the linked accounts belonging to the buyer that the logged-in user belongs to.

Required user role: CONTROLLER

SecurityapiKey and authToken
Responses
200

OK

400

Bad Request Error - Your request is invalid.

401

Unauthorized - Your credentials or access token are invalid.

403

Forbidden - Access to the requested resource or action is forbidden.

429

Too many requests.

500

Internal Server Error - There is a problem with the server. Please try again later.

503

Service Unavailable - We're temporarily offline for maintenance. Please try again later.

default

Error

get/v1/linked_accounts
Response samples
application/json
{
  • "linkedAccounts": [
    ],
  • "count": 0,
  • "responseCount": 0
}

Get Linked account

Retrieves a linked account of the buyer that the logged-in user belongs to.

Required user role: CONTROLLER

SecurityapiKey and authToken
Request
path Parameters
linked_account_id
required
string^[0-9a-fA-F]{24}$

The unique identifier of the linked account.

Responses
200

OK

400

Bad Request Error - Your request is invalid.

401

Unauthorized - Your credentials or access token are invalid.

403

Forbidden - Access to the requested resource or action is forbidden.

404

Not found - The requested resource couldn't be found.

429

Too many requests.

500

Internal Server Error - There is a problem with the server. Please try again later.

503

Service Unavailable - We're temporarily offline for maintenance. Please try again later.

default

Error

get/v1/linked_accounts/{linked_account_id}
Response samples
application/json
{
  • "id": "652d25b73541d8084a88a38d",
  • "accountIdentification": {
    },
  • "currency": "GBP",
  • "institution": {
    },
  • "consent": {
    },
  • "status": "LINKED"
}

Delete a linked accountDeprecated

Delete a linked account.

Required user role: CONTROLLER

SecurityapiKey and authToken
Request
path Parameters
linked_account_id
required
string^[0-9a-fA-F]{24}$

The unique identifier of the linked account.

Responses
204

Success - No Content.

400

Bad Request Error - Your request is invalid.

401

Unauthorized - Your credentials or access token are invalid.

403

Forbidden - Access to the requested resource or action is forbidden.

404

Not found - The requested resource couldn't be found.

429

Too many requests.

500

Internal Server Error - There is a problem with the server. Please try again later.

503

Service Unavailable - We're temporarily offline for maintenance. Please try again later.

default

Error

delete/v1/linked_accounts/{linked_account_id}
Response samples
application/json
{
  • "message": "string",
  • "syntaxErrors": {
    }
}

Unlink a linked account

Unlinks a linked account identified by the linked_account_id.

This action is not reversible and if the buyer wants to use this linked account again to fund payment runs, they will have to re-link the account. More information on how to link an account can be found here.

Details of an unlinked account, can still be retrieved via the Get linked accounts and Get linked account endpoints.

Required user role: CONTROLLER

SecurityapiKey and authToken
Request
path Parameters
linked_account_id
required
string^[0-9a-fA-F]{24}$

The unique identifier of the linked account.

Responses
200

OK

400

Bad Request Error - Your request is invalid.

401

Unauthorized - Your credentials or access token are invalid.

403

Forbidden - Access to the requested resource or action is forbidden.

404

Not found - The requested resource couldn't be found.

429

Too many requests.

500

Internal Server Error - There is a problem with the server. Please try again later.

503

Service Unavailable - We're temporarily offline for maintenance. Please try again later.

default

Error

post/v1/linked_accounts/{linked_account_id}/unlink
Response samples
application/json
{
  • "id": "652d25b73541d8084a88a38d",
  • "accountIdentification": {
    },
  • "currency": "GBP",
  • "institution": {
    },
  • "consent": {
    },
  • "status": "LINKED"
}

Simulator

Simulators enable you to trigger processes in Sandbox that in Production are triggered from an external action rather than from your application. this way you can test scenarios that otherwise you would only encounter in the Live environment.

Note: These endpoints are only available on Sandbox and won’t work in the Live environment.

Simulate Funding

Simulate funding a payment run using a linked account.

This endpoint will only function in Sandbox and should not be used in the Live environment.

SecurityapiKey
Request
path Parameters
payment_run_id
required
string^[0-9a-fA-F]{24}$
group_reference
required
string
Responses
201

Success

400

Bad Request Error - Your request is invalid.

401

Unauthorized - Your credentials or access token are invalid.

403

Forbidden - Access to the requested resource or action is forbidden.

404

Not found - The requested resource couldn't be found.

409

Conflict

500

Internal Server Error - There is a problem with the server. Please try again later.

503

Service Unavailable - We're temporarily offline for maintenance. Please try again later.

default

Error

post/simulate/v1/payment_runs/{payment_run_id}/fund_group/{group_reference}
Response samples
application/json
{
  • "message": "string",
  • "syntaxErrors": {
    }
}

Simulate Linked Account

Simulate linking an account via Open Banking to fund payments within a payment run.

This endpoint will only function in Sandbox and should not be used in the Live environment.

SecurityapiKey
Request
Request Body schema: application/json
required
institutionId
required
string
buyerId
required
string
createdBy
required
string
required
FasterPaymentsBankDetails (object)

The bank details that uniquely identify the account on the banking systems.

Responses
201

OK

400

Bad Request Error - Your request is invalid.

401

Unauthorized - Your credentials or access token are invalid.

403

Forbidden - Access to the requested resource or action is forbidden.

409

Conflict

500

Internal Server Error - There is a problem with the server. Please try again later.

503

Service Unavailable - We're temporarily offline for maintenance. Please try again later.

default

Error

post/simulate/v1/linked_accounts
Request samples
application/json
{
  • "institutionId": "string",
  • "buyerId": "string",
  • "createdBy": "string",
  • "accountIdentification": {
    }
}
Response samples
application/json
{
  • "id": "652d25b73541d8084a88a38d",
  • "accountIdentification": {
    },
  • "currency": "GBP",
  • "institution": {
    },
  • "consent": {
    },
  • "status": "LINKED",
  • "createdAt": "string"
}

Simulate Buyer KYB Verify

Simulates due diligence (KYB) for Buyers.

This endpoint will only function in Sandbox and should not be used in the Live environment.

SecurityapiKey
Request
path Parameters
buyer_id
required
string
Responses
204

Success - No Content.

400

Bad Request Error - Your request is invalid.

401

Unauthorized - Your credentials or access token are invalid.

403

Forbidden - Access to the requested resource or action is forbidden.

404

Not found - The requested resource couldn't be found.

500

Internal Server Error - There is a problem with the server. Please try again later.

503

Service Unavailable - We're temporarily offline for maintenance. Please try again later.

default

Error

post/simulate/v1/buyers/{buyer_id}/verify
Response samples
application/json
{
  • "message": "string",
  • "syntaxErrors": {
    }
}

Simulate Payment Run SCA Challange Issuance

Simulates issuing the SCA challenge for a payment run.

SecurityapiKey and authToken
Request
path Parameters
channel
required
string

The unique identifier for the channel.

Value: "SMS"
payment_run_id
required
string^[0-9a-fA-F]{24}$

The unique identifier for the payment run.

Responses
204

No Content

400

Bad Request Error - Your request is invalid.

401

Unauthorized - Your credentials or access token are invalid.

403

Forbidden - Access to the requested resource or action is forbidden.

404

Not found - The requested resource couldn't be found.

409

Conflict

429

Too many requests.

500

Internal Server Error - There is a problem with the server. Please try again later.

503

Service Unavailable - We're temporarily offline for maintenance. Please try again later.

default

Error

post/simulate/v1/payment_run_sca/{payment_run_id}/challenges/otp/{channel}
Response samples
application/json
{
  • "message": "string",
  • "syntaxErrors": {
    }
}

Simulate Payment Run SCA Challange Verification

Simulates verifying the SCA challenge for a payment run.

SecurityapiKey and authToken
Request
path Parameters
channel
required
string

The unique identifier for the channel.

Value: "SMS"
payment_run_id
required
string^[0-9a-fA-F]{24}$

The unique identifier for the payment run.

Request Body schema: application/json
required
verificationCode
required
string non-empty
Responses
204

No Content

400

Bad Request Error - Your request is invalid.

401

Unauthorized - Your credentials or access token are invalid.

403

Forbidden - Access to the requested resource or action is forbidden.

404

Not found - The requested resource couldn't be found.

409

Conflict

429

Too many requests.

500

Internal Server Error - There is a problem with the server. Please try again later.

503

Service Unavailable - We're temporarily offline for maintenance. Please try again later.

default

Error

post/simulate/v1/payment_run_sca/{payment_run_id}/challenges/otp/{channel}/verify
Request samples
application/json
{
  • "verificationCode": "string"
}
Response samples
application/json
{
  • "message": "string",
  • "syntaxErrors": {
    }
}

Buyers

Buyers are identities representing companies. Once on-boarded, Buyers can create and manage their own instruments via your application.

Buyer KYB status updateWebhook

Notification that the KYB status of a buyer identity has been updated.

Request
header Parameters
call-ref
string

A call reference generated by the caller and unique to the caller to provide correlation between the caller and system with a maximum length of 255

published-timestamp
required
integer <int64>

The timestamp, expressed in Epoch timestamp using millisecond precision, when this event was published.

signature
required
string

The signature to verify the authenticity of this request. This is the base64 hash (HmacSHA256) of the published-timestamp using your API key.

Request Body schema: application/json
required
type
string
Value: "buyerKYBWatch"
object
Responses
200

Return a 200 status to indicate that the data was received successfully

Request samples
application/json
{
  • "type": "buyerKYBWatch",
  • "payload": {
    }
}

Buyer Beneficiary status updateWebhook

Notification that the verification status of a buyer beneficiary has been updated.

Request
header Parameters
call-ref
string

A call reference generated by the caller and unique to the caller to provide correlation between the caller and system with a maximum length of 255

published-timestamp
required
integer <int64>

The timestamp, expressed in Epoch timestamp using millisecond precision, when this event was published.

signature
required
string

The signature to verify the authenticity of this request. This is the base64 hash (HmacSHA256) of the published-timestamp using your API key.

Request Body schema: application/json
required
type
string
Value: "buyerBeneficiaryStatusWatch"
object
Responses
200

Return a 200 status to indicate that the data was received successfully

Request samples
application/json
{
  • "type": "buyerBeneficiaryStatusWatch",
  • "payload": {
    }
}

Buyer activationWebhook

Notification that a buyer has been activated.

Request
header Parameters
call-ref
string

A call reference generated by the caller and unique to the caller to provide correlation between the caller and system with a maximum length of 255

published-timestamp
required
integer <int64>

The timestamp, expressed in Epoch timestamp using millisecond precision, when this event was published.

signature
required
string

The signature to verify the authenticity of this request. This is the base64 hash (HmacSHA256) of the published-timestamp using your API key.

Request Body schema: application/json
required
type
string
Value: "buyerActivatedWatch"
object
Responses
200

Return a 200 status to indicate that the data was received successfully

Request samples
application/json
{
  • "type": "buyerActivatedWatch",
  • "payload": {
    }
}

Buyer deactivationWebhook

Notification that a buyer identity has been deactivated.

Request
header Parameters
call-ref
string

A call reference generated by the caller and unique to the caller to provide correlation between the caller and system with a maximum length of 255

published-timestamp
required
integer <int64>

The timestamp, expressed in Epoch timestamp using millisecond precision, when this event was published.

signature
required
string

The signature to verify the authenticity of this request. This is the base64 hash (HmacSHA256) of the published-timestamp using your API key.

Request Body schema: application/json
required
type
string
Value: "buyerDeactivatedWatch"
object
Responses
200

Return a 200 status to indicate that the data was received successfully

Request samples
application/json
{
  • "type": "buyerDeactivatedWatch",
  • "payload": {
    }
}

Payment runs

Notification that the Payment Run and payment statuses have been updated.

Payment Run UpdateWebhook

Notification that the status of a Payment Run has been updated.

Request
header Parameters
call-ref
string

A call reference generated by the caller and unique to the caller to provide correlation between the caller and system with a maximum length of 255

published-timestamp
required
integer <int64>

The timestamp, expressed in Epoch timestamp using millisecond precision, when this event was published.

signature
required
string

The signature to verify the authenticity of this request. This is the base64 hash (HmacSHA256) of the published-timestamp using your API key.

Request Body schema: application/json
required

Payment run event triggered when the status changes

type
string
Value: "paymentRunWatch"
object (PaymentRun)
Responses
200

Return a 200 status to indicate that the data was received successfully

Request samples
application/json
{
  • "type": "paymentRunWatch",
  • "payload": {
    }
}

Payment UpdateWebhook

Notification that the status of a payment in the Payment Run has been updated.

Request
header Parameters
call-ref
string

A call reference generated by the caller and unique to the caller to provide correlation between the caller and system with a maximum length of 255

published-timestamp
required
integer <int64>

The timestamp, expressed in Epoch timestamp using millisecond precision, when this event was published.

signature
required
string

The signature to verify the authenticity of this request. This is the base64 hash (HmacSHA256) of the published-timestamp using your API key.

Request Body schema: application/json
required

Event triggered when the status of a payment run payment changes

type
string
Value: "paymentRunPaymentWatch"
object (Payment)
Responses
200

Return a 200 status to indicate that the data was received successfully

Request samples
application/json
{
  • "type": "paymentRunPaymentWatch",
  • "payload": {
    }
}

Linked Accounts

Notification that the status of a Linked Account has been updated.

Linked Account UpdateWebhook

Notification of the status update for a linked Account.

Request
header Parameters
call-ref
string

A call reference generated by the caller and unique to the caller to provide correlation between the caller and system with a maximum length of 255

published-timestamp
required
integer <int64>

The timestamp, expressed in Epoch timestamp using millisecond precision, when this event was published.

signature
required
string

The signature to verify the authenticity of this request. This is the base64 hash (HmacSHA256) of the published-timestamp using your API key.

Request Body schema: application/json
required

Payment run event triggered when the status changes

type
required
string
Value: "linkedAccountWatch"
required
Linked Account Status (object) or StatusErrorDuplicatedAccount (object) (Linked Account Status)
Responses
200

Return a 200 status to indicate that the data was received successfully

Request samples
application/json
{
  • "type": "linkedAccountWatch",
  • "payload": {
    }
}

Login

Tokens webhooks

Login attemptWebhook

Notification that a login attempt was completed successfully or declined.

Request
header Parameters
call-ref
string

A call reference generated by the caller and unique to the caller to provide correlation between the caller and system with a maximum length of 255

published-timestamp
required
integer <int64>

The timestamp, expressed in Epoch timestamp using millisecond precision, when this event was published.

signature
required
string

The signature to verify the authenticity of this request. This is the base64 hash (HmacSHA256) of the published-timestamp using your API key.

Request Body schema: application/json
required
type
string
Value: "loginWatch"
object
Responses
200

Return a 200 status to indicate that the data was received successfully

Request samples
application/json
{
  • "type": "loginWatch",
  • "payload": {
    }
}

Stepup

Notification that a step-up has been completed or declined.

Step-up statusWebhook

Notification that a step-up has been completed or declined.

Request
header Parameters
call-ref
string

A call reference generated by the caller and unique to the caller to provide correlation between the caller and system with a maximum length of 255

published-timestamp
required
integer <int64>

The timestamp, expressed in Epoch timestamp using millisecond precision, when this event was published.

signature
required
string

The signature to verify the authenticity of this request. This is the base64 hash (HmacSHA256) of the published-timestamp using your API key.

Request Body schema: application/json
required
type
string
Value: "stepupWatch"
object
Responses
200

Return a 200 status to indicate that the data was received successfully

Request samples
application/json
{
  • "type": "stepupWatch",
  • "payload": {
    }
}

Authentication Factors

Notification of the Authentication Factors that are used for the Identity.

Enrolment statusWebhook

Notification that an enrolment has been accepted or declined.

Request
header Parameters
call-ref
string

A call reference generated by the caller and unique to the caller to provide correlation between the caller and system with a maximum length of 255

published-timestamp
required
integer <int64>

The timestamp, expressed in Epoch timestamp using millisecond precision, when this event was published.

signature
required
string

The signature to verify the authenticity of this request. This is the base64 hash (HmacSHA256) of the published-timestamp using your API key.

Request Body schema: application/json
required
type
string
Value: "authenticationFactorsWatch"
object
Responses
200

Return a 200 status to indicate that the data was received successfully

Request samples
application/json
{
  • "type": "authenticationFactorsWatch",
  • "payload": {
    }
}

Transactions

Notification that the status of a transaction has been updated.

Sweeping status updateWebhook

Notification that the sweeping status has been updated.

Sweeping represents transactions that return money to the source account. It may be triggered by unmatched incoming transaction or by failed payment run payments.

Request
header Parameters
call-ref
string

A call reference generated by the caller and unique to the caller to provide correlation between the caller and system with a maximum length of 255

published-timestamp
required
integer <int64>

The timestamp, expressed in Epoch timestamp using millisecond precision, when this event was published.

signature
required
string

The signature to verify the authenticity of this request. This is the base64 hash (HmacSHA256) of the published-timestamp using your API key.

Request Body schema: application/json
required
type
required
string
Value: "sweepingWatch"
required
object
Responses
200

Return a 200 status to indicate that the data was received successfully

Request samples
application/json
{
  • "type": "sweepingWatch",
  • "payload": {
    }
}