Payouts

The payout object represents the actual transfer of funds between bank accounts and wallets.

Endpoints

POST

/v1/payout

GET

/v1/payout/:id

POST

/v1/payout/cancel/:id

Usage

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

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

Payouts that are funded will be executed on next payout execution cycle.

Lifecycle

Payouts 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 Payout object

Properties

Name
id
Type
string
Description
A unique identifier for the payout. Auto-generated by Sphere upon creation.
Name
number
Type
number
Description
A number that tracks the chronological order of the customer's payouts, automatically incremented by Sphere with each new payout creation.
Name
status
Type
string
Description
The payout status. One of pending, funded, processing, succeeded, failed, cancelled, or refunded.
Name
type
Type
string
Description
The payout type. Either onRamp or offRamp.
Name
thirdParty
Type
boolean
Description
Whether the payout 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 payout object which can be useful for storing additional information about the object.
Name
lookupKey
Type
string
Description
The lookup key of a payout. A lookup key allows you to list all resources associated with a given key.
Name
amount
Type
string
Description
The amount for the payout, 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 payout, what the customer will be sending initial funds from. A bankAccount for onRamp payouts or a wallet for offRamp payouts.

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 sol, ethereum, or base.

For an offRamp, it is one of achPull, achPush, wire, or sepa.
Name
funding
Type
object
Description
The funding account for the payout, 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 payout, what the customer will be receiving funds on. A wallet for onRamp payouts or a bankAccount for offRamp payouts.

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 ach, wire, or sepa.

For an offRamp, it is one of sol, ethereum, or base.
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 payout 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 payout. A bankAccount for onRamp payouts or a wallet for offRamp payouts.

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 payout.
Name
updated
Type
string
Description
Datetime at which the payout was last updated.
Name
created
Type
string
Description
Datetime at which the account was created.

Payout Object

{
  "id": "payout_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 payout 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": null,
      "last4": "",
      "routingNumber": "",
      "meta": {},
      "currency": "usd",
      "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/payout

Create a payout

This endpoint allows you to create a new payout.

Parameters

Name
amount
Type
string
Required
Required
Description
The amount for the payout.
Name
customer
Type
string
Required
Required
Description
The id of the customer associated with the payout.
Name
source
Type
object
Required
Required
Description
The source for the payout.
- 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 sol, ethereum, or base.
  
  For an offRamp, it is one of achPull, achPush, wire, or sepa.
- 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 payout.
- 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 ach, wire, or sepa.
  
  For an offRamp, it is one of sol, ethereum, or base.
- 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 payout. 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/payout

curl https://api.spherepay.co/v1/payout \
  -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": {
    "payout": {
      "id": "payout_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 payout 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": "1000682035",
          "customer": "customer_f5bd32a916584675b739b8e2301f1480",
          "last4": "2035",
          "routingNumber": "101206101",
          "bic": null,
          "iban": null,
          "bankAddressString": "1801 Main St. Kansas City MO 64108, Kansas, United States of America",
          "meta": {},
          "lookupKey": null,
          "currency": "usd",
          "provider": "bridge",
          "beneficiaryAddress": {
            "line1": "1801 Main St",
            "line2": null,
            "city": "Kansas City",
            "postalCode": "64108",
            "state": "MO",
            "country": "USA"
          },
          "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/payout/:id

Retrieve a payout

This endpoint allows you to retrieve a payout by id.

Request

GET

/v1/payout/payout_c7372579861745a8a7623a888633d2fa

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

Response

{
  "ok": true,
  "object": "object",
  "statusCode": 200,
  "error": null,
  "message": "success",
  "data": {
    "payout": {
      "id": "payout_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 payout 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": "1000682035",
          "customer": null,
          "last4": "2035",
          "routingNumber": "101206101",
          "bic": null,
          "iban": null,
          "bankAddressString": "1801 Main St. Kansas City MO 64108, Kansas, United States of America",
          "meta": {},
          "lookupKey": null,
          "currency": "usd",
          "provider": "bridge",
          "beneficiaryAddress": {
            "id": null,
            "line1": null,
            "line2": null,
            "city": null,
            "postalCode": null,
            "state": null,
            "country": null,
            "application": null
          },
          "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"
}

POST/v1/payout/cancel/:id

Cancel a payout

This endpoint allows you to cancel a payout. Cancelling a payout sets its status to cancelled and will not be processed. You are still able to fetch a cancelled payout.

Request

POST

/v1/payout/cancel/:id

curl -X POST https://api.spherepay.co/v1/payout/cancel/payout_26321135c2a34f4f8d95d78ea76eff0a \
  -H "Authorization: Bearer {token}"

Response

{
  "ok": true,
  "object": "object",
  "statusCode": 200,
  "error": null,
  "message": "success",
  "data": {
    "payout": {
      "id": "payout_26321135c2a34f4f8d95d78ea76eff0a",
      "number": 18,
      "type": "onRamp",
      "status": "cancelled",
      "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 payout 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": "U2FsdGVkX1/prAk5aKPvMvZN6pyFDTTiEm5BV6JJtDI=",
          "accountHolderName": "U2FsdGVkX1+QIgRXsMcq7HNZobT3HZEZU16z2kbaxJ7+Q4E46hRwlxE4uRLNZEo8",
          "accountName": "U2FsdGVkX1+CvXibnvtjrHsVqSZDpeLRAJwBulSt4/EsbPE/k6QleNSamJp+D/n/",
          "accountNumber": "U2FsdGVkX18uGbww4XVNluNyIYRtRozOpNUXfC/HWv0=",
          "customer": null,
          "last4": "Wv0=",
          "routingNumber": "U2FsdGVkX1/KS6BRk4dycnCw+UVQw8H5fyGxj9Rax8w=",
          "bic": null,
          "iban": null,
          "bankAddressString": "1801 Main St. Kansas City MO 64108, Kansas, United States of America",
          "meta": {},
          "lookupKey": null,
          "currency": "usd",
          "provider": "bridge",
          "beneficiaryAddress": {
            "id": null,
            "line1": null,
            "line2": null,
            "city": null,
            "postalCode": null,
            "state": null,
            "country": null,
            "application": null
          },
          "walletBankAccounts": [],
          "mock": false,
          "accountType": "U2FsdGVkX19XY01c6PEkxvHPWER7EkTJDtfalizbcPw=",
          "updated": "2024-05-02T20:19:33.531Z",
          "created": "2024-05-02T20:19:33.531Z",
          "deleted": null
        }
      },
      "mock": false,
      "customer": "customer_f5bd32a916584675b739b8e2301f1480",
      "updated": "2024-08-13T15:04:51.715Z",
      "created": "2024-08-13T13:57:18.570Z"
    }
  },
  "ts": "2024-08-13T15:04:51.725Z",
  "request": "request_1d7a7f6f3a934d76ae8daeea87e324b0"
}