Weavr 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.

After you get sandbox access and configure your app profilesProfile A template defining the configuration for one type of object - corporate identity, consumer identity, managed account, managed card, transfer, or outgoing wire transfer. When you create one of these objects you reference its Profile ID, which tells Weavr which limits, currencies, supported countries, branding, and fees to apply. Your programme ships with one or more Profile IDs per supported object type., you can start building your app. API environment URLs are as follows.

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

API conventions

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 app in a Sandbox environment.

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

GET and DELETE operations are inherently idempotent - repeating them produces the same result as a single call.

For POST and PATCH operations that 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., set the optional idempotency-ref request header. A retry with the same idempotency-ref, payload, and endpoint won't create a duplicate operation. The reference is tracked for at least 24 hours; after that, a previously used value may be reused as if it were new.

Not every POST or PATCH accepts idempotency-ref. Check each endpoint in the API reference to confirm whether it's supported.

When to retry with idempotency

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. to make your integration fault-tolerant. If your app doesn't receive a response, or receives a 5xx response - meaning the operation neither definitely succeeded nor definitely failed - retry with the same payload and the same idempotency-ref until you receive a 2xx or 4xx response that confirms the outcome.

Example

POST /managed_cards HTTP/1.1
Host: sandbox.weavr.io
Content-Type: application/json
api-key: <YOUR_API_KEY>
idempotency-ref: 9c8f7c4a-3b6e-4f8a-9b3a-1d4e2f5c8a91

{ ... }

Guidelines

• Generate a strong reference. Use a UUIDv4, or another high-entropy identifier up to 255 characters, to avoid collisions.
• Keep the payload identical on retries. Reusing the same idempotency-ref with a different body returns 400 Bad Request.
• Each response reflects the current state. A retry returns the status at the time of that call, not a cached response. For example, your app may receive 503 first and 200 on a subsequent retry.
• Don't send concurrent retries. 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. exists to retry after an inconclusive response, not to parallelize requests. Concurrent calls with the same idempotency-ref may return 409 Conflict or be queued.
• Don't send idempotency-ref to endpoints that don't support it. The platform may ignore the header (treating each call as a separate request) or return an error.

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.