Core concepts

Authentication

All API requests must include a valid session token in the Authorization header. This token can be obtained using the login endpoint and remains valid for 24 hours. We recommend triggering the login call when your actual request returns a 401 Unauthorized response. This approach simplifies token management by allowing your application to request a new token only when necessary.

Feeds

Status changes are much more common for agreements, invoices and transactions than for regular one-off payments. Since we don't want you to miss any event and multiple webhooks might not arrive in the correct order due to network latency, we provide "feeds" or queues which are actually a list of events you haven't received yet.

Each data feed (or queue of events so you will) includes the last sequence number (X-LAST) that allows clients to resume from a specific point in the event stream (via the request header X-RESUME-AFTER). This mechanism is particularly useful for error recovery or when reconnecting after an interruption (and also quite helpful when testing).

Continue reading the feed until there are no entries left. The crucial part being until no further updates are available.
This ensures that every update is properly handled and nothing is missed.

Avoid having multiple clients in your network access the same feed simultaneously with the same API key, as this can lead to race conditions and inconsistent data on your end. If concurrent access is necessary, consider one of the following approaches:

  • Use separate API keys: Assign a unique API key to each client. You can generate additional keys from the Twikey settings menu.
  • Implement a master-client pattern: Designate a single client as the master to fetch the feed. Other clients should read data from a shared datastore managed by the master.

As security is essential for payments, Twikey has decided not to pass on details about payments in webhooks, but only to provide them in requests coming from your end. We allow specific "detail" calls about an object but since they are only a snapshot of the object at that time (and might already have changed by the time you've handled it) we've added rate-limits to avoid using them.

Include parameters Some feeds support include parameters to request additional detail in the response. The available includes vary per feed and are documented in the API reference. By default, feeds return a compact response to minimize payload size.

Webhooks vs Polling

We support 2 kinds of integrations.

With a push-fetch architecture Twikey notifies you about an event in Twikey via a webhook. You can use this webhook as trigger to retrieve all events from the feed (or queue) and update your internal systems.

Note: Webhooks serve as notifications only and must be handled accordingly. To prevent duplicate deliveries due to timeouts or retries, ensure any internal business logic is handled asynchronously.

The alternative is a pull architecture, clients periodically fetch updates from Twikey to get the latest state within Twikey. This architecture caters for situations when no incoming webhooks are allowed. However, the downside is that there is a delay between the moment an event occurs in Twikey and the moment you receive the event.

Hybrid solutions where hooks are combined with recurrent pulls are obviously also possible.

Idempotency Keys

When a request fails due to a network issue, it may be unclear whether the request reached the server or not. Retrying without precaution could result in duplicate operations. Idempotency keys solve this by guaranteeing that a request with the same key is only processed once.

Twikey supports the standard idempotency header for creation endpoints of transactions, refunds, and subscriptions.

Idempotency-Key: "your unique reference"

How it works:

  • First request: processed normally. The response is stored and linked to the key.
  • Duplicate request while processing: returns 409 Conflict, indicating the original request is still being processed.
  • Duplicate request after completion: returns the original response (same HTTP status code and body), regardless of whether the original request succeeded or failed.

An idempotency key can only be used once per endpoint. After a response has been returned for a given key, any subsequent request with the same key returns that stored response.

Key expiry: Idempotency keys expire after 24 hours. After expiry, the same key can be reused.

Note that many Twikey operations are already implicitly idempotent. For example, canceling the same mandate multiple times has no adverse effect.

Error Handling

API errors fall into two main categories:

  1. Client Errors (HTTP 400):

    These occur due to issues in the request and are communicated via a 400 Bad Request response. An ApiError header will be included with further details about the issue. The error message is localized based on the Accept-Language header. If this header is not provided, the message defaults to English.

  2. Server Errors (HTTP 500):

    These indicate an internal error on our side. While rare, they suggest an unexpected failure in the API. In most cases, our team is already aware of such incidents when they occur.