payments

Add money (deposit details or conversion order)

POST /v1/add-money

• addMoney
• API key scope payments:write
• Idempotency-Key required
• Tenant customer

Parameters

Request body

Required. application/json

Responses

• 200 OK application/json

  Schema AddMoneyResult

  • method stringrequired

    One of: "bank_transfer", "conversion"

  • depositDetails array of AccountDetails

  • exchange Exchange | null

• 400 Malformed request: unparseable JSON, or an invalid header, path or query parameter (`errors[].field` is `header.X`, `path.x` or `query.x`). Body validation failures are 422 `validation-error`. application/problem+json

  Body Problem; see the error catalogue.

• 401 Missing, expired or invalid credentials (`unauthenticated`, `session-expired` with `reason` `idle` / `revoked` / `expired`, `invalid-api-key`, `mfa-required`). application/problem+json

  Body Problem; see the error catalogue.

• 403 Authenticated but not allowed: missing capability or scope, tenant not in memberships, `step-up-required`, IP not allow-listed, impersonation restriction. application/problem+json

  Body Problem; see the error catalogue.

• 409 State conflict: `invalid-transition`, `duplicate-recipient`, `quote-expired`, `insufficient-funds`, `idempotency-key-in-use` (with Retry-After), `not-cancellable`. application/problem+json

  Body Problem; see the error catalogue.

• 422 Semantically invalid request; `errors[]` lists field-level problems. Also `idempotency-key-reused` when the key was used with a different payload, `limit-exceeded`, `recipient-not-approved`. application/problem+json

  Body Problem; see the error catalogue.

• 429 Rate limit exceeded. application/problem+json

  Body Problem; see the error catalogue.

• default Unexpected error (`500 internal-error`, `501 not-implemented`, `502 provider-error`, `503 service-unavailable`, `504 provider-timeout`). Money operations that time out at the provider are never retried blindly; their state becomes `exception`/unknown and is reconciled. application/problem+json

  Body Problem; see the error catalogue.

Code samples

Against the sandbox (https://bank.wirebloom.com/v1).

curl -X POST "https://bank.wirebloom.com/v1/add-money" \
  -H "Authorization: Bearer $WIREBLOOM_API_KEY" \
  -H "X-Tenant-Id: $WIREBLOOM_CUSTOMER_ID" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  --data '{
  "method": "conversion",
  "balanceId": "0192a6f1-1111-7000-8000-00000000b003",
  "fromBalanceId": "0192a6f1-1111-7000-8000-00000000b001",
  "amount": {
    "amountMinor": "250000",
    "currency": "EUR"
  },
  "fixedSide": "buy",
  "quoteId": "0192a6f1-4444-7000-8000-00000000d001"
}'

const response = await fetch("https://bank.wirebloom.com/v1/add-money", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.WIREBLOOM_API_KEY}`,
    "X-Tenant-Id": process.env.WIREBLOOM_CUSTOMER_ID!,
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "method": "conversion",
    "balanceId": "0192a6f1-1111-7000-8000-00000000b003",
    "fromBalanceId": "0192a6f1-1111-7000-8000-00000000b001",
    "amount": {
      "amountMinor": "250000",
      "currency": "EUR"
    },
    "fixedSide": "buy",
    "quoteId": "0192a6f1-4444-7000-8000-00000000d001"
  }),
});
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
const result = await response.json();

import os, uuid

import requests

response = requests.request(
    "POST",
    "https://bank.wirebloom.com/v1/add-money",
    headers={
        "Authorization": f"Bearer {os.environ['WIREBLOOM_API_KEY']}",
        "X-Tenant-Id": os.environ["WIREBLOOM_CUSTOMER_ID"],
        "Idempotency-Key": str(uuid.uuid4()),
        "Content-Type": "application/json",
    },
    json={
      "method": "conversion",
      "balanceId": "0192a6f1-1111-7000-8000-00000000b003",
      "fromBalanceId": "0192a6f1-1111-7000-8000-00000000b001",
      "amount": {
        "amountMinor": "250000",
        "currency": "EUR"
      },
      "fixedSide": "buy",
      "quoteId": "0192a6f1-4444-7000-8000-00000000d001"
    },
    timeout=30,
)
response.raise_for_status()

Approvals inbox

GET /v1/approvals

• listApprovals
• API key scope payments:read
• Tenant any

Parameters

Responses

• 200 OK application/json

  Schema ApprovalPage

  Cursor-paginated list of Approval.

  • data array of Approvalrequired

  • page PageInforequired

• 304 Not modified (`If-None-Match` matched).
• 400 Malformed request: unparseable JSON, or an invalid header, path or query parameter (`errors[].field` is `header.X`, `path.x` or `query.x`). Body validation failures are 422 `validation-error`. application/problem+json

  Body Problem; see the error catalogue.

• 401 Missing, expired or invalid credentials (`unauthenticated`, `session-expired` with `reason` `idle` / `revoked` / `expired`, `invalid-api-key`, `mfa-required`). application/problem+json

  Body Problem; see the error catalogue.

• 403 Authenticated but not allowed: missing capability or scope, tenant not in memberships, `step-up-required`, IP not allow-listed, impersonation restriction. application/problem+json

  Body Problem; see the error catalogue.

• 429 Rate limit exceeded. application/problem+json

  Body Problem; see the error catalogue.

• default Unexpected error (`500 internal-error`, `501 not-implemented`, `502 provider-error`, `503 service-unavailable`, `504 provider-timeout`). Money operations that time out at the provider are never retried blindly; their state becomes `exception`/unknown and is reconciled. application/problem+json

  Body Problem; see the error catalogue.

Code samples

Against the sandbox (https://bank.wirebloom.com/v1).

curl -X GET "https://bank.wirebloom.com/v1/approvals" \
  -H "Authorization: Bearer $WIREBLOOM_API_KEY" \
  -H "X-Tenant-Id: $WIREBLOOM_CUSTOMER_ID"

const response = await fetch("https://bank.wirebloom.com/v1/approvals", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.WIREBLOOM_API_KEY}`,
    "X-Tenant-Id": process.env.WIREBLOOM_CUSTOMER_ID!,
  },
});
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
const result = await response.json();

import os

import requests

response = requests.request(
    "GET",
    "https://bank.wirebloom.com/v1/approvals",
    headers={
        "Authorization": f"Bearer {os.environ['WIREBLOOM_API_KEY']}",
        "X-Tenant-Id": os.environ["WIREBLOOM_CUSTOMER_ID"],
    },
    timeout=30,
)
response.raise_for_status()

Get approval

GET /v1/approvals/{approvalId}

• getApproval
• API key scope payments:read
• Tenant any

Parameters

Responses

• 200 OK application/json

  Schema Approval

  • id Uuidrequiredread-only

    Fields of id

    Uuid

  • subjectType ApprovalSubjectTyperequired

  • subjectId Uuidrequired

  • subjectSummary objectrequired

    Fields of subjectSummary

    • title stringrequired

    • amount Money | null

    • recipientName string | null

      Recipient (payments, recipients) or counterparty name.

    • sourceBalanceId Uuid | null

    • sourceBalanceName string | null

    • rail Rail | null

    • itemCount integer | null

      Bulk uploads: payments in the batch.

      min 0

    • recipientMaskedIdentifier string | null

      Masked account identifier of the recipient the approver binds to (payments: the snapshot taken at submission, which the payment is sent to or refused against; recipients: the current details). Null for other subjects (security audit S-01, D-47).

  • tier integerrequired

    min 0

  • status ApprovalStatusrequiredread-only

    Fields of status

    ApprovalStatus

  • requiredApprovals integerrequired

    min 1

  • received integerrequiredread-only

    Approvals received so far (approved decisions).

    min 0

  • decisions array of objectrequired

    Fields of decisions

    • by Uuid

    • byName string

    • decision string

      One of: "approved", "rejected"

    • comment string | null

    • at Timestamp

  • requestedBy Uuidrequired

  • requestedByName string

  • canDecide booleanrequiredread-only

    Whether the caller is an eligible approver (not the requester unless self-approval allowed).

  • expiresAt Timestamp | null

  • createdAt Timestamprequiredread-only

    Fields of createdAt

    Timestamp

  • policy objectread-only

    The effective policy tier the request is judged against.

    Fields of policy

    • kind ApprovalPolicyKind | null

    • source stringrequired

      snapshot: the tier captured when the request opened; policy: the current policy; default: the built-in single approval; recipient: recipient approval mode.

      One of: "snapshot", "policy", "default", "recipient"

    • tier ApprovalTierrequired

    • issues array of objectrequired

      Fields of issues

      • code stringrequired

      • message stringrequired

• 401 Missing, expired or invalid credentials (`unauthenticated`, `session-expired` with `reason` `idle` / `revoked` / `expired`, `invalid-api-key`, `mfa-required`). application/problem+json

  Body Problem; see the error catalogue.

• 403 Authenticated but not allowed: missing capability or scope, tenant not in memberships, `step-up-required`, IP not allow-listed, impersonation restriction. application/problem+json

  Body Problem; see the error catalogue.

• 404 Resource does not exist in this tenant (cross-tenant ids also return 404), or feature disabled (`feature-disabled`). application/problem+json

  Body Problem; see the error catalogue.

• 429 Rate limit exceeded. application/problem+json

  Body Problem; see the error catalogue.

• default Unexpected error (`500 internal-error`, `501 not-implemented`, `502 provider-error`, `503 service-unavailable`, `504 provider-timeout`). Money operations that time out at the provider are never retried blindly; their state becomes `exception`/unknown and is reconciled. application/problem+json

  Body Problem; see the error catalogue.

Code samples

Against the sandbox (https://bank.wirebloom.com/v1).

curl -X GET "https://bank.wirebloom.com/v1/approvals/{approvalId}" \
  -H "Authorization: Bearer $WIREBLOOM_API_KEY" \
  -H "X-Tenant-Id: $WIREBLOOM_CUSTOMER_ID"

const response = await fetch("https://bank.wirebloom.com/v1/approvals/{approvalId}", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.WIREBLOOM_API_KEY}`,
    "X-Tenant-Id": process.env.WIREBLOOM_CUSTOMER_ID!,
  },
});
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
const result = await response.json();

import os

import requests

response = requests.request(
    "GET",
    "https://bank.wirebloom.com/v1/approvals/{approvalId}",
    headers={
        "Authorization": f"Bearer {os.environ['WIREBLOOM_API_KEY']}",
        "X-Tenant-Id": os.environ["WIREBLOOM_CUSTOMER_ID"],
    },
    timeout=30,
)
response.raise_for_status()

List bulk uploads

GET /v1/bulk-payments

• listBulkPayments
• API key scope payments:read
• Tenant customer

Parameters

Responses

• 200 OK application/json

  Schema BulkPaymentPage

  Cursor-paginated list of BulkPayment.

  • data array of BulkPaymentrequired

  • page PageInforequired

• 400 Malformed request: unparseable JSON, or an invalid header, path or query parameter (`errors[].field` is `header.X`, `path.x` or `query.x`). Body validation failures are 422 `validation-error`. application/problem+json

  Body Problem; see the error catalogue.

• 401 Missing, expired or invalid credentials (`unauthenticated`, `session-expired` with `reason` `idle` / `revoked` / `expired`, `invalid-api-key`, `mfa-required`). application/problem+json

  Body Problem; see the error catalogue.

• 403 Authenticated but not allowed: missing capability or scope, tenant not in memberships, `step-up-required`, IP not allow-listed, impersonation restriction. application/problem+json

  Body Problem; see the error catalogue.

• 429 Rate limit exceeded. application/problem+json

  Body Problem; see the error catalogue.

• default Unexpected error (`500 internal-error`, `501 not-implemented`, `502 provider-error`, `503 service-unavailable`, `504 provider-timeout`). Money operations that time out at the provider are never retried blindly; their state becomes `exception`/unknown and is reconciled. application/problem+json

  Body Problem; see the error catalogue.

Code samples

Against the sandbox (https://bank.wirebloom.com/v1).

curl -X GET "https://bank.wirebloom.com/v1/bulk-payments" \
  -H "Authorization: Bearer $WIREBLOOM_API_KEY" \
  -H "X-Tenant-Id: $WIREBLOOM_CUSTOMER_ID"

const response = await fetch("https://bank.wirebloom.com/v1/bulk-payments", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.WIREBLOOM_API_KEY}`,
    "X-Tenant-Id": process.env.WIREBLOOM_CUSTOMER_ID!,
  },
});
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
const result = await response.json();

import os

import requests

response = requests.request(
    "GET",
    "https://bank.wirebloom.com/v1/bulk-payments",
    headers={
        "Authorization": f"Bearer {os.environ['WIREBLOOM_API_KEY']}",
        "X-Tenant-Id": os.environ["WIREBLOOM_CUSTOMER_ID"],
    },
    timeout=30,
)
response.raise_for_status()

Upload bulk payments file for validation

POST /v1/bulk-payments

• createBulkPayment
• API key scope payments:write
• Idempotency-Key required
• Tenant customer

Parameters

Request body

Required. application/json

Responses

• 202 Accepted application/json

  Schema BulkPayment

  • id Uuidrequiredread-only

    Fields of id

    Uuid

  • customerId Uuidrequiredread-only

    Fields of customerId

    Uuid

  • documentId Uuidrequired

  • sourceBalanceId Uuidrequired

  • status BulkUploadStatusrequiredread-only

    Fields of status

    BulkUploadStatus

  • rowsTotal integerrequired

  • rowsOk integerrequired

  • rowsFailed integerrequired

  • total Money | null

  • resultsDocumentId string | null (uuid)read-only

    Per-row results file (CSV document, GET /documents/{documentId}/download) written after validation and after submission; null until produced.

  • createdBy Uuidread-only

    Fields of createdBy

    Uuid

  • createdAt Timestamprequiredread-only

    Fields of createdAt

    Timestamp

• 400 Malformed request: unparseable JSON, or an invalid header, path or query parameter (`errors[].field` is `header.X`, `path.x` or `query.x`). Body validation failures are 422 `validation-error`. application/problem+json

  Body Problem; see the error catalogue.

• 401 Missing, expired or invalid credentials (`unauthenticated`, `session-expired` with `reason` `idle` / `revoked` / `expired`, `invalid-api-key`, `mfa-required`). application/problem+json

  Body Problem; see the error catalogue.

• 403 Authenticated but not allowed: missing capability or scope, tenant not in memberships, `step-up-required`, IP not allow-listed, impersonation restriction. application/problem+json

  Body Problem; see the error catalogue.

• 409 State conflict: `invalid-transition`, `duplicate-recipient`, `quote-expired`, `insufficient-funds`, `idempotency-key-in-use` (with Retry-After), `not-cancellable`. application/problem+json

  Body Problem; see the error catalogue.

• 422 Semantically invalid request; `errors[]` lists field-level problems. Also `idempotency-key-reused` when the key was used with a different payload, `limit-exceeded`, `recipient-not-approved`. application/problem+json

  Body Problem; see the error catalogue.

• 429 Rate limit exceeded. application/problem+json

  Body Problem; see the error catalogue.

• default Unexpected error (`500 internal-error`, `501 not-implemented`, `502 provider-error`, `503 service-unavailable`, `504 provider-timeout`). Money operations that time out at the provider are never retried blindly; their state becomes `exception`/unknown and is reconciled. application/problem+json

  Body Problem; see the error catalogue.

Code samples

Against the sandbox (https://bank.wirebloom.com/v1).

curl -X POST "https://bank.wirebloom.com/v1/bulk-payments" \
  -H "Authorization: Bearer $WIREBLOOM_API_KEY" \
  -H "X-Tenant-Id: $WIREBLOOM_CUSTOMER_ID" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  --data '{
  "documentId": "0192a6f0-7c1e-7b3a-9d2e-5f4c3b2a1908",
  "sourceBalanceId": "0192a6f0-7c1e-7b3a-9d2e-5f4c3b2a1908"
}'

const response = await fetch("https://bank.wirebloom.com/v1/bulk-payments", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.WIREBLOOM_API_KEY}`,
    "X-Tenant-Id": process.env.WIREBLOOM_CUSTOMER_ID!,
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "documentId": "0192a6f0-7c1e-7b3a-9d2e-5f4c3b2a1908",
    "sourceBalanceId": "0192a6f0-7c1e-7b3a-9d2e-5f4c3b2a1908"
  }),
});
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
const result = await response.json();

import os, uuid

import requests

response = requests.request(
    "POST",
    "https://bank.wirebloom.com/v1/bulk-payments",
    headers={
        "Authorization": f"Bearer {os.environ['WIREBLOOM_API_KEY']}",
        "X-Tenant-Id": os.environ["WIREBLOOM_CUSTOMER_ID"],
        "Idempotency-Key": str(uuid.uuid4()),
        "Content-Type": "application/json",
    },
    json={
      "documentId": "0192a6f0-7c1e-7b3a-9d2e-5f4c3b2a1908",
      "sourceBalanceId": "0192a6f0-7c1e-7b3a-9d2e-5f4c3b2a1908"
    },
    timeout=30,
)
response.raise_for_status()

Bulk upload status

GET /v1/bulk-payments/{bulkPaymentId}

• getBulkPayment
• API key scope payments:read
• Tenant customer

Parameters

Responses

• 200 OK application/json

  Schema BulkPayment

  • id Uuidrequiredread-only

    Fields of id

    Uuid

  • customerId Uuidrequiredread-only

    Fields of customerId

    Uuid

  • documentId Uuidrequired

  • sourceBalanceId Uuidrequired

  • status BulkUploadStatusrequiredread-only

    Fields of status

    BulkUploadStatus

  • rowsTotal integerrequired

  • rowsOk integerrequired

  • rowsFailed integerrequired

  • total Money | null

  • resultsDocumentId string | null (uuid)read-only

    Per-row results file (CSV document, GET /documents/{documentId}/download) written after validation and after submission; null until produced.

  • createdBy Uuidread-only

    Fields of createdBy

    Uuid

  • createdAt Timestamprequiredread-only

    Fields of createdAt

    Timestamp

• 401 Missing, expired or invalid credentials (`unauthenticated`, `session-expired` with `reason` `idle` / `revoked` / `expired`, `invalid-api-key`, `mfa-required`). application/problem+json

  Body Problem; see the error catalogue.

• 403 Authenticated but not allowed: missing capability or scope, tenant not in memberships, `step-up-required`, IP not allow-listed, impersonation restriction. application/problem+json

  Body Problem; see the error catalogue.

• 404 Resource does not exist in this tenant (cross-tenant ids also return 404), or feature disabled (`feature-disabled`). application/problem+json

  Body Problem; see the error catalogue.

• 429 Rate limit exceeded. application/problem+json

  Body Problem; see the error catalogue.

• default Unexpected error (`500 internal-error`, `501 not-implemented`, `502 provider-error`, `503 service-unavailable`, `504 provider-timeout`). Money operations that time out at the provider are never retried blindly; their state becomes `exception`/unknown and is reconciled. application/problem+json

  Body Problem; see the error catalogue.

Code samples

Against the sandbox (https://bank.wirebloom.com/v1).

curl -X GET "https://bank.wirebloom.com/v1/bulk-payments/{bulkPaymentId}" \
  -H "Authorization: Bearer $WIREBLOOM_API_KEY" \
  -H "X-Tenant-Id: $WIREBLOOM_CUSTOMER_ID"

const response = await fetch("https://bank.wirebloom.com/v1/bulk-payments/{bulkPaymentId}", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.WIREBLOOM_API_KEY}`,
    "X-Tenant-Id": process.env.WIREBLOOM_CUSTOMER_ID!,
  },
});
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
const result = await response.json();

import os

import requests

response = requests.request(
    "GET",
    "https://bank.wirebloom.com/v1/bulk-payments/{bulkPaymentId}",
    headers={
        "Authorization": f"Bearer {os.environ['WIREBLOOM_API_KEY']}",
        "X-Tenant-Id": os.environ["WIREBLOOM_CUSTOMER_ID"],
    },
    timeout=30,
)
response.raise_for_status()

Cancel bulk upload

POST /v1/bulk-payments/{bulkPaymentId}/cancel

• cancelBulkPayment
• API key scope payments:write
• Tenant customer

Parameters

Responses

• 200 OK application/json

  Schema BulkPayment

  • id Uuidrequiredread-only

    Fields of id

    Uuid

  • customerId Uuidrequiredread-only

    Fields of customerId

    Uuid

  • documentId Uuidrequired

  • sourceBalanceId Uuidrequired

  • status BulkUploadStatusrequiredread-only

    Fields of status

    BulkUploadStatus

  • rowsTotal integerrequired

  • rowsOk integerrequired

  • rowsFailed integerrequired

  • total Money | null

  • resultsDocumentId string | null (uuid)read-only

    Per-row results file (CSV document, GET /documents/{documentId}/download) written after validation and after submission; null until produced.

  • createdBy Uuidread-only

    Fields of createdBy

    Uuid

  • createdAt Timestamprequiredread-only

    Fields of createdAt

    Timestamp

• 401 Missing, expired or invalid credentials (`unauthenticated`, `session-expired` with `reason` `idle` / `revoked` / `expired`, `invalid-api-key`, `mfa-required`). application/problem+json

  Body Problem; see the error catalogue.

• 403 Authenticated but not allowed: missing capability or scope, tenant not in memberships, `step-up-required`, IP not allow-listed, impersonation restriction. application/problem+json

  Body Problem; see the error catalogue.

• 404 Resource does not exist in this tenant (cross-tenant ids also return 404), or feature disabled (`feature-disabled`). application/problem+json

  Body Problem; see the error catalogue.

• 409 State conflict: `invalid-transition`, `duplicate-recipient`, `quote-expired`, `insufficient-funds`, `idempotency-key-in-use` (with Retry-After), `not-cancellable`. application/problem+json

  Body Problem; see the error catalogue.

• 429 Rate limit exceeded. application/problem+json

  Body Problem; see the error catalogue.

• default Unexpected error (`500 internal-error`, `501 not-implemented`, `502 provider-error`, `503 service-unavailable`, `504 provider-timeout`). Money operations that time out at the provider are never retried blindly; their state becomes `exception`/unknown and is reconciled. application/problem+json

  Body Problem; see the error catalogue.

Code samples

Against the sandbox (https://bank.wirebloom.com/v1).

curl -X POST "https://bank.wirebloom.com/v1/bulk-payments/{bulkPaymentId}/cancel" \
  -H "Authorization: Bearer $WIREBLOOM_API_KEY" \
  -H "X-Tenant-Id: $WIREBLOOM_CUSTOMER_ID"

const response = await fetch("https://bank.wirebloom.com/v1/bulk-payments/{bulkPaymentId}/cancel", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.WIREBLOOM_API_KEY}`,
    "X-Tenant-Id": process.env.WIREBLOOM_CUSTOMER_ID!,
  },
});
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
const result = await response.json();

import os

import requests

response = requests.request(
    "POST",
    "https://bank.wirebloom.com/v1/bulk-payments/{bulkPaymentId}/cancel",
    headers={
        "Authorization": f"Bearer {os.environ['WIREBLOOM_API_KEY']}",
        "X-Tenant-Id": os.environ["WIREBLOOM_CUSTOMER_ID"],
    },
    timeout=30,
)
response.raise_for_status()

Per-row validation results

GET /v1/bulk-payments/{bulkPaymentId}/rows

• listBulkPaymentRows
• API key scope payments:read
• Tenant customer

Parameters

Responses

• 200 OK application/json

  Schema BulkPaymentRowPage

  Cursor-paginated list of BulkPaymentRow.

  • data array of BulkPaymentRowrequired

  • page PageInforequired

• 400 Malformed request: unparseable JSON, or an invalid header, path or query parameter (`errors[].field` is `header.X`, `path.x` or `query.x`). Body validation failures are 422 `validation-error`. application/problem+json

  Body Problem; see the error catalogue.

• 401 Missing, expired or invalid credentials (`unauthenticated`, `session-expired` with `reason` `idle` / `revoked` / `expired`, `invalid-api-key`, `mfa-required`). application/problem+json

  Body Problem; see the error catalogue.

• 403 Authenticated but not allowed: missing capability or scope, tenant not in memberships, `step-up-required`, IP not allow-listed, impersonation restriction. application/problem+json

  Body Problem; see the error catalogue.

• 404 Resource does not exist in this tenant (cross-tenant ids also return 404), or feature disabled (`feature-disabled`). application/problem+json

  Body Problem; see the error catalogue.

• 429 Rate limit exceeded. application/problem+json

  Body Problem; see the error catalogue.

• default Unexpected error (`500 internal-error`, `501 not-implemented`, `502 provider-error`, `503 service-unavailable`, `504 provider-timeout`). Money operations that time out at the provider are never retried blindly; their state becomes `exception`/unknown and is reconciled. application/problem+json

  Body Problem; see the error catalogue.

Code samples

Against the sandbox (https://bank.wirebloom.com/v1).

curl -X GET "https://bank.wirebloom.com/v1/bulk-payments/{bulkPaymentId}/rows" \
  -H "Authorization: Bearer $WIREBLOOM_API_KEY" \
  -H "X-Tenant-Id: $WIREBLOOM_CUSTOMER_ID"

const response = await fetch("https://bank.wirebloom.com/v1/bulk-payments/{bulkPaymentId}/rows", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.WIREBLOOM_API_KEY}`,
    "X-Tenant-Id": process.env.WIREBLOOM_CUSTOMER_ID!,
  },
});
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
const result = await response.json();

import os

import requests

response = requests.request(
    "GET",
    "https://bank.wirebloom.com/v1/bulk-payments/{bulkPaymentId}/rows",
    headers={
        "Authorization": f"Bearer {os.environ['WIREBLOOM_API_KEY']}",
        "X-Tenant-Id": os.environ["WIREBLOOM_CUSTOMER_ID"],
    },
    timeout=30,
)
response.raise_for_status()

Submit validated rows as payments

POST /v1/bulk-payments/{bulkPaymentId}/submit

• submitBulkPayment
• API key scope payments:write
• Idempotency-Key required
• Tenant customer

Parameters

Responses

• 202 Accepted application/json

  Schema BulkPaymentSubmitAccepted

  202 of submit: the job that creates the payments in the background (kind bulk_validation, poll GET /jobs/{jobId} for progress) and the batch as it stands (status submitting; poll GET /bulk-payments/{bulkPaymentId} for the final submitted / partially_submitted and the row results).

  • id Uuidrequiredread-only

    Fields of id

    Uuid

  • kind stringrequired

    One of: "export", "statement", "report", "bulk_validation", "billing_run", "reconciliation", "replay"

  • status stringrequired

    One of: "queued", "running", "succeeded", "failed", "cancelled"

  • progress integer

    min 0 · max 100

  • resultUrl string | null (uri)

    Pre-signed download URL (valid 15 minutes) when status=succeeded.

  • error Problem | null

  • createdAt Timestamprequiredread-only

    Fields of createdAt

    Timestamp

  • finishedAt Timestamp | null

  • bulkPayment BulkPaymentrequired

• 401 Missing, expired or invalid credentials (`unauthenticated`, `session-expired` with `reason` `idle` / `revoked` / `expired`, `invalid-api-key`, `mfa-required`). application/problem+json

  Body Problem; see the error catalogue.

• 403 Authenticated but not allowed: missing capability or scope, tenant not in memberships, `step-up-required`, IP not allow-listed, impersonation restriction. application/problem+json

  Body Problem; see the error catalogue.

• 404 Resource does not exist in this tenant (cross-tenant ids also return 404), or feature disabled (`feature-disabled`). application/problem+json

  Body Problem; see the error catalogue.

• 409 State conflict: `invalid-transition`, `duplicate-recipient`, `quote-expired`, `insufficient-funds`, `idempotency-key-in-use` (with Retry-After), `not-cancellable`. application/problem+json

  Body Problem; see the error catalogue.

• 429 Rate limit exceeded. application/problem+json

  Body Problem; see the error catalogue.

• default Unexpected error (`500 internal-error`, `501 not-implemented`, `502 provider-error`, `503 service-unavailable`, `504 provider-timeout`). Money operations that time out at the provider are never retried blindly; their state becomes `exception`/unknown and is reconciled. application/problem+json

  Body Problem; see the error catalogue.

Code samples

Against the sandbox (https://bank.wirebloom.com/v1).

curl -X POST "https://bank.wirebloom.com/v1/bulk-payments/{bulkPaymentId}/submit" \
  -H "Authorization: Bearer $WIREBLOOM_API_KEY" \
  -H "X-Tenant-Id: $WIREBLOOM_CUSTOMER_ID" \
  -H "Idempotency-Key: $(uuidgen)"

const response = await fetch("https://bank.wirebloom.com/v1/bulk-payments/{bulkPaymentId}/submit", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.WIREBLOOM_API_KEY}`,
    "X-Tenant-Id": process.env.WIREBLOOM_CUSTOMER_ID!,
    "Idempotency-Key": crypto.randomUUID(),
  },
});
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
const result = await response.json();

import os, uuid

import requests

response = requests.request(
    "POST",
    "https://bank.wirebloom.com/v1/bulk-payments/{bulkPaymentId}/submit",
    headers={
        "Authorization": f"Bearer {os.environ['WIREBLOOM_API_KEY']}",
        "X-Tenant-Id": os.environ["WIREBLOOM_CUSTOMER_ID"],
        "Idempotency-Key": str(uuid.uuid4()),
    },
    timeout=30,
)
response.raise_for_status()

List direct debit collections

GET /v1/collections

• listCollections
• API key scope payments:read
• Tenant customer

Parameters

Responses

• 200 OK application/json

  Schema CollectionPage

  Cursor-paginated list of Collection.

  • data array of Collectionrequired

  • page PageInforequired

• 400 Malformed request: unparseable JSON, or an invalid header, path or query parameter (`errors[].field` is `header.X`, `path.x` or `query.x`). Body validation failures are 422 `validation-error`. application/problem+json

  Body Problem; see the error catalogue.

• 401 Missing, expired or invalid credentials (`unauthenticated`, `session-expired` with `reason` `idle` / `revoked` / `expired`, `invalid-api-key`, `mfa-required`). application/problem+json

  Body Problem; see the error catalogue.

• 403 Authenticated but not allowed: missing capability or scope, tenant not in memberships, `step-up-required`, IP not allow-listed, impersonation restriction. application/problem+json

  Body Problem; see the error catalogue.

• 404 Resource does not exist in this tenant (cross-tenant ids also return 404), or feature disabled (`feature-disabled`). application/problem+json

  Body Problem; see the error catalogue.

• 429 Rate limit exceeded. application/problem+json

  Body Problem; see the error catalogue.

• default Unexpected error (`500 internal-error`, `501 not-implemented`, `502 provider-error`, `503 service-unavailable`, `504 provider-timeout`). Money operations that time out at the provider are never retried blindly; their state becomes `exception`/unknown and is reconciled. application/problem+json

  Body Problem; see the error catalogue.

Code samples

Against the sandbox (https://bank.wirebloom.com/v1).

curl -X GET "https://bank.wirebloom.com/v1/collections" \
  -H "Authorization: Bearer $WIREBLOOM_API_KEY" \
  -H "X-Tenant-Id: $WIREBLOOM_CUSTOMER_ID"

const response = await fetch("https://bank.wirebloom.com/v1/collections", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.WIREBLOOM_API_KEY}`,
    "X-Tenant-Id": process.env.WIREBLOOM_CUSTOMER_ID!,
  },
});
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
const result = await response.json();

import os

import requests

response = requests.request(
    "GET",
    "https://bank.wirebloom.com/v1/collections",
    headers={
        "Authorization": f"Bearer {os.environ['WIREBLOOM_API_KEY']}",
        "X-Tenant-Id": os.environ["WIREBLOOM_CUSTOMER_ID"],
    },
    timeout=30,
)
response.raise_for_status()

Request a collection on a mandate

POST /v1/collections

• createCollection
• API key scope payments:write
• Idempotency-Key required
• Tenant customer

Parameters

Request body

Required. application/json

Responses

• 201 Created application/json

  Schema Collection

  • id Uuidrequiredread-only

    Fields of id

    Uuid

  • mandateId Uuidrequired

  • amount Moneyrequired

  • dueDate Daterequired

  • status CollectionStatusrequiredread-only

    Fields of status

    CollectionStatus

  • providerRef string | nullread-only

  • transactionId Uuid | null

  • failureReason string | nullread-only

  • createdAt Timestamprequiredread-only

    Fields of createdAt

    Timestamp

  • reference string | null

  • sequenceType stringread-only

    One of: "FRST", "RCUR", "OOFF", "FNAL"

  • submitOn Date | null

  • collectedAt Timestamp | null

  • returnReasonCode string | nullread-only

    R-transaction reason code (SEPA / Bacs ARUDD).

  • returnedAt Timestamp | null

  • scheduledPaymentId Uuid | null

• 400 Malformed request: unparseable JSON, or an invalid header, path or query parameter (`errors[].field` is `header.X`, `path.x` or `query.x`). Body validation failures are 422 `validation-error`. application/problem+json

  Body Problem; see the error catalogue.

• 401 Missing, expired or invalid credentials (`unauthenticated`, `session-expired` with `reason` `idle` / `revoked` / `expired`, `invalid-api-key`, `mfa-required`). application/problem+json

  Body Problem; see the error catalogue.

• 403 Authenticated but not allowed: missing capability or scope, tenant not in memberships, `step-up-required`, IP not allow-listed, impersonation restriction. application/problem+json

  Body Problem; see the error catalogue.

• 404 Resource does not exist in this tenant (cross-tenant ids also return 404), or feature disabled (`feature-disabled`). application/problem+json

  Body Problem; see the error catalogue.

• 409 State conflict: `invalid-transition`, `duplicate-recipient`, `quote-expired`, `insufficient-funds`, `idempotency-key-in-use` (with Retry-After), `not-cancellable`. application/problem+json

  Body Problem; see the error catalogue.

• 422 Semantically invalid request; `errors[]` lists field-level problems. Also `idempotency-key-reused` when the key was used with a different payload, `limit-exceeded`, `recipient-not-approved`. application/problem+json

  Body Problem; see the error catalogue.

• 429 Rate limit exceeded. application/problem+json

  Body Problem; see the error catalogue.

• default Unexpected error (`500 internal-error`, `501 not-implemented`, `502 provider-error`, `503 service-unavailable`, `504 provider-timeout`). Money operations that time out at the provider are never retried blindly; their state becomes `exception`/unknown and is reconciled. application/problem+json

  Body Problem; see the error catalogue.

Code samples

Against the sandbox (https://bank.wirebloom.com/v1).

curl -X POST "https://bank.wirebloom.com/v1/collections" \
  -H "Authorization: Bearer $WIREBLOOM_API_KEY" \
  -H "X-Tenant-Id: $WIREBLOOM_CUSTOMER_ID" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  --data '{
  "mandateId": "0192a6f0-7c1e-7b3a-9d2e-5f4c3b2a1908",
  "amount": {
    "amountMinor": "125050",
    "currency": "GBP"
  },
  "dueDate": "2026-09-30"
}'

const response = await fetch("https://bank.wirebloom.com/v1/collections", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.WIREBLOOM_API_KEY}`,
    "X-Tenant-Id": process.env.WIREBLOOM_CUSTOMER_ID!,
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "mandateId": "0192a6f0-7c1e-7b3a-9d2e-5f4c3b2a1908",
    "amount": {
      "amountMinor": "125050",
      "currency": "GBP"
    },
    "dueDate": "2026-09-30"
  }),
});
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
const result = await response.json();

import os, uuid

import requests

response = requests.request(
    "POST",
    "https://bank.wirebloom.com/v1/collections",
    headers={
        "Authorization": f"Bearer {os.environ['WIREBLOOM_API_KEY']}",
        "X-Tenant-Id": os.environ["WIREBLOOM_CUSTOMER_ID"],
        "Idempotency-Key": str(uuid.uuid4()),
        "Content-Type": "application/json",
    },
    json={
      "mandateId": "0192a6f0-7c1e-7b3a-9d2e-5f4c3b2a1908",
      "amount": {
        "amountMinor": "125050",
        "currency": "GBP"
      },
      "dueDate": "2026-09-30"
    },
    timeout=30,
)
response.raise_for_status()

Get collection

GET /v1/collections/{collectionId}

• getCollection
• API key scope payments:read
• Tenant customer

Parameters

Responses

• 200 OK application/json

  Schema Collection

  • id Uuidrequiredread-only

    Fields of id

    Uuid

  • mandateId Uuidrequired

  • amount Moneyrequired

  • dueDate Daterequired

  • status CollectionStatusrequiredread-only

    Fields of status

    CollectionStatus

  • providerRef string | nullread-only

  • transactionId Uuid | null

  • failureReason string | nullread-only

  • createdAt Timestamprequiredread-only

    Fields of createdAt

    Timestamp

  • reference string | null

  • sequenceType stringread-only

    One of: "FRST", "RCUR", "OOFF", "FNAL"

  • submitOn Date | null

  • collectedAt Timestamp | null

  • returnReasonCode string | nullread-only

    R-transaction reason code (SEPA / Bacs ARUDD).

  • returnedAt Timestamp | null

  • scheduledPaymentId Uuid | null

• 401 Missing, expired or invalid credentials (`unauthenticated`, `session-expired` with `reason` `idle` / `revoked` / `expired`, `invalid-api-key`, `mfa-required`). application/problem+json

  Body Problem; see the error catalogue.

• 403 Authenticated but not allowed: missing capability or scope, tenant not in memberships, `step-up-required`, IP not allow-listed, impersonation restriction. application/problem+json

  Body Problem; see the error catalogue.

• 404 Resource does not exist in this tenant (cross-tenant ids also return 404), or feature disabled (`feature-disabled`). application/problem+json

  Body Problem; see the error catalogue.

• 429 Rate limit exceeded. application/problem+json

  Body Problem; see the error catalogue.

• default Unexpected error (`500 internal-error`, `501 not-implemented`, `502 provider-error`, `503 service-unavailable`, `504 provider-timeout`). Money operations that time out at the provider are never retried blindly; their state becomes `exception`/unknown and is reconciled. application/problem+json

  Body Problem; see the error catalogue.

Code samples

Against the sandbox (https://bank.wirebloom.com/v1).

curl -X GET "https://bank.wirebloom.com/v1/collections/{collectionId}" \
  -H "Authorization: Bearer $WIREBLOOM_API_KEY" \
  -H "X-Tenant-Id: $WIREBLOOM_CUSTOMER_ID"

const response = await fetch("https://bank.wirebloom.com/v1/collections/{collectionId}", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.WIREBLOOM_API_KEY}`,
    "X-Tenant-Id": process.env.WIREBLOOM_CUSTOMER_ID!,
  },
});
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
const result = await response.json();

import os

import requests

response = requests.request(
    "GET",
    "https://bank.wirebloom.com/v1/collections/{collectionId}",
    headers={
        "Authorization": f"Bearer {os.environ['WIREBLOOM_API_KEY']}",
        "X-Tenant-Id": os.environ["WIREBLOOM_CUSTOMER_ID"],
    },
    timeout=30,
)
response.raise_for_status()

Cancel collection (before submission)

POST /v1/collections/{collectionId}/cancel

• cancelCollection
• API key scope payments:write
• Tenant customer

Parameters

Responses

• 200 OK application/json

  Schema Collection

  • id Uuidrequiredread-only

    Fields of id

    Uuid

  • mandateId Uuidrequired

  • amount Moneyrequired

  • dueDate Daterequired

  • status CollectionStatusrequiredread-only

    Fields of status

    CollectionStatus

  • providerRef string | nullread-only

  • transactionId Uuid | null

  • failureReason string | nullread-only

  • createdAt Timestamprequiredread-only

    Fields of createdAt

    Timestamp

  • reference string | null

  • sequenceType stringread-only

    One of: "FRST", "RCUR", "OOFF", "FNAL"

  • submitOn Date | null

  • collectedAt Timestamp | null

  • returnReasonCode string | nullread-only

    R-transaction reason code (SEPA / Bacs ARUDD).

  • returnedAt Timestamp | null

  • scheduledPaymentId Uuid | null

• 401 Missing, expired or invalid credentials (`unauthenticated`, `session-expired` with `reason` `idle` / `revoked` / `expired`, `invalid-api-key`, `mfa-required`). application/problem+json

  Body Problem; see the error catalogue.

• 403 Authenticated but not allowed: missing capability or scope, tenant not in memberships, `step-up-required`, IP not allow-listed, impersonation restriction. application/problem+json

  Body Problem; see the error catalogue.

• 404 Resource does not exist in this tenant (cross-tenant ids also return 404), or feature disabled (`feature-disabled`). application/problem+json

  Body Problem; see the error catalogue.

• 409 State conflict: `invalid-transition`, `duplicate-recipient`, `quote-expired`, `insufficient-funds`, `idempotency-key-in-use` (with Retry-After), `not-cancellable`. application/problem+json

  Body Problem; see the error catalogue.

• 429 Rate limit exceeded. application/problem+json

  Body Problem; see the error catalogue.

• default Unexpected error (`500 internal-error`, `501 not-implemented`, `502 provider-error`, `503 service-unavailable`, `504 provider-timeout`). Money operations that time out at the provider are never retried blindly; their state becomes `exception`/unknown and is reconciled. application/problem+json

  Body Problem; see the error catalogue.

Code samples

Against the sandbox (https://bank.wirebloom.com/v1).

curl -X POST "https://bank.wirebloom.com/v1/collections/{collectionId}/cancel" \
  -H "Authorization: Bearer $WIREBLOOM_API_KEY" \
  -H "X-Tenant-Id: $WIREBLOOM_CUSTOMER_ID"

const response = await fetch("https://bank.wirebloom.com/v1/collections/{collectionId}/cancel", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.WIREBLOOM_API_KEY}`,
    "X-Tenant-Id": process.env.WIREBLOOM_CUSTOMER_ID!,
  },
});
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
const result = await response.json();

import os

import requests

response = requests.request(
    "POST",
    "https://bank.wirebloom.com/v1/collections/{collectionId}/cancel",
    headers={
        "Authorization": f"Bearer {os.environ['WIREBLOOM_API_KEY']}",
        "X-Tenant-Id": os.environ["WIREBLOOM_CUSTOMER_ID"],
    },
    timeout=30,
)
response.raise_for_status()

List exchanges

GET /v1/exchanges

• listExchanges
• API key scope exchanges:read
• Tenant customer

Parameters

Responses

• 200 OK application/json

  Schema ExchangePage

  Cursor-paginated list of Exchange.

  • data array of Exchangerequired

  • page PageInforequired

• 400 Malformed request: unparseable JSON, or an invalid header, path or query parameter (`errors[].field` is `header.X`, `path.x` or `query.x`). Body validation failures are 422 `validation-error`. application/problem+json

  Body Problem; see the error catalogue.

• 401 Missing, expired or invalid credentials (`unauthenticated`, `session-expired` with `reason` `idle` / `revoked` / `expired`, `invalid-api-key`, `mfa-required`). application/problem+json

  Body Problem; see the error catalogue.

• 403 Authenticated but not allowed: missing capability or scope, tenant not in memberships, `step-up-required`, IP not allow-listed, impersonation restriction. application/problem+json

  Body Problem; see the error catalogue.

• 429 Rate limit exceeded. application/problem+json

  Body Problem; see the error catalogue.

• default Unexpected error (`500 internal-error`, `501 not-implemented`, `502 provider-error`, `503 service-unavailable`, `504 provider-timeout`). Money operations that time out at the provider are never retried blindly; their state becomes `exception`/unknown and is reconciled. application/problem+json

  Body Problem; see the error catalogue.

Code samples

Against the sandbox (https://bank.wirebloom.com/v1).

curl -X GET "https://bank.wirebloom.com/v1/exchanges" \
  -H "Authorization: Bearer $WIREBLOOM_API_KEY" \
  -H "X-Tenant-Id: $WIREBLOOM_CUSTOMER_ID"

const response = await fetch("https://bank.wirebloom.com/v1/exchanges", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.WIREBLOOM_API_KEY}`,
    "X-Tenant-Id": process.env.WIREBLOOM_CUSTOMER_ID!,
  },
});
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
const result = await response.json();

import os

import requests

response = requests.request(
    "GET",
    "https://bank.wirebloom.com/v1/exchanges",
    headers={
        "Authorization": f"Bearer {os.environ['WIREBLOOM_API_KEY']}",
        "X-Tenant-Id": os.environ["WIREBLOOM_CUSTOMER_ID"],
    },
    timeout=30,
)
response.raise_for_status()

Execute exchange from a quote

POST /v1/exchanges

• createExchange
• API key scope exchanges:write
• Idempotency-Key required
• Tenant customer

Parameters

Request body

Required. application/json

Responses

• 201 Created application/json

  Schema Exchange

  • id Uuidrequiredread-only

    Fields of id

    Uuid

  • customerId Uuidrequiredread-only

    Fields of customerId

    Uuid

  • kind ExchangeKindrequired

  • status ExchangeStatusrequiredread-only

    Fields of status

    ExchangeStatus

  • sellBalanceId Uuidrequired

  • buyBalanceId Uuidrequired

  • sellAmount Moneyrequired

  • buyAmount Moneyrequired

  • rate Raterequired

  • fixedSide FixedSiderequired

  • quoteId Uuidrequired

  • fee Money | null

  • settlementDate Date | null

  • deposit Money | null

  • remaining Money | null

  • orderId stringrequiredread-only

    Human order id shown on confirmations.

  • providerRef string | nullread-only

  • createdBy Uuid | null

  • createdAt Timestamprequiredread-only

    Fields of createdAt

    Timestamp

  • completedAt Timestamp | null

  • purpose stringread-only

    What the conversion is for: a direct exchange, an add-money conversion order or the funding of a cross-currency payment.

    One of: "exchange", "add_money", "payment"

  • statusReason string | nullread-only

    Why the exchange failed or was cancelled.

  • marginCall object | nullread-only

    Open margin call on a forward: deposit top-up required (POST /forward-contracts/{exchangeId}/deposit).

    Fields of marginCall

    • at Timestamprequired

    • amount Moneyrequired

  • drawdownCount integerread-only

    Drawdowns requested on a forward or held-rate contract.

    min 0

• 400 Malformed request: unparseable JSON, or an invalid header, path or query parameter (`errors[].field` is `header.X`, `path.x` or `query.x`). Body validation failures are 422 `validation-error`. application/problem+json

  Body Problem; see the error catalogue.

• 401 Missing, expired or invalid credentials (`unauthenticated`, `session-expired` with `reason` `idle` / `revoked` / `expired`, `invalid-api-key`, `mfa-required`). application/problem+json

  Body Problem; see the error catalogue.

• 403 Authenticated but not allowed: missing capability or scope, tenant not in memberships, `step-up-required`, IP not allow-listed, impersonation restriction. application/problem+json

  Body Problem; see the error catalogue.

• 409 State conflict: `invalid-transition`, `duplicate-recipient`, `quote-expired`, `insufficient-funds`, `idempotency-key-in-use` (with Retry-After), `not-cancellable`. application/problem+json

  Body Problem; see the error catalogue.

• 422 Semantically invalid request; `errors[]` lists field-level problems. Also `idempotency-key-reused` when the key was used with a different payload, `limit-exceeded`, `recipient-not-approved`. application/problem+json

  Body Problem; see the error catalogue.

• 429 Rate limit exceeded. application/problem+json

  Body Problem; see the error catalogue.

• default Unexpected error (`500 internal-error`, `501 not-implemented`, `502 provider-error`, `503 service-unavailable`, `504 provider-timeout`). Money operations that time out at the provider are never retried blindly; their state becomes `exception`/unknown and is reconciled. application/problem+json

  Body Problem; see the error catalogue.

Code samples

Against the sandbox (https://bank.wirebloom.com/v1).

curl -X POST "https://bank.wirebloom.com/v1/exchanges" \
  -H "Authorization: Bearer $WIREBLOOM_API_KEY" \
  -H "X-Tenant-Id: $WIREBLOOM_CUSTOMER_ID" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  --data '{
  "quoteId": "0192a6f1-4444-7000-8000-00000000d001",
  "sellBalanceId": "0192a6f1-1111-7000-8000-00000000b001",
  "buyBalanceId": "0192a6f1-1111-7000-8000-00000000b003"
}'

const response = await fetch("https://bank.wirebloom.com/v1/exchanges", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.WIREBLOOM_API_KEY}`,
    "X-Tenant-Id": process.env.WIREBLOOM_CUSTOMER_ID!,
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "quoteId": "0192a6f1-4444-7000-8000-00000000d001",
    "sellBalanceId": "0192a6f1-1111-7000-8000-00000000b001",
    "buyBalanceId": "0192a6f1-1111-7000-8000-00000000b003"
  }),
});
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
const result = await response.json();

import os, uuid

import requests

response = requests.request(
    "POST",
    "https://bank.wirebloom.com/v1/exchanges",
    headers={
        "Authorization": f"Bearer {os.environ['WIREBLOOM_API_KEY']}",
        "X-Tenant-Id": os.environ["WIREBLOOM_CUSTOMER_ID"],
        "Idempotency-Key": str(uuid.uuid4()),
        "Content-Type": "application/json",
    },
    json={
      "quoteId": "0192a6f1-4444-7000-8000-00000000d001",
      "sellBalanceId": "0192a6f1-1111-7000-8000-00000000b001",
      "buyBalanceId": "0192a6f1-1111-7000-8000-00000000b003"
    },
    timeout=30,
)
response.raise_for_status()

Get exchange

GET /v1/exchanges/{exchangeId}

• getExchange
• API key scope exchanges:read
• Tenant customer

Parameters

Responses

• 200 OK application/json

  Schema Exchange

  • id Uuidrequiredread-only

    Fields of id

    Uuid

  • customerId Uuidrequiredread-only

    Fields of customerId

    Uuid

  • kind ExchangeKindrequired

  • status ExchangeStatusrequiredread-only

    Fields of status

    ExchangeStatus

  • sellBalanceId Uuidrequired

  • buyBalanceId Uuidrequired

  • sellAmount Moneyrequired

  • buyAmount Moneyrequired

  • rate Raterequired

  • fixedSide FixedSiderequired

  • quoteId Uuidrequired

  • fee Money | null

  • settlementDate Date | null

  • deposit Money | null

  • remaining Money | null

  • orderId stringrequiredread-only

    Human order id shown on confirmations.

  • providerRef string | nullread-only

  • createdBy Uuid | null

  • createdAt Timestamprequiredread-only

    Fields of createdAt

    Timestamp

  • completedAt Timestamp | null

  • purpose stringread-only

    What the conversion is for: a direct exchange, an add-money conversion order or the funding of a cross-currency payment.

    One of: "exchange", "add_money", "payment"

  • statusReason string | nullread-only

    Why the exchange failed or was cancelled.

  • marginCall object | nullread-only

    Open margin call on a forward: deposit top-up required (POST /forward-contracts/{exchangeId}/deposit).

    Fields of marginCall

    • at Timestamprequired

    • amount Moneyrequired

  • drawdownCount integerread-only

    Drawdowns requested on a forward or held-rate contract.

    min 0

• 401 Missing, expired or invalid credentials (`unauthenticated`, `session-expired` with `reason` `idle` / `revoked` / `expired`, `invalid-api-key`, `mfa-required`). application/problem+json

  Body Problem; see the error catalogue.

• 403 Authenticated but not allowed: missing capability or scope, tenant not in memberships, `step-up-required`, IP not allow-listed, impersonation restriction. application/problem+json

  Body Problem; see the error catalogue.

• 404 Resource does not exist in this tenant (cross-tenant ids also return 404), or feature disabled (`feature-disabled`). application/problem+json

  Body Problem; see the error catalogue.

• 429 Rate limit exceeded. application/problem+json

  Body Problem; see the error catalogue.

• default Unexpected error (`500 internal-error`, `501 not-implemented`, `502 provider-error`, `503 service-unavailable`, `504 provider-timeout`). Money operations that time out at the provider are never retried blindly; their state becomes `exception`/unknown and is reconciled. application/problem+json

  Body Problem; see the error catalogue.

Code samples

Against the sandbox (https://bank.wirebloom.com/v1).

curl -X GET "https://bank.wirebloom.com/v1/exchanges/{exchangeId}" \
  -H "Authorization: Bearer $WIREBLOOM_API_KEY" \
  -H "X-Tenant-Id: $WIREBLOOM_CUSTOMER_ID"

const response = await fetch("https://bank.wirebloom.com/v1/exchanges/{exchangeId}", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.WIREBLOOM_API_KEY}`,
    "X-Tenant-Id": process.env.WIREBLOOM_CUSTOMER_ID!,
  },
});
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
const result = await response.json();

import os

import requests

response = requests.request(
    "GET",
    "https://bank.wirebloom.com/v1/exchanges/{exchangeId}",
    headers={
        "Authorization": f"Bearer {os.environ['WIREBLOOM_API_KEY']}",
        "X-Tenant-Id": os.environ["WIREBLOOM_CUSTOMER_ID"],
    },
    timeout=30,
)
response.raise_for_status()

Exchange order confirmation (PDF)

GET /v1/exchanges/{exchangeId}/confirmation

• getExchangeConfirmation
• API key scope statements:read
• Tenant customer

Parameters

Responses

• 200 OK application/pdf

  string

• 401 Missing, expired or invalid credentials (`unauthenticated`, `session-expired` with `reason` `idle` / `revoked` / `expired`, `invalid-api-key`, `mfa-required`). application/problem+json

  Body Problem; see the error catalogue.

• 403 Authenticated but not allowed: missing capability or scope, tenant not in memberships, `step-up-required`, IP not allow-listed, impersonation restriction. application/problem+json

  Body Problem; see the error catalogue.

• 404 Resource does not exist in this tenant (cross-tenant ids also return 404), or feature disabled (`feature-disabled`). application/problem+json

  Body Problem; see the error catalogue.

• 429 Rate limit exceeded. application/problem+json

  Body Problem; see the error catalogue.

• default Unexpected error (`500 internal-error`, `501 not-implemented`, `502 provider-error`, `503 service-unavailable`, `504 provider-timeout`). Money operations that time out at the provider are never retried blindly; their state becomes `exception`/unknown and is reconciled. application/problem+json

  Body Problem; see the error catalogue.

Code samples

Against the sandbox (https://bank.wirebloom.com/v1).

curl -X GET "https://bank.wirebloom.com/v1/exchanges/{exchangeId}/confirmation" \
  -H "Authorization: Bearer $WIREBLOOM_API_KEY" \
  -H "X-Tenant-Id: $WIREBLOOM_CUSTOMER_ID"

const response = await fetch("https://bank.wirebloom.com/v1/exchanges/{exchangeId}/confirmation", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.WIREBLOOM_API_KEY}`,
    "X-Tenant-Id": process.env.WIREBLOOM_CUSTOMER_ID!,
  },
});
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
const result = await response.json();

import os

import requests

response = requests.request(
    "GET",
    "https://bank.wirebloom.com/v1/exchanges/{exchangeId}/confirmation",
    headers={
        "Authorization": f"Bearer {os.environ['WIREBLOOM_API_KEY']}",
        "X-Tenant-Id": os.environ["WIREBLOOM_CUSTOMER_ID"],
    },
    timeout=30,
)
response.raise_for_status()

Create FX quote

POST /v1/exchanges/quotes

• createQuote
• API key scope exchanges:write
• Tenant customer

Parameters

Request body

Required. application/json

Responses

• 201 Created application/json

  Schema Quote

  Firm quote; typically valid 30 seconds (countdown in the UI). Refresh to get a new rate.

  • id Uuidrequiredread-only

    Fields of id

    Uuid

  • sellAmount Moneyrequired

  • buyAmount Moneyrequired

  • rate Raterequired

  • inverseRate Raterequired

  • fixedSide FixedSiderequired

  • kind ExchangeKindrequired

  • fee Money | null

  • settlementDate Date | null

  • depositRequired Money | null

  • expiresAt Timestamprequired

  • used booleanrequired

  • createdAt Timestamprequiredread-only

    Fields of createdAt

    Timestamp

• 400 Malformed request: unparseable JSON, or an invalid header, path or query parameter (`errors[].field` is `header.X`, `path.x` or `query.x`). Body validation failures are 422 `validation-error`. application/problem+json

  Body Problem; see the error catalogue.

• 401 Missing, expired or invalid credentials (`unauthenticated`, `session-expired` with `reason` `idle` / `revoked` / `expired`, `invalid-api-key`, `mfa-required`). application/problem+json

  Body Problem; see the error catalogue.

• 403 Authenticated but not allowed: missing capability or scope, tenant not in memberships, `step-up-required`, IP not allow-listed, impersonation restriction. application/problem+json

  Body Problem; see the error catalogue.

• 409 State conflict: `invalid-transition`, `duplicate-recipient`, `quote-expired`, `insufficient-funds`, `idempotency-key-in-use` (with Retry-After), `not-cancellable`. application/problem+json

  Body Problem; see the error catalogue.

• 422 Semantically invalid request; `errors[]` lists field-level problems. Also `idempotency-key-reused` when the key was used with a different payload, `limit-exceeded`, `recipient-not-approved`. application/problem+json

  Body Problem; see the error catalogue.

• 429 Rate limit exceeded. application/problem+json

  Body Problem; see the error catalogue.

• default Unexpected error (`500 internal-error`, `501 not-implemented`, `502 provider-error`, `503 service-unavailable`, `504 provider-timeout`). Money operations that time out at the provider are never retried blindly; their state becomes `exception`/unknown and is reconciled. application/problem+json

  Body Problem; see the error catalogue.

Code samples

Against the sandbox (https://bank.wirebloom.com/v1).

curl -X POST "https://bank.wirebloom.com/v1/exchanges/quotes" \
  -H "Authorization: Bearer $WIREBLOOM_API_KEY" \
  -H "X-Tenant-Id: $WIREBLOOM_CUSTOMER_ID" \
  -H "Content-Type: application/json" \
  --data '{
  "sellCurrency": "GBP",
  "buyCurrency": "EUR",
  "amount": {
    "amountMinor": "100000",
    "currency": "EUR"
  },
  "fixedSide": "buy",
  "kind": "spot"
}'

const response = await fetch("https://bank.wirebloom.com/v1/exchanges/quotes", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.WIREBLOOM_API_KEY}`,
    "X-Tenant-Id": process.env.WIREBLOOM_CUSTOMER_ID!,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "sellCurrency": "GBP",
    "buyCurrency": "EUR",
    "amount": {
      "amountMinor": "100000",
      "currency": "EUR"
    },
    "fixedSide": "buy",
    "kind": "spot"
  }),
});
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
const result = await response.json();

import os

import requests

response = requests.request(
    "POST",
    "https://bank.wirebloom.com/v1/exchanges/quotes",
    headers={
        "Authorization": f"Bearer {os.environ['WIREBLOOM_API_KEY']}",
        "X-Tenant-Id": os.environ["WIREBLOOM_CUSTOMER_ID"],
        "Content-Type": "application/json",
    },
    json={
      "sellCurrency": "GBP",
      "buyCurrency": "EUR",
      "amount": {
        "amountMinor": "100000",
        "currency": "EUR"
      },
      "fixedSide": "buy",
      "kind": "spot"
    },
    timeout=30,
)
response.raise_for_status()

Get quote

GET /v1/exchanges/quotes/{quoteId}

• getQuote
• API key scope exchanges:read
• Tenant customer

Parameters

Responses

• 200 OK application/json

  Schema Quote

  Firm quote; typically valid 30 seconds (countdown in the UI). Refresh to get a new rate.

  • id Uuidrequiredread-only

    Fields of id

    Uuid

  • sellAmount Moneyrequired

  • buyAmount Moneyrequired

  • rate Raterequired

  • inverseRate Raterequired

  • fixedSide FixedSiderequired

  • kind ExchangeKindrequired

  • fee Money | null

  • settlementDate Date | null

  • depositRequired Money | null

  • expiresAt Timestamprequired

  • used booleanrequired

  • createdAt Timestamprequiredread-only

    Fields of createdAt

    Timestamp

• 401 Missing, expired or invalid credentials (`unauthenticated`, `session-expired` with `reason` `idle` / `revoked` / `expired`, `invalid-api-key`, `mfa-required`). application/problem+json

  Body Problem; see the error catalogue.

• 403 Authenticated but not allowed: missing capability or scope, tenant not in memberships, `step-up-required`, IP not allow-listed, impersonation restriction. application/problem+json

  Body Problem; see the error catalogue.

• 404 Resource does not exist in this tenant (cross-tenant ids also return 404), or feature disabled (`feature-disabled`). application/problem+json

  Body Problem; see the error catalogue.

• 429 Rate limit exceeded. application/problem+json

  Body Problem; see the error catalogue.

• default Unexpected error (`500 internal-error`, `501 not-implemented`, `502 provider-error`, `503 service-unavailable`, `504 provider-timeout`). Money operations that time out at the provider are never retried blindly; their state becomes `exception`/unknown and is reconciled. application/problem+json

  Body Problem; see the error catalogue.

Code samples

Against the sandbox (https://bank.wirebloom.com/v1).

curl -X GET "https://bank.wirebloom.com/v1/exchanges/quotes/{quoteId}" \
  -H "Authorization: Bearer $WIREBLOOM_API_KEY" \
  -H "X-Tenant-Id: $WIREBLOOM_CUSTOMER_ID"

const response = await fetch("https://bank.wirebloom.com/v1/exchanges/quotes/{quoteId}", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.WIREBLOOM_API_KEY}`,
    "X-Tenant-Id": process.env.WIREBLOOM_CUSTOMER_ID!,
  },
});
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
const result = await response.json();

import os

import requests

response = requests.request(
    "GET",
    "https://bank.wirebloom.com/v1/exchanges/quotes/{quoteId}",
    headers={
        "Authorization": f"Bearer {os.environ['WIREBLOOM_API_KEY']}",
        "X-Tenant-Id": os.environ["WIREBLOOM_CUSTOMER_ID"],
    },
    timeout=30,
)
response.raise_for_status()

Refresh an expired quote (new quote, same terms)

POST /v1/exchanges/quotes/{quoteId}/refresh

• refreshQuote
• API key scope exchanges:write
• Tenant customer

Parameters

Responses

• 201 Created application/json

  Schema Quote

  Firm quote; typically valid 30 seconds (countdown in the UI). Refresh to get a new rate.

  • id Uuidrequiredread-only

    Fields of id

    Uuid

  • sellAmount Moneyrequired

  • buyAmount Moneyrequired

  • rate Raterequired

  • inverseRate Raterequired

  • fixedSide FixedSiderequired

  • kind ExchangeKindrequired

  • fee Money | null

  • settlementDate Date | null

  • depositRequired Money | null

  • expiresAt Timestamprequired

  • used booleanrequired

  • createdAt Timestamprequiredread-only

    Fields of createdAt

    Timestamp

• 401 Missing, expired or invalid credentials (`unauthenticated`, `session-expired` with `reason` `idle` / `revoked` / `expired`, `invalid-api-key`, `mfa-required`). application/problem+json

  Body Problem; see the error catalogue.

• 403 Authenticated but not allowed: missing capability or scope, tenant not in memberships, `step-up-required`, IP not allow-listed, impersonation restriction. application/problem+json

  Body Problem; see the error catalogue.

• 404 Resource does not exist in this tenant (cross-tenant ids also return 404), or feature disabled (`feature-disabled`). application/problem+json

  Body Problem; see the error catalogue.

• 409 State conflict: `invalid-transition`, `duplicate-recipient`, `quote-expired`, `insufficient-funds`, `idempotency-key-in-use` (with Retry-After), `not-cancellable`. application/problem+json

  Body Problem; see the error catalogue.

• 429 Rate limit exceeded. application/problem+json

  Body Problem; see the error catalogue.

• default Unexpected error (`500 internal-error`, `501 not-implemented`, `502 provider-error`, `503 service-unavailable`, `504 provider-timeout`). Money operations that time out at the provider are never retried blindly; their state becomes `exception`/unknown and is reconciled. application/problem+json

  Body Problem; see the error catalogue.

Code samples

Against the sandbox (https://bank.wirebloom.com/v1).

curl -X POST "https://bank.wirebloom.com/v1/exchanges/quotes/{quoteId}/refresh" \
  -H "Authorization: Bearer $WIREBLOOM_API_KEY" \
  -H "X-Tenant-Id: $WIREBLOOM_CUSTOMER_ID"

const response = await fetch("https://bank.wirebloom.com/v1/exchanges/quotes/{quoteId}/refresh", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.WIREBLOOM_API_KEY}`,
    "X-Tenant-Id": process.env.WIREBLOOM_CUSTOMER_ID!,
  },
});
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
const result = await response.json();

import os

import requests

response = requests.request(
    "POST",
    "https://bank.wirebloom.com/v1/exchanges/quotes/{quoteId}/refresh",
    headers={
        "Authorization": f"Bearer {os.environ['WIREBLOOM_API_KEY']}",
        "X-Tenant-Id": os.environ["WIREBLOOM_CUSTOMER_ID"],
    },
    timeout=30,
)
response.raise_for_status()

List forward contracts and held rates

GET /v1/forward-contracts

• listForwardContracts
• API key scope exchanges:read
• Tenant customer

Parameters

Responses

• 200 OK application/json

  Schema ExchangePage

  Cursor-paginated list of Exchange.

  • data array of Exchangerequired

  • page PageInforequired

• 400 Malformed request: unparseable JSON, or an invalid header, path or query parameter (`errors[].field` is `header.X`, `path.x` or `query.x`). Body validation failures are 422 `validation-error`. application/problem+json

  Body Problem; see the error catalogue.

• 401 Missing, expired or invalid credentials (`unauthenticated`, `session-expired` with `reason` `idle` / `revoked` / `expired`, `invalid-api-key`, `mfa-required`). application/problem+json

  Body Problem; see the error catalogue.

• 403 Authenticated but not allowed: missing capability or scope, tenant not in memberships, `step-up-required`, IP not allow-listed, impersonation restriction. application/problem+json

  Body Problem; see the error catalogue.

• 404 Resource does not exist in this tenant (cross-tenant ids also return 404), or feature disabled (`feature-disabled`). application/problem+json

  Body Problem; see the error catalogue.

• 429 Rate limit exceeded. application/problem+json

  Body Problem; see the error catalogue.

• default Unexpected error (`500 internal-error`, `501 not-implemented`, `502 provider-error`, `503 service-unavailable`, `504 provider-timeout`). Money operations that time out at the provider are never retried blindly; their state becomes `exception`/unknown and is reconciled. application/problem+json

  Body Problem; see the error catalogue.

Code samples

Against the sandbox (https://bank.wirebloom.com/v1).

curl -X GET "https://bank.wirebloom.com/v1/forward-contracts" \
  -H "Authorization: Bearer $WIREBLOOM_API_KEY" \
  -H "X-Tenant-Id: $WIREBLOOM_CUSTOMER_ID"

const response = await fetch("https://bank.wirebloom.com/v1/forward-contracts", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.WIREBLOOM_API_KEY}`,
    "X-Tenant-Id": process.env.WIREBLOOM_CUSTOMER_ID!,
  },
});
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
const result = await response.json();

import os

import requests

response = requests.request(
    "GET",
    "https://bank.wirebloom.com/v1/forward-contracts",
    headers={
        "Authorization": f"Bearer {os.environ['WIREBLOOM_API_KEY']}",
        "X-Tenant-Id": os.environ["WIREBLOOM_CUSTOMER_ID"],
    },
    timeout=30,
)
response.raise_for_status()

Book forward contract / held rate

POST /v1/forward-contracts

• createForwardContract
• API key scope exchanges:write
• Idempotency-Key required
• Tenant customer

Parameters

Request body

Required. application/json

Responses

• 201 Created application/json

  Schema Exchange

  • id Uuidrequiredread-only

    Fields of id

    Uuid

  • customerId Uuidrequiredread-only

    Fields of customerId

    Uuid

  • kind ExchangeKindrequired

  • status ExchangeStatusrequiredread-only

    Fields of status

    ExchangeStatus

  • sellBalanceId Uuidrequired

  • buyBalanceId Uuidrequired

  • sellAmount Moneyrequired

  • buyAmount Moneyrequired

  • rate Raterequired

  • fixedSide FixedSiderequired

  • quoteId Uuidrequired

  • fee Money | null

  • settlementDate Date | null

  • deposit Money | null

  • remaining Money | null

  • orderId stringrequiredread-only

    Human order id shown on confirmations.

  • providerRef string | nullread-only

  • createdBy Uuid | null

  • createdAt Timestamprequiredread-only

    Fields of createdAt

    Timestamp

  • completedAt Timestamp | null

  • purpose stringread-only

    What the conversion is for: a direct exchange, an add-money conversion order or the funding of a cross-currency payment.

    One of: "exchange", "add_money", "payment"

  • statusReason string | nullread-only

    Why the exchange failed or was cancelled.

  • marginCall object | nullread-only

    Open margin call on a forward: deposit top-up required (POST /forward-contracts/{exchangeId}/deposit).

    Fields of marginCall

    • at Timestamprequired

    • amount Moneyrequired

  • drawdownCount integerread-only

    Drawdowns requested on a forward or held-rate contract.

    min 0

• 400 Malformed request: unparseable JSON, or an invalid header, path or query parameter (`errors[].field` is `header.X`, `path.x` or `query.x`). Body validation failures are 422 `validation-error`. application/problem+json

  Body Problem; see the error catalogue.

• 401 Missing, expired or invalid credentials (`unauthenticated`, `session-expired` with `reason` `idle` / `revoked` / `expired`, `invalid-api-key`, `mfa-required`). application/problem+json

  Body Problem; see the error catalogue.

• 403 Authenticated but not allowed: missing capability or scope, tenant not in memberships, `step-up-required`, IP not allow-listed, impersonation restriction. application/problem+json

  Body Problem; see the error catalogue.

• 404 Resource does not exist in this tenant (cross-tenant ids also return 404), or feature disabled (`feature-disabled`). application/problem+json

  Body Problem; see the error catalogue.

• 409 State conflict: `invalid-transition`, `duplicate-recipient`, `quote-expired`, `insufficient-funds`, `idempotency-key-in-use` (with Retry-After), `not-cancellable`. application/problem+json

  Body Problem; see the error catalogue.

• 422 Semantically invalid request; `errors[]` lists field-level problems. Also `idempotency-key-reused` when the key was used with a different payload, `limit-exceeded`, `recipient-not-approved`. application/problem+json

  Body Problem; see the error catalogue.

• 429 Rate limit exceeded. application/problem+json

  Body Problem; see the error catalogue.

• default Unexpected error (`500 internal-error`, `501 not-implemented`, `502 provider-error`, `503 service-unavailable`, `504 provider-timeout`). Money operations that time out at the provider are never retried blindly; their state becomes `exception`/unknown and is reconciled. application/problem+json

  Body Problem; see the error catalogue.

Code samples

Against the sandbox (https://bank.wirebloom.com/v1).

curl -X POST "https://bank.wirebloom.com/v1/forward-contracts" \
  -H "Authorization: Bearer $WIREBLOOM_API_KEY" \
  -H "X-Tenant-Id: $WIREBLOOM_CUSTOMER_ID" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  --data '{
  "quoteId": "0192a6f0-7c1e-7b3a-9d2e-5f4c3b2a1908",
  "sellBalanceId": "0192a6f0-7c1e-7b3a-9d2e-5f4c3b2a1908",
  "buyBalanceId": "0192a6f0-7c1e-7b3a-9d2e-5f4c3b2a1908"
}'

const response = await fetch("https://bank.wirebloom.com/v1/forward-contracts", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.WIREBLOOM_API_KEY}`,
    "X-Tenant-Id": process.env.WIREBLOOM_CUSTOMER_ID!,
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "quoteId": "0192a6f0-7c1e-7b3a-9d2e-5f4c3b2a1908",
    "sellBalanceId": "0192a6f0-7c1e-7b3a-9d2e-5f4c3b2a1908",
    "buyBalanceId": "0192a6f0-7c1e-7b3a-9d2e-5f4c3b2a1908"
  }),
});
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
const result = await response.json();

import os, uuid

import requests

response = requests.request(
    "POST",
    "https://bank.wirebloom.com/v1/forward-contracts",
    headers={
        "Authorization": f"Bearer {os.environ['WIREBLOOM_API_KEY']}",
        "X-Tenant-Id": os.environ["WIREBLOOM_CUSTOMER_ID"],
        "Idempotency-Key": str(uuid.uuid4()),
        "Content-Type": "application/json",
    },
    json={
      "quoteId": "0192a6f0-7c1e-7b3a-9d2e-5f4c3b2a1908",
      "sellBalanceId": "0192a6f0-7c1e-7b3a-9d2e-5f4c3b2a1908",
      "buyBalanceId": "0192a6f0-7c1e-7b3a-9d2e-5f4c3b2a1908"
    },
    timeout=30,
)
response.raise_for_status()

Get forward contract

GET /v1/forward-contracts/{exchangeId}

• getForwardContract
• API key scope exchanges:read
• Tenant customer

Parameters

Responses

• 200 OK application/json

  Schema Exchange

  • id Uuidrequiredread-only

    Fields of id

    Uuid

  • customerId Uuidrequiredread-only

    Fields of customerId

    Uuid

  • kind ExchangeKindrequired

  • status ExchangeStatusrequiredread-only

    Fields of status

    ExchangeStatus

  • sellBalanceId Uuidrequired

  • buyBalanceId Uuidrequired

  • sellAmount Moneyrequired

  • buyAmount Moneyrequired

  • rate Raterequired

  • fixedSide FixedSiderequired

  • quoteId Uuidrequired

  • fee Money | null

  • settlementDate Date | null

  • deposit Money | null

  • remaining Money | null

  • orderId stringrequiredread-only

    Human order id shown on confirmations.

  • providerRef string | nullread-only

  • createdBy Uuid | null

  • createdAt Timestamprequiredread-only

    Fields of createdAt

    Timestamp

  • completedAt Timestamp | null

  • purpose stringread-only

    What the conversion is for: a direct exchange, an add-money conversion order or the funding of a cross-currency payment.

    One of: "exchange", "add_money", "payment"

  • statusReason string | nullread-only

    Why the exchange failed or was cancelled.

  • marginCall object | nullread-only

    Open margin call on a forward: deposit top-up required (POST /forward-contracts/{exchangeId}/deposit).

    Fields of marginCall

    • at Timestamprequired

    • amount Moneyrequired

  • drawdownCount integerread-only

    Drawdowns requested on a forward or held-rate contract.

    min 0

• 401 Missing, expired or invalid credentials (`unauthenticated`, `session-expired` with `reason` `idle` / `revoked` / `expired`, `invalid-api-key`, `mfa-required`). application/problem+json

  Body Problem; see the error catalogue.

• 403 Authenticated but not allowed: missing capability or scope, tenant not in memberships, `step-up-required`, IP not allow-listed, impersonation restriction. application/problem+json

  Body Problem; see the error catalogue.

• 404 Resource does not exist in this tenant (cross-tenant ids also return 404), or feature disabled (`feature-disabled`). application/problem+json

  Body Problem; see the error catalogue.

• 429 Rate limit exceeded. application/problem+json

  Body Problem; see the error catalogue.

• default Unexpected error (`500 internal-error`, `501 not-implemented`, `502 provider-error`, `503 service-unavailable`, `504 provider-timeout`). Money operations that time out at the provider are never retried blindly; their state becomes `exception`/unknown and is reconciled. application/problem+json

  Body Problem; see the error catalogue.

Code samples

Against the sandbox (https://bank.wirebloom.com/v1).

curl -X GET "https://bank.wirebloom.com/v1/forward-contracts/{exchangeId}" \
  -H "Authorization: Bearer $WIREBLOOM_API_KEY" \
  -H "X-Tenant-Id: $WIREBLOOM_CUSTOMER_ID"

const response = await fetch("https://bank.wirebloom.com/v1/forward-contracts/{exchangeId}", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.WIREBLOOM_API_KEY}`,
    "X-Tenant-Id": process.env.WIREBLOOM_CUSTOMER_ID!,
  },
});
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
const result = await response.json();

import os

import requests

response = requests.request(
    "GET",
    "https://bank.wirebloom.com/v1/forward-contracts/{exchangeId}",
    headers={
        "Authorization": f"Bearer {os.environ['WIREBLOOM_API_KEY']}",
        "X-Tenant-Id": os.environ["WIREBLOOM_CUSTOMER_ID"],
    },
    timeout=30,
)
response.raise_for_status()

Top up a forward deposit (margin call)

POST /v1/forward-contracts/{exchangeId}/deposit

• topUpForwardDeposit
• API key scope exchanges:write
• Idempotency-Key required
• Tenant customer

Parameters

Request body

Required. application/json

Responses

• 200 OK application/json

  Schema Exchange

  • id Uuidrequiredread-only

    Fields of id

    Uuid

  • customerId Uuidrequiredread-only

    Fields of customerId

    Uuid

  • kind ExchangeKindrequired

  • status ExchangeStatusrequiredread-only

    Fields of status

    ExchangeStatus

  • sellBalanceId Uuidrequired

  • buyBalanceId Uuidrequired

  • sellAmount Moneyrequired

  • buyAmount Moneyrequired

  • rate Raterequired

  • fixedSide FixedSiderequired

  • quoteId Uuidrequired

  • fee Money | null

  • settlementDate Date | null

  • deposit Money | null

  • remaining Money | null

  • orderId stringrequiredread-only

    Human order id shown on confirmations.

  • providerRef string | nullread-only

  • createdBy Uuid | null

  • createdAt Timestamprequiredread-only

    Fields of createdAt

    Timestamp

  • completedAt Timestamp | null

  • purpose stringread-only

    What the conversion is for: a direct exchange, an add-money conversion order or the funding of a cross-currency payment.

    One of: "exchange", "add_money", "payment"

  • statusReason string | nullread-only

    Why the exchange failed or was cancelled.

  • marginCall object | nullread-only

    Open margin call on a forward: deposit top-up required (POST /forward-contracts/{exchangeId}/deposit).

    Fields of marginCall

    • at Timestamprequired

    • amount Moneyrequired

  • drawdownCount integerread-only

    Drawdowns requested on a forward or held-rate contract.

    min 0

• 400 Malformed request: unparseable JSON, or an invalid header, path or query parameter (`errors[].field` is `header.X`, `path.x` or `query.x`). Body validation failures are 422 `validation-error`. application/problem+json

  Body Problem; see the error catalogue.

• 401 Missing, expired or invalid credentials (`unauthenticated`, `session-expired` with `reason` `idle` / `revoked` / `expired`, `invalid-api-key`, `mfa-required`). application/problem+json

  Body Problem; see the error catalogue.

• 403 Authenticated but not allowed: missing capability or scope, tenant not in memberships, `step-up-required`, IP not allow-listed, impersonation restriction. application/problem+json

  Body Problem; see the error catalogue.

• 404 Resource does not exist in this tenant (cross-tenant ids also return 404), or feature disabled (`feature-disabled`). application/problem+json

  Body Problem; see the error catalogue.

• 409 State conflict: `invalid-transition`, `duplicate-recipient`, `quote-expired`, `insufficient-funds`, `idempotency-key-in-use` (with Retry-After), `not-cancellable`. application/problem+json

  Body Problem; see the error catalogue.

• 422 Semantically invalid request; `errors[]` lists field-level problems. Also `idempotency-key-reused` when the key was used with a different payload, `limit-exceeded`, `recipient-not-approved`. application/problem+json

  Body Problem; see the error catalogue.

• 429 Rate limit exceeded. application/problem+json

  Body Problem; see the error catalogue.

• default Unexpected error (`500 internal-error`, `501 not-implemented`, `502 provider-error`, `503 service-unavailable`, `504 provider-timeout`). Money operations that time out at the provider are never retried blindly; their state becomes `exception`/unknown and is reconciled. application/problem+json

  Body Problem; see the error catalogue.

Code samples

Against the sandbox (https://bank.wirebloom.com/v1).

curl -X POST "https://bank.wirebloom.com/v1/forward-contracts/{exchangeId}/deposit" \
  -H "Authorization: Bearer $WIREBLOOM_API_KEY" \
  -H "X-Tenant-Id: $WIREBLOOM_CUSTOMER_ID" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  --data '{
  "amount": {
    "amountMinor": "125050",
    "currency": "GBP"
  }
}'

const response = await fetch("https://bank.wirebloom.com/v1/forward-contracts/{exchangeId}/deposit", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.WIREBLOOM_API_KEY}`,
    "X-Tenant-Id": process.env.WIREBLOOM_CUSTOMER_ID!,
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "amount": {
      "amountMinor": "125050",
      "currency": "GBP"
    }
  }),
});
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
const result = await response.json();

import os, uuid

import requests

response = requests.request(
    "POST",
    "https://bank.wirebloom.com/v1/forward-contracts/{exchangeId}/deposit",
    headers={
        "Authorization": f"Bearer {os.environ['WIREBLOOM_API_KEY']}",
        "X-Tenant-Id": os.environ["WIREBLOOM_CUSTOMER_ID"],
        "Idempotency-Key": str(uuid.uuid4()),
        "Content-Type": "application/json",
    },
    json={
      "amount": {
        "amountMinor": "125050",
        "currency": "GBP"
      }
    },
    timeout=30,
)
response.raise_for_status()

Draw down a forward contract

POST /v1/forward-contracts/{exchangeId}/drawdowns

• drawdownForwardContract
• API key scope exchanges:write
• Idempotency-Key required
• Tenant customer

Parameters

Request body

Required. application/json

Responses

• 200 OK application/json

  Schema Exchange

  • id Uuidrequiredread-only

    Fields of id

    Uuid

  • customerId Uuidrequiredread-only

    Fields of customerId

    Uuid

  • kind ExchangeKindrequired

  • status ExchangeStatusrequiredread-only

    Fields of status

    ExchangeStatus

  • sellBalanceId Uuidrequired

  • buyBalanceId Uuidrequired

  • sellAmount Moneyrequired

  • buyAmount Moneyrequired

  • rate Raterequired

  • fixedSide FixedSiderequired

  • quoteId Uuidrequired

  • fee Money | null

  • settlementDate Date | null

  • deposit Money | null

  • remaining Money | null

  • orderId stringrequiredread-only

    Human order id shown on confirmations.

  • providerRef string | nullread-only

  • createdBy Uuid | null

  • createdAt Timestamprequiredread-only

    Fields of createdAt

    Timestamp

  • completedAt Timestamp | null

  • purpose stringread-only

    What the conversion is for: a direct exchange, an add-money conversion order or the funding of a cross-currency payment.

    One of: "exchange", "add_money", "payment"

  • statusReason string | nullread-only

    Why the exchange failed or was cancelled.

  • marginCall object | nullread-only

    Open margin call on a forward: deposit top-up required (POST /forward-contracts/{exchangeId}/deposit).

    Fields of marginCall

    • at Timestamprequired

    • amount Moneyrequired

  • drawdownCount integerread-only

    Drawdowns requested on a forward or held-rate contract.

    min 0

• 400 Malformed request: unparseable JSON, or an invalid header, path or query parameter (`errors[].field` is `header.X`, `path.x` or `query.x`). Body validation failures are 422 `validation-error`. application/problem+json

  Body Problem; see the error catalogue.

• 401 Missing, expired or invalid credentials (`unauthenticated`, `session-expired` with `reason` `idle` / `revoked` / `expired`, `invalid-api-key`, `mfa-required`). application/problem+json

  Body Problem; see the error catalogue.

• 403 Authenticated but not allowed: missing capability or scope, tenant not in memberships, `step-up-required`, IP not allow-listed, impersonation restriction. application/problem+json

  Body Problem; see the error catalogue.

• 404 Resource does not exist in this tenant (cross-tenant ids also return 404), or feature disabled (`feature-disabled`). application/problem+json

  Body Problem; see the error catalogue.

• 409 State conflict: `invalid-transition`, `duplicate-recipient`, `quote-expired`, `insufficient-funds`, `idempotency-key-in-use` (with Retry-After), `not-cancellable`. application/problem+json

  Body Problem; see the error catalogue.

• 422 Semantically invalid request; `errors[]` lists field-level problems. Also `idempotency-key-reused` when the key was used with a different payload, `limit-exceeded`, `recipient-not-approved`. application/problem+json

  Body Problem; see the error catalogue.

• 429 Rate limit exceeded. application/problem+json

  Body Problem; see the error catalogue.

• default Unexpected error (`500 internal-error`, `501 not-implemented`, `502 provider-error`, `503 service-unavailable`, `504 provider-timeout`). Money operations that time out at the provider are never retried blindly; their state becomes `exception`/unknown and is reconciled. application/problem+json

  Body Problem; see the error catalogue.

Code samples

Against the sandbox (https://bank.wirebloom.com/v1).

curl -X POST "https://bank.wirebloom.com/v1/forward-contracts/{exchangeId}/drawdowns" \
  -H "Authorization: Bearer $WIREBLOOM_API_KEY" \
  -H "X-Tenant-Id: $WIREBLOOM_CUSTOMER_ID" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  --data '{
  "amount": {
    "amountMinor": "125050",
    "currency": "GBP"
  }
}'

const response = await fetch("https://bank.wirebloom.com/v1/forward-contracts/{exchangeId}/drawdowns", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.WIREBLOOM_API_KEY}`,
    "X-Tenant-Id": process.env.WIREBLOOM_CUSTOMER_ID!,
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "amount": {
      "amountMinor": "125050",
      "currency": "GBP"
    }
  }),
});
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
const result = await response.json();

import os, uuid

import requests

response = requests.request(
    "POST",
    "https://bank.wirebloom.com/v1/forward-contracts/{exchangeId}/drawdowns",
    headers={
        "Authorization": f"Bearer {os.environ['WIREBLOOM_API_KEY']}",
        "X-Tenant-Id": os.environ["WIREBLOOM_CUSTOMER_ID"],
        "Idempotency-Key": str(uuid.uuid4()),
        "Content-Type": "application/json",
    },
    json={
      "amount": {
        "amountMinor": "125050",
        "currency": "GBP"
      }
    },
    timeout=30,
)
response.raise_for_status()

Deposit balance held for forwards

GET /v1/forward-contracts/deposit-balance

• getForwardDepositBalance
• API key scope exchanges:read
• Tenant customer

Parameters

Responses

• 200 OK application/json

  Schema DepositBalance

  Deposits held against open forward contracts (Equals "View deposit balance").

  • balances array of objectrequired

    Fields of balances

    • currency CurrencyCoderequired

    • held Moneyrequired

    • contracts integerrequired

      min 0

• 401 Missing, expired or invalid credentials (`unauthenticated`, `session-expired` with `reason` `idle` / `revoked` / `expired`, `invalid-api-key`, `mfa-required`). application/problem+json

  Body Problem; see the error catalogue.

• 403 Authenticated but not allowed: missing capability or scope, tenant not in memberships, `step-up-required`, IP not allow-listed, impersonation restriction. application/problem+json

  Body Problem; see the error catalogue.

• 404 Resource does not exist in this tenant (cross-tenant ids also return 404), or feature disabled (`feature-disabled`). application/problem+json

  Body Problem; see the error catalogue.

• 429 Rate limit exceeded. application/problem+json

  Body Problem; see the error catalogue.

• default Unexpected error (`500 internal-error`, `501 not-implemented`, `502 provider-error`, `503 service-unavailable`, `504 provider-timeout`). Money operations that time out at the provider are never retried blindly; their state becomes `exception`/unknown and is reconciled. application/problem+json

  Body Problem; see the error catalogue.

Code samples

Against the sandbox (https://bank.wirebloom.com/v1).

curl -X GET "https://bank.wirebloom.com/v1/forward-contracts/deposit-balance" \
  -H "Authorization: Bearer $WIREBLOOM_API_KEY" \
  -H "X-Tenant-Id: $WIREBLOOM_CUSTOMER_ID"

const response = await fetch("https://bank.wirebloom.com/v1/forward-contracts/deposit-balance", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.WIREBLOOM_API_KEY}`,
    "X-Tenant-Id": process.env.WIREBLOOM_CUSTOMER_ID!,
  },
});
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
const result = await response.json();

import os

import requests

response = requests.request(
    "GET",
    "https://bank.wirebloom.com/v1/forward-contracts/deposit-balance",
    headers={
        "Authorization": f"Bearer {os.environ['WIREBLOOM_API_KEY']}",
        "X-Tenant-Id": os.environ["WIREBLOOM_CUSTOMER_ID"],
    },
    timeout=30,
)
response.raise_for_status()

List funds requests

GET /v1/funds-requests

• listFundsRequests
• API key scope payments:read
• Tenant customer

Parameters

Responses

• 200 OK application/json

  Schema FundsRequestPage

  Cursor-paginated list of FundsRequest.

  • data array of FundsRequestrequired

  • page PageInforequired

• 400 Malformed request: unparseable JSON, or an invalid header, path or query parameter (`errors[].field` is `header.X`, `path.x` or `query.x`). Body validation failures are 422 `validation-error`. application/problem+json

  Body Problem; see the error catalogue.

• 401 Missing, expired or invalid credentials (`unauthenticated`, `session-expired` with `reason` `idle` / `revoked` / `expired`, `invalid-api-key`, `mfa-required`). application/problem+json

  Body Problem; see the error catalogue.

• 403 Authenticated but not allowed: missing capability or scope, tenant not in memberships, `step-up-required`, IP not allow-listed, impersonation restriction. application/problem+json

  Body Problem; see the error catalogue.

• 429 Rate limit exceeded. application/problem+json

  Body Problem; see the error catalogue.

• default Unexpected error (`500 internal-error`, `501 not-implemented`, `502 provider-error`, `503 service-unavailable`, `504 provider-timeout`). Money operations that time out at the provider are never retried blindly; their state becomes `exception`/unknown and is reconciled. application/problem+json

  Body Problem; see the error catalogue.

Code samples

Against the sandbox (https://bank.wirebloom.com/v1).

curl -X GET "https://bank.wirebloom.com/v1/funds-requests" \
  -H "Authorization: Bearer $WIREBLOOM_API_KEY" \
  -H "X-Tenant-Id: $WIREBLOOM_CUSTOMER_ID"

const response = await fetch("https://bank.wirebloom.com/v1/funds-requests", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.WIREBLOOM_API_KEY}`,
    "X-Tenant-Id": process.env.WIREBLOOM_CUSTOMER_ID!,
  },
});
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
const result = await response.json();

import os

import requests

response = requests.request(
    "GET",
    "https://bank.wirebloom.com/v1/funds-requests",
    headers={
        "Authorization": f"Bearer {os.environ['WIREBLOOM_API_KEY']}",
        "X-Tenant-Id": os.environ["WIREBLOOM_CUSTOMER_ID"],
    },
    timeout=30,
)
response.raise_for_status()

Request funds

POST /v1/funds-requests

• createFundsRequest
• API key scope payments:write
• Idempotency-Key required
• Tenant customer

Parameters

Request body

Required. application/json

Responses

• 201 Created application/json

  Schema FundsRequest

  Equals "Requests": a member asks balance holders for funds (e.g. to a sub-balance or card). Fulfilment is an internal transfer (transferId) into balanceId from the approver's chosen source.

  • id Uuidrequiredread-only

    Fields of id

    Uuid

  • customerId Uuidrequiredread-only

    Fields of customerId

    Uuid

  • balanceId Uuidrequired

  • amount Moneyrequired

  • reason stringrequired

    max length 500

  • status FundsRequestStatusrequiredread-only

    Fields of status

    FundsRequestStatus

  • approvalId Uuid | null

  • requestedBy Uuidrequiredread-only

    Fields of requestedBy

    Uuid

  • createdAt Timestamprequiredread-only

    Fields of createdAt

    Timestamp

  • decidedAt Timestamp | null

  • fromBalanceId Uuid | null

  • transferId Uuid | null

  • decisionReason string | nullread-only

  • expiresAt Timestamp | null

• 400 Malformed request: unparseable JSON, or an invalid header, path or query parameter (`errors[].field` is `header.X`, `path.x` or `query.x`). Body validation failures are 422 `validation-error`. application/problem+json

  Body Problem; see the error catalogue.

• 401 Missing, expired or invalid credentials (`unauthenticated`, `session-expired` with `reason` `idle` / `revoked` / `expired`, `invalid-api-key`, `mfa-required`). application/problem+json

  Body Problem; see the error catalogue.

• 403 Authenticated but not allowed: missing capability or scope, tenant not in memberships, `step-up-required`, IP not allow-listed, impersonation restriction. application/problem+json

  Body Problem; see the error catalogue.

• 409 State conflict: `invalid-transition`, `duplicate-recipient`, `quote-expired`, `insufficient-funds`, `idempotency-key-in-use` (with Retry-After), `not-cancellable`. application/problem+json

  Body Problem; see the error catalogue.

• 422 Semantically invalid request; `errors[]` lists field-level problems. Also `idempotency-key-reused` when the key was used with a different payload, `limit-exceeded`, `recipient-not-approved`. application/problem+json

  Body Problem; see the error catalogue.

• 429 Rate limit exceeded. application/problem+json

  Body Problem; see the error catalogue.

• default Unexpected error (`500 internal-error`, `501 not-implemented`, `502 provider-error`, `503 service-unavailable`, `504 provider-timeout`). Money operations that time out at the provider are never retried blindly; their state becomes `exception`/unknown and is reconciled. application/problem+json

  Body Problem; see the error catalogue.

Code samples

Against the sandbox (https://bank.wirebloom.com/v1).

curl -X POST "https://bank.wirebloom.com/v1/funds-requests" \
  -H "Authorization: Bearer $WIREBLOOM_API_KEY" \
  -H "X-Tenant-Id: $WIREBLOOM_CUSTOMER_ID" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  --data '{
  "balanceId": "0192a6f0-7c1e-7b3a-9d2e-5f4c3b2a1908",
  "amount": {
    "amountMinor": "125050",
    "currency": "GBP"
  },
  "reason": "string"
}'

const response = await fetch("https://bank.wirebloom.com/v1/funds-requests", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.WIREBLOOM_API_KEY}`,
    "X-Tenant-Id": process.env.WIREBLOOM_CUSTOMER_ID!,
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "balanceId": "0192a6f0-7c1e-7b3a-9d2e-5f4c3b2a1908",
    "amount": {
      "amountMinor": "125050",
      "currency": "GBP"
    },
    "reason": "string"
  }),
});
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
const result = await response.json();

import os, uuid

import requests

response = requests.request(
    "POST",
    "https://bank.wirebloom.com/v1/funds-requests",
    headers={
        "Authorization": f"Bearer {os.environ['WIREBLOOM_API_KEY']}",
        "X-Tenant-Id": os.environ["WIREBLOOM_CUSTOMER_ID"],
        "Idempotency-Key": str(uuid.uuid4()),
        "Content-Type": "application/json",
    },
    json={
      "balanceId": "0192a6f0-7c1e-7b3a-9d2e-5f4c3b2a1908",
      "amount": {
        "amountMinor": "125050",
        "currency": "GBP"
      },
      "reason": "string"
    },
    timeout=30,
)
response.raise_for_status()

Get funds request

GET /v1/funds-requests/{fundsRequestId}

• getFundsRequest
• API key scope payments:read
• Tenant customer

Parameters

Responses

• 200 OK application/json

  Schema FundsRequest

  Equals "Requests": a member asks balance holders for funds (e.g. to a sub-balance or card). Fulfilment is an internal transfer (transferId) into balanceId from the approver's chosen source.

  • id Uuidrequiredread-only

    Fields of id

    Uuid

  • customerId Uuidrequiredread-only

    Fields of customerId

    Uuid

  • balanceId Uuidrequired

  • amount Moneyrequired

  • reason stringrequired

    max length 500

  • status FundsRequestStatusrequiredread-only

    Fields of status

    FundsRequestStatus

  • approvalId Uuid | null

  • requestedBy Uuidrequiredread-only

    Fields of requestedBy

    Uuid

  • createdAt Timestamprequiredread-only

    Fields of createdAt

    Timestamp

  • decidedAt Timestamp | null

  • fromBalanceId Uuid | null

  • transferId Uuid | null

  • decisionReason string | nullread-only

  • expiresAt Timestamp | null

• 401 Missing, expired or invalid credentials (`unauthenticated`, `session-expired` with `reason` `idle` / `revoked` / `expired`, `invalid-api-key`, `mfa-required`). application/problem+json

  Body Problem; see the error catalogue.

• 403 Authenticated but not allowed: missing capability or scope, tenant not in memberships, `step-up-required`, IP not allow-listed, impersonation restriction. application/problem+json

  Body Problem; see the error catalogue.

• 404 Resource does not exist in this tenant (cross-tenant ids also return 404), or feature disabled (`feature-disabled`). application/problem+json

  Body Problem; see the error catalogue.

• 429 Rate limit exceeded. application/problem+json

  Body Problem; see the error catalogue.

• default Unexpected error (`500 internal-error`, `501 not-implemented`, `502 provider-error`, `503 service-unavailable`, `504 provider-timeout`). Money operations that time out at the provider are never retried blindly; their state becomes `exception`/unknown and is reconciled. application/problem+json

  Body Problem; see the error catalogue.

Code samples

Against the sandbox (https://bank.wirebloom.com/v1).

curl -X GET "https://bank.wirebloom.com/v1/funds-requests/{fundsRequestId}" \
  -H "Authorization: Bearer $WIREBLOOM_API_KEY" \
  -H "X-Tenant-Id: $WIREBLOOM_CUSTOMER_ID"

const response = await fetch("https://bank.wirebloom.com/v1/funds-requests/{fundsRequestId}", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.WIREBLOOM_API_KEY}`,
    "X-Tenant-Id": process.env.WIREBLOOM_CUSTOMER_ID!,
  },
});
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
const result = await response.json();

import os

import requests

response = requests.request(
    "GET",
    "https://bank.wirebloom.com/v1/funds-requests/{fundsRequestId}",
    headers={
        "Authorization": f"Bearer {os.environ['WIREBLOOM_API_KEY']}",
        "X-Tenant-Id": os.environ["WIREBLOOM_CUSTOMER_ID"],
    },
    timeout=30,
)
response.raise_for_status()

Cancel funds request

POST /v1/funds-requests/{fundsRequestId}/cancel

• cancelFundsRequest
• API key scope payments:write
• Tenant customer

Parameters

Responses

• 200 OK application/json

  Schema FundsRequest

  Equals "Requests": a member asks balance holders for funds (e.g. to a sub-balance or card). Fulfilment is an internal transfer (transferId) into balanceId from the approver's chosen source.

  • id Uuidrequiredread-only

    Fields of id

    Uuid

  • customerId Uuidrequiredread-only

    Fields of customerId

    Uuid

  • balanceId Uuidrequired

  • amount Moneyrequired

  • reason stringrequired

    max length 500

  • status FundsRequestStatusrequiredread-only

    Fields of status

    FundsRequestStatus

  • approvalId Uuid | null

  • requestedBy Uuidrequiredread-only

    Fields of requestedBy

    Uuid

  • createdAt Timestamprequiredread-only

    Fields of createdAt

    Timestamp

  • decidedAt Timestamp | null

  • fromBalanceId Uuid | null

  • transferId Uuid | null

  • decisionReason string | nullread-only

  • expiresAt Timestamp | null

• 401 Missing, expired or invalid credentials (`unauthenticated`, `session-expired` with `reason` `idle` / `revoked` / `expired`, `invalid-api-key`, `mfa-required`). application/problem+json

  Body Problem; see the error catalogue.

• 403 Authenticated but not allowed: missing capability or scope, tenant not in memberships, `step-up-required`, IP not allow-listed, impersonation restriction. application/problem+json

  Body Problem; see the error catalogue.

• 404 Resource does not exist in this tenant (cross-tenant ids also return 404), or feature disabled (`feature-disabled`). application/problem+json

  Body Problem; see the error catalogue.

• 409 State conflict: `invalid-transition`, `duplicate-recipient`, `quote-expired`, `insufficient-funds`, `idempotency-key-in-use` (with Retry-After), `not-cancellable`. application/problem+json

  Body Problem; see the error catalogue.

• 429 Rate limit exceeded. application/problem+json

  Body Problem; see the error catalogue.

• default Unexpected error (`500 internal-error`, `501 not-implemented`, `502 provider-error`, `503 service-unavailable`, `504 provider-timeout`). Money operations that time out at the provider are never retried blindly; their state becomes `exception`/unknown and is reconciled. application/problem+json

  Body Problem; see the error catalogue.

Code samples

Against the sandbox (https://bank.wirebloom.com/v1).

curl -X POST "https://bank.wirebloom.com/v1/funds-requests/{fundsRequestId}/cancel" \
  -H "Authorization: Bearer $WIREBLOOM_API_KEY" \
  -H "X-Tenant-Id: $WIREBLOOM_CUSTOMER_ID"

const response = await fetch("https://bank.wirebloom.com/v1/funds-requests/{fundsRequestId}/cancel", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.WIREBLOOM_API_KEY}`,
    "X-Tenant-Id": process.env.WIREBLOOM_CUSTOMER_ID!,
  },
});
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
const result = await response.json();

import os

import requests

response = requests.request(
    "POST",
    "https://bank.wirebloom.com/v1/funds-requests/{fundsRequestId}/cancel",
    headers={
        "Authorization": f"Bearer {os.environ['WIREBLOOM_API_KEY']}",
        "X-Tenant-Id": os.environ["WIREBLOOM_CUSTOMER_ID"],
    },
    timeout=30,
)
response.raise_for_status()

List direct debit mandates

GET /v1/mandates

• listMandates
• API key scope payments:read
• Tenant customer

Parameters

Responses

• 200 OK application/json

  Schema MandatePage

  Cursor-paginated list of Mandate.

  • data array of Mandaterequired

  • page PageInforequired

• 400 Malformed request: unparseable JSON, or an invalid header, path or query parameter (`errors[].field` is `header.X`, `path.x` or `query.x`). Body validation failures are 422 `validation-error`. application/problem+json

  Body Problem; see the error catalogue.

• 401 Missing, expired or invalid credentials (`unauthenticated`, `session-expired` with `reason` `idle` / `revoked` / `expired`, `invalid-api-key`, `mfa-required`). application/problem+json

  Body Problem; see the error catalogue.

• 403 Authenticated but not allowed: missing capability or scope, tenant not in memberships, `step-up-required`, IP not allow-listed, impersonation restriction. application/problem+json

  Body Problem; see the error catalogue.

• 404 Resource does not exist in this tenant (cross-tenant ids also return 404), or feature disabled (`feature-disabled`). application/problem+json

  Body Problem; see the error catalogue.

• 429 Rate limit exceeded. application/problem+json

  Body Problem; see the error catalogue.

• default Unexpected error (`500 internal-error`, `501 not-implemented`, `502 provider-error`, `503 service-unavailable`, `504 provider-timeout`). Money operations that time out at the provider are never retried blindly; their state becomes `exception`/unknown and is reconciled. application/problem+json

  Body Problem; see the error catalogue.

Code samples

Against the sandbox (https://bank.wirebloom.com/v1).

curl -X GET "https://bank.wirebloom.com/v1/mandates" \
  -H "Authorization: Bearer $WIREBLOOM_API_KEY" \
  -H "X-Tenant-Id: $WIREBLOOM_CUSTOMER_ID"

const response = await fetch("https://bank.wirebloom.com/v1/mandates", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.WIREBLOOM_API_KEY}`,
    "X-Tenant-Id": process.env.WIREBLOOM_CUSTOMER_ID!,
  },
});
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
const result = await response.json();

import os

import requests

response = requests.request(
    "GET",
    "https://bank.wirebloom.com/v1/mandates",
    headers={
        "Authorization": f"Bearer {os.environ['WIREBLOOM_API_KEY']}",
        "X-Tenant-Id": os.environ["WIREBLOOM_CUSTOMER_ID"],
    },
    timeout=30,
)
response.raise_for_status()

Create mandate

POST /v1/mandates

• createMandate
• API key scope payments:write
• Idempotency-Key required
• Tenant customer

Parameters

Request body

Required. application/json