Skip to content
SWIFTariusOpen in Telegram

API reference

SWIFTarius API reference

Track SWIFT payments by UETR from your own systems: check a payment, read its status history, open a follow-up case and give a counterparty a read-only status card.

Base URL https://api.swiftarius.com · OpenAPI 3.1.0 · API version 2.0.0

Check a payment in Telegram

Updated

Quick start

  1. 01

    Create an API key

    In the @swiftarius_bot Telegram bot, send /apikey. The key is shown once: store it in your secrets manager, for example as SWIFTARIUS_KEY. /keys lists your keys and /revoke turns one off.

  2. 02

    Add credits

    Checks are prepaid in USDT: packs from 50 USDT for 330 checks, or monthly API plans from 199 USDT for 2,000 checks. Prices and how to pay: pricing.

  3. 03

    Check a payment

    Send the UETR to POST /v1/track. The amount, currency and value date are optional and help locate the payment. A check usually takes 10 to 40 seconds.

POST /v1/track

curl https://api.swiftarius.com/v1/track \
  -H "X-API-Key: $SWIFTARIUS_KEY" \
  -H "Idempotency-Key: order-58213" \
  -H "Content-Type: application/json" \
  -d '{
    "uetr": "cf935c67-a3ac-4d58-b2fc-bf2267a14ecd",
    "amount": "12500.00",
    "currency": "USD",
    "value_date": "2026-10-27"
  }'

200 OK · application/json · excerpt

{
  "uetr": "cf935c67-a3ac-4d58-b2fc-bf2267a14ecd",
  "summary": {
    "status_code": "PDNG",
    "status_human": "pending: under review or on hold",
    "last_bank_time": "2026-10-26T16:40:00Z",
    "final": false
  },
  "charged_credits": 1
}

Authentication

Send your API key in the X-API-Key header. Create a key in the SWIFTarius Telegram bot (@swiftarius_bot) with /apikey. The key is shown once.

Credits

A check (POST /v1/track) costs check_cost service credits, see GET /v1/account. It is charged only when the check returns an answer, including "not found". When no answer could be obtained, the response is 503 sources_unavailable and nothing is charged.

Idempotency

POST /v1/track and invoice creation require an Idempotency-Key header, 8 to 128 characters. Repeating a request with the same key returns the original response with Idempotent-Replayed: true and is never charged twice. The same key with a different body returns 409 idempotency_conflict.

Errors

Errors are JSON objects: {"detail": "<code>"}.

Errors
StatusCodes
401invalid_api_key
402insufficient_balance
403account_blocked
400unknown_pack
404payment_not_found, share_not_found, invoice_not_found
409idempotency_conflict, request_in_progress
429rate_limit, daily_limit (with Retry-After)
503sources_unavailable, tracking_failed_balance_restored

Languages

Human-readable fields follow Accept-Language: en, zh, he, hi, ar, ru.

Statuses are what banks have reported for the UETR. They are not a confirmation that funds were credited. SWIFTarius is an independent service and is not affiliated with SWIFT.

Account

Balance, price of a check and credit history.

Account and balance GET /v1/account

Authentication: X-API-Key header.

Response 200

JSON object Account:

client_code required
string Your client code. Quote it when you contact support. Example: SW-7Q4K-M2XA.
balance required
integer Service credits available.
unit required
"service_credits"
check_cost required
integer Credits charged for one answered check.
subscription_until required
number End of the Telegram subscription, Unix time; 0 if none.
lang required
string or null Account language, used when the request has no Accept-Language.
languages required
array of string Example: ["ar","en","he","hi","ru","zh"].

Errors

  • 401 Unauthorized
  • 403 Forbidden
  • 429 Too Many Requests

Error bodies are {"detail": "<code>"}; the codes are listed under Errors. A 422 response lists the fields that failed validation.

Example

GET /v1/account

curl https://api.swiftarius.com/v1/account \
  -H "X-API-Key: $SWIFTARIUS_KEY"

Credit history GET /v1/ledger

Newest first.

Authentication: X-API-Key header.

Parameters

limit
query · integer From 1 to 500. Default: 100.

Response 200

JSON array of LedgerEntry objects:

amount required
integer Positive for top-ups and returned reservations, negative for reservations.
kind required
string reserve, charge, release, credit or external_credit. Example: reserve.
reference required
string Unique reference of the operation.
balance_after required
integer
created_at required
number Unix time.

Errors

  • 401 Unauthorized
  • 403 Forbidden
  • 422 Validation Error
  • 429 Too Many Requests

Error bodies are {"detail": "<code>"}; the codes are listed under Errors. A 422 response lists the fields that failed validation.

Example

GET /v1/ledger

curl "https://api.swiftarius.com/v1/ledger?limit=100" \
  -H "X-API-Key: $SWIFTARIUS_KEY"

Tracking

Check a payment by UETR.

Check a payment POST /v1/track

Checks the current status of a SWIFT payment by UETR and saves the payment to your register. A check usually takes 10 to 40 seconds. Credits are charged only for an answered check.

Authentication: X-API-Key header.

Parameters

Idempotency-Key required
header · string Your unique key for this operation, 8 to 128 characters.

Request body

JSON object TrackInput, required.

uetr required
string (UUID v4) Unique end-to-end transaction reference: MT103 field 121 or pacs.008 PmtId/UETR. Example: cf935c67-a3ac-4d58-b2fc-bf2267a14ecd.
amount
number or string or null Payment amount. Optional; amount and value date help locate the payment. Greater than 0. Example: 12500.00.
currency
string or null ISO 4217 code. Pattern ^[A-Z]{3}$. Example: USD.
value_date
string (date) or null Value date or payment date. Example: 2026-10-27.

Response 200

JSON object TrackReport:

uetr required
string Example: cf935c67-a3ac-4d58-b2fc-bf2267a14ecd.
summary required
Summary
elapsed_s required
number
results required
array of CheckResult
new_events required
array of Event Events not seen in earlier checks of this payment.
charged_credits required
integer
error
string or null sources_unavailable when no answer was obtained.

Errors

  • 401 Unauthorized
  • 402 Payment Required
  • 403 Forbidden
  • 409 Conflict
  • 422 Validation Error
  • 429 Too Many Requests
  • 503 No answer could be obtained. Nothing is charged.

Error bodies are {"detail": "<code>"}; the codes are listed under Errors. A 422 response lists the fields that failed validation.

Example

POST /v1/track

curl https://api.swiftarius.com/v1/track \
  -H "X-API-Key: $SWIFTARIUS_KEY" \
  -H "Idempotency-Key: order-58213" \
  -H "Content-Type: application/json" \
  -d '{
    "uetr": "cf935c67-a3ac-4d58-b2fc-bf2267a14ecd",
    "amount": "12500.00",
    "currency": "USD",
    "value_date": "2026-10-27"
  }'

Payments

Your payment register: statuses, history, passport and export.

List payments GET /v1/payments

Newest first.

Authentication: X-API-Key header.

Parameters

limit
query · integer From 1 to 1000. Default: 100.

Response 200

JSON array of Payment objects:

uetr required
string Example: cf935c67-a3ac-4d58-b2fc-bf2267a14ecd.
amount
string or null
currency
string or null
value_date
string or null
created_at required
number Unix time.
last_checked_at
number or null
summary required
Summary

Errors

  • 401 Unauthorized
  • 403 Forbidden
  • 422 Validation Error
  • 429 Too Many Requests

Error bodies are {"detail": "<code>"}; the codes are listed under Errors. A 422 response lists the fields that failed validation.

Example

GET /v1/payments

curl "https://api.swiftarius.com/v1/payments?limit=100" \
  -H "X-API-Key: $SWIFTARIUS_KEY"

Payment with status history GET /v1/payments/{uetr}

Authentication: X-API-Key header.

Parameters

uetr required
path · string (UUID v4)

Response 200

JSON object PaymentDetail:

payment required
Payment
events required
array of Event

Errors

  • 401 Unauthorized
  • 403 Forbidden
  • 404 Not Found
  • 422 Validation Error
  • 429 Too Many Requests

Error bodies are {"detail": "<code>"}; the codes are listed under Errors. A 422 response lists the fields that failed validation.

Example

GET /v1/payments/{uetr}

curl https://api.swiftarius.com/v1/payments/cf935c67-a3ac-4d58-b2fc-bf2267a14ecd \
  -H "X-API-Key: $SWIFTARIUS_KEY"

Export payments to Excel GET /v1/export

Up to 1,000 payments with statuses, as an .xlsx file.

Authentication: X-API-Key header.

Response 200

Excel workbook. Content type application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.

Errors

  • 401 Unauthorized
  • 403 Forbidden
  • 429 Too Many Requests

Error bodies are {"detail": "<code>"}; the codes are listed under Errors. A 422 response lists the fields that failed validation.

Example

GET /v1/export

curl https://api.swiftarius.com/v1/export \
  -H "X-API-Key: $SWIFTARIUS_KEY" \
  -o payments.xlsx

Delivery times by destination GET /v1/corridors

How long your own payments took, grouped by destination.

Authentication: X-API-Key header.

Response 200

JSON array of Corridor objects:

key required
string
label required
string Destination of the payments in this group.
n required
integer Payments found.
completed required
integer
rejected required
integer
in_flight required
integer
stuck required
integer Payments without a status change for too long.
timed required
integer Payments with a known duration.
p50_s required
number or null Median duration, seconds.
p90_s required
number or null
min_s required
number or null
max_s required
number or null

Errors

  • 401 Unauthorized
  • 403 Forbidden
  • 429 Too Many Requests

Error bodies are {"detail": "<code>"}; the codes are listed under Errors. A 422 response lists the fields that failed validation.

Example

GET /v1/corridors

curl https://api.swiftarius.com/v1/corridors \
  -H "X-API-Key: $SWIFTARIUS_KEY"

Payment passport GET /v1/payments/{uetr}/passport

Everything known about the payment in one document, what remains unknown, and a ready status request to send to your bank.

Authentication: X-API-Key header.

Parameters

uetr required
path · string (UUID v4)

Response 200

JSON object Passport:

uetr required
string
status_code required
string or null
status_human required
string
user_reported required
object Details you provided: amount, currency, value date.
tracker_metadata required
object Details reported by a bank.
unverified_metadata required
object
chronology required
array of object Bank reports and checks in time order.
unknowns required
array of string What the reports do not establish.
markdown required
string The whole passport as Markdown.
letters required
object Ready status request to the bank: in the language of the request and in English.
letters_en required
string
disclaimer required
string
lang required
string

Errors

  • 401 Unauthorized
  • 403 Forbidden
  • 404 Not Found
  • 422 Validation Error
  • 429 Too Many Requests

Error bodies are {"detail": "<code>"}; the codes are listed under Errors. A 422 response lists the fields that failed validation.

Example

GET /v1/payments/{uetr}/passport

curl https://api.swiftarius.com/v1/payments/cf935c67-a3ac-4d58-b2fc-bf2267a14ecd/passport \
  -H "X-API-Key: $SWIFTARIUS_KEY"

Cases

Follow-up work on a payment: owner, bank reference, next action.

Open or update a case PUT /v1/payments/{uetr}/case

Authentication: X-API-Key header.

Parameters

uetr required
path · string (UUID v4)

Request body

JSON object CaseInput, required.

owner
string Who handles the case. Up to 120 characters.
status
string One of: open, waiting_bank, waiting_documents, waiting_recipient, closed. Default: open.
next_action_at
number or null Next follow-up, Unix time. At least 0.
reference
string Your or the bank's case reference. Up to 160 characters.
note
string Up to 4000 characters.
closed_reason
string Required when status is closed. Up to 1000 characters.

Response 200

JSON object Case:

uetr required
string
owner required
string
status required
string One of: open, waiting_bank, waiting_documents, waiting_recipient, closed.
next_action_at required
number or null Unix time.
reference required
string Your or the bank's case reference.
note required
string
closed_reason required
string
created_at required
number
updated_at required
number
overdue required
boolean

Errors

  • 401 Unauthorized
  • 403 Forbidden
  • 404 Not Found
  • 422 Validation Error
  • 429 Too Many Requests

Error bodies are {"detail": "<code>"}; the codes are listed under Errors. A 422 response lists the fields that failed validation.

Example

PUT /v1/payments/{uetr}/case

curl -X PUT https://api.swiftarius.com/v1/payments/cf935c67-a3ac-4d58-b2fc-bf2267a14ecd/case \
  -H "X-API-Key: $SWIFTARIUS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "owner": "Treasury desk",
    "status": "waiting_documents",
    "reference": "BANK-CASE-1042",
    "note": "The bank asked for the invoice"
  }'

List cases GET /v1/cases

Overdue first, closed last.

Authentication: X-API-Key header.

Response 200

JSON array of Case objects:

uetr required
string
owner required
string
status required
string One of: open, waiting_bank, waiting_documents, waiting_recipient, closed.
next_action_at required
number or null Unix time.
reference required
string Your or the bank's case reference.
note required
string
closed_reason required
string
created_at required
number
updated_at required
number
overdue required
boolean

Errors

  • 401 Unauthorized
  • 403 Forbidden
  • 429 Too Many Requests

Error bodies are {"detail": "<code>"}; the codes are listed under Errors. A 422 response lists the fields that failed validation.

Example

GET /v1/cases

curl https://api.swiftarius.com/v1/cases \
  -H "X-API-Key: $SWIFTARIUS_KEY"

Sharing

Read-only status cards for counterparties.

Create a status card link POST /v1/payments/{uetr}/shares

A read-only page for your counterparty in their language. It shows the status, never amounts or your account.

Authentication: X-API-Key header.

Parameters

uetr required
path · string (UUID v4)

Request body

JSON object ShareInput, required.

ttl_seconds
integer Link lifetime: 60 seconds to 30 days. From 60 to 2592000. Default: 86400.

Response 200

JSON object Share:

token required
string Needed to revoke the link.
expires_at required
number Unix time.
url required
string Status card for your counterparty. Opens without login and shows no amounts.

Errors

  • 401 Unauthorized
  • 403 Forbidden
  • 404 Not Found
  • 422 Validation Error
  • 429 Too Many Requests

Error bodies are {"detail": "<code>"}; the codes are listed under Errors. A 422 response lists the fields that failed validation.

Example

POST /v1/payments/{uetr}/shares

curl https://api.swiftarius.com/v1/payments/cf935c67-a3ac-4d58-b2fc-bf2267a14ecd/shares \
  -H "X-API-Key: $SWIFTARIUS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ttl_seconds": 604800
  }'

Revoke a status card link DELETE /v1/shares/{token}

Authentication: X-API-Key header.

Parameters

token required
path · string Up to 128 characters.

Response 200

JSON object Revoked:

revoked required
true

Errors

  • 401 Unauthorized
  • 403 Forbidden
  • 404 Not Found
  • 422 Validation Error
  • 429 Too Many Requests

Error bodies are {"detail": "<code>"}; the codes are listed under Errors. A 422 response lists the fields that failed validation.

Example

DELETE /v1/shares/{token}

curl -X DELETE "https://api.swiftarius.com/v1/shares/$SHARE_TOKEN" \
  -H "X-API-Key: $SWIFTARIUS_KEY"

Data types

Objects that appear inside responses or as error bodies. Required fields are marked.

CheckResult

source required
string Reporting channel.
outcome required
string One of: found, not_found, error, skipped.
events required
array of Event

Error

detail required
string Machine-readable error code. Example: invalid_api_key.

Event

source required
string Reporting channel.
status_raw
string or null
gpi_code
string or null Example: ACSP.
reason_code
string or null Example: G000.
reporting_bank
string or null
bank_time
string or null Time reported by the bank, ISO 8601.
amount
string or null
currency
string or null
first_seen_at
number or null When SWIFTarius first saw the event, Unix time.

HTTPValidationError

detail
array of ValidationError

Payment

uetr required
string Example: cf935c67-a3ac-4d58-b2fc-bf2267a14ecd.
amount
string or null
currency
string or null
value_date
string or null
created_at required
number Unix time.
last_checked_at
number or null
summary required
Summary

Summary

status_code required
string or null ISO 20022 status: ACCC, ACSC, ACSP, ACTC, ACWC, ACWP, PDNG, RJCT, CANC. Null if not found. Example: ACSP.
status_human required
string Status in plain words, in the language of the request. Example: in transit: accepted for processing.
status_raw
string or null Status text as reported by the bank.
last_bank
string or null Bank that reported the latest status, when known.
last_bank_time
string or null Time of the latest status, ISO 8601.
initiated_at
string or null When the payment was initiated, ISO 8601, when known.
last_move_at
string or null Latest change of status, ISO 8601.
duration_s
number or null Seconds from initiation to the final status, or until now.
stale_s
number or null Seconds without a status change while not final.
final required
boolean True for ACCC, RJCT and CANC.
events_total required
integer

ValidationError

loc required
array of string or integer
msg required
string
type required
string
input
any
ctx
object

Interactive console and OpenAPI file

This page is generated from the same OpenAPI 3.1.0 definition the API publishes. To browse it interactively, open the interactive API console; to generate a client, download openapi.json.

For coding assistants, llms.txt lists the API reference, the OpenAPI file and the guides on this site.

First check free

Where is your payment now?

Send the UETR to @swiftarius_bot. SWIFTarius shows what banks report about your payment in plain words, usually in about half a minute. No sign-up and no bank login.

Check a payment in Telegram