DOCS

New!

/

10 minute read

August 3, 2019

Auto Reload

Auto reload enables you to automatically load a specified amount of funding into an account (MSA or GPA) when the account balance falls below a defined threshold. You can define auto reloads at the level of a user/business, card product, or program (users and businesses are at the same hierarchical level). Each auto reload draws from a single funding source.

In the case of auto reloads defined at more than one level, the following order of precedence (first to last) determines which of the auto reloads is executed:

  1. User/business level

  2. Card product level

  3. Program level

Auto reloads execute only when the account balance falls below the trigger value due to spending. They do not execute due to unloading of funds or because of lack of funds when a user/business is first created.

Create auto reload

Action: POST
Endpoint: /autoreloads

Develop Now!

Sign in and use your sandbox to access the API Explorer

Use this endpoint to create an auto reload.

Body field details

Fields Description

token

string, optional

The unique identifier of the auto reload.

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

active

boolean, optional

Specifies whether the auto reload is active.

Only one auto reload per level, per object, can be active.

Allowable Values: true, false

Default value: true

currency_code

string, required

The 3-character ISO 4217 currency code.

Allowable Values: The 3-character ISO 4217 currency code.

"USD" currently supported.

association

object, optional

Specifies the scope of the auto reload.

Input no more than one field. If no value is supplied, the auto reload applies at the program level.

funding_source_token

string, required

The unique identifier of the funding source to use for this auto reload.

Allowable Values: Existing funding source token.

Send a GET request to /fundingsources/user/{user_token} to retrieve funding source tokens for a user.

Send a GET request to /fundingsources/business/{business_token} to retrieve funding source tokens for a business.

funding_source_address_token

string, optional

The unique identifier of the funding source address to use for this auto reload.

If your funding source is an ACH account, then a funding_source_address_token is not required. If your funding source is a payment card, you must have at least one funding source address in order to create a GPA order.

Allowable Values: Existing funding source address token.

Send a GET request to /fundingsources/addresses/user/{user_token} to retrieve address tokens for a user.

Send a GET request to /fundingsources/addresses/business/{business_token} to retrieve address tokens for a business.

order_scope

object, required

Defines the balance threshold and reload amounts.

The autoreloads.association object

Fields Description

user_token

string, optional

The unique identifer of the user for which the auto reload is configured.

Allowable Values: Existing user token.

Send a GET request to /users to retrieve user tokens.

card_product_token

string, optional

The unique identifer of the card product for which the auto reload is configured.

Allowable Values: Existing card product token.

Send a GET request to /cardproducts to retrieve card product tokens.

business_token

string, optional

The unique identifer of the business for which the auto reload is configured.

Allowable Values: Existing business token.

Send a GET request to /businesss to retrieve business tokens.

The autoreloads.order_scope object

Fields Description

gpa

object, optional

Defines the type of order.

msa

object, optional

Defines the type of order.

The autoreloads.gpa object

Fields Description

trigger_amount

decimal, required

The threshold that determines when the reload happens.

The reload is triggered when the balance drops below this amount.

Allowable Values: Must be at least $0.01

reload_amount

decimal, required

The available balance on the card after the reload has completed.

This value must be greater than or equal to the value of trigger_amount. Note that this is not the same as the amount added to the card, which will vary from reload to reload.

Allowable Values: Must be at least $0.01

The autoreloads.msa object

Fields Description

campaign_token

string, required

Identifies the campaign on which the funds will be spent.

Allowable Values: Existing campaign token.

Send a GET request to /campaigns to retrieve campaign tokens.

trigger_amount

decimal, required

The threshold that determines when the reload happens.

The reload is triggered when the balance drops below this amount.

Allowable Values: Must be at least $0.01

reload_amount

decimal, required

The available balance on the card after the reload has completed.

This value must be greater than or equal to the value of trigger_amount. Note that this is not the same as the amount added to the card, which will vary from reload to reload.

Allowable Values: Must be at least $0.01

Sample request body

{
  "token": "my_user_01_autoreload_01",
  "active": false,
  "currency_code": "USD",
  "association": {
    "user_token": "my_user_01"
  },
  "funding_source_token": "my_program_funding_source_01",
  "order_scope": {
    "gpa": {
      "trigger_amount": 100,
      "reload_amount": 200
    }
  }
}

Is this helpful?

Sample response body

{
  "token": "my_user_01_autoreload_01",
  "active": false,
  "funding_source_token": "my_program_funding_source_01",
  "association": {
    "user_token": "my_user_01"
  },
  "order_scope": {
    "gpa": {
      "trigger_amount": 100,
      "reload_amount": 200
    }
  },
  "currency_code": "USD",
  "created_time": "2017-05-10T22:15:20Z",
  "last_modified_time": "2017-05-10T22:15:20Z"
}

Is this helpful?

Retrieve auto reload

Action: GET
Endpoint: /autoreloads/{token}

Develop Now!

Sign in and use your sandbox to access the API Explorer

Use this endpoint to retrieve a specific auto reload object.

URL path parameters

Fields Description

token

string, required

Identifies the auto reload to retrieve.

Allowable Values: Existing auto reload token.

Send a GET request to /autoreloads to retrieve auto reload tokens.

Sample response body

{
  "token": "my_user_01_autoreload_01",
  "active": false,
  "funding_source_token": "my_program_funding_source_01",
  "association": {
    "user_token": "my_user_01"
  },
  "order_scope": {
    "gpa": {
      "trigger_amount": 100,
      "reload_amount": 200
    }
  },
  "currency_code": "USD",
  "created_time": "2017-05-10T22:15:20Z",
  "last_modified_time": "2017-05-10T22:15:20Z"
}

Is this helpful?

Update auto reload

Action: PUT
Endpoint: /autoreloads/{token}

Develop Now!

Sign in and use your sandbox to access the API Explorer

Use this endpoint to update an auto reload. Only values of parameters in the request are modified; all others are left unchanged.

URL path parameters

Fields Description

token

string, required

Identifies the auto reload to update.

Allowable Values: Existing auto reload token.

Send a GET request to /autoreloads to retrieve auto reload tokens.

Body field details

Fields Description

active

boolean, optional

Specifies whether the auto reload is active.

Only one auto reload per level, per object, can be active.

Allowable Values: true, false

Default value: true

currency_code

string, required

The 3-character ISO 4217 currency code.

Allowable Values: The 3-character ISO 4217 currency code.

"USD" currently supported.

association

object, optional

Specifies the scope of the auto reload.

Input no more than one field. If no value is supplied, the auto reload applies at the program level.

funding_source_token

string, required

The unique identifier of the funding source to use for this auto reload.

Allowable Values: Existing funding source token.

Send a GET request to /fundingsources/user/{user_token} to retrieve funding source tokens for a user.

Send a GET request to /fundingsources/business/{business_token} to retrieve funding source tokens for a business.

funding_source_address_token

string, optional

The unique identifier of the funding source address to use for this auto reload.

If your funding source is an ACH account, then a funding_source_address_token is not required. If your funding source is a payment card, you must have at least one funding source address in order to create a GPA order.

Allowable Values: Existing funding source address token.

Send a GET request to /fundingsources/addresses/user/{user_token} to retrieve address tokens for a user.

Send a GET request to /fundingsources/addresses/business/{business_token} to retrieve address tokens for a business.

order_scope

object, required

Defines the balance threshold and reload amounts.

The autoreloads.association object

Fields Description

user_token

string, optional

The unique identifer of the user for which the auto reload is configured.

Allowable Values: Existing user token.

Send a GET request to /users to retrieve user tokens.

card_product_token

string, optional

The unique identifer of the card product for which the auto reload is configured.

Allowable Values: Existing card product token.

Send a GET request to /cardproducts to retrieve card product tokens.

business_token

string, optional

The unique identifer of the business for which the auto reload is configured.

Allowable Values: Existing business token.

Send a GET request to /businesss to retrieve business tokens.

The autoreloads.order_scope object

Fields Description

gpa

object, optional

Defines the type of order.

msa

object, optional

Defines the type of order.

The autoreloads.gpa object

Fields Description

trigger_amount

decimal, required

The threshold that determines when the reload happens.

The reload is triggered when the balance drops below this amount.

Allowable Values: Must be at least $0.01

reload_amount

decimal, required

The available balance on the card after the reload has completed.

This value must be greater than or equal to the value of trigger_amount. Note that this is not the same as the amount added to the card, which will vary from reload to reload.

Allowable Values: Must be at least $0.01

The autoreloads.msa object

Fields Description

campaign_token

string, required

Identifies the campaign on which the funds will be spent.

Allowable Values: Existing campaign token.

Send a GET request to /campaigns to retrieve campaign tokens.

trigger_amount

decimal, required

The threshold that determines when the reload happens.

The reload is triggered when the balance drops below this amount.

Allowable Values: Must be at least $0.01

reload_amount

decimal, required

The available balance on the card after the reload has completed.

This value must be greater than or equal to the value of trigger_amount. Note that this is not the same as the amount added to the card, which will vary from reload to reload.

Allowable Values: Must be at least $0.01

Sample request body

{
  "order_scope": {
    "gpa": {
      "trigger_amount": 250,
      "reload_amount": 500
    }
  }
}

Is this helpful?

Sample response body

{
  "token": "my_user_01_autoreload_01",
  "active": false,
  "funding_source_token": "my_program_funding_source_01",
  "association": {
    "user_token": "my_user_01"
  },
  "order_scope": {
    "gpa": {
      "trigger_amount": 250,
      "reload_amount": 500
    }
  },
  "currency_code": "USD",
  "created_time": "2017-05-10T22:15:20Z",
  "last_modified_time": "2017-05-10T22:21:59Z"
}

Is this helpful?

List auto reloads

Action: GET
Endpoint: /autoreloads

Develop Now!

Sign in and use your sandbox to access the API Explorer

Use this endpoint to list auto reloads configured for the program or for a specific card product, user, or business.

This endpoint supports field filtering and pagination.

Query parameters

Fields Description

card_product

string, optional

The token identifying the card product whose auto reloads you want to retrieve.

Allowable Values: Existing card product token.

Send a GET request to /cardproducts to retrieve card product tokens.

user_token

string, optional

The token identifying the user whose auto reloads you want to retrieve.

Allowable Values: Existing user token.

Send a GET request to /users to retrieve user tokens.

business_token

string, optional

The token identifying the business whose auto reloads you want to retrieve.

Allowable Values: Existing business token.

Send a GET request to /businesses to retrieve business tokens.

Sample response body

{
  "count": 1,
  "start_index": 0,
  "end_index": 0,
  "is_more": false,
  "data": [
    {
      "token": "my_user_01_autoreload_01",
      "active": false,
      "funding_source_token": "my_program_funding_source_01",
      "association": {
        "user_token": "my_user_01"
      },
      "order_scope": {
        "gpa": {
          "trigger_amount": 250,
          "reload_amount": 500
        }
      },
      "currency_code": "USD",
      "created_time": "2017-05-10T22:15:20Z",
      "last_modified_time": "2017-05-10T22:21:59Z"
    }
  ]
}

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.