Buyers are identities representing a business
Once on-boarded, Buyers can create payment runs and pay their suppliers in your application.
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.
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.
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
Overview
License
Languages
Servers
Mock server
https://api.weavr.io/_mock/products/payment-run/openapi
Sandbox
https://sandbox.weavr.io/payment-run
A Payment run contains a list of supplier payments. A Payment run can be
- created by a user with a
CREATORrole - confirmed by a user with a
CONTROLLERrole - funded by a user with a
CONTROLLERrole
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
Request
Create a new payment run containing a list of outstanding supplier payments.
Note that all the supplier payments in a payment run is limited to one currency. The currency of the payment run are enabled upon the Buyer’s registration.
Required user role: CREATOR
Security
apiKey and authToken
A unique identifier by which you identify the payment run with on your system.
Example: "94fddfb2-297d-423d-9157-4200b7beb834"
The tag field is a custom field that can be used to search and filter.
The list of payments associated with the payment run
The unique identifier by which you identify the associated payable on your system.
Example: "c99cd66c-82fc-4a01-977b-61a2f5a247a1"
The unique identifier by which you identify this payment on your system.
Example: "c99cd66c-82fc-4a01-977b-61a2f5a247a1"
The currency and amount to be paid to the supplier.
The currency expressed in ISO-4217 code.
Enum"GBP""EUR"
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
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: >=1character and <=150characters - with
FasterPaymentsBankDetails: >=1character and <=140characters 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))
The supplier's bank country in ISO 3166 alpha-2 format.
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.
Account number, required for wire transfer over Faster Payments.
Sort code, required for wire transfer over Faster Payments.
- Mock serverhttps://api.weavr.io/_mock/products/payment-run/openapi/v1/payment_runs
- Sandboxhttps://sandbox.weavr.io/payment-run/v1/payment_runs
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X POST \
https://api.weavr.io/_mock/products/payment-run/openapi/v1/payment_runs \
-H 'Authorization: Bearer <YOUR_JWT_HERE>' \
-H 'Content-Type: application/json' \
-H 'api-key: YOUR_API_KEY_HERE' \
-H 'idempotency-ref: string' \
-d '{
"paymentRunRef": "94fddfb2-297d-423d-9157-4200b7beb834",
"tag": "string",
"description": "September payment run 01",
"payments": [
{
"externalRef": "c99cd66c-82fc-4a01-977b-61a2f5a247a1",
"paymentRef": "c99cd66c-82fc-4a01-977b-61a2f5a247a1",
"paymentAmount": {
"currency": "GBP",
"amount": 1
},
"reference": "string",
"supplier": {
"name": "string",
"address": "string",
"bankName": "string",
"bankAddress": "string",
"bankCountry": "st",
"type": "PERSONAL",
"bankAccountDetails": {
"accountNumber": "stringst",
"sortCode": "string",
"secondaryReference": "string"
}
}
}
]
}'OK
A unique identifier by which you identify the payment run with on your system.
Example: "94fddfb2-297d-423d-9157-4200b7beb834"
The tag field is a custom field that can be used to search and filter.
The current status of the payment run.
QUEUED: The payment run creation is an asynchronous process. This status indicates that the payment run is currently being validated
Value"QUEUED"
Example: "PENDING_CONFIRMATION"
The status of the payment
QUEUED: The payment run creation is an asynchronous process. This status indicates that the payment run is currently being validatedPENDING_CHALLENGE: Waiting for the payment run to complete the SCA challengePENDING_FUNDING: Pending until the necessary funds are initiated. Initiate the funding process via the/payment_runs/{id}/fundendpointAWAITING_FUNDS: Waiting for the required funds to be available to execute paymentEXECUTING: Payment is being executed and awaiting final status confirmationCOMPLETED: Payment executed successfullyFAILED: Payment executed, but failedCANCELLED: Payment cancelled, because payment run was cancelledPENDING_CONFIRMATION: Payment run is pending confirmation by aCONTROLLERuserRETURNED: Payment sent, but was returned backSCA_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"
The unique identifier by which you identify the associated payable on your system.
Example: "c99cd66c-82fc-4a01-977b-61a2f5a247a1"
The unique identifier by which you identify this payment on your system.
Example: "c99cd66c-82fc-4a01-977b-61a2f5a247a1"
The currency and amount to be paid to the supplier.
The currency expressed in ISO-4217 code.
Enum"GBP""EUR"
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
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: >=1character and <=150characters - with
FasterPaymentsBankDetails: >=1character and <=140characters 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))
The supplier's bank country in ISO 3166 alpha-2 format.
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.
Account number, required for wire transfer over Faster Payments.
Sort code, required for wire transfer over Faster Payments.
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" }
Request
Retrieve the list of payment runs belonging to the buyer that the logged-in user belongs to.
Required user roles: CONTROLLER OR CREATOR
Security
apiKey and authToken
Query
The limit of the results for paging, starting at the offset. Limit is always capped at 100.
Default 100
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.
Default 0
Filter by tag. The exact tag must be provided, as wildcards are not supported. Leave out to fetch all entries.
The status of the payment run.
Enum"QUEUED""CANCELLED""COMPLETED""COMPLETED_WITH_ERRORS""EXECUTING""INVALID""PENDING_CHALLENGE""PENDING_CONFIRMATION""PENDING_FUNDING""SCA_FAILED"
Example: status=PENDING_CONFIRMATION
- Mock serverhttps://api.weavr.io/_mock/products/payment-run/openapi/v1/payment_runs
- Sandboxhttps://sandbox.weavr.io/payment-run/v1/payment_runs
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X GET \
'https://api.weavr.io/_mock/products/payment-run/openapi/v1/payment_runs?limit=100&offset=0&tag=string&status=PENDING_CONFIRMATION&reference=string&min_amount=0&max_amount=0' \
-H 'Authorization: Bearer <YOUR_JWT_HERE>' \
-H 'api-key: YOUR_API_KEY_HERE'OK
The total number of records returned in this response (always capped at 100).
Example: 100
A unique identifier by which you identify the payment run with on your system.
Example: "94fddfb2-297d-423d-9157-4200b7beb834"
The tag field is a custom field that can be used to search and filter.
The long form description of the payment run
Example: "September payment run 01"
The current status of the payment run.
QUEUED: The payment run creation is an asynchronous process. This status indicates that the payment run is currently being validatedCANCELLED: Payment run was manually cancelledCOMPLETED: All payments have been executed successfullyCOMPLETED_WITH_ERRORS: All payments have been executed and some failedEXECUTING: Funds received, executing paymentsINVALID: Payment run is invalidPENDING_CHALLENGE: Waiting for the payment run to complete the SCA challengePENDING_CONFIRMATION: Payment run is pending confirmation by aCONTROLLERuserPENDING_FUNDING: Pending until the necessary funds are initiated. Initiate the funding process via the/payment_runs/{id}/fundendpointSCA_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}/restartendpoint
Enum"QUEUED""CANCELLED""COMPLETED""COMPLETED_WITH_ERRORS""EXECUTING""INVALID""PENDING_CHALLENGE""PENDING_CONFIRMATION""PENDING_FUNDING""SCA_FAILED"
Example: "PENDING_CONFIRMATION"
The status of the payment
QUEUED: The payment run creation is an asynchronous process. This status indicates that the payment run is currently being validatedPENDING_CHALLENGE: Waiting for the payment run to complete the SCA challengePENDING_FUNDING: Pending until the necessary funds are initiated. Initiate the funding process via the/payment_runs/{id}/fundendpointAWAITING_FUNDS: Waiting for the required funds to be available to execute paymentEXECUTING: Payment is being executed and awaiting final status confirmationCOMPLETED: Payment executed successfullyFAILED: Payment executed, but failedCANCELLED: Payment cancelled, because payment run was cancelledPENDING_CONFIRMATION: Payment run is pending confirmation by aCONTROLLERuserRETURNED: Payment sent, but was returned backSCA_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"
The unique identifier by which you identify the associated payable on your system.
Example: "c99cd66c-82fc-4a01-977b-61a2f5a247a1"
The unique identifier by which you identify this payment on your system.
Example: "c99cd66c-82fc-4a01-977b-61a2f5a247a1"
The currency and amount to be paid to the supplier.
The currency expressed in ISO-4217 code.
Enum"GBP""EUR"
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
Represent the supplier bank account typically used in Outgoing Wire Transfer transactions.
paymentRuns[].​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: >=1character and <=150characters - with
FasterPaymentsBankDetails: >=1character and <=140characters 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))
The supplier's address.
The supplier's bank address.
The supplier's bank country in ISO 3166 alpha-2 format.
The type of supplier account. Required only when FasterPaymentsBankDetails are specified.
Enum"PERSONAL""BUSINESS"
paymentRuns[].​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.
paymentRuns[].​payments[].​supplier.​bankAccountDetails.​accountNumberstring= 8 characters^[0-9]{8}$required
Account number, required for wire transfer over Faster Payments.
Response
application/json
{ "count": 10, "responseCount": 100, "paymentRuns": [ { … } ] }
- Mock serverhttps://api.weavr.io/_mock/products/payment-run/openapi/v1/payment_runs/{payment_run_id}
- Sandboxhttps://sandbox.weavr.io/payment-run/v1/payment_runs/{payment_run_id}
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X GET \
'https://api.weavr.io/_mock/products/payment-run/openapi/v1/payment_runs/{payment_run_id}' \
-H 'Authorization: Bearer <YOUR_JWT_HERE>' \
-H 'api-key: YOUR_API_KEY_HERE'OK
A unique identifier by which you identify the payment run with on your system.
Example: "94fddfb2-297d-423d-9157-4200b7beb834"
The tag field is a custom field that can be used to search and filter.
The current status of the payment run.
QUEUED: The payment run creation is an asynchronous process. This status indicates that the payment run is currently being validatedCANCELLED: Payment run was manually cancelledCOMPLETED: All payments have been executed successfullyCOMPLETED_WITH_ERRORS: All payments have been executed and some failedEXECUTING: Funds received, executing paymentsINVALID: Payment run is invalidPENDING_CHALLENGE: Waiting for the payment run to complete the SCA challengePENDING_CONFIRMATION: Payment run is pending confirmation by aCONTROLLERuserPENDING_FUNDING: Pending until the necessary funds are initiated. Initiate the funding process via the/payment_runs/{id}/fundendpointSCA_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}/restartendpoint
Enum"QUEUED""CANCELLED""COMPLETED""COMPLETED_WITH_ERRORS""EXECUTING""INVALID""PENDING_CHALLENGE""PENDING_CONFIRMATION""PENDING_FUNDING""SCA_FAILED"
Example: "PENDING_CONFIRMATION"
The status of the payment
QUEUED: The payment run creation is an asynchronous process. This status indicates that the payment run is currently being validatedPENDING_CHALLENGE: Waiting for the payment run to complete the SCA challengePENDING_FUNDING: Pending until the necessary funds are initiated. Initiate the funding process via the/payment_runs/{id}/fundendpointAWAITING_FUNDS: Waiting for the required funds to be available to execute paymentEXECUTING: Payment is being executed and awaiting final status confirmationCOMPLETED: Payment executed successfullyFAILED: Payment executed, but failedCANCELLED: Payment cancelled, because payment run was cancelledPENDING_CONFIRMATION: Payment run is pending confirmation by aCONTROLLERuserRETURNED: Payment sent, but was returned backSCA_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"
The unique identifier by which you identify the associated payable on your system.
Example: "c99cd66c-82fc-4a01-977b-61a2f5a247a1"
The unique identifier by which you identify this payment on your system.
Example: "c99cd66c-82fc-4a01-977b-61a2f5a247a1"
The currency and amount to be paid to the supplier.
The currency expressed in ISO-4217 code.
Enum"GBP""EUR"
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
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: >=1character and <=150characters - with
FasterPaymentsBankDetails: >=1character and <=140characters 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))
The supplier's bank country in ISO 3166 alpha-2 format.
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.
Account number, required for wire transfer over Faster Payments.
Sort code, required for wire transfer over Faster Payments.
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" }
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