Bill Payments

The bill payments resource enables you to initiate, track, and reverse bill payments. A bill payment is a transaction that sends funds to billers on behalf of your users.

To use the bill payments feature, you must first create an association between the user who wants to pay a bill and the biller who receives the funds, as described on the Bill Configurations page.

Create bill payment

Action: POST
Endpoint: /billpayments

Initiate a bill payment for an account.

Body fields detail

Name Type Required? Description Allowable Values
token string No The unique identifier of the bill payment. 36 char max
account_token string Yes The unique identifier of the biller account. 36 char max
memo string No The description of the payment. 255 char max
amount decimal Yes The amount of the payment, in the specified currency (USD by default). Format: 0.00
currency_code string No The 3-character ISO 4217 currency code. USD

The status field (response only)

A bill payment can have one of the following statuses:

Status Description
REJECTED The bill payment was rejected due to a failed precondition, such as the user was not found or there were insufficient funds in the account associated with the user to fund the bill payment.
INITIATED There were sufficient funds in the account associated with the user to fund the bill payment, and the payment details could be verified.
SENT The bill payment is being processed by the card network.
CONFIRMED The bill payment is being processed by the biller.
REVERSED The biller could not process the bill payment, or the payment was reversed by the user.
APPLIED The bill payment was successfully paid to the biller.

A bill payment starts in one of the following statuses: INITIATED (if the funds are sufficient and the payment details can be verified) or REJECTED (if it is rejected due to a failed precondition).

You can reverse the bill payment in the INITIATED status by sending a POST /billpayments/transitions request with the status field of the request body set to REVERSED.

From the INITIATED status, the bill payment transitions to the SENT status after the payment is sent to the biller.

From the SENT status, the bill payment transitions to one of the following statuses: REVERSED (if the biller cannot process the payment) or APPLIED (if the bill payment is successfully paid to the biller).

Sample request body


   "token": "fb0bddfb-11c9-4833-bbee-550f5bece3c3",
   "account_token": "2099a533-66f6-45e0-92cc-516a8652cb52",
   "memo": "My monthly car loan payment",
   "amount": 59.87,
   "currency_code": "USD"
}

Sample response body

{
    "token": "fb0bddfb-11c9-4833-bbee-550f5bece3c3",
    "account_token": "2099a533-66f6-45e0-92cc-516a8652cb52",
    "user_token": "db731ccf-31ac-4188-be21-7065c2a48905",
    "memo": "My monthly car loan payment",
    "amount": 59.87,
    "currency_code": "USD",
    "status": "INITIATED",
    "created_time": "2018-09-20T21:47:10Z",
    "last_modified_time": "2018-09-20T21:47:10Z"
}


Retrieve bill payment

Action: GET
Endpoint: /billpayments/{token}

Retrieve a specific bill payment. Include the bill payment token as the path parameter.

URL path parameters

Name Type Required? Description Allowable Values
token string Yes The unique identifier of the bill payment you want to retrieve. Existing bill payment token.

Sample response body

{
    "token": "fb0bddfb-11c9-4833-bbee-550f5bece3c3",
    "account_token": "2099a533-66f6-45e0-92cc-516a8652cb52",
    "user_token": "db731ccf-31ac-4188-be21-7065c2a48905",
    "memo": "My monthly car loan payment",
    "amount": 59.87,
    "currency_code": "USD",
    "status": "INITIATED",
    "created_time": "2018-09-20T21:47:11Z",
    "last_modified_time": "2018-09-20T21:47:11Z"
}


List bill payments

Action: GET
Endpoint: /billpayments

List all bill payments associated with a specific account, user, 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 whose bill payments you want to list. Existing biller account token.
user_token string No The unique identifier of the user whose bill payments you want to list. Existing user token.
status string No The status (or a comma-separated list of statuses) of the bill payments you want to list. REJECTED | INITIATED | SENT | REVERSED | APPLIED

Sample response body

{
    "count": 3,
    "start_index": 0,
    "end_index": 2,
    "is_more": false,
    "data": [
        {
            "token": "fb0bddfb-11c9-4833-bbee-550f5bece3c3",
            "account_token": "2099a533-66f6-45e0-92cc-516a8652cb52",
            "user_token": "db731ccf-31ac-4188-be21-7065c2a48905",
            "memo": "My monthly car loan payment",
            "amount": 59.87,
            "currency_code": "USD",
            "status": "INITIATED",
            "created_time": "2018-09-20T21:47:11Z",
            "last_modified_time": "2018-09-20T21:47:11Z"
        },
        {
            "token": "ad62a0e3-880a-45a8-b2fc-5ab7cb077518",
            "account_token": "c7b42bf2-b5ac-4de2-aaf6-9e802eacf92c",
            "user_token": "db731ccf-31ac-4188-be21-7065c2a48905",
            "memo": "My monthly water bill",
            "amount": 23.64,
            "currency_code": "USD",
            "status": "SENT",
            "created_time": "2018-09-20T18:21:08Z",
            "last_modified_time": "2018-09-20T18:21:08Z"
        },
        {
            "token": "ad62a0e3-880a-45a8-b2fc-5ab7cb077565",
            "account_token": "c5482bbe-0f46-4e30-b660-3b1bb0ea773f",
            "user_token": "db731ccf-31ac-4188-be21-7065c2a48905",
            "memo": "My monthly phone bill",
            "amount": 63.42,
            "currency_code": "USD",
            "status": "APPLIED",
            "created_time": "2018-09-20T18:20:40Z",
            "last_modified_time": "2018-09-20T18:20:40Z"
        }
    ]
}


Create bill payment transition

Action: POST
Endpoint: /billpayments/transitions

Change a bill payment status, for example to reverse a bill payment.

Body fields detail

Name Type Required? Description Allowable Values
token string No The unique identifier of the bill payment transition. 36 char max
bill_payment_token string Yes The unique identifier of the bill payment. 36 char max
status string Yes The new status of the bill payment. REVERSED
reason string No The reason for the bill payment status change. 255 char max
channel string No The channel by which the status change occurred. API

Sample request body


   "token": "fe193ab0-962f-4115-bbb3-62c107077ccc",
   "bill_payment_token": "fb0bddfb-11c9-4833-bbee-550f5bece3c3",
   "status": "REVERSED",
   "reason": "Reversing a bill payment",
   "channel": "API"
}

Sample response body

{
    "token": "fe193ab0-962f-4115-bbb3-62c107077ccc",
    "bill_payment_token": "fb0bddfb-11c9-4833-bbee-550f5bece3c3",
    "transaction_token": "62862eb8-75ca-4e43-8ce2-41d91bea29b9",
    "user_token": "db731ccf-31ac-4188-be21-7065c2a48905",
    "status": "REVERSED",
    "reason": "Reversing a bill payment",
    "channel": "API",
    "created_time": "2018-09-20T22:59:34Z"
}


Retrieve bill payment transition

Action: GET
Endpoint: /billpayments/transitions/{token}

Retrieve a specific bill payment transition. Include the bill payment transition token as the path parameter.

URL path parameters

Name Type Required? Description Allowable Values
token string Yes The unique identifier of the bill payment transition to retrieve. Existing bill payment transition token.

Sample response body

{
    "token": "fe193ab0-962f-4115-bbb3-62c107077ccc",
    "bill_payment_token": "fb0bddfb-11c9-4833-bbee-550f5bece3c3",
    "transaction_token": "62862eb8-75ca-4e43-8ce2-41d91bea29b9",
    "user_token": "db731ccf-31ac-4188-be21-7065c2a48905",
    "status": "REVERSED",
    "reason": "Reversing a bill payment",
    "channel": "API",
    "created_time": "2018-09-20T22:59:35Z"
}


List bill payment transitions

Action: GET
Endpoint: /billpayments/transitions

List all bill payment transitions associated with a specific bill payment, user, and/or status.

This endpoint supports sorting and pagination.

Query parameters

Name Type Required? Description Allowable Values
bill_payment_token string No The unique identifier of the bill payment whose transitions you want to list. Existing bill payment token.
user_token string No The unique identifier of the user whose bill payment transitions you want to list. Existing user token.
status string No The status (or a comma-separated list of statuses) of the transitions you want to list. REJECTED | INITIATED | SENT | REVERSED | APPLIED

Sample response body

{
    "count": 1,
    "start_index": 0,
    "end_index": 0,
    "is_more": false,
    "data": [
        {
            "token": "fe193ab0-962f-4115-bbb3-62c107077ccc",
            "bill_payment_token": "fb0bddfb-11c9-4833-bbee-550f5bece3c3",
            "transaction_token": "62862eb8-75ca-4e43-8ce2-41d91bea29b9",
            "user_token": "db731ccf-31ac-4188-be21-7065c2a48905",
            "status": "REVERSED",
            "reason": "Reversing a bill payment",
            "channel": "API",
            "created_time": "2018-09-20T22:59:35Z"
        }
    ]
}