Embedded Payments
Overview
Spinwheel offers a number of payment mechanisms and options depending on the specific use case you are supporting. All debt types can have direct payments submitted to them, with some unique structures to give better flexibility and control.
The key payment use cases we provide are:
- Cross debt payment: Payment that is able to be run with all liability types, loan servicers, and individual user debt lines.
- Student Loan Direct Payments: Direct student loan payments for liabilities connected via Direct Student Loan Connection. These payments have enhanced functionality intended to give more flexibility to how the payment is applied with an individual loan
General Payments References
Here are the broad concepts/models that are necessary to understand our payments flows.
An object that dictates how funds will be used for a given payment. Funds can be directed towards multiple liabilities and goals based on the configuration of the use of funds object.
Payment Requests
The submission point for all payment origination, made up of a few key aspects:
| Term | Definition |
|---|---|
| Amount | The amount to be applied with the transaction |
| Type | The type of transaction it is (ONE_TIME, RECURRING) |
| Use of Funds | Allocation model for how the amount is to be distributed |
Transactions
Generated from the payment requests and the reference point for transaction status and lifecycle of the transaction itself
Payments to Platform
The starting point of funds disbursement, where you are transferring funds on to the platform for payment toward liabilities. Think of this as pre-filling the account where the funds will be disbursed from.
Transaction Statuses
These statuses and their corresponding definitions can be found
| Transaction Status | Description |
|---|---|
| SCHEDULING | When a Transaction has been received by Spinwheel but not is yet in the process of being scheduled |
| PROCESSING | When a Transaction is in the process of being scheduled with the loan servicer by Spinwheel |
| SCHEDULING_REVIEW | When a Transaction was flagged for additional review by Spinwheel. |
| SCHEDULED | Once a Transaction has been successfully scheduled with a loan servicer |
| APPLIED | Once a Transaction has been successfully applied with a loan servicer |
| FAILED | When a Transaction was not able to be successfully scheduled with a loan servicer |
| CANCELLED | When a Transaction has been cancelled and will not be completed because the payment request was deleted or the transaction is in an unrecoverable state |
| RETURNED | When a Transaction has been returned by the servicer back to the originated account |
Sandbox Transaction Testing
In order to test a payment in sandbox, please refer to the following:
- Submit a payment request or payment to platform
- Retrieve the transactionId
- Submit a PATCH request to simulate a payment transaction
https://sandbox-api.spinwheel.io/sandbox/transactions/{transactionId}/simulate
This process will allow a payment to move through the following payment lifecycle:
- SCHEDULING > SCHEDULED, CANCELLED
- SCHEDULED > APPLIED, FAILED
- APPLIED > FAILED
- FAILED > RETURNED
This will trigger the corresponding webhook (UserPaymentStatusWebhookor the PlatformPaymentWebhook)
To learn more about our debt APIs and full product suite, visit spinwheel.io.
Updated 4 months ago