Pay

Overview

At its core, payments are meant to be a straightforward flow: connect a user, fetch a debt profile, and find out what you can (and can't) pay.

That third step is the one that most payment integrations get wrong. Instead of telling you upfront what's payable, a lot of platforms make you find out by trying — submit a request and wait to see if it bounces. Spinwheel's capabilities matrix flips that around.

Every liability on a consumer’s debt profile tells you, before you ever submit a payment, whether it's SUPPORTED, needs an account number update, or simply isn't payable. No guessing games and your user experience can react to it directly: show, flag, or filter it out.

Once you've reviewed what you can pay, what needs an account number update, and what to disqualify from your experience, the rest of the flow is simple:

1. Fund your FBO account.
2. Submit your liability payments.
3. Track them.

You can query the status of any transaction at any time, but you shouldn't have to do so. The moment a transaction's status changes, Spinwheel sends it to you via webhook — from when it's scheduled with the institution to the moment the payment is applied. You'll always know where a payment stands without needing to ask.

Built to Grow With You

We don't try to lock you into using Spinwheel for payments forever. We understand that as your organization scales, payments is a function you may eventually want to bring in-house, or move to your own rails.

Whether you're using Spinwheel to fully execute payments today or just to get clean, verified disbursement data for your own infrastructure, we give you the flexibility to adjust as your needs change. See Using Spinwheel Disbursement Data Only for what that looks like in practice.

Setting Up Payments

Setting up payments requires a few foundational pieces before your first payment request. Get these right once, and every payment will follow the same pattern afterwards.

1. Set Up Your FBO Funding Flow

The first requirement is a proper funding flow through an FBO (for benefit of) account dedicated to your funds. This is the account Spinwheel disburses from when your liability payments are submitted. Think of it as pre-funding the well that payments draw from, kept entirely separate from your operating capital.

1. Set Up Your FBO Funding Flow

The first requirement is a proper funding flow through an FBO (for benefit of) account dedicated to your funds. This is the account Spinwheel disburses from when your liability payments are submitted. Think of it as pre-funding the well that payments draw from, kept entirely separate from your operating capital.

2. Decide How You'll Fund the Account

Once your FBO account is in place, the decision point is how you want to get money into it. That choice mostly comes down to your volume and use case:

• Paying down large volumes daily: If you're moving millions of dollars toward debt on a daily basis, wiring funds in directly from your operating account is typically the right call — it gives you the fastest, most predictable funding mechanism at scale.
• Paying on behalf of individual end users: If you're funding transactions one end user at a time and don’t own the consumer’s bank account, you'll want to look at our payment to platform flow instead, which is built for that per-user pattern. If you do own their bank account, discuss your options with your Spinwheel account owner.

Cut-Off Times

Funding speed and payment settlement both run on defined cut-off windows. Plan around these when deciding how to fund and when to submit:

---

With funding in place, you're ready to move into either using Spinwheel Direct Pay or Disbursement Data Only, depending on which model fits your integration.

Using Spinwheel Direct Pay

If you're using Spinwheel to facilitate payments directly to the liabilities themselves, the flow below is what you'll follow — end to end, from connection to a completed payment.

1. Set Up Your Webhooks

Before you submit your first payment, make sure your webhook subscriptions are in place. This is what lets you track the full lifecycle of every payment without polling for it.

At minimum, subscribe to:

• USER_PAYMENT_STATUS: Fires your flows, we make the full account number available to consume via the profile data.
• Credit Card Name & Art: A consumer's real card program and card art, without needing sensitive account details.
• Vehicle Attributes: Make, model, trim, and year, from a VIN or license plate.
• Real-time balances and payoff summaries: Layered on top of the bureau data via the capabilities matrix above.
• The result is one standardized view inste on every status change for a liability payment, from SCHEDULING through to a terminal state like APPLIED, FAILED, or RETURNED.
• PLATFORM_PAYMENT_STATUS: Fires when a payment to platform (funding your FBO account) changes status.

A representative USER_PAYMENT_STATUS payload looks like this:

{"userId": "e1b0d89d-6d86-4ff6-a2ab-46b99e2c1b1e", "status": "SCHEDULED", "statusComment": "Scheduled payment towards loan account", "requestId": "a564cbf8-8669-481d-ad4b-82843462b31c", "transactionRequestId": "c8301530-b77e-46c5-9c03-8d3233ff6b8d"}

2. Confirm Your Funds Flow

Make sure your FBO funding flow is fully set up and confirmed. Direct Pay draws from this account to fund every liability payment you submit, so this needs to be in place before you go any further.

3. Connect, Pull a Debt Profile, and Check the Capabilities Matrix

With funding and webhooks in place, the sequence for every user is the same:

• Connect
• Pull a debt profile
• Pay

Before submitting a payment, evaluate the liability's entry in the capabilities matrix. This is the earliest point where you'll know whether that liability is actually payable — not after a failed attempt, but from the first look at a consumer’s debt profile.

The bill pay section of the capabilities matrix returns one of three states:

SUPPORTED: The liability can have a payment submitted directly, no further action needed.

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

NOT_SUPPORTED: The liability isn't payable through Spinwheel. A reason code is often included in the description field so you know why, without having to ask.

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

FIELD_ERROR: The liability is payable, but only after you resolve a specific issue first. The most common case is a credit card account number that needs to be refreshed via API or the credit-card-update drop-in module.

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

This is the same message that runs through the rest of our platform. No guessing what’s payable or submitting a request and hoping for the best. Spinwheel’s capability matrix tells you upfront — supported, needs something from you, or not possible — so you can react accordingly before a user ever sees a failed payment.

4. Submit the Payment

Once a liability shows SUPPORTED, submit a payment request against it. Spinwheel handles scheduling with the creditor and keeps you updated via the USER_PAYMENT_STATUS webhook — all the way through to APPLIED.

Using Spinwheel Disbursement Data Only

If you already have your own payment rails, or you're looking to graduate to new ones, we've got you covered. You don't have to route payments through Spinwheel to benefit from the data behind them.

Out of the box, we support fetching the proper payee information for the liabilities you're looking to pay — the same verified account, routing, and creditor details that power Direct Pay, just handed to you to execute on your own infrastructure instead.

The Capabilities Matrix Remains Key

Even without submitting a payment through Spinwheel, the capabilities matrix remains your starting point. It tells you, per liability, whether disbursement data is available and payable.

Fetching Disbursement Data

Instead of submitting a payment request, you'll call the disbursement data endpoint to retrieve payee information for a supported liability — account and routing details, creditor identifiers, and anything else your own payment rails need to originate the transaction.

This path is built for two situations in particular

• You already run your own payment infrastructure and want verified, current payee data without duplicating a payments stack.
• You're planning to move off Spinwheel Direct Pay as you scale, and want a clean way to bring payments in-house without losing the data quality you started with.

Either way, the switch between models doesn't lock you out or force a rebuild. It's the same underlying data, just handed off at a different point in the flow.

Payments Requirements

Spinwheel operates on a good funds model. In practical terms, this means you're responsible for making sure your FBO account has adequate funds in place before liability payments are pushed out against it.

We don't leave you to track that blind. A few things make it easier to stay ahead of your funding position:

• Simplified reporting on your account activity, so you can see funding and disbursement in one place rather than reconciling across systems.
• A balance endpoint to check your current FBO balance on demand.
• Additional checks built into the payment flow to help catch a shortfall before it becomes a failed transaction.

The responsibility for adequate funding sits with you, but the tools to stay on top of it are built in from Day 1 — not something you have to build or monitor separately.

Verifying a Payer

Before a payer can initiate a payment-to-platform, Spinwheel needs to confirm that they own the bank account. There are two ways to do this:

Verify with a Plaid Token (Recommended)

When a consumer has already connected and verified their bank account through Plaid Link,, Spinwheel can confirm ownership as soon as you create the payer. There's no waiting, and the payer can start ACH payments right away.

How It Works

1. The consumer selects a bank account through Plaid Link.
2. Your application exchanges the Plaid public token for a Plaid processor token.
3. You call the Create a Payer endpoint with tokenType: "PLAID" and the processor token.
4. Spinwheel validates the token and verifies that the consumer owns the bank account.
5. The payer can initiate ACH payments immediately.

Example Request

{"firstName": "John", "lastName": "Doe", "email": "[email protected]", "paymentMethod": { "routingNumber": "021000021", "accountNumber": "123456789", "tokenType": "PLAID", "token": "processor-sandbox-123456789" }}

---

📓 Before You Start

Plaid token verification requires a couple of configuration items on your account before it will work end to end — including Tabapay enablement on your Plaid integration. Check with your Spinwheel contact to confirm you have what you need configured before rolling this out.

---

Verify with Microdeposits (Fallback Method)

If you don't have a Plaid token for a consumer, use micro-deposit verification instead. Two small deposits are sent to the consumer's bank account. The consumer then checks their bank statement and confirms the amounts. This usually takes 1–3 business days, and the payer can't initiate ACH payments until it's done.

To use this method, call the same Create a Payer endpoint and leave out tokenType and token:

Example Request

{"firstName": "John", "lastName": "Doe", "email": "[email protected]", "paymentMethod": { "routingNumber": "021000021", "accountNumber": "123456789" }}