DOCS

New!

/

5 minute read

August 2, 2019

Bill Payments (Beta)

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.

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

Create bill payment

Action: POST
Endpoint: /billpayments

Initiate a bill payment for an account.

Body field details

Fields Description

token

string, optional

The unique identifier of the bill payment.

Allowable Values: 36 char max

account_token

string, required

The unique identifier of the biller account.

Allowable Values: 36 char max

memo

string, optional

The description of the payment.

Allowable Values: 255 char max

amount

decimal, required

The amount of the payment, in the specified currency.

Allowable Values: Format: 0.00

Default value: USD

currency_code

string, optional

The 3-character ISO 4217 currency code.

Allowable Values: USD

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

Is this helpful?

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

Is this helpful?

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

Fields Description

token

string, required

The unique identifier of the bill payment you want to retrieve.

Allowable Values: Existing bill payment token.

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.

A newly created bill payment can start in this status.

INITIATED

There were sufficient funds in the account associated with the user to fund the bill payment, and the payment details could be verified.

A newly created bill payment can start in this status.

A bill payment in this status can transition to:

  • REVERSED - If manually reversed. To reverse the bill payment, send a POST request to /billpayments/transitions with the status field set to REVERSED.

  • SENT - If the payment was sent to the biller.

  • ON_HOLD - If the bill payment is stuck in this status for two or more days.

SENT

The bill payment was sent to the biller and is being processed by the card network.

A bill payment in this status can transition to:

  • REVERSED - If biller cannot process the payment.

  • APPLIED - If the bill payment is successfully paid to the biller.

  • ON_HOLD - If the bill payment is stuck in this status for two or more days.

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.

ON_HOLD

The bill payment has expired from being stuck in the INITIATE or SENT status for two or more days.

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

Is this helpful?

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

Fields Description

account_token

string, optional

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

Allowable Values: Existing biller account token.

user_token

string, optional

The unique identifier of the user whose bill payments you want to list.

Allowable Values: Existing user token.

status

string, optional

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

Allowable Values: 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"
         }
     ]
 }

Is this helpful?

Create bill payment transition

Action: POST
Endpoint: /billpayments/transitions

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

Body field details

Fields Description

token

string, optional

The unique identifier of the bill payment transition.

Allowable Values: 36 char max

bill_payment_token

string, required

The unique identifier of the bill payment.

Allowable Values: 36 char max

status

string, required

The new status of the bill payment.

Allowable Values: REVERSED

reason

string, optional

The reason for the bill payment 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": "fe193ab0-962f-4115-bbb3-62c107077ccc",
    "bill_payment_token": "fb0bddfb-11c9-4833-bbee-550f5bece3c3",
    "status": "REVERSED",
    "reason": "Reversing a bill payment",
    "channel": "API"
 }

Is this helpful?

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

Is this helpful?

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

Fields Description

token

string, required

The unique identifier of the bill payment transition to retrieve.

Allowable Values: 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"
 }

Is this helpful?

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

Fields Description

bill_payment_token

string, optional

The unique identifier of the bill payment whose transitions you want to list.

Allowable Values: Existing bill payment token.

user_token

string, optional

The unique identifier of the user whose bill payment transitions you want to list.

Allowable Values: Existing user token.

status

string, optional

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

Allowable Values: 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"
         }
     ]
 }

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.