Bill Configurations

The bill configurations resource enables you to configure and manage associations between biller accounts and users on the Marqeta platform. A biller is a service provider or a creditor to whom a user can make a payment.

After you configure a biller account association for a user, you can start using the bill payments feature described on the Bill Payments page.

List billers

Action: GET
Endpoint: /billconfigurations/billers

List all billers to which users can make payments.

This endpoint supports sorting and pagination.

Query parameters

Name Type Required? Description Allowable Values
name string No The biller name. 255 char max
category string No The biller category. 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"
        },
        ...
    ]
}


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. You must include either the account number or the username and password associated with the account.

If you create a biller account association for a credit card using a username and password, the API response prompts you to confirm the account by sending the full PAN in a PUT request to /billconfigurations/accounts/{token}. The biller account association remains in the PENDING status until you confirm the PAN.

If your user has multiple accounts with a biller, 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. You must present the matching accounts 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.

The biller account association remains in the PENDING status until you confirm the account number and the required personally identifying information is present.

Body fields detail

Name Type Required? Description Allowable Values
token string No The unique identifier of the biller account association.

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.
36 char max
name string No The name of the biller account association. 255 char max
user_token string Yes The unique identifier of the user. 36 char max
biller_token string Yes The unique identifier of the biller. 36 char max
account_number string Yes, if username/password are not provided. 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.
50 char max
username string No The username of the user.

Note: You must include username/password in the request body for billers that provide balance updates.
password string No The password of the user.
payer_data object Yes The personally identifiable information of the user. See the payer_data object

The payer_data object

Name Type Required? Description Allowable Values
birth_date string Yes The date of birth of the user. Format: yyyy-MM-dd
phone_number string Yes The phone number of the user. 36 char max
first_name string Yes, if username/password are not provided. The first name of the user. 255 char max
last_name string Yes, if username/password are not provided. The last name of the user. 255 char max
address string No The street address of the user. 255 char max
city string Yes The city of the user. 36 char max
state string Yes The state of the user. 2 char max
postal_code string No The postal code of the user. 36 char max

The status field (response only)

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

Status Description
PENDING Account details of the user are being validated.
ACTIVE Account details have been validated, and the biller account is linked to the user.
DEACTIVATED The account association is deactivated.
SUSPENDED The account association is suspended.

For billers that provide balance updates, account associations start in the PENDING status and transition to the ACTIVE status after the username/password provided in the request are verified.

For billers that do not provide balance updates, account associations start in the ACTIVE status.

You can deactivate a biller account association in the ACTIVE status by sending a POST /billconfigurations/accounts/transitions request with the status field of the request body set to DEACTIVATED.

The reason and reason_code fields (response only)

Reason Code Reason
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"
   }
}

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"
}


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

Name Type Required? Description Allowable Values
token string Yes The unique identifier of the biller account association you want to update. Existing biller account association token.

Body fields detail

Name Type Required? Description Allowable Values
name string No The name of the biller account association. 255 char max
account_number string Yes, if username/password are not provided. 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.
50 char max
username string No The username of the user.
password string No The password of the user.
payer_data object No The personally identifiable information of the user. See the payer_data object
mfa_challenge_answers array of mfa_challenge_answer objects No The multi-factor authentication (MFA) challenge answers. See the mfa_challenge_answer object

The payer_data object

Name Type Required? Description Allowable Values
birth_date string No The date of birth of the user. Format: yyyy-MM-dd
phone_number string No The phone number of the user. 36 char max
first_name string No The first name of the user. 255 char max
last_name string No The last name of the user. 255 char max
address string No The street address of the user. 255 char max
city string No The city of the user. 36 char max
state string No The state of the user. 2 char max
postal_code string No The postal code of the user. 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.

Name Type Required? Description Allowable Values
id string Yes ID or UUID of the challenge that is being answered.
type string Yes Type of challenge. code | question | image | choice | image_choice
response string Yes 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.

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

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

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 Reason
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"
}

Sample request body


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

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"
}


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

Name Type Required? Description Allowable Values
token string Yes The unique identifier of the biller account association you want to retrieve. 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"
    }
}


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

Name Type Required? Description Allowable Values
user_token string No The unique identifier of the user whose biller account associations you want to list. Existing user token.
biller_token string No The unique identifier of the biller whose biller account associations you want to list. Existing biller token.
status string No The status (or a comma-separated list of statuses) of the biller account associations you want to list. 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"
            }
        }
    ]
}


Create biller account association transition

Action: POST
Endpoint: /billconfigurations/accounts/transitions

Change a biller account association status, for example from ACTIVE to DEACTIVATED.

Body fields detail

Name Type Required? Description Allowable Values
token string No The unique identifier of the biller account association transition. 36 char max
account_token string Yes The unique identifier of the biller account association. 36 char max
status string Yes The new status of the biller account association. DEACTIVATED
reason string No The reason for the biller account association status change. 255 char max
channel string No The channel by which the status change occurred. 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"
}

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"
}


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

Name Type Required? Description Allowable Values
token string Yes The unique identifier of the biller account association transition to retrieve. 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"
}


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

Name Type Required? Description Allowable Values
account_token string No The unique identifier of the biller account association whose transitions you want to list. Existing biller account association token.
status string No The status (or a comma-separated list of statuses) of the transitions you want to list. PENDING | ACTIVE | DEACTIVATED | SUSPENDED
user_token string No The unique identifier of the user. 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"
        }
    ]
}