DOCS

New!

/

20 minute read

October 2, 2019

Bill Configurations (Beta)

The bill configurations resource enables you to list billers, create associations between biller accounts and users on the Marqeta platform, and create biller account subscriptions that initiate recurring bill payments. A biller is a service provider or a creditor to whom a user can make a payment.

After you create a biller account association for a user, you can initiate bill payments (see Bill Payments) and create biller account subscriptions.

Tip
To learn about bill payments and debt consolidation, see the Managing Bill Payments guide.

List billers

Action: GET
Endpoint: /billconfigurations/billers

List all billers to which users can make payments.

This endpoint supports sorting and pagination.

Query parameters

Fields Description

name

string, optional

The biller name.

Allowable Values:

255 char max

bin

string, optional

The biller’s bank identification number (BIN).

Allowable Values:

Must be 6 or 8 char

category

string, optional

The biller category.

Allowable Values:

255 char max

Sample response body

{
     "count": 10,
     "start_index": 0,
     "end_index": 9,
     "is_more": false,
     "data": [
         {
             "token": "368ebf14-c07e-4702-bce9-411d09abc652",
             "name": "City Water Company",
             "balance_updates_available": false,
             "currency_code": "USD",
             "category": "Water",
             "masks": [
                 "###"
             ],
             "created_time": "2018-09-18T18:23:57Z"
         },
         {
             "token": "9c215342-a4d1-4d10-a8f6-b4647088eb81",
             "name": "Local Bank",
             "balance_updates_available": true,
             "currency_code": "USD",
             "category": "Money",
             "masks": [
                 "###"
             ],
             "created_time": "2018-09-18T18:23:57Z"
         },
         {
             "token": "2fe8144f-d666-4531-9d8c-48683d396c3c",
             "name": "State Phone Company",
             "balance_updates_available": true,
             "currency_code": "USD",
             "category": "Telecom",
             "masks": [
                 "###"
             ],
             "created_time": "2018-09-18T18:23:57Z"
         },
         ...
      ]
 }

Is this helpful?

Create biller account association

Action: POST
Endpoint: /billconfigurations/accounts

Create an association between an account at the biller and a user on the Marqeta platform.

Note
A newly created biller account association may start in the PENDING status. For how to transition an association to the ACTIVE status, see The status field (response) table.

Body field details

Fields Description

token

string, optional

The unique identifier of the biller account association.

If you do not include a token, the system automatically generates one. This token is necessary for use in other API calls. It is recommended that, rather than let the system, you create a simple, easy-to-remember string. This value cannot be updated.

Allowable Values:

36 char max

name

string, optional

The name of the biller account association.

Allowable Values:

255 char max

user_token

string, required

The unique identifier of the user.

Allowable Values:

36 char max

biller_token

string, required

The unique identifier of the biller.

Allowable Values:

36 char max

account_number

string, optional

The user account number at the biller.

Required if username and password are not included in the request body, or if paying a credit card biller.

Allowable Values:

50 char max

username

string, optional

The username of the user.

Required if account_number is not included in the request body, or if paying a credit card biller.

Include this field in the request body if the biller provides balance updates.

Allowable Values:

password

string, optional

The password of the user.

Required if account_number is not included in the request body, or if paying a credit card biller.

Include this field in the request body if the biller provides balance updates.

Allowable Values:

payer_data

object, required

The personally identifiable information of the user.

Allowable Values:

See the payer_data object

The payer_data object

Fields Description

birth_date

string, required

The date of birth of the user.

Allowable Values:

yyyy-MM-ddb

phone_number

string, required

The telephone number of the user.

Allowable Values:

36 char max

first_name

string, optional

The first name of the user.

Allowable Values:

255 char max

last_name

string, optional

The last name of the user.

Allowable Values:

255 char max

address

string, optional

The street address of the user.

Allowable Values:

255 char max

city

string, required

The city of the user.

Allowable Values:

36 char max

state

string, required

The state of the user.

Allowable Values:

2 char max

postal_code

string, optional

The postal code of the user.

Allowable Values:

36 char max

The status field (response only)

A biller account association can have one of the following statuses:

Status Description Status Transition

PENDING

Account details of the user are being validated.

A biller account association starts or remains in the this status if:

  • The biller provides balance updates.

  • The biller account is being associated with a credit card using a username and password, but the PAN has not been confirmed.

  • The user has multiple accounts with a biller and the correct account has not been confirmed. In this case, the API response includes the mfa_challenges object containing an array of the matching accounts and a prompt to have the user select the correct account.

A biller account association in this status can transition to the ACTIVE status after:

  • If the biller provides balance updates, the username/password provided in the request are verified.

  • You confirm the account associated with a credit card using a username/password. To confirm, send the full PAN in a PUT request to /billconfigurations/accounts/{token}.

  • You confirm the correct account for a user that has multiple accounts with a biller. To confirm, present the matching accounts in the mfa_challenges_answers object to the user and, based on the input received, send a PUT request to /billconfigurations/accounts/{token} containing one of the following:

    • The mfa_challenge_answers object with the index of the correct account; see The mfa_challenge_answers object on this page for more information.

    • The account_number field with the correct account number and the payer_data object with the required personally identifying information.

ACTIVE

Account details have been validated, and the biller account is linked to the user.

A biller account association starts in the this status if the biller does not provide balance updates.

A biller account association in this status can transition to the DEACTIVATED status:

  • Send a POST request to /billconfigurations/accounts/transitions with the status field of the request body set to DEACTIVATED.

DEACTIVATED

The account association is deactivated.

SUSPENDED

The account association is suspended.

The reason and reason_code fields (response only)

Reason Code Description

01

Account number format does not match mask. Please update account number

02

Account number is PAN. Please confirm account number by sending full PAN

03

An error occurred, could not connect to biller. Please create a new account

Sample request body

{
    "name": "My Biller Account",
    "user_token": "db731ccf-31ac-4188-be21-7065c2a48905",
    "biller_token": "368ebf14-c07e-4702-bce9-411d09abc652",
    "account_number": "4222422244",
     "payer_data": {
       "birth_date": "1991-01-01",
       "first_name": "Blue",
       "last_name": "Bird",
       "phone_number": "5551234567",
       "city": "Berkeley",
       "state": "CA"
    }
 }

Is this helpful?

Sample response body

{
     "token": "c7b42bf2-b5ac-4de2-aaf6-9e802eacf92c",
     "name": "My Biller Account",
     "user_token": "db731ccf-31ac-4188-be21-7065c2a48905",
     "biller_token": "368ebf14-c07e-4702-bce9-411d09abc652",
     "account_number": "******2244",
     "status": "ACTIVE",
     "payer_data": {
         "birth_date": "1991-01-01",
         "first_name": "Blue",
         "last_name": "Bird",
         "phone_number": "5551234567",
         "city": "Berkeley",
         "state": "CA"
     },
     "created_time": "2018-09-27T18:40:16Z",
     "last_modified_time": "2018-09-27T18:40:16Z"
 }

Is this helpful?

Update biller account association

Action: PUT
Endpoint: /billconfigurations/accounts/{token}

Update a specific biller account association. Include the biller account association token as the path parameter.

URL path parameters

Fields Description

token

string, required

The unique identifier of the biller account association you want to update.

Allowable Values:

Existing biller account association token.

Body field details

Fields Description

name

string, optional

The name of the biller account association.

Allowable Values:

255 char max

account_number

string, optional

The user account number at the biller.

Note
You must include either the account number or the username/password in the request body, not both.

Allowable Values:

50 char max

username

string, optional

The username of the user.

Allowable Values:

password

string, optional

The password of the user.

Allowable Values:

payer_data

object, optional

The personally identifiable information of the user.

Allowable Values:

See the payer_data object

mfa_challenge_answers

array of mfa_challenge_answer objects, optional

The multi-factor authentication (MFA) challenge answers.

Allowable Values:

See the mfa_challenge_answer object

The payer_data object

Fields Description

birth_date

string, optional

The date of birth of the user.

Allowable Values:

yyyy-MM-dd

phone_number

string, optional

The telephone number of the user.

Allowable Values:

36 char max

first_name

string, optional

The first name of the user.

Allowable Values:

255 char max

last_name

string, optional

The last name of the user.

Allowable Values:

255 char max

address

string, optional

The street address of the user.

Allowable Values:

255 char max

city

string, optional

The city of the user.

Allowable Values:

36 char max

state

string, optional

The state of the user.

Allowable Values:

2 char max

postal_code

string, optional

The postal code of the user.

Allowable Values:

36 char max

The mfa_challenge_answers object

The multi-factor authentication (MFA) challenges are questions intended to verify the identity of the user. The answers are entered by the user as part of the multi-factor authentication process.

Fields Description

id

string, required

ID or UUID of the challenge that is being answered.

Allowable Values:

type

string, required

Type of challenge.

Allowable Values:

code, question, image, choice, image_choice

response

string, required

If the type is code or question, the answer to the challenge. If the type is image, the size of the image. If the type is choice or image_choice, the index of the correct choice.

Allowable Values:

This table describes values for each type in the mfa_challenge_answers object:

Challenge type Description

code

A verification code sent to a user’s mobile phone and required for login. Verification codes cannot be reused.

question

A challenge question that the user must answer correctly to log in.

image

An image that the user must select to log in.

choice

A multiple-choice question that the user must answer correctly to log in.

image_choice

Multiple images from which the user must select the correct ones to log in.

The following sample shows an mfa_challenge_answers object that answers a "choice" type challenge.

{
  "mfa_challenge_answers": [
    {
      "id":"18eb7f6d-4cf1-48a0-a515-dd773aaadd03",
      "type":"choice",
      "response":"0"
    }
  ]
}

Is this helpful?

The connectivity object (response only)

The connectivity object is included in the response body for billers that provide balance updates. This object has the following fields:

Name Description

status

This field indicates the status of the request processing and can have the following values: SYNCING, WAITING_MFA, SYNCED, ERROR.

reason_code

This field is included only when the status field is equal to ERROR.

reason

This field is included only when the status field is equal to ERROR.

The following table describes possible values of the reason_code and reason fields:

Reason Code Description

01

There was a temporary connection error, please try again later.

02

Invalid username or password.

03

Incorrect or expired identification answer.

04

Balance not yet available for this biller.

The following sample shows a connectivity object with an ERROR status:

"connectivity": {
    "status": "ERROR",
    "reason_code": "02",
    "reason": "Invalid username or password"
}

Is this helpful?

Sample request body

{
    "username": "bluebird@gmail.com",
    "password": "HeLl0o1!",
    "payer_data": {
       "phone_number": "510-111-1111"
    }
 }

Is this helpful?

Sample response body

{
     "token": "2099a533-66f6-45e0-92cc-516a8652cb52",
     "user_token": "db731ccf-31ac-4188-be21-7065c2a48905",
     "biller_token": "9c215342-a4d1-4d10-a8f6-b4647088eb81",
     "account_number": "******2244",
     "status": "ACTIVE",
     "balance": 59.87,
     "balance_due_date": "2018-10-01",
     "balance_updated": "2018-09-01 12:00:00",
     "currency_code": "USD",
     "connectivity": {
         "status": "SYNCED"
     },
     "payer_data": {
         "birth_date": "1991-01-01",
         "phone_number": "510-111-1111",
         "first_name": "Blue",
         "last_name": "Bird",
         "city": "Berkeley",
         "state": "CA"
     },
     "created_time": "2018-09-27T18:40:16Z",
     "last_modified_time": "2018-09-27T20:56:45Z"
 }

Is this helpful?

Retrieve biller account association

Action: GET
Endpoint: /billconfigurations/accounts/{token}

Retrieve a specific biller account association. Include the biller account association token as the path parameter.

URL path parameters

Fields Description

token

string, required

The unique identifier of the biller account association you want to retrieve.

Allowable Values:

Existing biller account association token.

Sample response body

{
     "token": "c5482bbe-0f46-4e30-b660-3b1bb0ea773f",
     "user_token": "db731ccf-31ac-4188-be21-7065c2a48905",
     "biller_token": "2fe8144f-d666-4531-9d8c-48683d396c3c",
     "account_number": "******2244",
     "status": "ACTIVE",
     "balance": 63.42,
     "balance_due_date": "2018-10-01",
     "balance_updated": "2018-09-01 12:00:00",
     "currency_code": "USD",
     "connectivity": {
         "status": "SYNCED"
     },
     "payer_data": {
         "birth_date": "1991-01-01",
         "phone_number": "510-111-1111",
         "first_name": "Blue",
         "last_name": "Bird",
         "address": "1234 Blake Street",
         "city": "Berkeley",
         "state": "CA",
         "postal_code": "94702"
     }
 }

Is this helpful?

List biller account associations

Action: GET
Endpoint: /billconfigurations/accounts

List all biller account associations related to a specific user, biller, and/or status.

This endpoint supports sorting and pagination.

Query parameters

Fields Description

user_token

string, optional

The unique identifier of the user whose biller account associations you want to list.

Allowable Values:

Existing user token.

biller_token

string, optional

The unique identifier of the biller whose biller account associations you want to list.

Allowable Values:

Existing biller token.

status

string, optional

The status (or a comma-separated list of statuses) of the biller account associations you want to list.

Allowable Values:

PENDING, ACTIVE, DEACTIVATED, SUSPENDED

Sample response body

{
     "count": 1,
     "start_index": 0,
     "end_index": 0,
     "is_more": false,
     "data": [
         {
             "token": "c5482bbe-0f46-4e30-b660-3b1bb0ea773f",
             "user_token": "db731ccf-31ac-4188-be21-7065c2a48905",
             "biller_token": "2fe8144f-d666-4531-9d8c-48683d396c3c",
             "account_number": "******2244",
             "status": "ACTIVE",
             "balance": 63.42,
             "balance_due_date": "2018-10-01",
             "balance_updated": "2018-09-01 12:00:00",
             "currency_code": "USD",
             "connectivity": {
                 "status": "SYNCED"
             },
             "payer_data": {
                 "birth_date": "1991-01-01",
                 "phone_number": "510-111-1111",
                 "first_name": "Blue",
                 "last_name": "Bird",
                 "address": "1234 Blake Street",
                 "city": "Berkeley",
                 "state": "CA",
                 "postal_code": "94702"
             }
         }
     ]
 }

Is this helpful?

Create biller account association transition

Action: POST
Endpoint: /billconfigurations/accounts/transitions

Create a transition to change the status of a biller account association, for example from ACTIVE to DEACTIVATED.

Body field details

Fields Description

token

string, optional

The unique identifier of the biller account association transition.

Allowable Values:

36 char max

account_token

string, required

The unique identifier of the biller account association.

Allowable Values:

36 char max

status

string, required

The new status of the biller account association.

Allowable Values:

DEACTIVATED

reason

string, optional

The reason for the biller account association status change.

Allowable Values:

255 char max

channel

string, optional

The channel by which the status change occurred.

Allowable Values:

API

Sample request body

{
    "token": "ce56e8a6-6162-423f-8dc6-e0ccab5ef70b",
    "account_token": "c5482bbe-0f46-4e30-b660-3b1bb0ea773f",
    "status": "DEACTIVATED",
    "reason": "Deactivating a biller account association",
    "channel": "API"
 }

Is this helpful?

Sample response body

{
     "token": "ce56e8a6-6162-423f-8dc6-e0ccab5ef70b",
     "user_token": "my_user",
     "account_token": "c5482bbe-0f46-4e30-b660-3b1bb0ea773f",
     "status": "DEACTIVATED",
     "reason": "Deactivating a biller account association",
     "channel": "API",
     "created_time": "2018-09-20T23:18:45Z"
 }

Is this helpful?

Retrieve biller account association transition

Action: GET
Endpoint: /billconfigurations/accounts/transitions/{token}

Retrieve a specific biller account association transition. Include the biller account association transition token as the path parameter.

URL path parameters

Fields Description

token

string, required

The unique identifier of the biller account association transition to retrieve.

Allowable Values:

Existing biller account association transition token.

Sample response body

{
     "token": "ce56e8a6-6162-423f-8dc6-e0ccab5ef70b",
     "user_token": "my_user",
     "account_token": "c5482bbe-0f46-4e30-b660-3b1bb0ea773f",
     "status": "DEACTIVATED",
     "reason": "Deactivating a biller account association",
     "channel": "API",
     "created_time": "2018-09-20T23:18:46Z"
 }

Is this helpful?

List biller account association transitions

Action: GET
Endpoint: /billconfigurations/accounts/transitions

List all biller account association transitions associated with a specific account and/or status.

This endpoint supports sorting and pagination.

Query parameters

Fields Description

account_token

string, optional

The unique identifier of the biller account association whose transitions you want to list.

Allowable Values:

Existing biller account association token.

status

string, optional

The status (or a comma-separated list of statuses) of the transitions you want to list.

Allowable Values:

PENDING, ACTIVE, DEACTIVATED, SUSPENDED

user_token

string, optional

The unique identifier of the user.

Allowable Values:

Existing user token.

Sample response body

{
     "count": 1,
     "start_index": 0,
     "end_index": 0,
     "is_more": false,
     "data": [
         {
             "token": "ce56e8a6-6162-423f-8dc6-e0ccab5ef70b",
             "user_token": "my_user",
             "account_token": "c5482bbe-0f46-4e30-b660-3b1bb0ea773f",
             "status": "DEACTIVATED",
             "reason": "Deactivating a biller account association",
             "channel": "API",
             "created_time": "2018-09-20T23:18:46Z"
         }
     ]
 }

Is this helpful?

Create biller account subscription

Action: POST
Endpoint: /billconfigurations/subscriptions

Create a biller account subscription that initiates bill payments on a set schedule. Specify details of the subscription in the config object.

Note
Subscriptions begin initiating bill payments at 6AM on the specified payment day. Failed bill payments due to a server issue will be automatically retried. If it is after the given cutoff time for the day, the bill payment will be processed on the following day.

Body field details

Fields Description

token

string, optional

The unique identifier of the biller account subscription.

If you do not include a token, the system generates 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

account_token

string, required

The unique identifier of the biller account association.

Allowable Values:

36 char max

name

string, optional

The name of the biller account subscription.

Allowable Values:

255 char max

config

object, required

The details of the biller account subscription, including the amount and frequency of payments.

Allowable Values:

The config object

Fields Description

amount

decimal, required

Amount of the recurring payment, in the specified currency

Allowable Values:

Default value: USD

Format: 0.00

Note
If variable_amount is true, and your biller account association receives balance updates from the biller, bill payments use the updated balance as the payment amount, not this value. If a balance is not available, bill payments use this amount value.

start_date

string, optional

Date when the subscription begins initiating bill payments.

Allowable Values:

yyyy-mm-dd

Default value: Today’s date

To ensure the initial bill payment is processed on time, enter a value later than today’s date.

expiration_date

string, optional

Date when the subscription stops initiating bill payments; required if number_of_payments is null.

Allowable Values:

yyyy-mm-dd

Value must be later than today’s date.

number_of_payments

integer, optional

Number of bill payments to initiate before ending the subscription; required if expiration_date is null.

Allowable Values:

days_of_month

array, optional

Array of integers indicating the days of each month on which bill payments should be initiated.

Allowable Values:

Array of integers 1-28.

Default value: Day in start_date, or [1] if start_date day is 29-31.

frequency

string, optional

Time interval for initiating bill payments.

Allowable Values:

MONTHLY, QUARTERLY, SEMI-ANNUAL, YEARLY

Default value: MONTHLY

variable_amount

boolean, optional

If true, the bill payment’s amount is based on the balance provided by the biller. Requires balance updates from the biller; refer to the associated biller account association.

Allowable Values:

TRUE, FALSE

Default value: FALSE

The status field (response only)

A biller account subscription can have one of the following statuses:

Status Description

ACTIVE

The biller account subscription is initiating bill payments as configured.

CANCELLED

The biller account subscription was ended.

EXPIRED

The biller account subscription ended because there is no next payment before the expiration date or number of payments was reached.

ERROR

An error occurred and the biller account subscription is not initiating bill payments.

Sample request body

{
  "token": "my_subscription_token",
  "account_token": "my_account_token",
  "name": "My Subscription",
  "config": {
    "amount": 100,
    "start_date": "2019-05-01",
    "expiration_date": "2019-012-31",
    "days_of_month": [1],
    "frequency": "MONTHLY"
  }
}

Is this helpful?

Sample response body

{
  "token": "my_subscription_token",
  "account_token": "my_account_token",
  "name": "My Subscription",
  "status": "ACTIVE",
  "next_payment_date": "2019-05-01",
  "config": {
    "amount": 100,
    "currency_code": "USD",
    "start_date": "2019-05-01",
    "expiration_date": "2019-12-31",
    "days_of_month": [1],
    "frequency": "MONTHLY"
  },
  "created_time": "2018-04-14T22:17:46Z",
  "last_modified_time": "2018-04-14T22:17:46Z"
}

Is this helpful?

Update biller account subscription

Action: PUT
Endpoint: /billconfigurations/subscriptions/{token}

Update a biller account subscription.

Note
You can only update start_date if the first bill payment has not yet been initiated.

URL path parameters

Fields Description

token

string, required

The unique identifier of the biller account subscription you want to update.

Allowable Values:

Existing biller account subscription token.

Body field details

Fields Description

name

string, optional

The name of the biller account subscription.

Allowable Values:

255 char max

config

object, optional

The details of the biller account subscription, including the amount and frequency of payments.

Allowable Values:

The config object

Fields Description

amount

decimal, optional

Amount of the payment, in the specified currency.

Allowable Values:

Format: 0.00

Default value: USD

start_date

string, optional

Date when the subscription begins initiating bill payments.

Allowable Values:

yyyy-mm-dd

Default value: Today’s date

expiration_date

string, optional

Date when the subscription stops initiating bill payments; required if number_of_payments is null.

Allowable Values:

yyyy-mm-dd

number_of_payments

integer, optional

Number of bill payments to initiate before ending the subscription; required if expiration_date is null.

Allowable Values:

days_of_month

array, optional

Array of integers indicating the days of each month on which bill payments should be initiated.

Allowable Values:

Array of integers 1-28.

Default value: Day in start_date, or [1] if start_date day is 29-31.

frequency

string, optional

Time interval for initiating bill payments.

Allowable Values:

MONTHLY, QUARTERLY, SEMI-ANNUAL, YEARLY

Default value: MONTHLY

variable_amount

boolean, optional

If true, adjusts the payment amount based on the balance provided by the biller. Requires balance updates from the biller; refer to the associated biller account association.

Allowable Values:

TRUE, FALSE

Default value: FALSE

Sample request body

{
  "config" : {
    "amount": 120.00
  }
}

Is this helpful?

Sample response body

{
  "token": "my_subscription_token",
  "account_token": "my_account_token",
  "name": "My Subscription",
  "status": "ACTIVE",
  "next_payment_date": "2019-05-01",
  "config": {
    "amount": 120.00,
    "currency_code": "USD",
    "start_date": "2019-05-01",
    "expiration_date": "2019-12-31",
    "days_of_month": [1],
    "frequency": "MONTHLY"
  },
  "created_time": "2018-04-14T22:17:46Z",
  "last_modified_time": "2018-04-14T23:22:31Z"
}

Is this helpful?

Retrieve biller account subscription

Action: GET
Endpoint: /billconfigurations/subscriptions/{token}

Retrieve a specific biller account subscription by including its token in the URL path of your request.

URL path parameters

Fields Description

token

string, required

The unique identifier of the biller account subscription you want to retrieve.

Allowable Values:

Existing biller account subscription token.

Sample response body

{
  "token": "my_subscription_token",
  "account_token": "my_account_token",
  "name": "My Subscription",
  "status": "ACTIVE",
  "next_payment_date": "2019-05-01",
  "config": {
    "amount": 120.00,
    "currency_code": "USD",
    "start_date": "2019-05-01",
    "expiration_date": "2019-12-31",
    "days_of_month": [1],
    "frequency": "MONTHLY"
  },
  "created_time": "2018-04-14T22:17:46Z",
  "last_modified_time": "2018-04-14T23:22:31Z"
}

Is this helpful?

List biller account subscriptions

Action: GET
Endpoint: /billconfigurations/subscriptions

List biller account subscriptions.

Query parameters

Fields Description

account_token

string, optional

The unique identifier of the biller account association.

Allowable Values:

Existing biller account association token.

user_token

string, optional

The unique identifier of the user.

Allowable Values:

Existing user token.

status

string, optional

The status of the biller account subscription.

Allowable Values:

ACTIVE, CANCELLED, EXPIRED, ERROR

Sample response body

{
  "count": 1,
  "start_index": 0,
  "end_index": 0,
  "is_more": false,
  "data": [
    {
      "token": "my_subscription_token",
      "account_token": "my_account_token",
      "name": "My Subscription",
      "status": "ACTIVE",
      "next_payment_date": "2019-05-01",
      "config": {
        "amount": 120.00,
        "currency_code": "USD",
        "start_date": "2019-05-01",
        "expiration_date": "2019-12-31",
        "days_of_month": [1],
        "frequency": "MONTHLY"
      },
      "created_time": "2018-04-14T22:17:46Z",
      "last_modified_time": "2018-04-14T23:22:31Z"
    }
  ]
}

Is this helpful?

Create biller account subscription transition

Action: POST
Endpoint: /billconfigurations/subscriptions/transitions

Create a transition to change the status of a biller account subscription, for example from ACTIVE to CANCELLED.

Body field details

Fields Description

token

string, optional

The unique identifier of the biller account subscription transition.

If you do not include a token, the system generates 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

subscription_token

string, required

The unique identifier of the biller account subscription.

Allowable Values:

Existing biller account subscription.

status

string, required

The new status of the biller account subscription.

Allowable Values:

ACTIVE, CANCELLED

reason

string, optional

The reason for the biller account subscription status change.

Allowable Values:

255 char max

channel

string, optional

The channel by which the status change occurred.

Allowable Values:

API, SYSTEM

Default value: SYSTEM

Sample request body

{
  "token: "my_subscription_transition_token",
  "subscription_token": "my_subscription_token",
  "status": "CANCELLED",
  "reason": "Cancelled bill payments",
  "channel": "API"
}

Is this helpful?

Sample response body

{
  "token": "my_subscription_transition_token",
  "subscription_token": "my_subscription_token",
  "user_token": "my_user_token",
  "status": "CANCELLED",
  "reason": "Cancelled bill payments",
  "channel": "API",
  "created_time": "2018-04-16T14:02:03Z"
}

Is this helpful?

Retrieve biller account subscription transition

Action: GET
Endpoint: /billconfigurations/subscriptions/transitions/{token}

Retrieve a specific biller account subscription transition by including its token in the URL path of your request.

URL path parameters

Fields Description

token

string, required

The unique identifier of the biller account subscription transition you want to retrieve.

Allowable Values:

Existing biller account subscription transition token.

Sample response body

{
  "token": "my_subscription_transition_token",
  "subscription_token": "my_subscription_token",
  "user_token": "my_user_token",
  "status": "CANCELLED",
  "reason": "Cancelled bill payments",
  "channel": "API",
  "created_time": "2018-04-16T14:02:03Z"
}

Is this helpful?

List biller account subscription transitions

Action: GET
Endpoint: /billconfigurations/subscriptions/transitions

Query parameters

Fields Description

subscription_token

string, optional

The unique identifier of the biller account subscription.

Allowable Values:

Existing biller account subscription token.

user_token

string, optional

The unique identifier of the user associated with the biller account subscription.

Allowable Values:

Existing user token.

status

string, optional

The status of the biller account subscription.

Allowable Values:

ACTIVE, CANCELLED, EXPIRED, ERROR

Sample response body

{
  "count": 1,
  "start_index": 0,
  "end_index": 0,
  "is_more": false,
  "data": [
    {
      "token": "my_subscription_transition_token",
      "subscription_token": "my_subscription_token",
      "user_token": "my_user_token",
      "status": "CANCELLED",
      "reason": "Cancelled bill payments",
      "channel": "API",
      "created_time": "2018-04-16T14:02:03Z"
    }
  ]
}

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.