Fee Charges

A fee charge moves funds from the general purpose account (GPA) of an account holder to your program’s fee account. The charge amount is determined by the fee that is assessed. The request returns an error if the GPA has insufficient funds to cover the fee. This behavior contrasts with assessing a fee using the /gpaorders endpoint, in which case the amount of the fee is loaded into the GPA from the funding source before the GPA is debited.

Create fee charge

Action: POST
Endpoint: /feecharges Use this endpoint to create a fee charge. You must pass in either user_token or business_token to associate a user or business with the fee charge. This is an all-or-nothing operation. When more than one fee is present, you must assess either all fees, or no fees.

Request body

Fields	Description
business_token string Required	Specifies the business account holder to which the fee applies. Pass either `business_token` or `user_token`, not both. Allowable Values: 1–36 chars
fees array of objects Optional	Contains attributes that define characteristics of one or more fees. Allowable Values: An array of one or more `fee_model` objects
fees[].memo string Optional	Additional text describing the fee. Allowable Values: 1–255 chars
fees[].overrideAmount decimal Optional	Dynamic fee amount that overrides the `fee.amount` field value. Allowable Values: decimal Format: 0.00
fees[].tags string Optional	Descriptive metadata about the fee. Allowable Values: 255 char max
fees[].token string Required	Unique identifier of the fee. Allowable Values: 1–36 chars
tags string Optional	Metadata about the transfer. Allowable Values: 255 char max
token string Optional	Unique identifier of the fee transfer. If you do not include a token, the system will generate one automatically. This token is necessary for use in other API calls, so we recommend that rather than let the system generate one, you use a simple string that is easy to remember. This value cannot be updated. Allowable Values: 1–36 chars
user_token string Required	Specifies the user account holder to which the fee applies. Pass either `user_token` or `business_token`, not both. Allowable Values: 1–36 chars

Sample request body

JSON

{
  "fees": [
    {
      "token": "my_fee_01",
      "memo": "Initiation fee"
    }
  ],
  "token": "my_feecharge_01",
  "user_token": "my_user_01",
  "business_token": "my_business_01"
}

Response body

Fields	Description
business_token string Returned	Specifies the business account holder to which the fee applies. Allowable Values: 1–36 chars
created_time datetime Returned	Date and time when the `fee_charge` object was created, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
fees array of objects Returned	Contains attributes that define characteristics of one or more fees. Allowable Values: Array of existing `fees` objects
fees[].fee object Returned	Contains details about the fee. Allowable Values: `amount`, `created_time`, `currency_code`, `last_modified_time`, `name`, `tags`, `token`
fees[].fee.amount decimal Returned	Amount of the fee. Allowable Values: decimal Format: 0.00
fees[].fee.created_time datetime Returned	Date and time when the `fees` object was created, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
fees[].fee.currency_code string Returned	Three-digit ISO 4217 currency code. Allowable Values: Valid three-digit ISO 4217 currency code
fees[].fee.last_modified_time datetime Returned	Date and time when the `fees` object was last modified, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
fees[].fee.name string Returned	Name of the fee. Allowable Values: 50 char max
fees[].fee.tags string Conditionally returned	Descriptive metadata about the fee. Allowable Values: 255 char max
fees[].fee.token string Returned	Unique identifier of the `fees` object. Allowable Values: Existing `fees` object token
fees[].memo string Conditionally returned	Additional text describing the fee. Allowable Values: 1–255 chars
fees[].overrideAmount decimal Conditionally returned	Dynamic fee amount that overrides the `fee.amount` field value. Allowable Values: decimal Format: 0.00
fees[].tags string Conditionally returned	Descriptive metadata about the fee. Allowable Values: 255 char max
fees[].token string Returned	Unique identifier of the fee. Allowable Values: 1–36 chars
fees[].transaction_token string Returned	Unique identifier of the fee transaction. Allowable Values: 36 char max
tags string Conditionally returned	Metadata about the fee charge. This field is returned if it exists in the resource. Allowable Values: 255 char max
token string Returned	Unique identifier of the fee transfer. Allowable Values: 1–36 chars
user_token string Returned	Specifies the user account holder to which the fee applies. Allowable Values: 1–36 chars

Sample response body

JSON

{
  "fees": [
    {
      "token": "my_fee_01",
      "memo": "Initiation fee",
      "transaction_token": "162",
      "fee": {
        "token": "my_fee_01",
        "active": true,
        "name": "My Fee 01",
        "amount": 1,
        "tags": "My Tags",
        "created_time": "2024-05-11T17:57:21Z",
        "last_modified_time": "2024-05-11T17:57:21Z",
        "currency_code": "USD"
      }
    }
  ],
  "token": "my_feecharge_01",
  "user_token": "my_user_01",
  "business_token": "my_business_01",
  "created_time": "2024-05-11T19:05:55Z"
}

Retrieve fee charge

Action: GET
Endpoint: /feecharges/{token} Use this endpoint to retrieve a specific fee charge. Include the fee transfer token path parameter to specify the fee charge to return.

URL path parameters

Fields	Description
token string Required	Unique identifier of the fee charge to retrieve. Allowable Values: Existing fee charge token

Response body

Fields	Description
business_token string Returned	Specifies the business account holder to which the fee applies. Allowable Values: 1–36 chars
created_time datetime Returned	Date and time when the `fee_charge` object was created, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
fees array of objects Returned	Contains attributes that define characteristics of one or more fees. Allowable Values: Array of existing `fees` objects
fees[].fee object Returned	Contains details about the fee. Allowable Values: `amount`, `created_time`, `currency_code`, `last_modified_time`, `name`, `tags`, `token`
fees[].fee.amount decimal Returned	Amount of the fee. Allowable Values: decimal Format: 0.00
fees[].fee.created_time datetime Returned	Date and time when the `fees` object was created, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
fees[].fee.currency_code string Returned	Three-digit ISO 4217 currency code. Allowable Values: Valid three-digit ISO 4217 currency code
fees[].fee.last_modified_time datetime Returned	Date and time when the `fees` object was last modified, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
fees[].fee.name string Returned	Name of the fee. Allowable Values: 50 char max
fees[].fee.tags string Conditionally returned	Descriptive metadata about the fee. Allowable Values: 255 char max
fees[].fee.token string Returned	Unique identifier of the `fees` object. Allowable Values: Existing `fees` object token
fees[].memo string Conditionally returned	Additional text describing the fee. Allowable Values: 1–255 chars
fees[].overrideAmount decimal Conditionally returned	Dynamic fee amount that overrides the `fee.amount` field value. Allowable Values: decimal Format: 0.00
fees[].tags string Conditionally returned	Descriptive metadata about the fee. Allowable Values: 255 char max
fees[].token string Returned	Unique identifier of the fee. Allowable Values: 1–36 chars
fees[].transaction_token string Returned	Unique identifier of the fee transaction. Allowable Values: 36 char max
tags string Conditionally returned	Metadata about the fee charge. This field is returned if it exists in the resource. Allowable Values: 255 char max
token string Returned	Unique identifier of the fee transfer. Allowable Values: 1–36 chars
user_token string Returned	Specifies the user account holder to which the fee applies. Allowable Values: 1–36 chars

Sample response body

JSON

{
  "fees": [
    {
      "token": "my_fee_01",
      "memo": "Initiation fee",
      "transaction_token": "162",
      "fee": {
        "token": "my_fee_01",
        "active": true,
        "name": "My Fee 01",
        "amount": 1,
        "tags": "My Tags",
        "created_time": "2024-05-11T17:57:21Z",
        "last_modified_time": "2024-05-11T17:57:21Z",
        "currency_code": "USD"
      }
    }
  ],
  "token": "my_feetransfer_01",
  "user_token": "my_user_01",
  "business_token": "my_business_01",
  "created_time": "2024-05-11T19:05:55Z"
}

​Create fee charge

​Request body

​Sample request body

​Response body

​Sample response body

​Retrieve fee charge

​URL path parameters

​Response body

​Sample response body

Create fee charge

Request body

Sample request body

Response body

Sample response body

Retrieve fee charge

URL path parameters

Response body

Sample response body