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.

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)
      • 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
    Description

    The amount for the transfer.

  • Name
    customer
    Type
    string
    Required
    Description

    The id of the customer associated with the transfer.

  • Name
    source
    Type
    object
    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
    Description

    The destination for the transfer.

    • Name
      id
      Type
      string
      Required
      Description

      The id of the destination bankAccount or wallet.

    • Name
      currency
      Type
      enum
      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
      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"
}

Was this page helpful?