Skip to content

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

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

Get Linked accounts

Request

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

Required user role: CONTROLLER

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

Responses

OK

Bodyapplication/json
linkedAccountsArray of objectsrequired
linkedAccounts[].​idstring^[0-9a-fA-F]{24}$required

The unique identifier of the linked account

Example: "652d25b73541d8084a88a38d"
linkedAccounts[].​accountIdentificationFasterPaymentsBankDetails (object) or SepaBankDetails (object)required

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

One of:

Bank details used in case the wire transfer is executed over Faster Payments.

linkedAccounts[].​accountIdentification.​accountNumberstring= 8 characters^[0-9]{8}$required

Account number, required for wire transfer over Faster Payments.

linkedAccounts[].​accountIdentification.​sortCodestring= 6 characters^[0-9]{6}$required

Sort code, required for wire transfer over Faster Payments.

linkedAccounts[].​accountIdentification.​secondaryReferencestring

Secondary reference data if applicable.

linkedAccounts[].​currencystring= 3 charactersrequired

The primary currency associated with the account

Enum"GBP""EUR"
linkedAccounts[].​institutionobjectrequired
linkedAccounts[].​institution.​displayNamestring

The name to be used when displaying the institution to users on user interfaces

linkedAccounts[].​institution.​countriesArray of stringsrequired

The institution's supported countries

Items Enum"GB""AT""BE""BG""HR""CY""CZ""DK""EE""FI"
linkedAccounts[].​institution.​imagesobject

The images that should be used when displaying the institution

linkedAccounts[].​institution.​infoobject
linkedAccounts[].​consentobjectrequired
linkedAccounts[].​consent.​expiresAtstring(date-time)required
linkedAccounts[].​consent.​expiresInintegerrequired
linkedAccounts[].​consent.​statusstringrequired
Enum"ACTIVE""EXPIRED""REVOKED"
linkedAccounts[].​statusstringrequired

The status of the linked account. The status can be one of the following:

  • PENDING_CHALLENGE: The Linked Account is pending challenge
  • PENDING_VERIFICATION: The Linked Account is pending the completion of the required verification steps
  • PENDING_FUNDING: Awaiting a wire transfer as part of the verification process when adding an account without Open Banking
  • REJECTED: The Linked Account did not pass one or more verification steps and is not eligible for use
  • LINKED: The linked account is linked and ready for use
  • UNLINKED: The linked account is not linked and cannot be used
Enum"LINKED""UNLINKED""PENDING_CHALLENGE""PENDING_FUNDING""PENDING_VERIFICATION""REJECTED"
linkedAccounts[].​friendlyNamestring<= 80 characters

A user-friendly name for the linked account

countinteger(int32)

The total number of records (excluding the paging limit).

responseCountinteger(int32)

The total number of records returned in this response (always capped at 100).

Response
application/json
{
  "linkedAccounts": [
    { … }
  ],
  "count": 0,
  "responseCount": 0
}

Get Linked account

Request

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

Required user role: CONTROLLER

Security
apiKey and authToken
Path
linked_account_idstring^[0-9a-fA-F]{24}$read-onlyrequired

The unique identifier of the linked account.

curl -i -X GET \
  'https://api.weavr.io/_mock/products/payment-run/openapi/v1/linked_accounts/{linked_account_id}' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'api-key: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/json
idstring^[0-9a-fA-F]{24}$required

The unique identifier of the linked account

Example: "652d25b73541d8084a88a38d"
accountIdentificationFasterPaymentsBankDetails (object) or SepaBankDetails (object)required

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

One of:

Bank details used in case the wire transfer is executed over Faster Payments.

accountIdentification.​accountNumberstring= 8 characters^[0-9]{8}$required

Account number, required for wire transfer over Faster Payments.

accountIdentification.​sortCodestring= 6 characters^[0-9]{6}$required

Sort code, required for wire transfer over Faster Payments.

accountIdentification.​secondaryReferencestring

Secondary reference data if applicable.

currencystring= 3 charactersrequired

The primary currency associated with the account

Enum"GBP""EUR"
institutionobjectrequired
institution.​displayNamestring

The name to be used when displaying the institution to users on user interfaces

institution.​countriesArray of stringsrequired

The institution's supported countries

Items Enum"GB""AT""BE""BG""HR""CY""CZ""DK""EE""FI"
institution.​imagesobject

The images that should be used when displaying the institution

institution.​infoobject
consentobjectrequired
consent.​expiresAtstring(date-time)required
consent.​expiresInintegerrequired
consent.​statusstringrequired
Enum"ACTIVE""EXPIRED""REVOKED"
statusstringrequired

The status of the linked account. The status can be one of the following:

  • PENDING_CHALLENGE: The Linked Account is pending challenge
  • PENDING_VERIFICATION: The Linked Account is pending the completion of the required verification steps
  • PENDING_FUNDING: Awaiting a wire transfer as part of the verification process when adding an account without Open Banking
  • REJECTED: The Linked Account did not pass one or more verification steps and is not eligible for use
  • LINKED: The linked account is linked and ready for use
  • UNLINKED: The linked account is not linked and cannot be used
Enum"LINKED""UNLINKED""PENDING_CHALLENGE""PENDING_FUNDING""PENDING_VERIFICATION""REJECTED"
friendlyNamestring<= 80 characters

A user-friendly name for the linked account

Response
application/json
{
  "id": "652d25b73541d8084a88a38d",
  "accountIdentification": {
    "accountNumber": "stringst",
    "sortCode": "string",
    "secondaryReference": "string"
  },
  "currency": "GBP",
  "institution": {
    "displayName": "string",
    "countries": [ … ],
    "images": { … },
    "info": { … }
  },
  "consent": {
    "expiresAt": "2019-08-24T14:15:22Z",
    "expiresIn": 0,
    "status": "ACTIVE"
  },
  "status": "LINKED",
  "friendlyName": "string"
}

Update a linked account

Request

Updates properties of a linked account such as friendly name.

Required user role: CONTROLLER

Security
apiKey and authToken
Path
linked_account_idstring^[0-9a-fA-F]{24}$read-onlyrequired

The unique identifier of the linked account.

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.

Bodyapplication/jsonrequired
friendlyNamestring<= 80 characters

A user-friendly name for the linked account. Allows special characters. Max 80 characters.

curl -i -X PATCH \
  'https://api.weavr.io/_mock/products/payment-run/openapi/v1/linked_accounts/{linked_account_id}' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'api-key: YOUR_API_KEY_HERE' \
  -H 'idempotency-ref: string' \
  -d '{
    "friendlyName": "string"
  }'

Responses

OK

Bodyapplication/json
idstring^[0-9a-fA-F]{24}$required

The unique identifier of the linked account

Example: "652d25b73541d8084a88a38d"
accountIdentificationFasterPaymentsBankDetails (object) or SepaBankDetails (object)required

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

One of:

Bank details used in case the wire transfer is executed over Faster Payments.

accountIdentification.​accountNumberstring= 8 characters^[0-9]{8}$required

Account number, required for wire transfer over Faster Payments.

accountIdentification.​sortCodestring= 6 characters^[0-9]{6}$required

Sort code, required for wire transfer over Faster Payments.

accountIdentification.​secondaryReferencestring

Secondary reference data if applicable.

currencystring= 3 charactersrequired

The primary currency associated with the account

Enum"GBP""EUR"
institutionobjectrequired
institution.​displayNamestring

The name to be used when displaying the institution to users on user interfaces

institution.​countriesArray of stringsrequired

The institution's supported countries

Items Enum"GB""AT""BE""BG""HR""CY""CZ""DK""EE""FI"
institution.​imagesobject

The images that should be used when displaying the institution

institution.​infoobject
consentobjectrequired
consent.​expiresAtstring(date-time)required
consent.​expiresInintegerrequired
consent.​statusstringrequired
Enum"ACTIVE""EXPIRED""REVOKED"
statusstringrequired

The status of the linked account. The status can be one of the following:

  • PENDING_CHALLENGE: The Linked Account is pending challenge
  • PENDING_VERIFICATION: The Linked Account is pending the completion of the required verification steps
  • PENDING_FUNDING: Awaiting a wire transfer as part of the verification process when adding an account without Open Banking
  • REJECTED: The Linked Account did not pass one or more verification steps and is not eligible for use
  • LINKED: The linked account is linked and ready for use
  • UNLINKED: The linked account is not linked and cannot be used
Enum"LINKED""UNLINKED""PENDING_CHALLENGE""PENDING_FUNDING""PENDING_VERIFICATION""REJECTED"
friendlyNamestring<= 80 characters

A user-friendly name for the linked account

Response
application/json
{
  "id": "652d25b73541d8084a88a38d",
  "accountIdentification": {
    "accountNumber": "stringst",
    "sortCode": "string",
    "secondaryReference": "string"
  },
  "currency": "GBP",
  "institution": {
    "displayName": "string",
    "countries": [ … ],
    "images": { … },
    "info": { … }
  },
  "consent": {
    "expiresAt": "2019-08-24T14:15:22Z",
    "expiresIn": 0,
    "status": "ACTIVE"
  },
  "status": "LINKED",
  "friendlyName": "string"
}

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