DOCS

New!

/

5 minute read

October 2, 2019

Managing Bill Payments

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
The current 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

Step one. 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.

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

Is this helpful?

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

{
     "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"
         },
         ...
      ]
}

Is this helpful?

Step two. 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 one.

  • 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:

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

Is this helpful?

Step three. Configure a recurring bill payment (Optional)

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 two, 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:

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

Is this helpful?

Step four. 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 two, 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:

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

Is this helpful?

Step five. (Optional) Reverse the bill payment

Note
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 four.

  • 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:

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

Is this helpful?

Webhooks notifications

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

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.