Using 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.
  • 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. Fund the FBO Account

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. Check the Capabilities Matrix and Send a Payment Request

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.


Did this page help you?