Transfers

A transfer is the movements of funds between financial accounts, ie: wallets and bank accounts. It contains a source and destination.

Limited Access

Transfers interacts closely with fiat rails and BSA/AML and are only avaliable to merchants that undergo KYB and enter a service agreement.

Endpoints

Usage

The instructions field of the transfer object describes what funds need to be sent to which destination in order for the transfer to be fulfilled.

On creating an off-ramp transfer, you may use the depositInstructions to build and deliver a transaction to your customers on the source network of transfer.

Transfers that are funded will be executed on next transfer execution cycle.

Lifecycle

Transfers are initialized with a status of pending and move into funded when the funds are sent to the address detailed in the depositInstructions field.

The Transfer object

Properties

Name
id
Type
string
Description
A unique identifier for the object.
Name
number
Type
number
Description
A number that tracks the chronological order of the customer's transfers, automatically incremented by Sphere with each new transfer creation.
Name
status
Type
string
Description
The transfer status. One of pending, funded, processing, succeeded, failed, cancelled, or refunded.
Name
type
Type
string
Description
The transfer type. Either onRamp or offRamp.
Name
thirdParty
Type
boolean
Description
Whether the transfer is being sent on behalf of someone else.
Name
thirdPartyMessage
Type
string
Description
A detailed reason or business case for this third party transfer. Maximum length of 500 characters.
Name
meta
Type
object
Description
Set of key-value pairs (JSON) that you can attach to a transfer object which can be useful for storing additional information about the object.
Name
lookupKey
Type
string
Description
The lookup key of a transfer. A lookup key allows you to list all resources associated with a given key.
Name
amount
Type
string
Description
The amount for the transfer, how much the customer is sending to the funding bank account or wallet.
Name
finalAmount
Type
string
Description
The amount for the payour after accounting for fees, how much the customer is receiving on their bank account or wallet.
Name
source
Type
object
Description
The source for the transfer, what the customer will be sending initial funds from. A bankAccount for onRamp transfers or a wallet for offRamp transfers.

Name
id
Type
string
Description
The id of the bankAccount or wallet.

Name
currency
Type
enum
Description
The currency of the bankAccount or wallet.

For an onRamp, it is either usd or eur.

For an offRamp, it is either usdc or usdt.

Name
network
Type
enum
Description
The network of the bankAccount or wallet.

For an onRamp, it is one of achPush, achSameDay, wire, or sepa.

For an offRamp, it is one of sol, ethereum, or base.
Name
funding
Type
object
Description
The funding account for the transfer, what the customer will be sending funds to. Shares the same id type, currency, and network as the source field. The only difference is the id itself.

Name
id
Type
string
Description
The id of the funding bankAccount or wallet.

Name
currency
Type
enum
Description
The source currency.

Name
network
Type
enum
Description
The source network.
Name
destination
Type
object
Description
The destination for the transfer, what the customer will be receiving funds on. A wallet for onRamp transfers or a bankAccount for offRamp transfers.

Name
id
Type
string
Description
The id of the bankAccount or wallet.

Name
currency
Type
enum
Description
The currency of the bankAccount or wallet.

For an onRamp, it is either usdc or usdt.

For an offRamp, it is either usd or eur.

Name
network
Type
enum
Description
The network of the bankAccount or wallet.

For an onRamp, it is one of sol, ethereum, or base.

For an offRamp, it is one of achSameDay, ach, wire, or sepa.
Name
instructions
Type
object
Description
The instructions for the source deposit, details of how the customer should send the funds to the funding bank account or wallet.

Name
memo
Type
string
Description
The message that must be included in the customer's wire memo/message.

Name
human
Type
string
Description
A human readable message describing the transfer instructions.

Name
machine
Type
string
Description
The machine message.

Name
imad
Type
string
Description
The IMAD of an incoming wire transfer.

Name
omad
Type
string
Description
The OMAD of an incomding wire transfer.

Name
resource
Type
object
Description
Either the funding bankAccount or wallet object associated with the transfer. A bankAccount for onRamp transfers or a wallet for offRamp transfers.

Bank Account (For on-ramps)

Refer to the Bank Account object for more details.

Wallet (For off-ramps)

Refer to the Wallet object for more details.
Name
customer
Type
string
Description
The id of the customer associated with the transfer.
Name
updated
Type
string
Description
Datetime at which the transfer was last updated.
Name
created
Type
string
Description
Datetime at which the account was created.

Transfer Object

{
  "id": "transfer_c7372579861745a8a7623a888633d2fa",
  "type": "onRamp",
  "status": "pending",
  "meta": {},
  "amount": "10",
  "source": {
    "id": "bankAccount_68f570bab5544c1d92c84189c8de52b3",
    "currency": "usd",
    "network": "wire"
  },
  "funding": {
    "id": "bankAccount_6f23b8bc1f2f481790c3c571e145113e",
    "currency": "usd",
    "network": "wire"
  },
  "destination": {
    "id": "wallet_0425b010af7a4206900e6f44f527e20a",
    "currency": "usdc",
    "network": "sol"
  },
  "instructions": {
    "memo": "BVI7EF089F7AC34FF27B",
    "human": "Send 10 usd via the wire network from bankAccount_68f570bab5544c1d92c84189c8de52b3 with an account number of ********9942 to bankAccount_6f23b8bc1f2f481790c3c571e145113e with an account number of ********. After sending usd, the transfer will be funded and 10 of usdc will be on-ramped to wallet_0425b010af7a4206900e6f44f527e20a with an address of DuUf1ThgCQcwrrW6X6dw5MTwsHcTrxSg1rMhSSbvL1Zr on the sol network.",
    "machine": "",
    "resource": {
      "id": "bankAccount_6f23b8bc1f2f481790c3c571e145113e",
      "bankName": "",
      "accountHolderName": "",
      "accountName": "",
      "accountNumber": "",
      "customer": "",
      "last4": "",
      "routingNumber": "",
      "bic": "",
      "iban": "",
      "meta": {},
      "currency": "usd",
      "walletBankAccounts": [],
      "updated": "2023-11-05T14:23:33.588Z",
      "created": "2023-11-05T14:23:33.588Z"
    }
  },
  "customer": "customer_653318f146c84adc91fa287f0c6fc2c2",
  "created": "2023-11-06T13:43:03.878Z",
  "updated": "2023-11-06T13:43:03.878Z"
}

POST/v1/transfer

Create a transfer

This endpoint allows you to create a new transfer.

Parameters

Name
amount
Type
string
Required
Required
Description
The amount for the transfer.
Name
customer
Type
string
Required
Required
Description
The id of the customer associated with the transfer.
Name
source
Type
object
Required
Required
Description
The source for the transfer.
- Name
  id
  Type
  string
  Description
  The id of the source bankAccount or wallet.
- Name
  currency
  Type
  enum
  Description
  The currency of the source bankAccount or wallet.
  
  For an onRamp, it is either usd or eur.
  
  For an offRamp, it is either usdc or usdt.
- Name
  network
  Type
  enum
  Description
  The network of the source bankAccount or wallet.
  
  For an onRamp, it is one of achPush, achSameDay, wire, or sepa.
  
  For an offRamp, it is one of sol, ethereum, or base.
- Name
  thirdParty
  Type
  boolean
  Description
  Whether the destination is being sent on behalf of someone else. Defaults to false.
- Name
  thirdPartyMessage
  Type
  string
  Description
  A detailed reason or business case for this third party transfer. Maximum length of 500 characters.
Name
destination
Type
object
Required
Required
Description
The destination for the transfer.
- Name
  id
  Type
  string
  Required
  Required
  Description
  The id of the destination bankAccount or wallet.
- Name
  currency
  Type
  enum
  Required
  Required
  Description
  The currency of the destination bankAccount or wallet.
  
  For an onRamp, it is either usdc or usdt.
  
  For an offRamp, it is either usd or eur.
- Name
  network
  Type
  enum
  Required
  Required
  Description
  The network of the destination bankAccount or wallet.
  
  For an onRamp, it is one of sol, ethereum, or base.
  
  For an offRamp, it is one of achSameDay, ach, wire, or sepa.
- Name
  wireMessage
  Type
  string
  Description
  The wire message that is used when initiating a wire transfer to the bank account. Can at most be 3 lines long, separated by \n, each with a maximum length of 35 characters.
Name
lookupKey
Type
string
Description
The lookup key of a transfer. A lookup key allows you to list all resources associated with a given key.
Name
meta
Type
object
Description
Set of key-value pairs (JSON) for arbitrary usage. Used to save structured information about the object to reference elsewhere. Think of it as general purpose storage space.

Request

POST

/v1/transfer

curl https://api.spherepay.co/v1/transfer \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "10.00",
    "customer": "customer_f5bd32a916584675b739b8e2301f1480",
    "source": {
      "id": "bankAccount_3d67e78e590c4270bdebee7fc6d5075c",
      "currency": "usd",
      "network": "wire"
    },
    "destination": {
      "id": "wallet_a25c82a765d0499a861cff1b3e8812f2",
      "currency": "usdc",
      "network": "sol"
    }
  }'

Response

{
  "ok": true,
  "object": "object",
  "statusCode": 200,
  "error": null,
  "message": "success",
  "data": {
    "transfer": {
      "id": "transfer_26321135c2a34f4f8d95d78ea76eff0a",
      "number": 18,
      "type": "onRamp",
      "status": "pending",
      "meta": {},
      "lookupKey": null,
      "amount": "10.00",
      "finalAmount": null,
      "source": {
        "id": "bankAccount_3d67e78e590c4270bdebee7fc6d5075c",
        "currency": "usd",
        "network": "wire"
      },
      "funding": {
        "id": "bankAccount_c8ec5bdca412485ea50b7f5d1494e4a1",
        "currency": "usd",
        "network": "wire"
      },
      "destination": {
        "id": "wallet_a25c82a765d0499a861cff1b3e8812f2",
        "currency": "usdc",
        "network": "sol"
      },
      "instructions": {
        "memo": "BRGSFNHQBH3RKPEQDMD2",
        "imad": null,
        "omad": null,
        "human": "Send 10 usd via the wire network from bankAccount_3d67e78e590c4270bdebee7fc6d5075c with an account number of ********5771 to bankAccount_c8ec5bdca412485ea50b7f5d1494e4a1 with an account number of ********2035. After sending usd, the transfer will be funded and 10 of usdc will be on-ramped to wallet_a25c82a765d0499a861cff1b3e8812f2 with an address of 7hPhaUpydpvm8wtiS3k4LPZKUmivQRs7YQmpE1hFshHx on the sol network.",
        "machine": "",
        "resource": {
          "id": "bankAccount_c8ec5bdca412485ea50b7f5d1494e4a1",
          "status": "active",
          "bankName": "Lead Bank",
          "accountHolderName": "Bridge Ventures Inc",
          "accountName": "Bridge Ventures Inc",
          "accountNumber": "1234567890",
          "customer": "customer_f5bd32a916584675b739b8e2301f1480",
          "last4": "2035",
          "routingNumber": "0987654321",
          "bic": null,
          "iban": null,
          "bankAddressString": "1801 Main St. Kansas City MO 64108, Kansas, United States of America",
          "meta": {},
          "lookupKey": null,
          "currency": "usd",
          "walletBankAccounts": [],
          "mock": false,
          "accountType": "checking",
          "updated": "2024-05-02T20:19:33.531Z",
          "created": "2024-05-02T20:19:33.531Z",
          "deleted": null
        }
      },
      "mock": false,
      "customer": "customer_f5bd32a916584675b739b8e2301f1480",
      "updated": "2024-08-13T13:57:18.570Z",
      "created": "2024-08-13T13:57:18.570Z"
    }
  },
  "ts": "2024-08-13T13:57:18.580Z",
  "request": "request_0abb672dad5446d3b9f016ec77dd13b0"
}

GET/v1/transfer/:id

Retrieve a transfer

This endpoint allows you to retrieve a transfer by id.

Request

GET

/v1/transfer/transfer_c7372579861745a8a7623a888633d2fa

curl https://api.spherepay.co/v1/transfer/transfer_26321135c2a34f4f8d95d78ea76eff0a \
  -H "Authorization: Bearer {token}"

Response

{
  "ok": true,
  "object": "object",
  "statusCode": 200,
  "error": null,
  "message": "success",
  "data": {
    "transfer": {
      "id": "transfer_26321135c2a34f4f8d95d78ea76eff0a",
      "number": 18,
      "type": "onRamp",
      "status": "pending",
      "meta": {},
      "lookupKey": null,
      "amount": "10.00",
      "finalAmount": "10.00",
      "source": {
        "id": "bankAccount_3d67e78e590c4270bdebee7fc6d5075c",
        "currency": "usd",
        "network": "wire"
      },
      "funding": {
        "id": "bankAccount_c8ec5bdca412485ea50b7f5d1494e4a1",
        "currency": "usd",
        "network": "wire"
      },
      "destination": {
        "id": "wallet_a25c82a765d0499a861cff1b3e8812f2",
        "currency": "usdc",
        "network": "sol"
      },
      "instructions": {
        "memo": "BRGSFNHQBH3RKPEQDMD2",
        "imad": null,
        "omad": null,
        "human": "Send 10 usd via the wire network from bankAccount_3d67e78e590c4270bdebee7fc6d5075c with an account number of ********5771 to bankAccount_c8ec5bdca412485ea50b7f5d1494e4a1 with an account number of ********2035. After sending usd, the transfer will be funded and 10 of usdc will be on-ramped to wallet_a25c82a765d0499a861cff1b3e8812f2 with an address of 7hPhaUpydpvm8wtiS3k4LPZKUmivQRs7YQmpE1hFshHx on the sol network.",
        "machine": "",
        "resource": {
          "id": "bankAccount_c8ec5bdca412485ea50b7f5d1494e4a1",
          "status": "active",
          "bankName": "Lead Bank",
          "accountHolderName": "Bridge Ventures Inc",
          "accountName": "Bridge Ventures Inc",
          "accountNumber": "1234567890",
          "customer": null,
          "last4": "2035",
          "routingNumber": "0987654321",
          "bic": null,
          "iban": null,
          "bankAddressString": "1801 Main St. Kansas City MO 64108, Kansas, United States of America",
          "meta": {},
          "lookupKey": null,
          "currency": "usd",
          "walletBankAccounts": [],
          "mock": false,
          "accountType": "checking",
          "updated": "2024-05-02T20:19:33.531Z",
          "created": "2024-05-02T20:19:33.531Z",
          "deleted": null
        }
      },
      "mock": false,
      "customer": "customer_f5bd32a916584675b739b8e2301f1480",
      "updated": "2024-08-13T14:00:00.852Z",
      "created": "2024-08-13T13:57:18.570Z"
    }
  },
  "ts": "2024-08-13T15:01:11.323Z",
  "request": "request_0fe03b2bb5fa4a199c89418e7242b887"
}

GET/v1/transfer

List transfers

This endpoint allows you to retrieve a paginated list of all your contacts. By default, a maximum of ten contacts are shown per page.

Optional attributes

Name
search
Type
string
Description
Limit the number of contacts returned.
Name
sort
Type
string
Description
Limit the number of contacts returned.
Name
direction
Type
string
Description
Limit the number of contacts returned. Either ASC or DESC.
Name
limit
Type
integer
Description
Limit the number of contacts returned.
Name
customer
Type
string
Description
Limit the number of contacts returned.

Request

GET

/v1/contacts

curl https://api.spherepay.co/v1/transfer \
  -H "Authorization: Bearer {token}"

Response

{
  "ok": true,
  "object": "object",
  "statusCode": 200,
  "error": null,
  "message": "success",
  "data": {
    "transfers": [
      {
        "id": "transfer_0d649e1967a94c829fe19dfafeb8d0f2",
        "number": 16,
        "type": "onRamp",
        "status": "cancelled",
        "meta": {},
        "lookupKey": null,
        "amount": "3.00",
        "finalAmount": null,
        "source": {
          "id": "bankAccount_3d67e78e590c4270bdebee7fc6d5075c",
          "currency": "usd",
          "network": "wire"
        },
        "funding": {
          "id": "bankAccount_c8ec5bdca412485ea50b7f5d1494e4a1",
          "currency": "usd",
          "network": "wire"
        },
        "destination": {
          "id": "wallet_a25c82a765d0499a861cff1b3e8812f2",
          "currency": "usdc",
          "network": "sol"
        },
        "instructions": {
          "memo": "BRGATRRUVVAW3XRCY6QW",
          "imad": null,
          "omad": null,
          "human": "Send 3 usd via the wire network from bankAccount_3d67e78e590c4270bdebee7fc6d5075c with an account number of ********5771 to bankAccount_c8ec5bdca412485ea50b7f5d1494e4a1 with an account number of ********2035. After sending usd, the transfer will be funded and 3 of usdc will be on-ramped to wallet_a25c82a765d0499a861cff1b3e8812f2 with an address of 7hPhaUpydpvm8wtiS3k4LPZKUmivQRs7YQmpE1hFshHx on the sol network.",
          "machine": "",
          "resource": {
            "id": "bankAccount_c8ec5bdca412485ea50b7f5d1494e4a1",
            "status": "active",
            "bankName": "Lead Bank",
            "accountHolderName": "Bridge Ventures Inc",
            "accountName": "Bridge Ventures Inc",
            "accountNumber": "1234567890",
            "customer": null,
            "last4": "2035",
            "routingNumber": "0987654321",
            "bic": null,
            "iban": null,
            "bankAddressString": "1801 Main St. Kansas City MO 64108, Kansas, United States of America",
            "meta": {},
            "lookupKey": null,
            "currency": "usd",
            "walletBankAccounts": [],
            "mock": false,
            "accountType": "checking",
            "updated": "2024-05-02T20:19:33.531Z",
            "created": "2024-05-02T20:19:33.531Z",
            "deleted": null
          }
        },
        "mock": false,
        "customer": "customer_f5bd32a916584675b739b8e2301f1480",
        "updated": "2024-08-05T01:40:49.115Z",
        "created": "2024-08-05T01:40:32.153Z"
      },
      {
        "id": "transfer_85c539cdf9bf4ebaa4c216cfdf176ab1",
        // ...
      }
    ]
  },
  "ts": "2024-08-05T05:07:41.411Z",
  "request": "request_44bb2963303b44429d1e30cac2e8382b"
}