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
, orrefunded
.
- Name
type
- Type
- string
- Description
The transfer type. Either
onRamp
oroffRamp
.
- 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
foronRamp
transfers or awallet
foroffRamp
transfers.- Name
id
- Type
- string
- Description
The id of the
bankAccount
orwallet
.
- Name
currency
- Type
- enum
- Description
The currency of the
bankAccount
orwallet
.- For an
onRamp
, it is eitherusd
oreur
. - For an
offRamp
, it is eitherusdc
orusdt
.
- For an
- Name
network
- Type
- enum
- Description
The network of the
bankAccount
orwallet
.- For an
onRamp
, it is one ofachPush
,achSameDay
,wire
, orsepa
. - For an
offRamp
, it is one ofsol
,ethereum
, orbase
.
- For an
- 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 theid
itself.- Name
id
- Type
- string
- Description
The id of the funding
bankAccount
orwallet
.
- 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
foronRamp
transfers or abankAccount
foroffRamp
transfers.- Name
id
- Type
- string
- Description
The id of the
bankAccount
orwallet
.
- Name
currency
- Type
- enum
- Description
The currency of the
bankAccount
orwallet
.- For an
onRamp
, it is eitherusdc
orusdt
. - For an
offRamp
, it is eitherusd
oreur
.
- For an
- Name
network
- Type
- enum
- Description
The network of the
bankAccount
orwallet
.- For an
onRamp
, it is one ofsol
,ethereum
, orbase
. - For an
offRamp
, it is one ofachSameDay
,ach
,wire
, orsepa
.
- For an
- 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
orwallet
object associated with the transfer. AbankAccount
foronRamp
transfers or awallet
foroffRamp
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.
- Bank Account (For on-ramps)
- 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"
}
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
orwallet
.
- Name
currency
- Type
- enum
- Description
The currency of the source
bankAccount
orwallet
.- For an
onRamp
, it is eitherusd
oreur
. - For an
offRamp
, it is eitherusdc
orusdt
.
- For an
- Name
network
- Type
- enum
- Description
The network of the source
bankAccount
orwallet
.- For an
onRamp
, it is one ofachPush
,achSameDay
,wire
, orsepa
. - For an
offRamp
, it is one ofsol
,ethereum
, orbase
.
- For an
- 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
orwallet
.
- Name
currency
- Type
- enum
- Required
- Required
- Description
The currency of the destination
bankAccount
orwallet
.- For an
onRamp
, it is eitherusdc
orusdt
. - For an
offRamp
, it is eitherusd
oreur
.
- For an
- Name
network
- Type
- enum
- Required
- Required
- Description
The network of the destination
bankAccount
orwallet
.- For an
onRamp
, it is one ofsol
,ethereum
, orbase
. - For an
offRamp
, it is one ofachSameDay
,ach
,wire
, orsepa
.
- For an
- 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
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"
}
Retrieve a transfer
This endpoint allows you to retrieve a transfer by id.
Request
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"
}
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
orDESC
.
- Name
limit
- Type
- integer
- Description
Limit the number of contacts returned.
- Name
customer
- Type
- string
- Description
Limit the number of contacts returned.
Request
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"
}