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 register with the Weavr, you get an account in the Sandbox environment where you can configure your programme. We will give you access to the Live environment after we review your business (KYB) and your integration.

After you open a Multi account and configure your application profiles, you can start building your application. API environment URLs are as follows.

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

Simulating Operations

Our Sandbox environment includes a simulator that simulates external events not usually triggered by Weavr, for example, receipt of a bank transfer or a purchase on a card. You can use the simulator to test all the functions of your application in a Sandbox environment.

Handling Errors

When you invoke the Weavr 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: Unauthorised
  • 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 will be persisted.

All GET and DELETE operations in Multi are idempotent. Some but not all POST and PATCH operations in Multi support idempotency - only those POST and PATCH operations that accept the idempotency-ref header support idempotency. Check the documentation or the API specification to determine whether a specific endpoint supports idempotency.

While all GET and DELETE operations in Multi guarantee idempotency without needing any action, if you want to leverage idempotency with a POST or PATCH operation that supports it you need to provide the idempotency-ref parameter. Subsequent requests with the same idempotency reference are idempotent. Otherwise, repeated requests will result in duplicate operations.

You can therefore use idempotency for a more fault-tolerant integration with Weavr Multi. 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 idempotency in the Weavr Multi API:

• 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 will receive an HTTP 400 response code.

• Weavr 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 idempotency is to retry an operation after a non-definitive response is received by your application. If Weavr receives concurrent idempotent requests it can either return error status code 409, or queue execution of such requests (guaranteeing idempotency all along).

• Do not pass an idempotency-ref header to a non-idempotent operation. If Weavr receives an idempotency-ref header in a call to an endpoint which does not support idempotency, 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.