Weavr Embedded Payment Run API (v1)
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude
Connect to Cursor
Install MCP server on Cursor
Connect to VS Code
Install MCP server on VS Code

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

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

Confirm a payment run

Request

Confirm that a payment run can be executed.

Required user role: CONTROLLER

Security

apiKey and authToken

Path

payment_run_idstring^[0-9a-fA-F]{24}$read-onlyrequired

The unique identifier of the payment run.

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/payment_runs/{payment_run_id}/confirm' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'api-key: YOUR_API_KEY_HERE' \
  -H 'idempotency-ref: string'

Responses

Bodyapplication/json

idstring^[0-9a-fA-F]{24}$read-onlyrequired

paymentRunRefstring

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

Example: "94fddfb2-297d-423d-9157-4200b7beb834"

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

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

descriptionstring

The long form description of the payment run

Example: "September payment run 01"

createdBystring^[0-9]+$read-onlyrequired

Example: "110747174434373672"

statusstringread-onlyrequired

The current status of the payment run.

PENDING_CHALLENGE: Waiting for the payment run to complete the SCA challenge

Value"PENDING_CHALLENGE"

Example: "PENDING_CONFIRMATION"

statusReasonstring

paymentsArray of objects(Payment)required

payments[].idstringread-onlyrequired

The unique identifier of the payment line

payments[].statusstringread-onlyrequired

The status of the payment

QUEUED: The payment run creation is an asynchronous process. This status indicates that the payment run is currently being validated
PENDING_CHALLENGE: Waiting for the payment run to complete the SCA challenge
PENDING_FUNDING: Pending until the necessary funds are initiated. Initiate the funding process via the /payment_runs/{id}/fund endpoint
AWAITING_FUNDS: Waiting for the required funds to be available to execute payment
EXECUTING: Payment is being executed and awaiting final status confirmation
COMPLETED: Payment executed successfully
FAILED: Payment executed, but failed
CANCELLED: Payment cancelled, because payment run was cancelled
PENDING_CONFIRMATION: Payment run is pending confirmation by a CONTROLLER user
RETURNED: Payment sent, but was returned back
SCA_FAILED: Payment run failed due to SCA either expiring or max attempts reached. You can restart the payment run by calling the /payment_runs/{id}/restart endpoint

Enum"QUEUED""CANCELLED""COMPLETED""FAILED""PENDING_CHALLENGE""PENDING_CONFIRMATION""PENDING_FUNDING""RETURNED""AWAITING_FUNDS""EXECUTING"

payments[].externalRefstring

The unique identifier by which you identify the associated payable on your system.

Example: "c99cd66c-82fc-4a01-977b-61a2f5a247a1"

payments[].paymentRefstring

The unique identifier by which you identify this payment on your system.

Example: "c99cd66c-82fc-4a01-977b-61a2f5a247a1"

payments[].paymentAmountobjectrequired

The currency and amount to be paid to the supplier.

payments[].paymentAmount.currencystring= 3 charactersrequired

The currency expressed in ISO-4217 code.

Enum"GBP""EUR"

payments[].paymentAmount.amountinteger(int64)>= 1required

The monetary amount, scaled to the lowest denomination of the currency.

Example, an amount of 1000 for a GBP currency is actually 1000 pennies or GBP 10.00.

Example: 454321

payments[].referencestring[ 1 .. 18 ] characters^[0-9a-zA-Z.-]{1,18}$required

The long form description of the payment. This information is also shared with the supplier. The allowed length is dependent on the payment type: SEPA and SWIFT <= 35 characters Faster Payments <= 18 characters

payments[].supplierobjectrequired

Represent the supplier bank account typically used in Outgoing Wire Transfer transactions.

payments[].supplier.namestring[ 1 .. 140 ] characters^[a-zA-Z0-9\/\-?:().,’+\s#=!"%&*<>;{@\r\n]*$required

The supplier name. The allowed length and pattern is dependent on the bankAccountDetails type:

with SepaBankDetails: >= 1 character and <= 150 characters
with FasterPaymentsBankDetails: >= 1 character and <= 140 characters with a pattern of ^[a-zA-Z0-9\/\-?:().,’+\s#=!"%&*<>;{@\r\n]*$ (please note that the ’ symbol is the unicode value U+2019 (right single quotation mark) and not the unicode value U+0027 (apostrophe))

payments[].supplier.addressstring[ 1 .. 150 ] characters

The supplier's address.

payments[].supplier.bankNamestring

The supplier's bank name.

payments[].supplier.bankAddressstring[ 1 .. 150 ] characters

The supplier's bank address.

payments[].supplier.bankCountrystring= 2 characters^[A-Z]{2}$

The supplier's bank country in ISO 3166 alpha-2 format.

payments[].supplier.typestring

The type of supplier account. Required only when FasterPaymentsBankDetails are specified.

Enum"PERSONAL""BUSINESS"

payments[].supplier.bankAccountDetailsFasterPaymentsBankDetails (object) or SepaBankDetails (object)required

Details of the supplier bank account, depending on the type of transfer chosen.

One of:

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

payments[].supplier.bankAccountDetails.accountNumberstring= 8 characters^[0-9]{8}$required

Account number, required for wire transfer over Faster Payments.

payments[].supplier.bankAccountDetails.sortCodestring= 6 characters^[0-9]{6}$required

Sort code, required for wire transfer over Faster Payments.

payments[].supplier.bankAccountDetails.secondaryReferencestring

Secondary reference data if applicable.

payments[].validationOutcomesArray of objects

createdAtstring(date-time)read-onlyrequired

Response

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 a payment run funding instructions

Request

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

Security

apiKey and authToken

Path

payment_run_idstring^[0-9a-fA-F]{24}$read-onlyrequired

The unique identifier of the payment run.

Query

linkedAccountIdsArray of stringsuniquerequired

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

curl -i -X GET \
  'https://api.weavr.io/_mock/products/payment-run/openapi/v1/payment_runs/{payment_run_id}/fund?linkedAccountIds=652d25b73541d8084a88a38d' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'api-key: YOUR_API_KEY_HERE'

Responses

Bodyapplication/json

countintegerrequired

The total number of records (excluding the paging limit)

Example: 10

responseCountintegerrequired

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

Example: 100

fundingInstructionsArray of objects

One or more instructions required to fund the payment run

Response

application/json

{
  "count": 10,
  "responseCount": 100,
  "fundingInstructions": [
    { … }
  ]
}

Cancel a payment run

Request

Cancel a payment run.

Note that a payment run can be cancelled when it is in the states QUEUED, PENDING_CONFIRMATION, PENDING_CHALLENGE, OR PENDING_FUNDING

Required user roles: CONTROLLER OR CREATOR

Security

apiKey

Path

payment_run_idstring^[0-9a-fA-F]{24}$read-onlyrequired

The unique identifier of the payment run.

Headers

idempotency-refstring

curl -i -X POST \
  'https://api.weavr.io/_mock/products/payment-run/openapi/v1/payment_runs/{payment_run_id}/cancel' \
  -H 'api-key: YOUR_API_KEY_HERE' \
  -H 'idempotency-ref: string'

Responses

Success - No Content.

Headers

request-refstringrequired

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

Response

No content

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

Authentication

Postman Collection

Tokens

Passwords

Additional Factors

Step up

Buyers

Buyer Authorised Users

Payment runs

Confirm a payment run

Request

Responses

Was this helpful?

Get a payment run funding instructions

Request

Responses

Was this helpful?

Cancel a payment run

Request

Responses

Was this helpful?

Linked Accounts

Institutions

Simulator

Buyers

Payment runs

Linked Accounts

Login

Stepup

Authentication Factors

Transactions

Weavr Embedded Payment Run API (v1)CopyCopy for LLMCopy page as Markdown for LLMsView as MarkdownOpen this page as MarkdownOpen in ChatGPTGet insights from ChatGPTOpen in ClaudeGet insights from ClaudeConnect to CursorInstall MCP server on CursorConnect to VS CodeInstall MCP server on VS Code

Authentication

Postman Collection

Tokens

Passwords

Additional Factors

Step up

Buyers

Buyer Authorised Users

Payment runs

Confirm a payment run

Request

Responses

Was this helpful?

Get a payment run funding instructions

Request

Responses

Was this helpful?

Cancel a payment run

Request

Responses

Was this helpful?

Linked Accounts

Institutions

Simulator

Buyers

Payment runs

Linked Accounts

Login

Stepup

Authentication Factors

Transactions