Plugin API overview

The API is a RESTful API. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

You can test the API in the Sandbox environment, which does not affect your live data or interact with any banking networks. The environment that you use (Sandbox or Live) determines whether our platform treats the request as a test request or a live request. The API endpoints and API keys for the two environments are different.

When you get started with Weavr, you receive an account in the Sandbox environment where you can configure your program. You get access to the Live environment after we review your business (KYBKYB Know Your Business - the identity verification process for corporate identities. This process allows you to seamlessly and securely verify your business customer's identity. Weavr will ask users to submit the necessary information and documentation so that they can get approved by financial providers.) and your integration.

API conventions

Monetary amounts

All monetary values use minor currency units

Every amount field in the API-requests and responses-is expressed in minor units (cents for EUR and USD, pence for GBP). For example, 10000 represents €100.00, not €10,000.00. Multiply by 100 when sending; divide by 100 when displaying.

API environment URLs are as follows.

Environments

Environment	Endpoint
Sandbox	https://sandbox.weavr.io/
Live	on request

Simulator operations

Our Sandbox environment includes a simulator that allows you to trigger simulated external events which would be actions done by your application users such as funding a payment runPayment Run A list of payments created by Buyers to settle their outstanding financial obligations with their suppliers. Payment runs are typically managed by the accounts payable function within a business on a periodic basis and go through stages of creation, authorisation, funding, and execution., or by business processes with Weavr such as confirming a KYBKYB Know Your Business - the identity verification process for corporate identities. This process allows you to seamlessly and securely verify your business customer's identity. Weavr will ask users to submit the necessary information and documentation so that they can get approved by financial providers. process is complete.

Handling errors​

When you invoke our API, you may encounter errors, which may be caused by the request or by the server. Our API returns errors according to the standard HTTP status code scheme. For example, you may receive the following codes:

• 4XX: Client error
  • 400: Bad request
  • 401: Unauthorized
  • 403: Not authenticated
  • 409: Conflict, together with an error code that identifies the issue
  • 429: Too many requests
• 5XX: Server error
  • 500: Internal server error
  • 503: Service unavailable

Idempotent Requests

An idempotent API guarantees that you can call it multiple times with the outcome remaining the same. In other words, if you make many identical requests to an idempotent endpoint, the effect is the same as if you made just one request.

Idempotent operations thus guarantee that your application can safely retry an operation (one or more times) knowing that even if the operation was successfully executed, no additional state beyond a single execution is persisted.

While all GET operations in the plug-in guarantee idempotencyIdempotency A property of an API that guarantees calling it multiple times with the same inputs produces the same result, with no additional side effects beyond the first call. An idempotent endpoint can therefore be safely retried after network errors or timeouts without risking duplicate transactions or state changes. without needing any action, if you want to leverage idempotencyIdempotency A property of an API that guarantees calling it multiple times with the same inputs produces the same result, with no additional side effects beyond the first call. An idempotent endpoint can therefore be safely retried after network errors or timeouts without risking duplicate transactions or state changes. with a POST or PATCH operation that supports it you need to provide the idempotency-ref parameter. Subsequent requests with the same idempotencyIdempotency A property of an API that guarantees calling it multiple times with the same inputs produces the same result, with no additional side effects beyond the first call. An idempotent endpoint can therefore be safely retried after network errors or timeouts without risking duplicate transactions or state changes. reference are idempotent. Otherwise, repeated requests result in duplicate operations.

You can therefore use idempotencyIdempotency A property of an API that guarantees calling it multiple times with the same inputs produces the same result, with no additional side effects beyond the first call. An idempotent endpoint can therefore be safely retried after network errors or timeouts without risking duplicate transactions or state changes. for a more fault-tolerant integration with the plug-in endpoints. If your application does not receive any response, or receives a 5xx response, i.e. the requested operation was neither definitely successful, nor definitely failed, then your application can retry that operation using the same request parameters and the same idempotency-ref as the first call until a 2xx or 4xx response is returned indicating definitive success or failure of the requested operation.

Below are some additional guidelines related to leveraging idempotencyIdempotency A property of an API that guarantees calling it multiple times with the same inputs produces the same result, with no additional side effects beyond the first call. An idempotent endpoint can therefore be safely retried after network errors or timeouts without risking duplicate transactions or state changes. in the plug-in APIs:

• Use a sufficiently long and random identifier for the idempotency-ref header. We recommend v4 UUIDs, or an identifier with a maximum of 255 chars, to avoid collisions.

• When making multiple idempotent calls, ensure that you pass exactly the same request parameters for any single idempotency-ref. If you attempt to repeat an operation with the same idempotency-ref header but a different payload you receive an HTTP 400 response code.

• We always returns the status of a request at the time of execution, and not the status of the original request. For instance, your application can first receive a 503 response code, followed by a 200 response code for the second idempotent request

• Do not send concurrent idempotent requests - the purpose of idempotencyIdempotency A property of an API that guarantees calling it multiple times with the same inputs produces the same result, with no additional side effects beyond the first call. An idempotent endpoint can therefore be safely retried after network errors or timeouts without risking duplicate transactions or state changes. is to retry an operation after a non-definitive response is received by your application. If we receive concurrent idempotent requests it can either return error status code 409, or queue execution of such requests (guaranteeing idempotencyIdempotency A property of an API that guarantees calling it multiple times with the same inputs produces the same result, with no additional side effects beyond the first call. An idempotent endpoint can therefore be safely retried after network errors or timeouts without risking duplicate transactions or state changes. all along).

• Do not pass an idempotency-ref header to a non-idempotent operation. If we receive an idempotency-ref header in a call to an endpoint which does not support idempotencyIdempotency A property of an API that guarantees calling it multiple times with the same inputs produces the same result, with no additional side effects beyond the first call. An idempotent endpoint can therefore be safely retried after network errors or timeouts without risking duplicate transactions or state changes., it can either ignore the idempotency-ref parameter (with multiple requests with that same idempotency-ref being treated and executed as multiple, separate requests), or it can return an error-class HTTP status response code.