/
25 minute read
March 24, 2022

Program Transfers

A program transfer moves funds from an account holder’s GPA to a program funding source. As opposed to a fee transfer, the transfer amount is specified by the transfer itself and is therefore a dynamically settable value. An auto reload is triggered if the GPA has insufficient funds to cover the transfer amount and auto reload is enabled.

Create program transfer

Action: POST
Endpoint: /programtransfers

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

Include either user_token or business_token in the message body to specify the account holder whose GPA will be debited by the program transfer. The user or business must already exist.

A program transfer is an all-or-nothing operation. If the GPA has insufficient funds to cover both the amount of the program transfer and all attached fees, then no funds are transferred.

Request body
Fields Description

amount

decimal
Required

Amount of program transfer.

Allowable Values:

Format: 0.00

business_token

string
Optional

The unique identifier of the business. Pass either a business token or a user token, not both.

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

Allowable Values:

1–36 chars

currency_code

string
Required

The three-digit ISO 4217 currency code.

Allowable Values:

A valid three-digit ISO 4217 currency code

fees

array of objects
Optional

Contains attributes that define characteristics of one or more fees.

Allowable Values:

A valid fees object

fees[].memo

string
Optional

Memo or note describing the fee.

Allowable Values:

1–99 chars

fees[].tags

string
Optional

Comma-delimited list of tags describing the fee.

Allowable Values:

255 char max

fees[].token

string
Required

Specifies the fee to add.

Allowable Values:

1–36 chars

memo

string
Optional

Memo or note describing the program transfer.

Allowable Values:

1–99 chars

tags

string
Optional

Comma-delimited list of tags describing the program transfer.

Allowable Values:

1–255 chars

token

string
Optional

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

type_token

string
Required

The unique identifier of the program transfer type.

Send a GET request to /programtransfers/types to retrieve program transfer type tokens.

Allowable Values:

1–36 chars

user_token

string
Optional

The unique identifier of the user. Pass either a user token or a business token, not both.

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

Allowable Values:

1–36 chars

Sample request body
JSON
Copied

Is this helpful?

Yes
No
Response body
Fields Description

amount

decimal
Returned

Amount of program transfer.

Allowable Values:

Format: 0.00

business_token

string
Conditionally returned

The unique identifier of the business.

This field is returned if it exists in the resource.

Allowable Values:

1–36 chars

created_time

datetime
Conditionally returned

The date and time when the program transfer object was created, in UTC. 2021-10-26T20:03:05Z, for example.

Allowable Values:

Format: yyyy-MM-ddTHH:mm:ssZ

currency_code

string
Returned

The three-digit ISO 4217 currency code.

This field is returned if it exists in the resource.

Allowable Values:

A valid three-digit ISO 4217 currency code

fees

array of objects
Conditionally returned

Contains attributes that define characteristics of one or more fees.

This array is returned if it exists in the resource.

Allowable Values:

A valid fees array

fees[].fee

object
Returned

Contains details about the fee.

Allowable Values:

A valid fees.fee object

fees[].fee.active

boolean
Returned

Indicates whether the fee is active.

Allowable Values:

true, false

fees[].fee.amount

decimal
Returned

The amount of the fee.

Allowable Values:

Format: 0.00

fees[].fee.created_time

datetime
Returned

The date and time when the fees object was created, in UTC. 2021-10-26T20:03:05Z, for example.

Allowable Values:

Format: yyyy-MM-ddTHH:mm:ssZ

fees[].fee.currency_code

string
Returned

The three-digit ISO 4217 currency code.

Allowable Values:

A valid three-digit ISO 4217 currency code

fees[].fee.last_modified_time

datetime
Returned

The date and time when the fees object was created, in UTC. 2021-10-26T20:03:05Z, for example.

Allowable Values:

Format: yyyy-MM-ddTHH:mm:ssZ

fees[].fee.name

string
Returned

The name of the fees object.

Allowable Values:

50 char max

fees[].fee.real_time_assessment

object
Conditionally returned

Controls the assessment of real-time fees.

This object is returned if it exists in the resource.

Allowable Values:

A valid real_time_fee_assessment object

fees[].fee.real_time_assessment.domestic_enabled

boolean
Conditionally returned

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

This field is returned if it exists in the resource.

Allowable Values:

true, false

fees[].fee.real_time_assessment.international_enabled

boolean
Conditionally returned

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

This field is returned if it exists in the resource.

Allowable Values:

true, false

fees[].fee.real_time_assessment.transaction_type

string
Conditionally returned

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

This field is returned if it exists in the resource.

Allowable Values:

authorization, pindebit.atm.withdrawal, pindebit

fees[].fee.tags

string
Conditionally returned

Descriptive metadata about the fee.

This field is returned if it exists in the resource.

Allowable Values:

255 char max

fees[].fee.token

string
Returned

The unique identifier of the fee.

This field is returned if it exists in the resource.

Allowable Values:

36 char max

fees[].memo

string
Conditionally returned

Additional text that describes the fee.

This field is returned if it exists in the resource.

Allowable Values:

1–99 chars

fees[].tags

string
Conditionally returned

Comma-delimited list of tags describing the fee.

This field is returned if it exists in the resource.

Allowable Values:

255 char max

fees[].token

string
Returned

The unique identifier of the fee.

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

Allowable Values:

1–36 chars

fees[].transaction_token

string
Returned

Unique identifier of the transaction.

Allowable Values:

Format: UUID

Sample response body
JSON
Copied

Is this helpful?

Yes
No

List program transfers

Action: GET
Endpoint: /programtransfers

Use this endpoint to list all program transfers.

To narrow your result set to program transfers of a particular type or that are associated with a particular account holder, include the appropriate parameters from the following Query Parameters table. This endpoint also supports field filtering, pagination, and sorting.

URL query parameters
Fields Description

count

integer
Optional

The number of program transfers to retrieve.

Allowable Values:

Any integer

start_index

integer
Optional

The sort order index of the first resource in the returned array.

Allowable Values:

Any integer

fields

string
Optional

Comma-delimited list of fields to return (field_1,field_2, and so on). Leave blank to return all fields.

Allowable Values:

A comma-delimited list of fields, or blank

sort_by

string
Optional

Field on which to sort. Use any field in the resource model, or one of the system fields lastModifiedTime or createdTime. Prefix the field name with a hyphen (-) to sort in descending order. Omit the hyphen to sort in ascending order.

Allowable Values:

lastModifiedTime, createdTime, or any field in the resource model

user_token

string
Optional

Identifies the user account holder whose program transfers you want to retrieve.

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

Allowable Values:

Existing user token

business_token

string
Optional

Identifies the business account holder whose program transfers you want to retrieve.

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

Allowable Values:

Existing buiness token

type_token

string
Optional

Identifies the type of program transfers to retrieve.

Allowable Values:

Existing program transfer type token

Response body
Fields Description

count

integer
Conditionally returned

The number of program transfer resources to retrieve.

Allowable Values:

1-10

data

array of objects
Conditionally returned

An array of program transfer objects.

This array is returned if it exists in the resource.

Allowable Values:

A valid data object

data[].amount

decimal
Conditionally returned

Amount of program transfer.

This field is returned if it exists in the resource.

Allowable Values:

Format: 0.00

data[].business_token

string
Conditionally returned

The unique identifier of the business.

This field is returned if it exists in the resource.

Allowable Values:

1–36 chars

data[].created_time

datetime
Conditionally returned

The date and time when the program transfer object was created, in UTC. 2021-10-26T20:03:05Z, for example.

Allowable Values:

Format: yyyy-MM-ddTHH:mm:ssZ

data[].currency_code

string
Conditionally returned

The three-digit ISO 4217 currency code.

This field is returned if it exists in the resource.

Allowable Values:

A valid three-digit ISO 4217 currency code

data[].fees

array of objects
Conditionally returned

Contains attributes that define characteristics of one or more fees.

This array is returned if it exists in the resource.

Allowable Values:

A valid fees object

data[].fees[].fee

object
Returned

Contains details about the fee.

This object is returned if it exists in the resource.

Allowable Values:

A valid fees.fee object

data[].fees[].fee.active

boolean
Returned

Indicates whether the fee is active.

This field is returned if it exists in the resource.

Allowable Values:

true, false

data[].fees[].fee.amount

decimal
Returned

The amount of the fee.

Allowable Values:

Format: 0.00

data[].fees[].fee.created_time

datetime
Returned

The date and time when the fees object was created, in UTC. 2021-10-26T20:03:05Z, for example.

Allowable Values:

Format: yyyy-MM-ddTHH:mm:ssZ

data[].fees[].fee.currency_code

string
Returned

The three-digit ISO 4217 currency code.

Allowable Values:

A valid three-digit ISO 4217 currency code

data[].fees[].fee.last_modified_time

datetime
Returned

The date and time when the fees object was created, in UTC. 2021-10-26T20:03:05Z, for example.

Allowable Values:

Format: yyyy-MM-ddTHH:mm:ssZ

data[].fees[].fee.name

string
Returned

The name of the fees object.

Allowable Values:

50 char max

data[].fees[].fee.real_time_assessment

object
Conditionally returned

Controls the assessment of real-time fees.

This field is returned if it exists in the resource.

Allowable Values:

A valid real_time_fee_assessment object

data[].fees[].fee.real_time_assessment.domestic_enabled

boolean
Conditionally returned

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

This field is returned if it exists in the resource.

Allowable Values:

true, false

data[].fees[].fee.real_time_assessment.international_enabled

boolean
Conditionally returned

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

This field is returned if it exists in the resource.

Allowable Values:

true, false

data[].fees[].fee.real_time_assessment.transaction_type

string
Conditionally returned

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

This field is returned if it exists in the resource.

Allowable Values:

authorization, pindebit.atm.withdrawal, pindebit

data[].fees[].fee.tags

string
Conditionally returned

Descriptive metadata about the fee.

This field is returned if it exists in the resource.

Allowable Values:

255 char max

data[].fees[].fee.token

string
Returned

The unique identifier of the fee.

This field is returned if it exists in the resource.

Allowable Values:

36 char max

data[].fees[].memo

string
Conditionally returned

Additional text that describes the fee.

This field is returned if it exists in the resource.

Allowable Values:

1–99 chars

data[].fees[].tags

string
Conditionally returned

Comma-delimited list of tags describing the fee.

This field is returned if it exists in the resource.

Allowable Values:

255 char max

data[].fees[].token

string
Returned

The unique identifier of the fee.

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

Allowable Values:

1–36 chars

data[].fees[].transaction_token

string
Returned

Unique identifier of the transaction.

Allowable Values:

Format: UUID

end_index

integer
Conditionally returned

The sort order index of the last resource in the returned array.

Allowable Values:

Any integer

is_more

boolean
Conditionally returned

A value of true indicates that more unreturned resources exist.

Allowable Values:

true, false

start_index

integer
Conditionally returned

The sort order index of the first resource in the returned array.

Allowable Values:

Any integer

Sample response body
JSON
Copied

Is this helpful?

Yes
No

Retrieve program transfer

Action: GET
Endpoint: /programtransfers/{token}

Use this endpoint to retrieve a specific program transfer. Include the program transfer token path parameter to specify the program transfer to retrieve.

URL path parameters
Fields Description

token

string
Required

Program transfer token

Allowable Values:

Existing program transfer token

Response body
Fields Description

amount

decimal
Conditionally returned

Amount of program transfer.

This field is returned if it exists in the resource.

Allowable Values:

Format: 0.00

business_token

string
Conditionally returned

The unique identifier of the business.

This field is returned if it exists in the resource.

Allowable Values:

1–36 chars

created_time

datetime
Conditionally returned

The date and time when the program transfer object was created, in UTC. 2021-10-26T20:03:05Z, for example.

This field is returned if it exists in the resource.

Allowable Values:

Format: yyyy-MM-ddTHH:mm:ssZ

currency_code

string
Conditionally returned

The three-digit ISO 4217 currency code.

This field is returned if it exists in the resource.

Allowable Values:

A valid three-digit ISO 4217 currency code

fees

array of objects
Conditionally returned

Contains attributes that define characteristics of one or more fees.

This array is returned if it exists in the resource.

Allowable Values:

A valid fees object

fees[].fee

object
Returned

Contains details about the fee.

Allowable Values:

A valid fees.fee object

fees[].fee.active

boolean
Returned

Indicates whether the fee is active.

Allowable Values:

true, false

fees[].fee.amount

decimal
Returned

The amount of the fee.

Allowable Values:

Format: 0.00

fees[].fee.created_time

datetime
Returned

The date and time when the fees object was created, in UTC. 2021-10-26T20:03:05Z, for example.

Allowable Values:

Format: yyyy-MM-ddTHH:mm:ssZ

fees[].fee.currency_code

string
Returned

The three-digit ISO 4217 currency code.

Allowable Values:

A valid three-digit ISO 4217 currency code

fees[].fee.last_modified_time

datetime
Returned

The date and time when the fees object was created, in UTC. 2021-10-26T20:03:05Z, for example.

Allowable Values:

Format: yyyy-MM-ddTHH:mm:ssZ

fees[].fee.name

string
Returned

The name of the fees object.

Allowable Values:

50 char max

fees[].fee.real_time_assessment

object
Conditionally returned

Controls the assessment of real-time fees.

This field is returned if it exists in the resource.

Allowable Values:

A valid real_time_fee_assessment object

fees[].fee.real_time_assessment.domestic_enabled

boolean
Conditionally returned

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

This field is returned if it exists in the resource.

Allowable Values:

true, false

fees[].fee.real_time_assessment.international_enabled

boolean
Conditionally returned

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

This field is returned if it exists in the resource.

Allowable Values:

true, false

fees[].fee.real_time_assessment.transaction_type

string
Conditionally returned

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

This field is returned if it exists in the resource.

Allowable Values:

authorization, pindebit.atm.withdrawal, pindebit

fees[].fee.tags

string
Conditionally returned

Descriptive metadata about the fee.

This field is returned if it exists in the resource.

Allowable Values:

255 char max

fees[].fee.token

string
Returned

The unique identifier of the fee.

This field is returned if it exists in the resource.

Allowable Values:

36 char max

fees[].memo

string
Conditionally returned

Additional text that describes the fee.

This field is returned if it exists in the resource.

Allowable Values:

1–99 chars

fees[].tags

string
Conditionally returned

Comma-delimited list of tags describing the fee.

This field is returned if it exists in the resource.

Allowable Values:

255 char max

fees[].token

string
Returned

The unique identifier of the fee.

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

Allowable Values:

1–36 chars

fees[].transaction_token

string
Returned

Unique identifier of the transaction.

Allowable Values:

Format: UUID

Sample response body
JSON
Copied

Is this helpful?

Yes
No

Create program transfer type

Action: POST
Endpoint: /programtransfers/types

Use this endpoint to create a program transfer type. Add the program transfer details to the body of the request in JSON format.

You are required to pass in a program_funding_source_token to associate a program funding source with the program transfer type. You must therefore create a program funding source before creating a program transfer type.

Request body
Fields Description

memo

string
Required

Memo or note describing the program transfer type.

Allowable Values:

1–99 chars

program_funding_source_token

string
Required

Identifies the program funding source to which program transfers will be credited.

Send a GET request to /fundingsources/program to retrieve program funding source tokens.

Allowable Values:

1–36 chars

tags

string
Optional

Comma-delimited list of tags describing the program transfer type.

Allowable Values:

1–255 chars

token

string
Optional

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

Sample request body
JSON
Copied

Is this helpful?

Yes
No
Response body
Fields Description

created_time

datetime
Conditionally returned

The date and time when the program transfer type object was created, in UTC. 2021-10-26T20:03:05Z, for example.

This field is returned if it exists in the resource.

Allowable Values:

Format: yyyy-MM-ddTHH:mm:ssZ

last_modified_time

datetime
Conditionally returned

The date and time when the program transfer type object was last modified, in UTC. 2021-10-26T20:03:05Z, for example.

This field is returned if it exists in the resource.

Allowable Values:

Format: yyyy-MM-ddTHH:mm:ssZ

memo

string
Conditionally returned

Memo or note describing the program transfer type.

This field is returned if it exists in the resource.

Allowable Values:

99 char max

program_funding_source_token

string
Returned

Identifies the program funding source to which program transfers will be credited.

Allowable Values:

Token of existing program funding source

tags

string
Conditionally returned

Comma-delimited list of tags describing the program transfer type.

This field is returned if it exists in the resource.

Allowable Values:

255 char max

token

string
Returned

The unique identifier of the program transfer type request object.

Allowable Values:

36 char max

Sample response body
JSON
Copied

Is this helpful?

Yes
No

List program transfer types

Action: GET
Endpoint: /programtransfers/types

Use this endpoint to list all program transfer types.

This endpoint supports field filtering, pagination, and sorting.

URL query parameters
Fields Description

count

integer
Optional

The number of program transfer types to retrieve.

Allowable Values:

1-10

start_index

integer
Optional

The sort order index of the first resource in the returned array.

Allowable Values:

Any integer

fields

string
Optional

Comma-delimited list of fields to return (field_1,field_2, and so on). Leave blank to return all fields.

Allowable Values:

A comma-delimited list of fields, or blank

sort_by

string
Optional

Field on which to sort. Use any field in the resource model, or one of the system fields lastModifiedTime or createdTime. Prefix the field name with a hyphen (-) to sort in descending order. Omit the hyphen to sort in ascending order.

Allowable Values:

lastModifiedTime, createdTime, or any field in the resource model

Response body
Fields Description

count

integer
Conditionally returned

The number of program transfer resources to retrieve.

Allowable Values:

1-10

data

array of objects
Conditionally returned

An array of program transfer types.

This array is returned if it exists in the resource.

Allowable Values:

A valid data array

data[].created_time

datetime
Conditionally returned

The date and time when the program transfer type object was created, in UTC. 2021-10-26T20:03:05Z, for example.

This field is returned if it exists in the resource.

Allowable Values:

Format: yyyy-MM-ddTHH:mm:ssZ

data[].last_modified_time

datetime
Conditionally returned

The date and time when the program transfer type object was last modified, in UTC. 2021-10-26T20:03:05Z, for example.

This field is returned if it exists in the resource.

Allowable Values:

Format: yyyy-MM-ddTHH:mm:ssZ

data[].memo

string
Conditionally returned

Memo or note describing the program transfer type.

This field is returned if it exists in the resource.

Allowable Values:

99 char max

data[].program_funding_source_token

string
Returned

Identifies the program funding source to which program transfers will be credited.

Allowable Values:

Token of existing program funding source

data[].tags

string
Conditionally returned

Comma-delimited list of tags describing the program transfer type.

This field is returned if it exists in the resource.

Allowable Values:

255 char max

data[].token

string
Returned

The unique identifier of the program transfer type request object.

Allowable Values:

36 char max

end_index

integer
Conditionally returned

The sort order index of the last resource in the returned array.

This field is returned if it exists in the resource.

Allowable Values:

Any integer

is_more

boolean
Conditionally returned

A value of true indicates that more unreturned resources exist.

Allowable Values:

true, false

start_index

integer
Conditionally returned

The sort order index of the first resource in the returned array.

Allowable Values:

Any integer

Sample response body
JSON
Copied

Is this helpful?

Yes
No

Update program transfer type

Action: PUT
Endpoint: /programtransfers/types/{type_token}

Use this endpoint to update a program transfer type. Include the type_token path parameter to indicate the program transfer type to update. Add the modified detail parameters to the body of the request in JSON format. Only values of parameters in the request are modified; all others are left unchanged.

URL path parameters
Fields Description

type_token

string
Required

The unique identifier of the program transfer type.

Allowable Values:

Existing program transfer type token

Request body
Fields Description

memo

string
Required

Memo or note describing the program transfer type.

Allowable Values:

1–99 chars

program_funding_source_token

string
Required

Identifies the program funding source to which program transfers will be credited.

Send a GET request to /fundingsources/program to retrieve program funding source tokens.

Allowable Values:

1–36 chars

tags

string
Optional

Comma-delimited list of tags describing the program transfer type.

Allowable Values:

1–255 chars

token

string
Optional

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

Sample request body
JSON
Copied

Is this helpful?

Yes
No
Response body
Fields Description

created_time

datetime
Conditionally returned

The date and time when the program transfer type object was created, in UTC. 2021-10-26T20:03:05Z, for example.

This field is returned if it exists in the resource.

Allowable Values:

Format: yyyy-MM-ddTHH:mm:ssZ

last_modified_time

datetime
Conditionally returned

The date and time when the program transfer type object was last modified, in UTC. 2021-10-26T20:03:05Z, for example.

This field is returned if it exists in the resource.

Allowable Values:

Format: yyyy-MM-ddTHH:mm:ssZ

memo

string
Conditionally returned

Memo or note describing the program transfer type.

This field is returned if it exists in the resource.

Allowable Values:

99 char max

program_funding_source_token

string
Returned

Identifies the program funding source to which program transfers will be credited.

Allowable Values:

Token of existing program funding source

tags

string
Conditionally returned

Comma-delimited list of tags describing the program transfer type.

This field is returned if it exists in the resource.

Allowable Values:

255 char max

token

string
Returned

The unique identifier of the program transfer type request object.

Allowable Values:

36 char max

Sample response body
JSON
Copied

Is this helpful?

Yes
No

Retrieve program transfer type

Action: GET
Endpoint: /programtransfers/types/{type_token}

Use this endpoint to retrieve a specific program transfer. Include the type_token path parameter to indicate the program transfer type to return.

URL path parameters
Fields Description

type_token

string
Required

The unique identifier of the program transfer type.

Allowable Values:

Existing program transfer type token

Response body
Fields Description

created_time

datetime
Conditionally returned

The date and time when the program transfer type object was created, in UTC. 2021-10-26T20:03:05Z, for example.

This field is returned if it exists in the resource.

Allowable Values:

Format: yyyy-MM-ddTHH:mm:ssZ

last_modified_time

datetime
Conditionally returned

The date and time when the program transfer type object was last modified, in UTC. 2021-10-26T20:03:05Z, for example.

This field is returned if it exists in the resource.

Allowable Values:

Format: yyyy-MM-ddTHH:mm:ssZ

memo

string
Conditionally returned

Memo or note describing the program transfer type.

This field is returned if it exists in the resource.

Allowable Values:

99 char max

program_funding_source_token

string
Returned

Identifies the program funding source to which program transfers will be credited.

Allowable Values:

Token of existing program funding source

tags

string
Conditionally returned

Comma-delimited list of tags describing the program transfer type.

This field is returned if it exists in the resource.

Allowable Values:

255 char max

token

string
Returned

The unique identifier of the program transfer type request object.

Allowable Values:

36 char max

Sample response body
JSON
Copied

Is this helpful?

Yes
No
Join our developer newsletter