Transfer Fees
As a merchant you are able to set percentage fees for your customers.
By default your fee will be a global fee applying to all your customers. You can also set a specific customer as a target for your fee by setting a targetCustomerId
parameter when creating a fee.
A global fee will no longer apply to a customer who has a fee specific to them, their specific fee will be used instead.
There can only be one active
fee per "level", meaning an application can have only one active global fee and each customer can have only one active fee specific to them at a time.
Calculation
Fees are denominated in basis points (1 bps = 0.01%). Percentage fee is always calculated base on amount paid and always calculated in dollars. Example:
Imagine a customer making an on-ramp of 100€ to USDC and exchange rate of €/USD being "1.1". A merchant has set his fee to 100 bps (1%). The calculations will happen as follows:
- €100 * 1.1 = $110
- $110 * 1% = $1.1
Below is an example of a transfer fee object:
The Transfer Fee object
Properties
- Name
id
- Type
- string
- Description
Unique identifier for a transferFee.
- Name
setter
- Type
- string
- Description
Can be either "merchant" or "sphere", depending on who created the fee.
- Name
application
- Type
- string
- Description
Application relevant to the fee, if applicable.
- Name
targetCustomer
- Type
- string
- Description
Customer relevant to the fee, if applicable.
- Name
active
- Type
- boolean
- Description
Whether fee is currently active.
- Name
activeSince
- Type
- string
- Description
Timestamp of fee activation.
- Name
deactivated
- Type
- string
- Description
Timestamp of fee deactivation, if applicable.
- Name
bpsFee
- Type
- string
- Description
Basis point percentage fee.
- Name
inheritFixedFees
- Type
- boolean
- Description
Whether fixed fees should be charged to customer. Only applicable to Sphere fees.
- Name
updated
- Type
- string
- Description
Last time fee was updated.
- Name
created
- Type
- string
- Description
Time when fee was created
TransferFee Object
{
"id": "transferFee_b76e7dd171af4479b72396fd44b0c276",
"setter": "merchant",
"application": {
"id": "application_1c4077f593c94a9184a55da30d02b0ea",
...
},
"targetCustomer": {
"id": "customer_f5cf0fe1462d4edbb80b08b67bbd3da5",
...
},
"active": true,
"activeSince": "2019-01-01T00:00:00Z",
"deactivated": null,
"bpsFee": "100",
"inheritFixedFees": false,
"updated": "2019-01-01T00:00:00Z",
"created": "2019-01-01T00:00:00Z",
}
Set a transfer fee
This endpoint allows you to set a new fee, overriding current one if applicable.
Required attributes
- Name
bpsFee
- Type
- string
- Description
Basis point percentage fee.
Optional attributes
- Name
targetCustomer
- Type
- string
- Description
Customer relevant to the fee, if applicable.
Request
curl https://api.spherepay.co/v1/transfer/fee \
-H "Authorization: Bearer {token}" \
-d bpsFee="20" \
-d targetCustomerId="customer_f5cf0fe1462d4edbb80b08b67bbd3da5"
Response
{
"ok": true,
"object": "object",
"statusCode": 200,
"error": null,
"message": "success",
"data": {
"newTransferFee": {
"id": "transferFee_12ae85c47f0a4ba29066e55d656008e5",
"setter": "merchant",
"application": {
"id": "application_1c4077f593c94a9184a55da30d02b0ea"
},
"targetCustomer": null,
"active": true,
"activeSince": "2024-06-17T11:20:51.424Z",
"deactivated": null,
"bpsFee": "20",
"inheritFixedFees": false,
"updated": "2024-06-17T11:20:51.439Z",
"created": "2024-06-17T11:20:51.439Z"
},
"deactivatedTransferFee": {
"id": "transferFee_869ccc7eadf342bcb4aa44ab6cca61a5",
"setter": "merchant",
"application": {
"id": "application_1c4077f593c94a9184a55da30d02b0ea"
},
"targetCustomer": null,
"active": false,
"activeSince": "2024-06-14T10:26:21.270Z",
"deactivated": "2024-06-17T11:20:51.423Z",
"bpsFee": "20",
"inheritFixedFees": false,
"updated": "2024-06-17T11:20:51.431Z",
"created": "2024-06-14T10:26:21.283Z"
}
},
"ts": "2024-06-17T11:20:51.446Z",
"request": "request_84153586b60c4eb5ad46f820506d7d86"
}
Retrieve a transferFee by id
This endpoint allows you to retrieve a transferFee by their id.
Required attributes
- Name
id
- Type
- string
- Description
Unique identifier for a transferFee.
Request
curl -G https://api.spherepay.co/v1/transfer/fee/transferFee_f071b8911a934551b75793f7bf6ad481 \
-H "Authorization: Bearer {token}"
Response
{
"ok": true,
"object": "object",
"statusCode": 200,
"error": null,
"message": "success",
"data": {
"transferFee": {
"id": "transferFee_f071b8911a934551b75793f7bf6ad481",
"setter": "merchant",
"application": {
"id": "application_1c4077f593c94a9184a55da30d02b0ea"
},
"targetCustomer": {
"id": "customer_f5cf0fe1462d4edbb80b08b67bbd3da5"
},
"active": true,
"activeSince": "2024-06-14T10:42:19.211Z",
"deactivated": null,
"bpsFee": "20",
"inheritFixedFees": false,
"updated": "2024-06-14T10:42:19.263Z",
"created": "2024-06-14T10:42:19.263Z"
}
},
"ts": "2024-06-17T11:25:24.971Z",
"request": "request_9d4732ada4fd436f81408cd2886b5a8d"
}
List active transfer fees for application
This endpoint allows you to retrieve a list of all your applicable active fees.
Request
curl -G https://api.spherepay.co/v1/transfer/fee \
-H "Authorization: Bearer {token}"
Response
{
"ok": true,
"object": "object",
"statusCode": 200,
"error": null,
"message": "success",
"data": {
"providerTransferFees": [
{
"id": "transferFee_eaa07183b0794045acd2dfd767e0635f",
"setter": "sphere",
"application": null,
"targetCustomer": null,
"active": true,
"activeSince": "2024-06-07T11:52:08.289Z",
"deactivated": null,
"bpsFee": "10",
"inheritFixedFees": true,
"updated": "2024-06-07T11:52:08.297Z",
"created": "2024-06-07T11:52:08.297Z"
}
],
"applicationTransferFees": [
{
"id": "transferFee_12ae85c47f0a4ba29066e55d656008e5",
"setter": "merchant",
"application": {
"id": "application_1c4077f593c94a9184a55da30d02b0ea"
},
"targetCustomer": null,
"active": true,
"activeSince": "2024-06-17T11:20:51.424Z",
"deactivated": null,
"bpsFee": "20",
"inheritFixedFees": false,
"updated": "2024-06-17T11:20:51.439Z",
"created": "2024-06-17T11:20:51.439Z"
}
],
"customerTransferFees": [
{
"id": "transferFee_f071b8911a934551b75793f7bf6ad481",
"setter": "merchant",
"application": {
"id": "application_1c4077f593c94a9184a55da30d02b0ea"
},
"targetCustomer": {
"id": "customer_f5cf0fe1462d4edbb80b08b67bbd3da5"
},
"active": true,
"activeSince": "2024-06-14T10:42:19.211Z",
"deactivated": null,
"bpsFee": "20",
"inheritFixedFees": false,
"updated": "2024-06-14T10:42:19.263Z",
"created": "2024-06-14T10:42:19.263Z"
}
]
},
"ts": "2024-06-17T11:30:48.379Z",
"request": "request_25b2c2c3d05a4dafba9b1702bd8b59bb"
}
Deactivate fee by id
This endpoint allows you to deactivate an active fee.
Required attributes
- Name
id
- Type
- string
- Description
Unique identifier for a transferFee.
Request
curl https://api.spherepay.co/v1/transfer/fee/deactivate/transferFee_12ae85c47f0a4ba29066e55d656008e5 \
-H "Authorization: Bearer {token}"
Response
{
"ok": true,
"object": "object",
"statusCode": 200,
"error": null,
"message": "success",
"data": {
"transferFee": {
"id": "transferFee_12ae85c47f0a4ba29066e55d656008e5",
"setter": "merchant",
"application": {
"id": "application_1c4077f593c94a9184a55da30d02b0ea"
},
"targetCustomer": null,
"active": false,
"activeSince": "2024-06-17T11:20:51.424Z",
"deactivated": "2024-06-17T16:42:23.498Z",
"bpsFee": "20",
"inheritFixedFees": false,
"updated": "2024-06-17T16:42:23.503Z",
"created": "2024-06-17T11:20:51.439Z"
}
},
"ts": "2024-06-17T16:42:23.509Z",
"request": "request_c347fba7b7574421b1d9080932ac5cf9"
}