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",
}

POST/v1/transfer/fee

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

POST
/v1/transfer/fee
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"
}

GET/v1/transfer/fee/:id

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

GET
/v1/transfer/fee/:id
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"
}

GET/v1/transfer/fee/active

List active transfer 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/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"
}

POST/v1/transfer/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 transferFee.

Request

POST
/v1/transfer/fee/deactivate/:id
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"
}

Was this page helpful?