Managing Bill Payments (Beta)

Hidden

This page is strictly internal to Marqeta, and is not to be shared outside the organization.

A bill payment is a transaction that sends funds to a biller, such as a service provider or creditor, on behalf of your users. The Marqeta platform enables you to manage one-time or recurring bill payments, and to consolidate debt. Use the Bill Configurations API to list billers, create an association between a biller account and user, and configure a recurring bill payment by creating a biller account subscription. Once configured, use the Bill Payments API to initiate, track, and reverse a bill payment. Note that this version of Bill Payments supports only ACH payments. By the end of this guide, you should understand:

What one-off and recurring bill payments are.
How the debt consolidation process works.
How to initiate, track, and reverse a bill payment.

Bill Payments

Use bill payments to send funds to vendors or creditors to pay off bills and loans, such as utility bills, internet bills, auto loans, or student loans. Bill payments can be one-off or recurring. A recurring bill payment is a funds transfer scheduled to recur on a set time interval and predetermined day of the month. For more on setting up a recurring bill payment, see the Create biller account subscription section of the Bill Configurations API reference.

Debt Consolidation

The debt consolidation process enables you to pay off your user’s previous debts and transfer the balance to you, combining all their debts into one loan. Transferring the balance to you means they will no longer owe their previous creditors, offering immediate relief. Debt consolidation can also lower a user’s monthly payments and reduce their risk profile.

Tutorial

This tutorial walks you through how to configure, initiate, and reverse a bill payment.

Prerequisites

Read the Core API Quick Start.
Obtain a user token.

Step 1 — Obtain a biller token

Send a GET request to the /billconfigurations/billers endpoint to return an array of billers. If desired, include the following URL query parameters:

name – Set to the biller’s name.
bin – Set to the biller’s BIN.
category – Set to the biller’s category.

For example, the following URL returns a list of billers named Water Company categorized under utilities.

HTTP

/billconfigurations/billers?name=watercompany&category=utilities

The biller token is represented in the response body by the token value.

JSON

{
     "count": 10,
     "start_index": 0,
     "end_index": 9,
     "is_more": false,
     "data": [
         {
             "token": "368ebf14-c07e-4702-bce9-411d09abc652",
             "name": "Water Company",
             "balance_updates_available": false,
             "currency_code": "USD",
             "category": "utilities",
             "masks": [
                 "###"
             ],
             "created_time": "2018-09-18T18:23:57Z"
         },
         ...
      ]
}

Step 2 — Associate the biller and the user

In order to pay a biller, the user on the Marqeta platform must be associated with an account at the biller. This association is called a biller account association. To create one, send a POST request to the /billconfigurations/accounts endpoint with at least the following fields included:

token – Set the value to a unique identifier of the biller account association. If you do not include a token, the system generates one automatically.
user_token – Set to the value of the user token.
biller_token – Set to the value of the biller token obtained in Step 1.
account_number – You must include either the user’s account number or their username/password at the biller, but rarely both. Include username and password only if the biller provides balance updates; otherwise, include account number. Include both if paying a credit card biller.
The payer_data object – Contains personally identifiable information (PII) for the user’s account at the biller. Define at least the following required fields: birth_date, phone_number, city, state.

The following code block shows a sample biller account association as it would appear in a POST request:

JSON

{
    "token": "mywaterbilleraccountassociationtoken1234",
    "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"
    }
 }

Step 3 (Optional) — Configure a recurring bill payment

To create biller account subscription that initiates recurring bill payments on a set schedule (in this case, quarterly), send a POST request to the /billconfigurations/subscriptions endpoint with the following fields included:

token (Optional) – Set the value to a unique identifier of the biller account subscription. If you do not include a token, the system generates one automatically.
account_token – Set to the token value of the biller account association defined in Step 2, to which recurring payments are made.
The config object – Contains information on the details of the subscription. Define at least the following fields:
- Set the amount field to the value of the recurring payment.
- (Optional) Set the frequency field to QUARTERLY to initiate payments quarterly. Default is monthly.
- (Optional) Set the days_of_month field to 1 to initiate payments on the 1st day of each month.

The following code block shows a sample biller account subscription as it would appear in a POST request:

JSON

{
  "token": "mywaterbilleraccountsubscriptiontoken1111",
  "account_token": "mywaterbilleraccountassociationtoken1234",
  "name": "My Water Subscription",
  "config": {
    "amount": 20,
    "days_of_month": [1],
    "frequency": "QUARTERLY"
  }
}

Step 4 — Initiate a bill payment

To initiate a bill payment, send a POST request to the /billpayments endpoint with at least the following fields included:

token (Optional) – Set the value to a unique identifier of the bill payment. If you do not include a token, the system generates one automatically.
account_token – Set to the token value of the biller account association defined in Step 2, to which bill payments are made.
amount – Set the value to the amount of the bill.
memo (Optional) – Set the value to a description of the bill payment.

The following code block shows a sample bill payment as it would appear in a POST request:

JSON

{
    "token": "mywaterbillpaymenttoken0044",
    "account_token": "mywaterbilleraccountassociationtoken1234",
    "memo": "My water bill payment #44",
    "amount": 23.87,
 }

Step 5 (Optional) — Reverse the bill payment

A manual reversal can only be performed if the bill payment’s status is INITIATED. To retrieve a bill payment’s status, send a GET request to the /billpayments/{token} endpoint with the bill payment token as the path parameter. The bill payment’s status is represented in the response body as status.

To manually reverse the bill payment initiated in the previous step, send a POST request to the /billpayments/transitions endpoint with at least the following fields defined:

token (Optional) – Set the value to a unique identifier of the bill payment transition; in this case, a reversal. If you do not include a token, the system generates one automatically.
bill_payment_token – Set to the token value of the bill payment defined in Step 4.
status – Set to REVERSED.
reason – Set to the reason for the reversal.

The following code block shows a sample bill payment reversal as it would appear in a POST request:

JSON

{
    "token": "mywaterbillpayment0044reversaltoken",
    "bill_payment_token": "mywaterbillpaymenttoken0044",
    "status": "REVERSED",
    "reason": "Accidentally paid the wrong biller",
 }

Webhooks notifications

The Marqeta platform pushes webhook-style notifications in response to bill configuration and payment transition events.

For more on webhook-enabled events for bill payments, see the configuration and payment transition events section of the Event Types guide.
To learn about how the Marqeta platform uses webhooks, see the About Webhooks guide.
To learn how to configure a webhook, see the Webhooks API reference.

Guides

Documentation Index

​Bill Payments

​Debt Consolidation

​Tutorial

​Prerequisites

​Step 1 — Obtain a biller token

​Step 2 — Associate the biller and the user

​Step 3 (Optional) — Configure a recurring bill payment

​Step 4 — Initiate a bill payment

​Step 5 (Optional) — Reverse the bill payment

​Webhooks notifications

Bill Payments

Debt Consolidation

Tutorial

Prerequisites

Step 1 — Obtain a biller token

Step 2 — Associate the biller and the user

Step 3 (Optional) — Configure a recurring bill payment

Step 4 — Initiate a bill payment

Step 5 (Optional) — Reverse the bill payment

Webhooks notifications