Sign in
Transfers

Request transfer cancellation

Cancel a transfer that has not received funds. The transfer becomes CANCELLED after the request is processed. If funds have already arrived or started moving, the transfer moves to IN_REVIEW while our operations team handles the unwind. Completed, failed, reversed, or already cancelled transfers cannot be cancelled.

post/v1/transfers/{id}/cancel

Path parameters

idstring required

Headers

X-API-Keystring

API key

Request body

reasonstring

Optional reason for cancellation. This will be stored in the transfer metadata.

Example request

{
  "reason": "Customer requested cancellation"
}

Response

Cancellation accepted. The response status is CANCELLED when terminal, IN_REVIEW when funds require an unwind, or the current non-terminal status while cancellation processing completes.

idstring required

Transfer ID (tfr_xxx)

organizationIdstring required

Organization ID

clientReferenceIdstring nullable

Client's internal reference ID

sourceCustomerIdstring required

Source customer ID

counterpartyIdstring nullable

Counterparty ID for third-party recipient transfers

flow'CRYPTO_TO_CRYPTO' | 'CRYPTO_TO_FIAT' | 'FIAT_TO_CRYPTO' | 'FIAT_TO_FIAT' | 'FIAT_TO_CRYPTO_TO_FIAT' | 'FX' | 'INTERNAL' | 'FEE_CRYPTO' | 'REFUND_CRYPTO' | 'REFUND_FIAT' required

Transfer flow type describing the asset conversion

status'DRAFT' | 'PENDING_AUTHORIZATION' | 'IN_REVIEW' | 'PENDING' | 'PROCESSING' | 'COMPLETED' | 'FAILED' | 'CANCELLED' | 'REVERSED' required

Transfer status

quoteIdstring nullable

Quote ID if transfer was created from a quote

exchangeRatestring nullable

Exchange rate applied to the currency conversion, inclusive of all fees. Expressed on minor-unit amounts: destinationAmount = sourceAmount * exchangeRate. Populated for FX trades.

developerFeeFixedstring nullable

Fixed developer fee in minor units of source currency. Prefer the developerFee object, which also carries the collected amount and payout hash.

developerFeePercentnumber nullable

Variable developer fee as decimal percentage (e.g., 0.005 = 0.5%). Prefer the developerFee object, which also carries the collected amount and payout hash.

createdAtstring date-time required

Transfer creation date

updatedAtstring date-time required

Transfer last update date

currentLegIndexnumber nullable

Index of the current active leg in the legs array (0-indexed). Null if all legs are done.

fundingNeededboolean required

Whether the transfer is waiting for the customer to send funds (deposit)

isThirdPartyboolean

Whether this is a third-party payment (destination account belongs to someone other than the customer)

remarksstring nullable

Free-form remarks or notes about the transfer

internalRemarksstring nullable

Internal remarks visible only within your organization. Never forwarded to payment rails or counterparties.

uetrstring nullable

SWIFT UETR (Universal End-to-End Transaction Reference)

imadstring nullable

Wire IMAD (Input Message Accountability Data)

omadstring nullable

Wire OMAD (Output Message Accountability Data)

achTraceNumberstring nullable

ACH trace number from the payment network

txHashstring nullable

Blockchain transaction hash

systemRemarkstring nullable

System-generated status note with important transfer context for the customer

metadataobject

Additional non-contractual transfer metadata for UI display

estimatedSettlementAtstring date-time nullable

Estimated time the recipient will receive funds. Best-effort projection — fiat rails account for bank cutoff times, weekends, and US Federal Reserve holidays; crypto conversions project from recently observed processing times for the route. Not a guarantee.

nextCutoffAtstring date-time nullable

Next time the customer can submit and still settle same business day. Past this time, transfers settle next business day.

cutoffTimezonestring nullable

IANA timezone for the cutoff time, e.g. "America/New_York".

Example response

{
  "id": "tfr_1234567890abcdef",
  "organizationId": "org_abc123",
  "clientReferenceId": "order_abc123",
  "sourceCustomerId": "cus_abc123",
  "counterpartyId": "cp_abc123",
  "flow": "CRYPTO_TO_FIAT",
  "status": "COMPLETED",
  "source": {
    "currency": "usd",
    "fundingCurrency": "usdc",
    "paymentRail": "ACH",
    "direction": "CREDIT",
    "accountId": "vba_abc123",
    "accountType": "VIRTUAL_BANK",
    "externalAccountId": "ext_bank_456",
    "fromAddress": "0x1234567890abcdef1234567890abcdef12345678",
    "refundAccountId": "inw_abc123",
    "accountName": "Acme Corporation"
  },
  "destination": {
    "currency": "USDC",
    "paymentRail": "ETHEREUM",
    "accountId": "vwa_def456",
    "accountType": "EXTERNAL_BANK",
    "externalAccountId": "ext_bank_789",
    "toAddress": "0x1234567890abcdef1234567890abcdef12345678",
    "accountName": "Acme Corporation",
    "wireMessage": "Payment for invoice INV-2026-001",
    "achReference": "ORDER123",
    "swiftReference": "Payment for invoice INV-2026-001",
    "rtpReference": "Payment for invoice INV-2026-001",
    "payoutReference": "INV2026"
  },
  "sourceAmount": {
    "currency": "USD",
    "exponent": 2,
    "value": "12345",
    "displayValue": "123.45"
  },
  "destinationAmount": {
    "currency": "USD",
    "exponent": 2,
    "value": "12345",
    "displayValue": "123.45"
  },
  "refund": {
    "status": "COMPLETED",
    "reason": "Fees exceed deposit amount",
    "amount": {
      "currency": "USD",
      "exponent": 2,
      "value": "12345",
      "displayValue": "123.45"
    },
    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "txHash": "0x1234567890abcdef..."
  },
  "quoteId": "quote_abc123",
  "exchangeRate": "0.99985",
  "developerFeeFixed": "100",
  "developerFeePercent": 0.005,
  "developerFee": {
    "amount": {
      "currency": "USD",
      "exponent": 2,
      "value": "12345",
      "displayValue": "123.45"
    },
    "fixed": "100",
    "percent": 0.005,
    "txHash": "0x1234567890abcdef..."
  },
  "depositInstructions": {
    "type": "crypto",
    "paymentRail": "ETHEREUM",
    "toAddress": "0x1234567890abcdef1234567890abcdef12345678",
    "amount": {
      "currency": "USD",
      "exponent": 2,
      "value": "12345",
      "displayValue": "123.45"
    },
    "accountId": "acc_abc123"
  },
  "createdAt": "2026-09-15T10:00:00.000Z",
  "updatedAt": "2026-09-15T10:00:00.000Z",
  "legs": [
    {
      "id": "tleg_abc123",
      "type": "DEPOSIT_CRYPTO",
      "inputCurrency": "USDC",
      "outputCurrency": "USD",
      "inputRail": "ETHEREUM",
      "outputRail": "ACH",
      "status": "PENDING",
      "uetr": "9b6f37f2-21f0-4b2b-b03c-1893364782ce",
      "imad": "20260309EREBBANK000002",
      "omad": "20260309MMQFMP0B012345",
      "achTraceNumber": "021000021234567",
      "txHash": "0x1234567890abcdef...",
      "developerFee": {
        "currency": "USD",
        "exponent": 2,
        "value": "12345",
        "displayValue": "123.45"
      },
      "feeTxHash": "0x1234567890abcdef..."
    }
  ],
  "remarks": "Partial payment - remaining balance to be paid next month",
  "uetr": "9b6f37f2-21f0-4b2b-b03c-1893364782ce",
  "imad": "20260309EREBBANK000002",
  "omad": "20260309MMQFMP0B012345",
  "achTraceNumber": "021000021234567",
  "txHash": "0x1234567890abcdef...",
  "systemRemark": "Tracking is unavailable for this SWIFT transfer. We will auto-complete it after 24 hours and mark it with an asterisk because settlement is assumed rather than confirmed.",
  "metadata": {
    "swiftRouting": {
      "source": "GPI_ROUTE",
      "senderBic": "CHASUS33",
      "receiverBic": "CLRBGB22",
      "checkedAt": "2026-05-10T16:34:42.597Z",
      "steps": [
        {
          "label": "Sender bank",
          "bic": "CHASUS33",
          "bankName": "JP Morgan Chase",
          "status": "Confirmed Active"
        }
      ]
    }
  },
  "estimatedSettlementAt": "2026-05-26T13:00:00.000Z",
  "nextCutoffAt": "2026-05-19T19:00:00.000Z",
  "cutoffTimezone": "America/New_York",
  "counterparty": {
    "id": "cp_abc123",
    "name": "Jane Doe",
    "beneficiaryType": "INDIVIDUAL",
    "address": {
      "addressLine1": "123 Main Street",
      "addressLine2": "Apt 4B",
      "city": "San Francisco",
      "state": "CA",
      "postalCode": "94102",
      "country": "US",
      "transliterated": {
        "addressLine1": "123 Main Street",
        "addressLine2": "Apt 4B",
        "city": "Beijing",
        "state": "Hebei"
      }
    }
  }
}

Changes

No recorded changes to this endpoint across all 1 revision of this API.