Skip to content
/
Get buyer KYB status

Weavr Embedded Payment Run API (v1)

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.

Download OpenAPI description
openapi.json
openapi.yaml
Overview
License
private
Languages
Servers
Mock server
https://api.weavr.io/_mock/products/payment-run/openapi
Sandbox
https://sandbox.weavr.io/payment-run

Tokens

Operations

Passwords

Operations

Additional Factors

Operations

Step up

Operations

Buyers

Buyers are identities representing a business

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

Operations

Start buyer KYB

Request

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

Security
apiKey and authToken
Headers
idempotency-refstring

A unique call reference generated by the caller that, taking into consideration the payload as well as the operation itself, helps avoid duplicate operations. Idempotency reference uniqueness is maintained for at least 24 hours.

curl -i -X POST \
  https://api.weavr.io/_mock/products/payment-run/openapi/v1/buyers/kyb \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'api-key: YOUR_API_KEY_HERE' \
  -H 'idempotency-ref: string'

Responses

Success

Headers
request-refstringrequired

A request identifier. Providing this reference when contacting our support team will help us investigate your query.

Bodyapplication/json
referencestring^[0-9]+$required

The reference required to initialise the KYB UI Component.

Response
application/json
{
  "reference": "string"
}

Get buyer KYB status

Request

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

Required user role: ADMIN

Security
apiKey and authToken
curl -i -X GET \
  https://api.weavr.io/_mock/products/payment-run/openapi/v1/buyers/kyb \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'api-key: YOUR_API_KEY_HERE'

Responses

Success

Headers
request-refstringrequired

A request identifier. Providing this reference when contacting our support team will help us investigate your query.

Bodyapplication/json
kybStatusstring

The effective due diligence status of the buyer that the logged-in user belongs to.

Enum"NOT_STARTED""INITIATED""PENDING_REVIEW""APPROVED""REJECTED"
ongoingKybStatusstring

The ongoing due diligence status of the buyer that the logged-in user belongs to.

Enum"NOT_STARTED""INITIATED""PENDING_REVIEW""APPROVED""REJECTED"
Response
application/json
{
  "kybStatus": "NOT_STARTED",
  "ongoingKybStatus": "NOT_STARTED"
}

Update Buyer's KYB details

Request

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

Security
apiKey and authToken
Bodyapplication/jsonrequired
tagstring<= 50 characters^[a-zA-Z0-9_-]+$

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

companyobject

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

adminUserobject

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

curl -i -X PATCH \
  https://api.weavr.io/_mock/products/payment-run/openapi/v1/buyers/kyb \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'api-key: YOUR_API_KEY_HERE' \
  -d '{
    "tag": "string",
    "company": {
      "businessAddress": {
        "addressLine1": "string",
        "addressLine2": "string",
        "city": "string",
        "postCode": "string",
        "state": "string",
        "country": "st"
      }
    },
    "adminUser": {
      "name": "string",
      "surname": "string",
      "email": "user@example.com",
      "mobile": {
        "countryCode": "string",
        "number": "string"
      },
      "dateOfBirth": {
        "year": 1900,
        "month": 1,
        "day": 1
      }
    }
  }'

Responses

Success

Bodyapplication/json
idstring^[0-9]+$required

Id of the buyer.

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

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

adminUserobjectrequired

The admin user of the Buyer Identity.

adminUser.​idstring^[0-9]+$required

The identifier of the user.

adminUser.​namestring<= 100 charactersrequired

First name of the admin user.

adminUser.​surnamestring<= 100 charactersrequired

Last name of the admin user.

adminUser.​emailstring(email)required

E-mail Address of the user

adminUser.​mobileobjectrequired

Mobile number of the user

adminUser.​mobile.​countryCodestring[ 1 .. 6 ] characters^[\+][0-9]{1,5}$required

The country code of the Buyer's admin user mobile number (e.g. +44).

adminUser.​mobile.​numberstring[ 1 .. 15 ] characters^[0-9]+$required

The mobile number of the Buyer's admin user - excluding country code.

adminUser.​companyPositionstringrequired

The company position of the Buyer Admin User.

Enum"DIRECTOR""AUTHORISED_REPRESENTATIVE"
adminUser.​dateOfBirthobject

Date of birth of the authorised user.

adminUser.​activebooleanread-onlyrequired

The state of the admin user. If false, then the user will not be able to log in.

adminUser.​emailVerifiedbooleanread-onlyrequired

Indicates if the admin user's email has been verified.

adminUser.​mobileNumberVerifiedbooleanread-onlyrequired

Indicates if the admin user's mobile number has been verified.

adminUser.​rolesArray of stringsnon-emptyrequired

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.
  • ADMIN: Users assigned to this role can create a business and ensure that systems and processes are effectively managed.
Items Enum"ADMIN""CREATOR""CONTROLLER"
companyobjectrequired

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

company.​typestringrequired

Supported company types - if company type is not listed, please contact our support team to check if the company type can be supported.

Enum"LLC""PUBLIC_LIMITED_COMPANY""LIMITED_LIABILITY_PARTNERSHIP"
company.​namestring<= 100 charactersrequired

The registered name of the company.

company.​registrationNumberstring[ 1 .. 20 ] characters

The company registration number.

company.​businessAddressobject

The address where the business is based.

company.​countryOfRegistrationstring= 2 characters^[A-Z]+$required

The country of company registration in ISO 3166 alpha-2.

Enum"GB""AT""BE""BG""HR""CY""CZ""DK""EE""FI"
company.​registeredAddressobjectread-only

The legal address of the company. This information is captured via the Due Diligence (KYB) process.

company.​incorporatedOnobjectread-only

The company's date of incorporation

acceptedTermsbooleanrequired

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

supportedCurrenciesArray of objectsrequired
supportedCurrencies[].​currencystring= 3 charactersrequired

The currency expressed in ISO-4217 code.

Enum"GBP""EUR"
supportedCurrencies[].​statusstringrequired

The status of the currency, which can include the following values

  • PENDING_KYB_APPROVAL: The buyer’s KYB process is pending approval.
  • STEPUP_LOGIN_REQUIRED: The buyer needs to perform a stepped-up login for higher authentication.
  • PENDING_CREATION: Awaiting the setup completion of the currency
  • ACTIVE: The ZBA has been successfully created and is ready for use.
  • UNAVAILABLE: The currency is unavailable and cannot be used.
Enum"PENDING_KYB_APPROVAL""STEPUP_LOGIN_REQUIRED""PENDING_CREATION""ACTIVE""UNAVAILABLE"
creationTimestampinteger(int64)read-onlyrequired

The time when the Buyer was created, expressed in Epoch timestamp using millisecond precision.

Response
application/json
{
  "id": "string",
  "tag": "string",
  "adminUser": {
    "id": "string",
    "name": "string",
    "surname": "string",
    "email": "user@example.com",
    "mobile": { … },
    "companyPosition": "DIRECTOR",
    "dateOfBirth": { … },
    "active": true,
    "emailVerified": true,
    "mobileNumberVerified": true,
    "roles": [ … ]
  },
  "company": {
    "type": "LLC",
    "name": "string",
    "registrationNumber": "string",
    "businessAddress": { … },
    "countryOfRegistration": "GB",
    "registeredAddress": { … },
    "incorporatedOn": { … }
  },
  "acceptedTerms": true,
  "supportedCurrencies": [
    { … }
  ],
  "creationTimestamp": 0
}

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.

Operations

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.

Operations

Linked Accounts

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

Operations

Institutions

Institutions supported by Embedded Payment Run.

Operations

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.

Operations

Buyers

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

Webhooks

Payment runs

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

Webhooks

Linked Accounts

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

Webhooks

Login

Tokens webhooks

Webhooks

Stepup

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

Webhooks

Authentication Factors

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

Webhooks

Transactions

Notification that the status of a transaction has been updated.

Webhooks