Bill Pay

Before getting started

This guide will assume you've already created and authenticated a user. If you haven't done that then please first read our User Connect guide.

Overview

There are a number of steps that need to be carried out in order to make a bill payment. At a high level, these are:

1. Create a partner payer
2. Verify that partner payer
3. Fund your account
4. Checking to make sure a liability is payable
5. Make a payment to a liability

Follow along with the steps below to help you through the process or get started with our Payments API Reference.

📘

Be sure to subscribe to the USER_PAYMENT_STATUS webhook

Check out the webhook here!

Creating and verifying a partner payer

To initiate a bill payment on the Spinwheel platform, the first step is to create a partner payer. By doing so, an entity will be created that can be utilized to finance all payments. You have the freedom to add numerous partner payers to your organization.

Please note that there is a verification process necessary to finalize the creation of a partner payer. This involves a micro-deposit flow, which requires you to verify two recent bank account transactions and send an API call to confirm these transactions. This step is crucial in ensuring that the correct bank account has been connected.

Funding your account

After successfully creating your partner payer, the next step is to fund your account by making a payment to platform. By doing so, you can ensure that there are sufficient funds available in your account to cover any payments that need to be made.

We will emit a PLATFORM_PAYMENT_STATUS webhook to notify you of the payment status after this step.

Checking to ensure a liability is payable

🚧

Check the Capabilities Matrix

Billers may or may not be available for payment processing, you can verify this on the institution's capabilities matrix

With all liabilities returned on a user, there is a section for each liability which dictates the supported functionality you can utilize with that liability. We call this the capabilities matrix, and when it comes to payments there are a few key statuses to be aware of.

SUPPORTED

Liabilities which show SUPPORTED in the bill pay section of the capabilities matrix are able to have payments submitted for them, as we have a connection for payments with that creditor and the specific account.

"payments": {  
                        "billPayment": {  
                            "availability": "SUPPORTED"  
                        }  
                    }

NOT_SUPPORTED

Liabilities which show NOT_SUPPORTED in the bill pay section of the capabilities matrix are not able to have payments submitted for them. Reason codes are frequently provided in a description field, however the end result is that these liabilities are not payable.

"payments": {  
                        "billPayment": {  
                            "availability": "NOT_SUPPORTED"  
                        }  
                    }

FIELD_ERROR

Liabilities which show FIELD_ERROR in the bill pay section of the capabilities matrix are able to have payments submitted for them, but only after an action is taken for that account. For the example noted below, the most common case for this is that the account number needs to be updated for a credit card. In this case, if you wanted to make a payment to this liability, the user would need to update the account number of the liability using the credit-card-update drop-in module.

"payments": {
                        "billPayment": {
                            "availability": "FIELD_ERROR",
                            "fieldErrors": [
                                {
                                    "field": "CREDIT_CARD_NUMBER",
                                    "error": "NOT_PRESENT"
                                }
                            ]
                        }
                    }

Making a payment

The final step is to create a payment request. Simply call the linked endpoint and we will emit a USER_PAYMENT_STATUS webhook to update you on the payment's status.

To learn more about our debt APIs and full product suite, visit spinwheel.io.