Introduction
Rightfoot's API generates student debt beneficiary accounts and transfers funds to their loans.
We have language bindings for Python and TypeScript. You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right. If SDKs/libraries are desired for other languages, we are happy to develop them based on demand.
Authentication
import rightfoot
configuration = rightfoot.Configuration()
# Defaults to sandbox, but can be explicitly set to sandbox/production.
configuration.host="https://sandbox.api.rightfoot.com/v1"
configuration.api_key['Authorization'] = os.env['RIGHTFOOT_API_KEY']
configuration.api_key_prefix['Authorization'] = 'Bearer'
rightfoot_client = rightfoot.RightfootApi(rightfoot.ApiClient(configuration))
import { Configuration, RightfootApi } from 'rightfoot-node';
const config: Configuration = new Configuration( {
apiKey: `Bearer ${RIGHTFOOT_API_KEY}`,
});
const rightfootClient = new RightfootApi(config, "https://sandbox.api.rightfoot.com");
export RIGHTFOOT_HOST=https://sandbox.api.rightfoot.com/v1
export RIGHTFOOT_API_KEY=sandbox-rightfoot_api_key
Make sure to replace
secure-private-key
with your API key.
Rightfoot uses API keys to allow access to the API. You can register a new Rightfoot API key by contacting us at info@rightfoot.com.
Rightfoot expects for the API key to be included in all API requests to the server in a header that looks like the following:
Authorization: Bearer secure-private-key
Onboarding a New Application
To request a new Rightfoot API key, contact us at info@rightfoot.com. Rightfoot will facilitate the onboarding process to:
- Perform KYC verification of your business for compliance purposes.
- Connect a funding source/bank account for drawing payments against.
Beneficiaries
Beneficiaries are the end-users, which receive credits to their loans via use of these APIs. As appropriate for the given product consuming these APIs, beneficiaries are created and managed to attach loan accounts to and issue payment instructions to benefit.
Create a New Beneficiary
import rightfoot
from rightfoot.rest import ApiException
mailing_address = rightfoot.models.MailingAddress(
line1="123 Easy Street", city="Palo Alto", state="CA", zip_code="12345-0123")
request = rightfoot.CreateBeneficiaryRequest(
first_name="John", last_name="Doe", date_of_birth="1970-01-01",
phone_number="+1 650 555 5555", mailing_address=mailing_address)
try:
response = rightfoot_client.create_beneficiary(request)
print(response)
except ApiException as e:
print("Call failed: %s" % e)
import { CreateBeneficiaryRequest } from 'rightfoot-node';
import { parsePhoneNumber } from 'libphonenumber-js';
const phoneNumber = parsePhoneNumber('+1 555 555 5555');
const request: CreateBeneficiaryRequest = {
firstName: 'John',
lastName: 'Doe',
dateOfBirth: "1970-01-01",
phoneNumber: parsePhoneNumber('+1 555 555 5555').formatInternational(),
mailingAddress: {
line1: "123 Easy Street",
city: "Palo Alto",
state: "CA",
zipCode: "12345-0123"
}
};
rightfootClient.createBeneficiary(request)
.then(response => { console.log(response); })
.catch(err => { console.error(err); });
curl --request POST\
--header 'Authorization: Bearer '"$RIGHTFOOT_API_KEY" \
--header 'Content-Type: application/json'\
--data '{
"firstName": "John",
"lastName": "Doe",
"dateOfBirth": "1970-01-01",
"phoneNumber": "+1 555 555 5555",
"mailingAddress": {
"line1": "123 Easy Street",
"line2": null,
"city": "Palo Alto",
"state": "CA",
"zipCode": "12345-0123"
}
}'\
$RIGHTFOOT_HOST/beneficiaries
This endpoint creates a new beneficiary.
HTTP Request
POST
https://production.api.rightfoot.com/v1/beneficiaries
Body Parameters
Key | Type | Required | Description |
---|---|---|---|
firstName |
String | Yes | The given name of the beneficiary. |
lastName |
String | Yes | The family name of the beneficiary. |
dateOfBirth |
String | Yes | Birth date for the beneficiary formatted as YYYY-MM-DD. |
phoneNumber |
String | Yes | Phone number for the beneficiary formatted internationally with spacing such as +1 555 555 5555. |
mailingAddress |
Object<MailingAddress> |
Yes | Mailing address for the beneficiary, to be provided to payment provider. |
Response
{
"beneficiary": {
"uuid": "12345678-abcd-1234-abcd-12345678abcd",
"firstName": "Person",
"lastName": "Doe",
"dateOfBirth": "1970-01-01",
"phoneNumber": "+1 555 555 5555",
"mailingAddress": {
"line1": "123 Easy Street",
"line2": null,
"city": "Palo Alto",
"state": "CA",
"zipCode": "12345-0123"
}
}
}
This create API responds with the created Beneficiary.
Key | Type | Nullable? | Description |
---|---|---|---|
beneficiary |
Object<Beneficiary> |
No | The created beneficiary with provided fields populated. |
Retrieve Beneficiary
import rightfoot
from rightfoot.rest import ApiException
request = rightfoot.GetBeneficiaryRequest(
uuid="12345678-abcd-1234-abcd-12345678abcd")
try:
response = rightfoot_client.get_beneficiary(
uuid="12345678-abcd-1234-abcd-12345678abcd")
print(response)
except ApiException as e:
print("Call failed: %s" % e)
const uuid = '12345678-abcd-1234-abcd-12345678abcd';
api.getBeneficiary(uuid)
.then(response => { console.log(response); })
.catch(err => { console.error(err); });
curl --request GET\
--header 'Authorization: Bearer '"$RIGHTFOOT_API_KEY" \
$RIGHTFOOT_HOST/beneficiaries/12345678-abcd-1234-abcd-12345678abcd
This endpoint retrieves an existing beneficiary.
HTTP Request
GET
https://production.api.rightfoot.com/v1/beneficiaries/{uuid}
Query Parameters
Parameter | Type | Required | Description |
---|---|---|---|
uuid |
String | Yes | Unique identifier generated by Rightfoot for the beneficiary. |
Response
{
"beneficiary": {
"uuid": "12345678-abcd-1234-abcd-12345678abcd",
"firstName": "Person",
"lastName": "Doe",
"dateOfBirth": "1970-01-01",
"phoneNumber": "+1 555 555 5555",
"mailingAddress": {
"line1": "123 Easy Street",
"line2": null,
"city": "Palo Alto",
"state": "CA",
"zipCode": "12345-0123"
}
}
}
This beneficiary API responds with the current state of the Beneficiary
object.
Key | Type | Nullable? | Description |
---|---|---|---|
beneficiary |
Object<Beneficiary> |
No | The created beneficiary with provided fields populated. |
List Beneficiaries
This endpoint provides a filterable list of beneficiaries.
import rightfoot
from rightfoot.rest import ApiException
try:
response = rightfoot_client.get_beneficiaries(count=50, offset=100)
print(response)
except ApiException as e:
print("Call failed: %s" % e)
import { ListBeneficiariesResponse } from 'rightfoot-node';
const count = 30;
const offset = 40;
api.getBeneficiaries(count, offset)
.then(({ beneficiaries }: ListBeneficiariesResponse) => { console.log(beneficiaries); })
.catch(err => { console.error(err); });
curl --request GET\
--header 'Authorization: Bearer '"$RIGHTFOOT_API_KEY"\
$RIGHTFOOT_HOST/beneficiaries
This endpoint retrieves existing beneficiaries.
HTTP Request
GET
https://production.api.rightfoot.com/v1/beneficiaries
Query Parameters
Parameter | Type | Required | Description |
---|---|---|---|
count |
Integer | No | Number of beneficiaries to return in one paged request. Defaults and limited to 50. |
offset |
Integer | No | Beneficiary offset to start query from, when paging through beneficiaries. |
Response
{
"beneficiaries": [
{
"uuid": "12345678-abcd-1234-abcd-12345678abcd",
"firstName": "Person",
"lastName": "Doe",
"dateOfBirth": "1970-01-01",
"phoneNumber": "+1 555 555 5555",
"mailingAddress": {
"line1": "123 Easy Street",
"line2": null,
"city": "Palo Alto",
"state": "CA",
"zipCode": "12345-0123"
}
}
]
}
This API responds with the current state of the Beneficiary
s matching the
requested filters.
Key | Type | Nullable? | Description |
---|---|---|---|
beneficiaries |
Object<Beneficiary>[] |
No | The beneficiaries matching the filters. |
Loan Linking
Beneficiaries need to link their loans to Rightfoot's API platform to complete their onboarding process. We support two approaches for providing loan account details to Rightfoot: 1) a Rightfoot-managed Plaid experience and 2) a generic loan data experience.
There are advantages and disadvantages to both approaches, but generally a developer would choose each approach based on priorities:
- Rightfoot-managed Plaid Integration,
- Have Rightfoot own the business relationship with Plaid, billing you the costs associated with this.
- Not have access to the loan data for privacy and security reasons, deferring that responsibility to Rightfoot.
- Want to avoid any backend integration against Plaid, and only integrate your backend against Rightfoot's APIs. (note: this still requires use of Plaid Link in a UI with Rightfoot's public key, but this is a thin-integration).
- Generic Loan Data, if you want to:
- Own the business relationship with Plaid or other financial aggregators.
- Avoid vendor lock-in with Rightfoot due to Rightfoot having sole-access to loan data.
- Grant Rightfoot access to only the loan data required for payments, for privacy and security reasons, owning the responsibility for all other data acquired about users' loans.
Link Rightfoot-Managed Plaid Loan
import rightfoot
from rightfoot.rest import ApiException
request = rightfoot.AddPlaidTokenToBeneficiaryRequest(
uuid="12345678-abcd-1234-abcd-12345678abcd",
plaid_public_token="plaid-token")
try:
response = rightfoot_client.add_plaid_token_to_beneficiary(request)
print(response)
except ApiException as e:
print("Call failed: %s" % e)
import { AddPlaidTokenToBeneficiaryRequest } from 'rightfoot-node';
const request: AddPlaidTokenToBeneficiaryRequest = {
uuid: '12345678-abcd-1234-abcd-12345678abcd',
plaidPublicToken: 'plaid-token',
};
rightfootClient.addPlaidTokenToBeneficiary(request)
.then(response => { console.log(response); })
.catch(err => { console.error(err); });
curl --request POST\
--header 'Authorization: Bearer '"$RIGHTFOOT_API_KEY" \
--header 'Content-Type: application/json'\
--data '{
"uuid": "12345678-abcd-1234-abcd-12345678abcd",
"plaidPublicToken":"public-12345678-abcd-1234-abcd-12345678abcd"
}'\
$RIGHTFOOT_HOST/beneficiaries/addPlaidToken
This endpoint connects an authenticated Plaid account, when beneficiaries log
into their loans using
Plaid Link in your
UI using Rightfoot's public Plaid key, 1773c898604f2bd4d68ecbbc8504f9
. This
has the advantage of an experience completely controlled by the consuming
product. Rightfoot binds the loan accounts, billing the customer for the
one-time charges incurred, exchanging the public key in the background,
maintaining loan records. Your application does not have access to the loan
data in this approach.
HTTP Request
POST
https://production.api.rightfoot.com/v1/beneficiaries/addPlaidToken
Body Parameters
Parameter | Type | Required | Description |
---|---|---|---|
uuid |
String | Yes | Unique identifier for the beneficiary to attach the loans to. |
plaidPublicToken |
String | Yes | Public token obtained from Plaid using Rightfoot's Plaid public key. |
Response
{
"uuid": "12345678-abcd-1234-abcd-12345678abcd",
"firstName": "Person",
"lastName": "Doe",
"dateOfBirth": "1991-02-29",
"phoneNumber": "+15555555555",
"mailingAddress": {
"line1": "123 Easy Street",
"line2": null,
"city": "Palo Alto",
"state": "CA",
"zipCode": "12345-0123"
}
}
This addPlaidLoan API responds with the updated Beneficiary.
Key | Type | Nullable? | Description |
---|---|---|---|
beneficiary |
Object<Beneficiary> |
No | The updated beneficiary with set fields populated. |
Link Generic Loan Data
import rightfoot
from rightfoot.rest import ApiException
request = rightfoot.AddGenericLoanToBeneficiaryRequest(
uuid="12345678-abcd-1234-abcd-12345678abcd",
plaid_institution_id="ins_12345",
account_number="123-ABC-0",
sequence_number="001",
payment_reference_number="123-ABC-00123-ABC",
guarantor_name="Foo Guarantor")
try:
response = rightfoot_client.add_generic_loan_to_beneficiary(request)
print(response)
except ApiException as e:
print("Call failed: %s" % e)
import { AddGenericLoanToBeneficiaryRequest } from 'rightfoot-node';
const request: AddGenericLoanToBeneficiaryRequest = {
uuid: '12345678-abcd-1234-abcd-12345678abcd',
plaidInstitutionId: 'ins_12345',
accountNumber: '123-ABC-0',
sequenceNumber: '001',
paymentReferenceNumber: '"123-ABC-00123-ABC',
guarantor_name: 'Foo Guarantor',
};
rightfootClient.addGenericLoanToBeneficiary(request)
.then(response => { console.log(response); })
.catch(err => { console.error(err); });
curl --request POST\
--header 'Authorization: Bearer '"$RIGHTFOOT_API_KEY" \
--header 'Content-Type: application/json'\
--data '{
"uuid": "16a21f69-52db-4356-8342-80e02f8eaf4b",
"plaidInstitutionId": "ins_1",
"accountNumber": "123-ABC-0",
"sequenceNumber": "001",
"paymentReferenceNumber": "123-ABC-00123-ABC",
"guarantor_name": "Foo Guarantor"
}'\
$RIGHTFOOT_HOST/beneficiaries/addGenericLoan
This endpoint is agnostic to the collection method of loan data, and allows your application to own the loan data and loan data connection through financial data aggregators like Plaid, Finicity, Yodlee, MX, and more. A subset of data is required from the loan data obtained from the aggregator. While it is possible to collect this data directly from the beneficiary, it is strongly preferable to use an aggregator, as this provides validation to the data being correct. Human-entered data has a higher rate of failed payments.
HTTP Request
POST
https://production.api.rightfoot.com/v1/beneficiaries/addGenericLoan
Body Parameters
Parameter | Type | Required | Description |
---|---|---|---|
uuid |
String | Yes | Unique identifier for the beneficiary to attach the loans to. |
plaidInstitutionId |
String | Yes | Unique identifier used by Plaid for the loan servicer institution. For Plaid users, maps to item.institution_id . |
accountNumber |
String | Yes | The root account number for the loan. For Plaid users, maps to liabilities.student[*].account_number . |
sequenceNumber |
String | No | If available, the sub-loan sequence number within the account. For Plaid users, maps to liabilities.student[*].sequence_number . |
paymentReferenceNumber |
String or null |
Yes* | If a different payment reference number is available for accounts, identifies the loan account for payment purposes. Often the same as accountNumber but can be specified when known to be different. For Plaid users, maps to liabilities.student[*].payment_reference_number . |
guarantorName |
String or null |
Yes* | The name of the guarantor of the loan if used at the loan servicer. For Plaid users, maps to liabilities.student[*].guarantor . |
Response
{
"loan": {
"uuid": "12345678-abcd-1234-abcd-12345678abcd"
}
}
This addPlaidLoan API responds with the updated Beneficiary.
Key | Type | Nullable? | Description |
---|---|---|---|
loan |
Object<Loan> |
No | The loan created based on the information provided. |
List Loans for a Beneficiary
This endpoint provides a list of loans for a beneficiary.
from rightfoot.rest import ApiException
try:
response = rightfoot_client.get_loans_for_beneficiary(
uuid="12345678-abcd-1234-abcd-12345678abcd")
print(response)
except ApiException as e:
print("Call failed: %s" % e)
import { ListLoansResponse } from 'rightfoot-node';
const beneficiaryUuid = '12345678-abcd-1234-abcd-12345678abcd';
api.getLoansForBeneficiary(beneficiaryUuid)
.then(({ loans }: ListLoansResponse) => { console.log(loans); })
.catch(err => { console.error(err); });
curl --request GET\
--header 'Authorization: Bearer '"$RIGHTFOOT_API_KEY" \
$RIGHTFOOT_HOST/beneficiaries/12345678-abcd-1234-abcd-12345678abcd/loans
HTTP Request
GET
https://production.api.rightfoot.com/v1/beneficiaries/{uuid}/loans
Query Parameters
Parameter | Type | Required | Description |
---|---|---|---|
uuid |
String | Yes | Beneficiary id to retrieve loans for. |
Response
{
"loans": [
{
"uuid": "12345678-abcd-1234-abcd-12345678abcd"
}
]
}
This API responds with the current state of the Loan
s.
Parameter | Type | Nullable? | Description |
---|---|---|---|
loans |
Object<Loan>[] |
No | The loans linked to the beneficiary. |
Funding Sources
Create Funding Source
import { CreateFundingSourceRequest } from 'rightfoot-node';
const plaidRequest: CreateFundingSourceRequest = {
beneficiaryUuid: '12345678-abcd-1234-abcd-12345678abcd',
emailAddress: 'beneficiary@domain.com',
plaidPublicToken: 'plaid-public-token',
accountId: 'selected-account-id'
};
rightfootClient.createFundingSource(plaidRequest)
.then(response => console.log(response))
.catch(error => console.error(error));
const processorTokenRequest: CreateFundingSourceRequest = {
beneficiaryUuid: '12345678-abcd-1234-abcd-12345678abcd',
emailAddress: 'beneficiary@domain.com',
dwollaProcessorToken: 'dwolla-processor-token'
};
rightfootClient.createFundingSource(processorTokenRequest)
.then(response => console.log(response))
.catch(error => console.error(error));
import rightfoot
from rightfoot.rest import ApiException
plaid_request = rightfoot.CreateFundingSourceRequest(
beneficiary_uuid="12345678-abcd-1234-abcd-12345678abcd",
email_address="beneficiary@domain.com",
plaid_public_token="plaid-public-token",
account_id="selected-account-id")
try:
response = rightfoot_client.create_funding_source(plaid_request)
print(response)
except ApiException as e:
print("Call failed: %s" % e)
processor_token_request = rightfoot.CreateFundingSourceRequest(
beneficiary_uuid="12345678-abcd-1234-abcd-12345678abcd",
email_address="beneficiary@domain.com",
dwolla_processor_token="dwolla-processor-token")
try:
response = rightfoot_client.create_funding_source(processor_token_request)
print(response)
except ApiException as e:
print("Call failed: %s" % e)
curl --request POST\
--header 'Authorization: Bearer '"$RIGHTFOOT_API_KEY" \
--header 'Content-Type: application/json'\
--data '{
"beneficiaryUuid": "12345678-abcd-1234-abcd-12345678abcd",
"emailAddress": "beneficiary@domain.com",
"plaidPublicToken": "plaid-public-token",
"accountId": "selected-account-id",
}'\
$RIGHTFOOT_HOST/fundingSources
curl --request POST\
--header 'Authorization: Bearer '"$RIGHTFOOT_API_KEY" \
--header 'Content-Type: application/json'\
--data '{
"beneficiaryUuid": "12345678-abcd-1234-abcd-12345678abcd",
"emailAddress": "beneficiary@domain.com",
"dwollaProcessorToken": "dwolla-processor-token"
}'\
$RIGHTFOOT_HOST/fundingSources
Creates a new funding source attached to a beneficiary. Accepts a Plaid token linked using Plaid Link in the API application. This provides instant verification of the account and avoids exposure of end-user financial data to API Applications and Rightfoot. This funding source can be specified to the payments API to override the default application funding source, if configured.
Two models of providing a Plaid token are supported: a Rightfoot API Customer-managed model, and a Rightfoot-managed model. The API application can provide a Plaid public token associated with Rightfoot’s client id. Alternatively if the API application chooses to own the Plaid item, or the account was linked previously in the app, the API application can exchange for a Dwolla processor token and provide that to Rightfoot instead.
For more information on the flows that are being satisfied with our payment processor Dwolla, you can read Dwolla and Plaids’ official documentation on the topic.
HTTP Request
POST
https://production.api.rightfoot.com/v1/fundingSources
Body Parameters
Parameter | Type | Required | Description |
---|---|---|---|
beneficiaryUuid |
String | Yes | Unique identifier generated by Rightfoot for beneficiary. |
emailAddress |
String | Yes | Valid email address, which can be used to reach the user. Rightfoot and its partners do not conduct regular communication with end-users. Regulations require bank partner to have the ability to contact the end-user. |
plaidPublicToken |
String | No* | Public token provided by Plaid Link representing the beneficiary’s bank account. Grants Rightfoot permission to draw from the account backing this token. |
accountId |
String | No* | Account ID from Plaid Link when a user selects a specific checking or savings bank account from the bank institution they log into. |
dwollaProcessorToken |
String | No* | Dwolla Processor Token generated from a Plaid Auth access token owned by the API application. Grants Rightfoot permission to draw from the account backing this token. |
Response
{
"fundingSource": {
"uuid": "12345678-abcd-1234-abcd-12345678abcd",
"status": "VERIFIED"
}
}
This funding source creation API responds with the created funding source.
Parameter | Type | Nullable? | Description |
---|---|---|---|
fundingSource |
Object<FundingSource> |
No | The created funding source object. |
Retrieve Beneficiary Funding Sources
import rightfoot
from rightfoot.rest import ApiException
try:
response = rightfoot_client.list_funding_sources_for_beneficiary(
uuid="12345678-abcd-1234-abcd-12345678abcd")
print(response)
except ApiException as e:
print("Call failed: %s" % e)
const uuid = '12345678-abcd-1234-abcd-12345678abcd';
api.listFundingSourcesForBeneficiary(uuid)
.then(response => { console.log(response); })
.catch(err => { console.error(err); });
curl --request GET\
--header 'Authorization: Bearer '"$RIGHTFOOT_API_KEY" \
$RIGHTFOOT_HOST/beneficiaries/12345678-abcd-1234-abcd-12345678abcd/fundingSources
This endpoint retrieves a list of funding sources for the current beneficiary.
HTTP Request
GET
https://production.api.rightfoot.com/v1/beneficiaries/{uuid}/fundingSources
Query Parameters
Parameter | Type | Required | Description |
---|---|---|---|
uuid |
String | Yes | Unique identifier generated by Rightfoot for the beneficiary. |
Response
{
"funding_sources": [
{
"uuid": "12345678-abcd-1234-abcd-12345678abcd"
}
]
}
This API responds with the list of funding sources connected to the beneficiary.
Key | Type | Nullable? | Description |
---|---|---|---|
fundingSources |
Object<FundingSource>[] |
No | The funding sources connected to the provided beneficiary. |
Retrieve Organization Funding Sources
import rightfoot
from rightfoot.rest import ApiException
try:
response = rightfoot_client.list_funding_sources_for_organization(
uuid="12345678-abcd-1234-abcd-12345678abcd")
print(response)
except ApiException as e:
print("Call failed: %s" % e)
const uuid = '12345678-abcd-1234-abcd-12345678abcd';
api.listFundingSourcesForOrganization(uuid)
.then(response => { console.log(response); })
.catch(err => { console.error(err); });
curl --request GET\
--header 'Authorization: Bearer '"$RIGHTFOOT_API_KEY" \
$RIGHTFOOT_HOST/organizations/16a21f69-52db-4356-8342-80e02f8eaf4b/fundingSources
This endpoint retrieves a list of funding sources for the current organization.
HTTP Request
GET
https://production.api.rightfoot.com/v1/organizations/{uuid}/fundingSources
Query Parameters
Parameter | Type | Required | Description |
---|---|---|---|
uuid |
String | Yes | Unique identifier generated by Rightfoot for the organization. |
Response
{
"funding_sources": [
{
"uuid": "12345678-abcd-1234-abcd-12345678abcd"
}
]
}
This API responds with the list of funding sources connected to the organization.
Key | Type | Nullable? | Description |
---|---|---|---|
fundingSources |
Object<FundingSource>[] |
No | The funding sources connected to the provided organization. |
Payments
Payments are issued per-beneficiary with individual requests for transfer. They pay down the beneficiary's highest interest loan first, in order to minimize capitalized interest.
Payment transfers have direct costs associated with them but can be batched
based on the consuming product's configuration. See
PaymentBatchingOptions
.
Issue Payment
import rightfoot
from rightfoot.rest import ApiException
request = rightfoot.CreatePaymentRequest(
beneficiary_uuid="12345678-abcd-1234-abcd-12345678abcd",
payment_amount=50000)
try:
response = rightfoot_client.create_payment(request)
print(response)
except ApiException as e:
print("Call failed: %s" % e)
import { CreatePaymentRequest } from 'rightfoot-node';
const request: CreatePaymentRequest = {
beneficiaryUuid: '12345678-abcd-1234-abcd-12345678abcd',
paymentAmount: 50000,
};
rightfootClient.createPayment(request)
.then(response => { console.log(response); })
.catch(err => { console.error(err); });
curl --request POST\
--header 'Authorization: Bearer '"$RIGHTFOOT_API_KEY" \
--header 'Content-Type: application/json'\
--data '{
"beneficiaryUuid": "12345678-abcd-1234-abcd-12345678abcd",
"paymentAmount": "50000",
}'\
$RIGHTFOOT_HOST/payments
This endpoint issues a request to transfer funds from the consuming application's funding source to the beneficiary's loan account.
HTTP Request
POST
https://production.api.rightfoot.com/v1/payments
Body Parameters
Parameter | Type | Required | Description |
---|---|---|---|
beneficiaryUuid |
String | Yes | Unique identifier generated by Rightfoot for beneficiary. |
loanUuid |
String | No | UUID of the Loan to make payment against. Defaults to highest interest rate loan if using the Rightfoot-managed Plaid integration. |
paymentAmount |
Integer | Yes | Amount to pay to beneficiary's student loans, in cents USD. |
fundingSourceUuid |
String | No* | UUID of the FundingSource to make payments from. |
Response
{
"payment": {
"uuid": "12345678-abcd-1234-abcd-12345678abcd",
"status": "PENDING",
"description": null
}
}
This payment issuance API responds with the created payment.
Parameter | Type | Nullable? | Description |
---|---|---|---|
payment |
Object<Payment> |
No | The created payment object. |
Check Payment Status
import rightfoot
from rightfoot.rest import ApiException
request = rightfoot.GetPaymentRequest(
uuid="12345678-abcd-1234-abcd-12345678abcd")
try:
response = rightfoot_client.get_payment(
uuid="12345678-abcd-1234-abcd-12345678abcd")
print(response)
except ApiException as e:
print("Call failed: %s" % e)
const uuid = '12345678-abcd-1234-abcd-12345678abcd';
api.getPayment(uuid)
.then(response => { console.log(response); })
.catch(err => { console.error(err); });
curl --request GET\
--header 'Authorization: Bearer '"$RIGHTFOOT_API_KEY" \
$RIGHTFOOT_HOST/payments/12345678-abcd-1234-abcd-12345678abcd
This endpoint retrieves an existing payment, updated with the latest status of its processing along with error information.
HTTP Request
GET
https://production.api.rightfoot.com/v1/payments/{uuid}
Query Parameters
Parameter | Type | Required | Description |
---|---|---|---|
uuid |
String | Yes | Unique identifier generated by Rightfoot for the payment. |
Response
{
"payment": {
"uuid": "12345678-abcd-1234-abcd-12345678abcd",
"status": "COMPLETED",
"description": null
}
}
This payment status API responds with the current state of the Payment
object.
Parameter | Type | Nullable? | Description |
---|---|---|---|
payment |
Object<Payment> |
No | The created payment object. |
List Payment for Funding Source
For applications managing funding sources for their users, they must make available the list of transactions performed for those funding sources to the owners of those funding sources. This endpoint provides a filterable list of payments for a funding source.
import datetime
from rightfoot.rest import ApiException
try:
response = rightfoot_client.get_payments_for_funding_source(
uuid="12345678-abcd-1234-abcd-12345678abcd",
created_on_or_after=datetime.fromisoformat('2020-01-01T00:00:00').timestamp() * 1000,
created_before=datetime.fromisoformat('2021-01-01T00:00:00').timestamp() * 1000,
count=50, offset=100)
print(response)
except ApiException as e:
print("Call failed: %s" % e)
import { ListPaymentsResponse } from 'rightfoot-node';
const fundingSourceUuid = '12345678-abcd-1234-abcd-12345678abcd';
const createdOnOrAfter = 10;
const createdBefore = 20;
const count = 30;
const offset = 40;
api.getPaymentsForFundingSource(
fundingSourceUuid, createdOnOrAfter, createdBefore, count, offset)
.then(({ payments }: ListPaymentsResponse) => { console.log(payments); })
.catch(err => { console.error(err); });
curl --request GET\
--header 'Authorization: Bearer '"$RIGHTFOOT_API_KEY" \
$RIGHTFOOT_HOST/fundingSources/12345678-abcd-1234-abcd-12345678abcd/payments
This endpoint retrieves an existing payment, updated with the latest status of its processing along with error information.
HTTP Request
GET
https://production.api.rightfoot.com/v1/fundingSources/{uuid}/payments
Query Parameters
Parameter | Type | Required | Description |
---|---|---|---|
uuid |
String | Yes | Funding source id to retrieve payments for. |
createdOnOrAfter |
Integer | No | Filters payments started on or after provided time. Unix Epoch milliseconds. |
createdBefore |
Integer | No | Filters payments started before provided time. Unix Epoch milliseconds. |
count |
Integer | No | Number of payments to return in one paged request. Defaults and limited to 50. |
offset |
Integer | No | Payment offset to start query from, when paging through payments. |
Response
{
"payments": [
{
"uuid": "12345678-abcd-1234-abcd-12345678abcd",
"status": "COMPLETED",
"description": null
}
]
}
This API responds with the current state of the Payment
s matching the
requested filters.
Parameter | Type | Nullable? | Description |
---|---|---|---|
payments |
Object<Payment>[] |
No | The payments matching the filters. |
List Payment for a Beneficiary
This endpoint provides a filterable list of payments for a beneficiary.
import datetime
from rightfoot.rest import ApiException
try:
response = rightfoot_client.get_payments_for_beneficiary(
uuid="12345678-abcd-1234-abcd-12345678abcd",
created_on_or_after=datetime.fromisoformat('2020-01-01T00:00:00').timestamp() * 1000,
created_before=datetime.fromisoformat('2021-01-01T00:00:00').timestamp() * 1000,
count=50, offset=100)
print(response)
except ApiException as e:
print("Call failed: %s" % e)
import { ListPaymentsResponse } from 'rightfoot-node';
const beneficiaryUuid = '12345678-abcd-1234-abcd-12345678abcd';
const createdOnOrAfter = 10;
const createdBefore = 20;
const count = 30;
const offset = 40;
api.getPaymentsForBeneficiary(
beneficiaryUuid, createdOnOrAfter, createdBefore, count, offset)
.then(({ payments }: ListPaymentsResponse) => { console.log(payments); })
.catch(err => { console.error(err); });
curl --request GET\
--header 'Authorization: Bearer '"$RIGHTFOOT_API_KEY" \
$RIGHTFOOT_HOST/beneficiaries/12345678-abcd-1234-abcd-12345678abcd/payments
This endpoint retrieves existing payments, updated with the latest status of its processing along with error information.
HTTP Request
GET
https://production.api.rightfoot.com/v1/beneficiaries/{uuid}/payments
Query Parameters
Parameter | Type | Required | Description |
---|---|---|---|
uuid |
String | Yes | Beneficiary id to retrieve payments for. |
createdOnOrAfter |
Integer | No | Filters payments started on or after provided time. Unix Epoch milliseconds. |
createdBefore |
Integer | No | Filters payments started before provided time. Unix Epoch milliseconds. |
count |
Integer | No | Number of payments to return in one paged request. Defaults and limited to 50. |
offset |
Integer | No | Payment offset to start query from, when paging through payments. |
Response
{
"payments": [
{
"uuid": "12345678-abcd-1234-abcd-12345678abcd",
"status": "COMPLETED",
"description": null
}
]
}
This API responds with the current state of the Payment
s matching the
requested filters.
Parameter | Type | Nullable? | Description |
---|---|---|---|
payments |
Object<Payment>[] |
No | The payments matching the filters. |
Response Object Schemas
Rightfoot reuses object types across API endpoints for clear code reuse in server and client code.
Beneficiary
Schema
The Beneficiary
type represents an end-user receiving funds in their loan
accounts.
Key | Type | Nullable? | Description |
---|---|---|---|
uuid |
String | No | Unique identifier generated by Rightfoot. |
firstName |
String | No | The given name of the beneficiary. |
lastName |
String | No | The family name of the beneficiary. |
dateOfBirth |
String | No | Birth date for the beneficiary formatted as YYYY-MM-DD . |
phoneNumber |
String | No | Phone number for the beneficiary formatted internationally with spacing such as +1 555 555 5555 . |
mailingAddress |
Object<MailingAddress> |
No | Mailing address for the beneficiary, to be provided to payment provider. |
MailingAddress
Schema
Key | Type | Nullable? | Description |
---|---|---|---|
line1 |
String | No | Mandatory mailing address line. |
line2 |
String | Yes | Optional second line of an address. |
city |
String | No | The city of the location. |
state |
String | No | The two-letter state/territory abbreviation. |
zipCode |
String | No | US Zone Improvement Plan (ZIP) Code, or alternatively ZIP+4 Code. |
Loan
Schema
A bare-bones loan schema for wrapping identifying information about loans for API applications to specify which specific loan account to direct payments towards. This represents the lowest unit of loan, which in the interest of clarity given the use of Plaid on this platform, is comparable to a single student loan liability object and not an account.
Parameter | Type | Nullable? | Description |
---|---|---|---|
uuid |
String | No | Unique identifier for future API calls to reference a created loan. |
Payment
Schema
The Payment
type represents a single loan payment request.
Parameter | Type | Nullable? | Description |
---|---|---|---|
uuid |
String | No | Unique identifier generated by Rightfoot for payment. |
status |
Enum<PaymentStatus> |
No | Status of the payment. |
statusReason |
Enum<PaymentStatusReason> |
No | Detailed status reason. Contains more detail for presenting detail to users, rather than more programmatic process handling. This enum is meant to be extended regularly, whereas status is more stable. |
description |
String | Yes | In the case of errors or other variants, provides a description of the failed state. |
PaymentStatus
Enum
Value | Description |
---|---|
PENDING |
Payment request has been issued. |
ACCEPTED |
Payment request accepted by processors. Will update over several days until payment is completed. |
COMPLETED |
Payments verified to have been disbursed. |
RETURNED |
Payment is more than balance and note necessary. |
FAILED |
An irrecoverable error in processing has occurred. |
PaymentStatusReason
Enum
Value | Description |
---|---|
ACH_WITHDRAWAL_PENDING_SCHEDULING |
ACH payment not yet scheduled with payment processor. Will be scheduled soon. Can still be cancelled. |
ACH_WITHDRAWAL_CANCELLED |
ACH payment cancelled. Will not be processed by payment processor. |
ACH_WITHDRAWAL_SCHEDULED |
ACH payment scheduled for processing. No longer cancellable. |
ACH_WITHDRAWAL_SUCCESSFUL |
ACH payment successful from funding source. Funds now en route to destination. |
ACH_WITHDRAWAL_FAILED |
ACH payment failed to process. |
ACH_WITHDRAWAL_RETURNED |
ACH payment returned, potentially after successful. Funds were requested to be returned to funding source by bank. |
PAYMENT_DELIVERY_PENDING |
Delivery to final destination is in progress, potentially through multiple hops. This status might expand into more detail in the future. |
PAYMENT_DELIVERY_FAILED |
Delivery failed to process at loan servicer. Payment returning to funding source. This can happen if a loan servicer regresses confirmation. |
PAYMENT_DELIVERY_SUCCESSFUL |
Delivery successful at loan servicer. Payment may take more time to appear in statement. |
FundingSource
Schema
A bare-bones funding source schema is added primarily for wrapping identifying information about funding sources for API applications to specify which account payments should be withdrawn from.
Parameter | Type | Nullable? | Description |
---|---|---|---|
uuid |
String | No | Unique identifier generated by Rightfoot for the funding source. |
Errors
The Rightfoot API uses the following error codes across all endpoints:
Error Code | Meaning |
---|---|
400 | Bad Request -- Your request is invalid. |
401 | Unauthorized -- Your API key is wrong. |
403 | Forbidden -- The resource requested is not permitted to the requested account. |
404 | Not Found -- The specified resource could not be found. |
405 | Method Not Allowed -- The endpoint requested does not support that method. |
406 | Not Acceptable -- You requested a format that isn't json. |
418 | I'm a teapot. |
429 | Too Many Requests -- You're requesting too many things! Slow down! |
500 | Internal Server Error -- We had a problem with our server. Try again later. |
503 | Service Unavailable -- We're temporarily offline for maintenance. Please try again later. |