DOCS

New!

/

5 minute read

February 3, 2020

Fees

A fees resource represents a monetary assessment against a user’s general purpose account (GPA). Assessing a fee transfers funds from the user’s GPA account to your program’s fee account. By default, every user has a GPA used for the funding of transfers.

You can assess fees either post-transaction or in real time. Real-time fee assessment ensures the account has sufficient funds available to cover both the transaction amount and the fee before authorization of the transaction. To assess fees in real time, you must create a real-time fee group using the /realtimefeegroups endpoint.

When assessing a post-transaction fee, you can either debit existing GPA funds, or pull in new funds from a funding source. To use existing GPA funds, use the /feetransfers endpoint. To pull in new funds, leverage the fees array in /gpaorders.

Create fee

Action: POST
Endpoint: /fees

Develop Now!

Sign in and use your sandbox to access the API Explorer

Use this endpoint to create a fee. Add the source details to the body of the request in JSON format.

Body field details

Fields Description

token

string
Optional

The unique identifier of the fee.

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:

36 char max

name

string
Required

The name of the fee request.

Allowable Values:

50 char max

currency_code

string
Required

The three-character ISO 4217 currency code.

Allowable Values:

The three-character ISO 4217 currency code.

"USD" currently supported.

amount

decimal
Required

The amount of the fee.

Allowable Values:

Format: 0.00

active

boolean
Optional

Indicates whether the fee is active.

Allowable Values:

true, false

Default value: true

real_time_assessment

object
Optional

Controls the assessment of real-time fees.

Allowable Values:

tags

string
Optional

Descriptive metadata about the fee.

Allowable Values:

99 char max

The real_time_assessment object

Fields Description

international_enabled

boolean
Optional

Enables fee assessments where the origin of the transaction acquirer is outside the US.

Allowable Values:

true, false

domestic_enabled

boolean
Optional

Enables fee assessments where the origin of the transaction acquirer is inside the US.

Allowable Values:

true, false

transaction_type

string
Optional

Indicates the type of transactions on which the fee is assessed.

Allowable Values:

authorization, pindebit.atm.withdrawal, pindebit

Sample request body

{
  "token": "my_fee_01",
  "amount": "1.00",
  "name": "My Fee 01",
  "currency_code": "USD",
  "real_time_assessment": {
    "international_enabled": true,
    "domestic_enabled": true,
    "transaction_type": "authorization"
  },
  "tags": "My Tags"
}

Is this helpful?

Sample response body

{
  "token": "my_fee_01",
  "active": true,
  "name": "My Fee 01",
  "amount": 1,
  "tags": "My Tags",
  "created_time": "2019-05-11T17:57:21Z",
  "last_modified_time": "2019-05-11T17:57:21Z",
  "currency_code": "USD",
  "real_time_assessment": {
    "transaction_type": "authorization",
    "international_enabled": true,
    "domestic_enabled": true
  }
}

Is this helpful?

Retrieve fee

Action: GET
Endpoint: /fees/{token}

Develop Now!

Sign in and use your sandbox to access the API Explorer

Use this endpoint to retrieve a fee. Include the token path parameter to specify the fee to return.

URL path parameters

Fields Description

token

string
Required

Identifies the fee to retrieve.

Allowable Values:

Existing fee token.

Send a GET request to /fees to retrieve fee tokens.

Sample response body

{
  "token": "my_fee_01",
  "active": true,
  "name": "My Fee 01",
  "amount": 1,
  "tags": "My Tags",
  "created_time": "2019-05-11T17:57:21Z",
  "last_modified_time": "2019-05-11T17:57:21Z",
  "currency_code": "USD",
  "real_time_assessment": {
    "transaction_type": "authorization",
    "international_enabled": true,
    "domestic_enabled": true
  }
}

Is this helpful?

Update fee

Action: PUT
Endpoint: /fees/{token}

Develop Now!

Sign in and use your sandbox to access the API Explorer

Use this endpoint to update a fee. Include the token as a path parameter to indicate the fee to update.

URL path parameters

Fields Description

token

string
Required

Identifies the fee to update.

Allowable Values:

Existing fee token.

Send a GET request to /fees to retrieve fee tokens.

Body field details

Fields Description

name

string
Required

The name of the fee request.

Allowable Values:

50 char max

currency_code

decimal
Required

The three-character ISO 4217 currency code.

Allowable Values:

The three-character ISO 4217 currency code.

"USD" currently supported.

amount

decimal
Required

The amount of the fee.

Allowable Values:

Format: 0.00

active

boolean
Optional

Indicates whether the fee is active.

Allowable Values:

true, false

Default value: true

real_time_assessment

object
Optional

Controls the assessment of real-time fees.

Allowable Values:

tags

string
Optional

Descriptive metadata about the fee.

Allowable Values:

99 char max

The real_time_assessment object

Fields Description

international_enabled

boolean
Optional

Enables fee assessments where the origin of the transaction acquirer is outside the US.

Allowable Values:

true, false

domestic_enabled

boolean
Optional

Enables fee assessments where the origin of the transaction acquirer is inside the US.

Allowable Values:

true, false

transaction_type

string
Optional

Indicates the type of transactions on which the fee is assessed.

Allowable Values:

authorization, pindebit.atm.withdrawal, pindebit

Sample request body

{
    "active": false
}

Is this helpful?

Sample response body

{
  "token": "my_fee_01",
  "active": false,
  "name": "My Fee 01",
  "amount": 1,
  "tags": "My Tags",
  "created_time": "2019-05-11T17:57:21Z",
  "last_modified_time": "2019-05-11T17:57:21Z",
  "currency_code": "USD",
  "real_time_assessment": {
    "transaction_type": "authorization",
    "international_enabled": true,
    "domestic_enabled": true
  }
}

Is this helpful?

List fees

Action: GET
Endpoint: /fees

Develop Now!

Sign in and use your sandbox to access the API Explorer

Use this endpoint to list existing fees.

This endpoint supports field filtering and pagination.

Sample response body

{
  "count": 2,
  "start_index": 0,
  "end_index": 1,
  "is_more": false,
  "data": [
    {
      "token": "my_fee_02",
      "active": true,
      "name": "My Fee 02",
      "amount": 3,
      "tags": "My Tags",
      "created_time": "2019-05-11T18:03:39Z",
      "last_modified_time": "2019-05-11T18:03:39Z",
      "currency_code": "USD",
      "real_time_assessment": {
        "transaction_type": "authorization",
        "international_enabled": true,
        "domestic_enabled": true
      }
    },
    {
      "token": "my_fee_01",
      "active": true,
      "name": "My Fee 01",
      "amount": 1,
      "tags": "My Tags",
      "created_time": "2019-05-11T17:57:21Z",
      "last_modified_time": "2019-05-11T17:57:21Z",
      "currency_code": "USD",
      "real_time_assessment": {
        "transaction_type": "authorization",
        "international_enabled": true,
        "domestic_enabled": true
      }
    }
  ]
}

Is this helpful?

Have any feedback on this page?

If you feel we can do anything better, please let our team know.

We strive for the best possible developer experience.