Payouts allow you to manage on/off-ramp payouts.
The payout
object is a convenient way to manage on/off-ramping for your customers either directly to their bank, or to another cryptocurrency wallet.
You will need to use the bankAccount
object's id
when identify where to send it to.
The fee breakdown is:
- ACH: $0.50
- ACH (return): $5.00
- Wire: $20.00
There are no setup or KYC/B fees. All stated network fees are passed at cost.
This feature is available to merchants that have completed KYB and agreed to our terms of service and policy privacy. These compliance flows are also available in our Dashboard >> Settings >> Payouts. It is currently only available for entities with US bank accounts, with additional regional support coming soon.
It is important that you abide by the various jurisdictional regulations regarding sensitive data. Sphere does not store this data on our servers and all data is encrypted. In our interactions with licensed partners, we employ secure transfer protocols subject to GLBA, BSA/AML, FTC, and state laws.
How it works
Regardless of whether the fiat flow is on-ramp or off-ramp, you will generally:
- Create a
bankAccount
for each customer. - Create a
wallet
for each customer. - Create a
payout
for each instance of on/off-ramp.
Step #1 is unnecessary for walletToWallet
off-ramp, which is currently only available on Solana.
For off-ramp, Step #3 will return a liquidationAddress
, where the wallet address used to create the payout must send their tokens to. It is recommended that you build and serve a transaction on your frontend to let your customers transfer their tokens to this address, so that you get granular feedback on the status of pending payouts.
If you would prefer not to collect customer financial data yourself (strongly recommended unless you are familiar with dealing with sensitive financial data), we suggest using Teller to give your customers an inexpensive, pre-built bank account connection user flow where you can compliantly pass the relevant data.
The payout object
Let's take a look at a full example payout
object:
{
"id": "payout_587a3e6b1f6c4cd6a56be535e298fff6",
"status": "pending", // pending / completed / failed
"amount": "1000000",
"amountDecimal": 1,
"type": "walletToBankAccount", // walletToWallet / bankAccountToWallet / cardToWallet (coming soon)
"meta": {},
"source": {
"id": "wallet_995015d9e305415ab3900769d7943d24",
"currency": "usd",
"network": "eth"
},
"destination": {
"id": "bankAccount_58a554b59b3e443cb3840e77b63413e2",
"currency": "usdc",
"network": "eth"
},
"customer": {
"id": "customer_4f473af0a308438593aaea633f2ac2a8",
"meta": {},
"address": {
"line1": "205 S Peoria Street",
"line2": "Apt 12",
"city": "Chicago",
"postalCode": "11203",
"state": "IL",
"country": "US"
},
"email": "[email protected]",
"name": "John Smith",
"phone": "126172014075",
"kyc": "complete",
"wallets": [
"wallet_3e55c628f52349be866d551c992a126c"
],
"bankAccounts": [
"bankAccount_05edae9ca3b64765b2b450e032922632"
],
"created": "2023-10-20T16:12:13.750Z",
"updated": "2023-10-20T16:12:13.777Z"
},
"depositInstructions": {
"address": "0xD8FA8849032a4cF2B9563A27243b760B13F3B832",
"network": "ethereum",
"currency": "usdc",
"amountDecimal": 1,
"amount": "1000000"
}
}
Attributes
id
: string
Unique identifier for the object. Auto-generated by Sphere upon creation.
status
: enum
Denotes the status of the payout, (Either pending
, confirmed
, failed
)
amount
string
Total raw unit amount deposited to the destination from the payout.
amountDecimal
number
Total decimal adjusted.
- Is a
string
because it is aBigInt
.
type
: enum
defines if the payout is wallet to bank, or wallet to wallet.
enum
is one ofwalletToBankAccount
,walletToWallet
, orbankAccountToWallet
.walletToBankAccount
: the source must be a wallet, the destination must be a bank account.walletToWallet
: the source must be a wallet, the destination must also be a wallet.bankAccountToWallet
: the source must be a bank account, the destination must be a wallet.
source
: object
The source of the payout.
id
:string
The public key for the wallet that is originating the payout.currency
string
The original currency that is being paid out.- For crypto, is the public key of the token mint address (Solana) or token contract (EVM).
- For convenience, you can also pass in
usdc
,usdt
, orsol
. - For fiat, is one of
usd
(gbp
andeuro
coming soon).
network
string
Identifies the source network from which the payout is coming from.
destination
: object
The destination for the payout. Can either be a public key or bankAccount
.
id
string
Unique identifier of the bank account or the public key which will receive the payout.currency
string
The currency that the payout is converted to, and deposited in.- If crypto, then it is either a token mint address (Solana) or token contract address (EVM).
- For convenience, you can also pass in
usdc
,usdt
, orsol
. - If fiat, then one of
usd
,euro
,gbp
. Defaults tousd
.
network
string
Identifies the destination network that the payout is going to be delivered on.- Can be either blockchains -
sol
,eth
,tron
(coming soon), etc. - Or can be fiat -
ach
orwire
. (Push payments todebit
coming soon).
- Can be either blockchains -
created
:string
datetime for when the payout object was created.