Payout 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.

Endpoints

/v1/payout/fee/active

POST

/v1/payout/fee/deactivate/:id

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 payout fee object:

The Payout Fee object

Properties

Name
id
Type
string
Description
Unique identifier for a payoutFee.
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

PayoutFee Object

{
  "id": "payoutFee_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",
}

POST/v1/payout/fee

Set a payout 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

POST

/v1/payout/fee

curl https://api.spherepay.co/v1/payout/fee \
  -H "Authorization: Bearer {token}" \
  -d bpsFee="20" \
  -d targetCustomerId="customer_f5cf0fe1462d4edbb80b08b67bbd3da5"

Response

{
  "ok": true,
  "object": "object",
  "statusCode": 200,
  "error": null,
  "message": "success",
  "data": {
    "newFee": {
      "id": "payoutFee_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"
    },
    "deactivatedFee": {
      "id": "payoutFee_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"
}

GET/v1/payout/fee/:id

Retrieve a payoutFee by id

This endpoint allows you to retrieve a payoutFee by their id.

Required attributes

Name
id
Type
string
Description
Unique identifier for a payoutFee.

Request

GET

/v1/payout/fee/:id

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

Response

{
  "ok": true,
  "object": "object",
  "statusCode": 200,
  "error": null,
  "message": "success",
  "data": {
    "id": "payoutFee_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"
}

GET/v1/payout/fee/active

List active payout fees for application

This endpoint allows you to retrieve a list of all your applicable active fees.

Request

GET

/v1/contacts

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

Response

{
  "ok": true,
  "object": "object",
  "statusCode": 200,
  "error": null,
  "message": "success",
  "data": {
    "providerFees": [
      {
        "id": "payoutFee_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"
      }
    ],
    "applicationFees": [
      {
        "id": "payoutFee_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"
      }
    ],
    "customerFees": [
      {
        "id": "payoutFee_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"
}

POST/v1/payout/fee/deactivate/:id

Deactivate fee by id

This endpoint allows you to deactivate an active fee.

Required attributes

Name
id
Type
string
Description
Unique identifier for a payoutFee.

Request

POST

/v1/payout/fee/deactivate/:id

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

Response

{
  "ok": true,
  "object": "object",
  "statusCode": 200,
  "error": null,
  "message": "success",
  "data": {
    "id": "payoutFee_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"
}