Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.spherepay.co/llms.txt

Use this file to discover all available pages before exploring further.

Use this endpoint to cancel a transfer before funds have been received. Cancellation is only possible while the transfer is in pendingFunding status — once SpherePay detects an incoming deposit and the transfer moves to fundsReceived or beyond, it can no longer be canceled. If funds arrive after cancellation, SpherePay will attempt to return them and the transfer may transition to returned or pendingRefundInformation.
You cannot cancel a transfer that is in any status other than pendingFunding. Verify the transfer status with GET /v2/transfer/ before attempting cancellation.

​
Endpoint

DELETE https://api.spherepay.co/v2/transfer/{id}

​
Authentication

All requests require a Bearer token in the Authorization header. 
Authorization: Bearer <token>

​
Path parameters

​
id
string
required
The unique transfer ID, prefixed with payout_ (e.g. payout_d243ab2b1de4447d8a046d87fefe58cf).

​
Request body

This endpoint does not require a request body. 
  -H "Authorization: Bearer $SPHEREPAY_API_KEY"

​
Cancelable statuses

StatusCan cancel?
pendingFundingYes
pendingReviewNo
fundsReceivedNo
processingNo
succeededNo
failedNo
Any other terminal statusNo

​
Response fields

The response is the full transfer object reflecting the updated canceled status.
​
id
string
Unique transfer identifier.
​
type
string
Transfer direction: on_ramp or off_ramp.
​
status
string
Updated status. Will be canceled for a successful cancellation.
​
customer
string
The customer ID associated with this transfer.
​
externalId
string
Integrator-defined reference string, if one was provided at creation.
​
fees
object
Fee breakdown. Fees are not charged for canceled transfers.
​
source
object
Source identifier and type.
​
destination
object
Destination identifier, type, currency, and network.
​
depositAccount
object
Deposit instructions that were active before cancellation. Present for reference only — do not fund a canceled transfer.
​
tracking
object
Network-level tracking identifiers (empty for canceled transfers).
​
created
string
ISO 8601 timestamp of transfer creation.
​
updated
string
ISO 8601 timestamp reflecting the cancellation time.
  "id": "payout_d243ab2b1de4447d8a046d87fefe58cf",
  "externalId": "merchant_ref_123",
  "type": "on_ramp",
  "status": "canceled",
  "customer": "customer_f31121c389624d3697cbf3ea8830b7a4",
  "fees": {
    "integratorFee": {
      "fixedAmount": "0.00",
      "bpsRate": "25",
      "bpsAmount": "0.00",
      "totalAmount": "0.00",
      "currency": "usd"
    },
    "platformFee": {
      "fixedAmount": "0.00",
      "bpsRate": "10",
      "bpsAmount": "0.00",
      "totalAmount": "0.00",
      "currency": "usd"
    }
  },
  "source": {
    "id": "bankAccount_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "type": "bank_account"
  },
  "destination": {
    "id": "wallet_e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0",
    "type": "wallet",
    "currency": "usdc",
    "network": "sol",
    "amount": "0.00",
    "exchangeRate": "1.00"
  },
  "depositAccount": {
    "type": "bank_account",
    "bankDetails": {
      "bankName": "Bank of America",
      "accountHolderName": "SpherePay Inc.",
      "accountType": "checking",
      "accountNumber": "1234567890",
      "routingNumber": "026009593",
      "memo": "BBE6C7EB4A3F"
    }
  },
  "quote": null,
  "tracking": {
    "source": {},
    "destination": {}
  },
  "created": "2026-04-01T10:00:00.000Z",
  "updated": "2026-04-01T10:03:15.000Z"
}

​
What happens if funds arrive after cancellation

If a customer sends funds to the deposit account after the transfer has been canceled, SpherePay will detect the incoming deposit and attempt to return the funds. The transfer status will transition to returned once the refund is complete, or to pendingRefundInformation if additional details are needed. Monitor the transfer status by polling GET /v2/transfer/ or by listening for webhook events.

​
Error codes

StatusCodeDescription
400address/invalidThe transfer is not in a cancelable status (pendingFunding).
404resource/not-foundNo transfer exists with the given ID.
422validation/failedThe provided ID did not pass format validation.
Last modified on May 12, 2026