Remitflex Documentation

Network timeouts and client retries can cause duplicate operations. Remitflex idempotency lets you retry mutating requests safely when authenticated with an API key.

When idempotency is required

Auth method	Mutating requests (`POST`, `PUT`, `PATCH`, `DELETE`)
API key	Required — include `Idempotency-Key`
Dashboard JWT	Not required

Idempotency-Key: 7f3c2a1b-4e5d-6c7b-8a9f-0e1d2c3b4a5f

Max length: 255 characters
Use a fresh UUID (or similar unique string) per distinct operation
TTL: 24 hours (configurable server-side via IDEMPOTENCY_TTL_SECONDS)

Behavior

First request with a given key → processed normally; response cached in Redis.
Retry with the same key, org, HTTP method, and path → cached response returned without re-executing.
Different operation → use a new idempotency key.

Reusing an idempotency key for a different request body returns the original response. Always generate a new key per operation.

Example: create payment route

curl -X POST https://api.remitflex.io/v1/payment-routes \
  -H "Authorization: Bearer $REMITFLEX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Supplier collection",
    "originChainKey": "tron",
    "destinationChainKey": "base",
    "destinationCurrency": "USDC",
    "destinationAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
  }'

import { randomUUID } from "crypto";

const res = await fetch("https://api.remitflex.io/v1/payment-routes", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.REMITFLEX_API_KEY}`,
    "Idempotency-Key": randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Supplier collection",
    originChainKey: "tron",
    destinationChainKey: "base",
    destinationCurrency: "USDC",
    destinationAddress: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  }),
});

import os, uuid, requests

requests.post(
    "https://api.remitflex.io/v1/payment-routes",
    headers={
        "Authorization": f"Bearer {os.environ['REMITFLEX_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "name": "Supplier collection",
        "originChainKey": "tron",
        "destinationChainKey": "base",
        "destinationCurrency": "USDC",
        "destinationAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    },
)

Endpoints that require idempotency (API key)

All POST and DELETE endpoints in this reference, including:

POST /customers
POST /payment-routes, POST /payment-routes/{paymentRouteId}/deposits/sync, DELETE /payment-routes/{paymentRouteId}

Errors

Code	Message
`400`	`Idempotency-Key header is required for mutating API requests`
`422`	`Idempotency-Key must be 255 characters or fewer`

Failed requests are not cached — safe to retry with the same key after fixing the error.

Overview

Organisation

Customers

Discovery

Payment routes

Payment links

Local fiat

Swap rates (Solana)

Swaps

cNGN

Transactions

Webhooks

Notifications

Idempotency

When idempotency is required

Header

Behavior

Example: create payment route

Endpoints that require idempotency (API key)

Errors

​When idempotency is required

​Header

​Behavior

​Example: create payment route

​Endpoints that require idempotency (API key)

​Errors

When idempotency is required

Header

Behavior

Example: create payment route

Endpoints that require idempotency (API key)

Errors