Introduction - Payment API
Rightfoot's Student Loan Payment 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/v1");
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 $RIGHTFOOT_HOST/beneficiaries \
--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"
}
}'
This endpoint creates a new beneficiary.
HTTP Request
POST
https://production.api.rightfoot.com/v1/beneficiaries
Body Parameters
Key | Type | Required | Description | Constraints |
---|---|---|---|---|
firstName |
String | Yes | The given name of the beneficiary. | Limited to 64 characters. |
lastName |
String | Yes | The family name of the beneficiary. | Limited to 64 characters. |
dateOfBirth |
String | Yes | Birth date for the beneficiary formatted as YYYY-MM-DD. | Must match regex '\d{4}-\d{2}-\d{2}` and be a valid date. |
phoneNumber |
String | Yes | Phone number for the beneficiary formatted internationally with spacing such as +1 555 555 5555. | Phone numbers are validated using libphonenumber from Google using the "INTERNATIONAL" format. |
mailingAddress |
Object<MailingAddress> |
Yes | Mailing address for the beneficiary, to be provided to payment provider. | See Object<MailingAddress> |
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 $RIGHTFOOT_HOST/beneficiaries/12345678-abcd-1234-abcd-12345678abcd \
--request GET \
--header 'Authorization: Bearer '"$RIGHTFOOT_API_KEY"
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 $RIGHTFOOT_HOST/beneficiaries \
--request GET \
--header 'Authorization: Bearer '"$RIGHTFOOT_API_KEY"
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. |
Benefactors
Benefactor
s represent individuals who are making payments to Loan
s for the
benefit of a Beneficiary
. Benefactor
s can also be Beneficiary
s, as they
are conceptually just a non-business owner of a FundingSource
.
Create Benefactor
Creates a Benefactor
. Can be used to create FundingSource
s held by
individuals.
import rightfoot
from rightfoot.rest import ApiException
request = rightfoot.CreateBenefactorRequest(
first_name='John', last_name='Doe', email_address='john@example.com')
try:
response = rightfoot_client.create_benefactor(request)
print(response)
except ApiException as e:
print("Call failed: %s" % e)
import { CreateBenefactorRequest, CreateBenefactorResponse } from 'rightfoot-node';
const request: CreateBenefactorRequest = {
firstName: 'John',
lastName: 'Doe',
emailAddress: 'john@example.com'
};
api.createBenefactor(request)
.then(({ benefactor }: CreateBenefactorResponse) => { console.log(benefactor); })
.catch(err => { console.error(err); });
curl $RIGHTFOOT_HOST/benefactors \
--request POST \
--header 'Authorization: Bearer '"$RIGHTFOOT_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"firstName": "John",
"lastName": "Doe",
"emailAddress": "john@example.com"
}'
HTTP Request
POST
https://production.api.rightfoot.com/v1/benefactors
Body Parameters
Key | Type | Required | Description | Constraints |
---|---|---|---|---|
firstName |
String | Yes | The given name of the Benefactor . |
Limited to 64 characters. |
lastName |
String | Yes | The family name of the Benefactor . |
Limited to 64 characters. |
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. | Valid email address in |
Response
{
"benefactor": {
"uuid": "12345678-abcd-1234-abcd-12345678abcd",
"firstName": "John",
"lastName": "Doe",
}
}
This create API responds with the created Benefactor
.
Key | Type | Nullable? | Description |
---|---|---|---|
benefactor |
Object<Benefactor> |
No | The created Benefactor . |
Retrieve Benefactor
import rightfoot
from rightfoot.rest import ApiException
try:
response = rightfoot_client.get_benefactor(
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.getBenefactor(uuid)
.then(response => { console.log(response); })
.catch(err => { console.error(err); });
curl $RIGHTFOOT_HOST/benefactors/12345678-abcd-1234-abcd-12345678abcd \
--request GET \
--header 'Authorization: Bearer '"$RIGHTFOOT_API_KEY"
This endpoint retrieves an existing Benefactor
.
HTTP Request
GET
https://production.api.rightfoot.com/v1/benefactors/{uuid}
Query Parameters
Parameter | Type | Required | Description |
---|---|---|---|
uuid |
String | Yes | Unique identifier generated by Rightfoot for the benefactor. |
Response
{
"benefactor": {
"uuid": "12345678-abcd-1234-abcd-12345678abcd",
"firstName": "John",
"lastName": "Doe",
"verificationStatus": "UNVERIFIED"
}
}
This beneficiary API responds with the current state of the Benefactor
object.
Key | Type | Nullable? | Description |
---|---|---|---|
benefactor |
Object<Benefactor> |
No | The created benefactor with provided fields populated. |
List Benefactors
This endpoint provides a filterable list of benefactors.
import rightfoot
from rightfoot.rest import ApiException
try:
response = rightfoot_client.get_benefactors(count=50, offset=100)
print(response)
except ApiException as e:
print("Call failed: %s" % e)
import { ListBenefactorsResponse } from 'rightfoot-node';
const count = 30;
const offset = 40;
api.getBenefactors(count, offset)
.then(({ benefactors }: ListBenefactorsResponse) => { console.log(benefactors); })
.catch(err => { console.error(err); });
curl $RIGHTFOOT_HOST/benefactors \
--request GET \
--header 'Authorization: Bearer '"$RIGHTFOOT_API_KEY"
HTTP Request
GET
https://production.api.rightfoot.com/v1/benefactors
Query Parameters
Parameter | Type | Required | Description |
---|---|---|---|
count |
Integer | No | Number of benefactors to return in one paged request. Defaults and limited to 50. |
offset |
Integer | No | Benefactors offset to start query from, when paging through benefactors. |
Response
{
"benefactors": [
{
"uuid": "12345678-abcd-1234-abcd-12345678abcd",
"firstName": "John",
"lastName": "Doe",
"verificationStatus": "UNVERIFIED"
}
]
}
This API responds with the current state of the Benefactor
s matching the
requested filters.
Key | Type | Nullable? | Description |
---|---|---|---|
benefactors |
Object<Benefactor>[] |
No | The benefactors matching the filters. |
Verify Benefactor
This endpoint begins the verification process for a benefactor. It is recommended that a verification BenefactorDocument
is uploaded for this benefactor is uploaded immediately after starting benefactor verification.
import rightfoot
from rightfoot.rest import ApiException
benefactor_uuid = "12345678-abcd-1234-abcd-12345678abcd"
mailing_address = rightfoot.models.MailingAddress(
line1="901 Shelby Drive", city="Memphis", state="TN", zip_code="38116-0123")
request = rightfoot_client.VerifyBenefactorRequest(
date_of_birth="1986-10-24",
social_security_number="572-52-1234",
mailing_address=mailing_address)
try:
response = rightfoot_client.verify_benefactor(request, benefactor_uuid)
print(response)
except ApiException as e:
print("Call failed: %s" % e)
import {
VerifyBenefactorRequest,
VerifyBenefactorResponse
} from 'rightfoot-node';
const benefactor_uuid = "12345678-abcd-1234-abcd-12345678abcd";
const request: VerifyBenefactorRequest = {
dateOfBirth: "1986-10-24",
socialSecurityNumber: "572-52-1234",
mailingAddress: {
line1: "901 Shelby Drive",
city: "Memphis",
state: "TN",
zipCode: "38116-0123"
}
};
api.verifyBenefactor(request, benefactor_uuid)
.then(({ benefactor }: VerifyBenefactorResponse) => { console.log(benefactor); })
.catch(err => { console.error(err); });
curl $RIGHTFOOT_HOST/benefactors/12345678-abcd-1234-abcd-12345678abcd/verification/verify \
--request POST \
--header 'Authorization: Bearer '"$RIGHTFOOT_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
dateOfBirth: "1986-10-24",
socialSecurityNumber: "572-52-1234",
mailingAddress: {
line1: "901 Shelby Drive",
city: "Memphis",
state: "TN",
zipCode: "38116-0123"
}
}'
HTTP Request
POST
https://production.api.rightfoot.com/v1/benefactors/{uuid}/verification/verify
Body Parameters
Key | Type | Required | Description |
---|---|---|---|
dateOfBirth |
String | Yes | Birth date for the benefactor formatted as YYYY-MM-DD . |
socialSecurityNumber |
String | Yes | Social security number for the benefactor formatted as ###-##-#### . |
mailingAddress |
Object<MailingAddress> |
Yes | Mailing address for the benefactor, to be provided to payment provider. |
Response
{
"benefactor": {
"uuid": "12345678-abcd-1234-abcd-12345678abcd",
"firstName": "Aubrey",
"lastName": "Graham"
}
}
This verify API responds with the Benefactor
to be verified.
Key | Type | Nullable? | Description |
---|---|---|---|
benefactor |
Object<Benefactor> |
No | The Benefactor to be verified. |
Upload Benefactor Verification Document
This endpoint submits a BenefactorDocument
to verify a benefactor's identity. Verification documents will only be accepted for benefactors who have initiated the verification process.
import base64
import rightfoot
from rightfoot.rest import ApiException
benefactor_uuid = "12345678-abcd-1234-abcd-12345678abcd"
with open("path/to/license.jpg", "rb") as image_file:
base64_encoded_image_file = base64.b64encode(image_file.read())
request = rightfoot.UploadBenefactorVerificationDocumentRequest(
type="LICENSE",
file=base64_encoded_image_file)
try:
response =
rightfoot_client.upload_benefactor_verification_document(
request, benefactor_uuid)
print(response)
except ApiException as e:
print("Call failed: %s" % e)
import * as fs from 'fs';
import {
UploadBenefactorVerificationDocumentRequest,
UploadBenefactorVerificationDocumentResponse,
} from 'rightfoot-node';
const benefactor_uuid = "12345678-abcd-1234-abcd-12345678abcd";
let base64_encoded_image_file = null;
fs.readFile('path/to/license.jpg', (err, data) => {
if (err) {
console.error(err)
return;
}
base64_encoded_image_file = Buffer.from(data).toString('base64');
})
const request: UploadBenefactorVerificationDocumentRequest = {
type: UploadBenefactorVerificationDocumentRequest.TypeEnum.LICENSE,
file: base64_encoded_image_file
};
api.uploadBenefactorVerificationDocument(request, benefactor_uuid)
.then(({ benefactor }: UploadBenefactorVerificationDocumentResponse) => {
console.log(benefactor);
})
.catch(err => { console.error(err); });
curl $RIGHTFOOT_HOST/benefactors/12345678-abcd-1234-abcd-12345678abcd/verification/documents \
--request POST \
--header 'Authorization: Bearer '"$RIGHTFOOT_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
file: "'$({cat path/to/license.jpg | base64})'",
type: "LICENSE"
}'
HTTP Request
POST
https://production.api.rightfoot.com/v1/benefactors/{uuid}/verification/documents
Body Parameters
Key | Type | Required | Description |
---|---|---|---|
file |
String | Yes | The base 64 encoded content of the document. Must be a color scan or photo. Acceptable formats are .jpg, .jpeg, and .png. |
type |
Enum<VerificationDocumentType> |
Yes | Type of verification document being uploaded for the benefactor. |
Response
{
"document": {
"uuid": "12345678-abcd-1234-abcd-12345678abcd",
"type": "LICENSE",
"verificationStatus": "PENDING"
}
}
This upload API responds with the uploaded BenefactorDocument
.
Key | Type | Nullable? | Description |
---|---|---|---|
document |
Object<BenefactorDocument> |
No | The uploaded verification BenefactorDocument . |
List Benefactor Verification Documents
This endpoint provides a list of uploaded BenefactorDocument
s for a benefactor.
import rightfoot
from rightfoot.rest import ApiException
benefactor_uuid = "12345678-abcd-1234-abcd-12345678abcd"
try:
response = rightfoot_client.list_benefactor_documents(benefactor_uuid)
print(response)
except ApiException as e:
print("Call failed: %s" % e)
import { ListBenefactorDocumentsResponse } from 'rightfoot-node';
const benefactorUuid = "12345678-abcd-1234-abcd-12345678abcd";
api.listBenefactorDocuments(benefactorUuid)
.then(({ benefactorDocuments }: ListBenefactorDocumentsResponse) => { console.log(benefactorDocuments); })
.catch(err => { console.error(err); });
curl $RIGHTFOOT_HOST/benefactors/12345678-abcd-1234-abcd-12345678abcd/verification/documents \
--request GET \
--header 'Authorization: Bearer '"$RIGHTFOOT_API_KEY"
HTTP Request
GET
https://production.api.rightfoot.com/v1/benefactors/{uuid}/verification/documents
Query Parameters
Parameter | Type | Required | Description |
---|---|---|---|
uuid |
String | Yes | The unique identifier of the Benefactor for whom BenefactorDocument s are being fetched. |
Response
{
"documents": [
{
"uuid": "87654321-efgh-5678-efgh-87654321efgh",
"type": "PASSPORT",
"verificationStatus": "ACCEPTED",
}
]
}
This API responds with the current state of the BenefactorDocument
s for a Benefactor
.
Key | Type | Nullable? | Description |
---|---|---|---|
documents |
Object<BenefactorDocument>[] |
No | The BenefactorDocuments uploaded by the Benefactor . |
Organizations
Organization
is a business user, which can provide payments for a Beneficiary
's Loan
s.
Funding sources are added to them to originate payments similar to funding sources owned
by a Beneficiary
.
List Organizations
This endpoint provides a filterable list of organizations.
import rightfoot
from rightfoot.rest import ApiException
try:
response = rightfoot_client.get_organizations(count=50, offset=100)
print(response)
except ApiException as e:
print("Call failed: %s" % e)
import { ListOrganizationsResponse } from 'rightfoot-node';
const count = 30;
const offset = 40;
api.getOrganizations(count, offset)
.then(({ organizations }: ListOrganizationsResponse) => { console.log(organizations); })
.catch(err => { console.error(err); });
curl $RIGHTFOOT_HOST/organizations \
--request GET \
--header 'Authorization: Bearer '"$RIGHTFOOT_API_KEY"
HTTP Request
GET
https://production.api.rightfoot.com/v1/organizations
Query Parameters
Parameter | Type | Required | Description |
---|---|---|---|
count |
Integer | No | Number of organizations to return in one paged request. Defaults and limited to 50. |
offset |
Integer | No | Organizations offset to start query from, when paging through organizations. |
Response
{
"organizations": [
{
"uuid": "12345678-abcd-1234-abcd-12345678abcd",
"name": "My Organization",
"balance": 1000
}
]
}
This API responds with the current state of the Organization
s matching the
requested filters.
Key | Type | Nullable? | Description |
---|---|---|---|
organizations |
Object<Organization>[] |
No | The organizations matching the filters. |
Loan Linking
Beneficiaries need to add some basic information about their loans to complete their onboarding process. We support two approaches for providing loan account details to Rightfoot: 1) a bring-your-own-data experience, and 2) a Rightfoot-managed Plaid experience.
There are advantages and disadvantages to both approaches, but most customers choose to manage their own Plaid integration and link provide the subset of data because they:
- 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.
In some cases, customers choose to let Rightfoot manage the Plaid integration because they:
- Want Rightfoot to own the business relationship with Plaid, billing you the costs associated with this.
- Want to test Rightfoot end-to-end prior to finishing onboarding with Plaid.
- Avoid access to the loan data for privacy and security reasons, deferring that responsibility exclusively to Rightfoot.
- Do not have a use for the loan data provided by Plaid in their products.
- 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).
Bring Your Own 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 $RIGHTFOOT_HOST/beneficiaries/addGenericLoan \
--request POST \
--header 'Authorization: Bearer '"$RIGHTFOOT_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"uuid": "12345678-abcd-1234-abcd-12345678abcd",
"plaidInstitutionId": "ins_1",
"accountNumber": "123-ABC-0",
"sequenceNumber": "001",
"paymentReferenceNumber": "123-ABC-00123-ABC",
"guarantorName": "Foo Guarantor"
}'
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 . |
destinationUuid |
String | No | Unique identifier given by Rightfoot to identify a destination if vendor does not support plaid. |
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",
"beneficiaryUuid": "12345678-abcd-1234-abcd-12345678abcd",
"accountNumber": "*****BC-0",
"status": "ACTIVE"
}
}
This addGenericLoan
API responds with the updated Beneficiary.
Key | Type | Nullable? | Description |
---|---|---|---|
loan |
Object<Loan> |
No | The loan created based on the information provided. |
Rightfoot-Managed Plaid Loan Data
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 $RIGHTFOOT_HOST/beneficiaries/addPlaidToken \
--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"
}'
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. |
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 $RIGHTFOOT_HOST/beneficiaries/12345678-abcd-1234-abcd-12345678abcd/loans \
--request GET \
--header 'Authorization: Bearer '"$RIGHTFOOT_API_KEY"
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",
"beneficiaryUuid": "12345678-abcd-1234-abcd-12345678abcd",
"status": "ACTIVE"
}
]
}
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. |
Retrieve Loan
This endpoint retrieves the specified Loan
object.
import rightfoot
from rightfoot.rest import ApiException
try:
response = rightfoot_client.get_loan(uuid="12345678-abcd-1234-abcd-12345678abcd")
print(response)
except ApiException as e:
print("Call failed: %s" % e)
import { GetLoanResponse } from 'rightfoot-node';
const uuid = "12345678-abcd-1234-abcd-12345678abcd";
api.getLoan(uuid)
.then(({ loan }: GetLoanResponse) => { console.log(loan); })
.catch(err => { console.error(err); });
curl $RIGHTFOOT_HOST/loans/12345678-abcd-1234-abcd-12345678abcd \
--request GET \
--header 'Authorization: Bearer '"$RIGHTFOOT_API_KEY"
HTTP Request
GET
https://production.api.rightfoot.com/loans/{uuid}
Query Parameters
Parameter | Type | Required | Description |
---|---|---|---|
uuid |
String | Yes | Unique identifier generated by Rightfoot for the loan. |
Response
{
"loan": {
"uuid": "12345678-abcd-1234-abcd-12345678abcd",
"beneficiaryUuid": "12345678-abcd-1234-abcd-12345678abcd",
"accountNumber": "*****BC-0",
"status": "ACTIVE"
}
}
This getLoan
API responds with the updated Loan
.
Key | Type | Nullable? | Description |
---|---|---|---|
loan |
Object<Loan> |
No | The loan in its current state. |
Delete Loan
This endpoint deletes the specified Loan
object.
import rightfoot
from rightfoot.rest import ApiException
try:
response = rightfoot_client.delete_loan(uuid="12345678-abcd-1234-abcd-12345678abcd")
print(response)
except ApiException as e:
print("Call failed: %s" % e)
import { DeleteLoanResponse } from 'rightfoot-node';
const uuid = "12345678-abcd-1234-abcd-12345678abcd";
api.deleteLoan(uuid)
.then(({ loan }: DeleteLoanResponse) => { console.log(loan); })
.catch(err => { console.error(err); });
curl $RIGHTFOOT_HOST/loans/12345678-abcd-1234-abcd-12345678abcd \
--request DELETE \
--header 'Authorization: Bearer '"$RIGHTFOOT_API_KEY"
HTTP Request
DELETE
https://production.api.rightfoot.com/loans/{uuid}
Query Parameters
Parameter | Type | Required | Description |
---|---|---|---|
uuid |
String | Yes | Unique identifier generated by Rightfoot for the loan. |
Response
{
"loan": {
"uuid": "12345678-abcd-1234-abcd-12345678abcd",
"beneficiaryUuid": "12345678-abcd-1234-abcd-12345678abcd",
"accountNumber": "*****BC-0",
"status": "CLOSED"
}
}
This deleteLoan
API responds with the updated Loan
.
Key | Type | Nullable? | Description |
---|---|---|---|
loan |
Object<Loan> |
No | The loan created based on the information provided. |
Funding Sources
Funding sources specify the source where the payment is coming from. Funding sources can be attached to benefactors, organizations, or beneficiaries*, depending on your app's funding model. (*As of February 2022, creating funding sources with beneficiaries has been deprecated, please use the more robust benefactor model instead.)
Two models of providing a Plaid token are supported, depending on if you are already using Plaid in your application. If you currently use Plaid in your application you can pass in a Dwolla processor token that you retrieve with the Plaid-Dwolla integration. 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.
If you do not have a relationship with Plaid, you can pass in the Plaid
Token created with Plaid Link using Rightfoot's public Plaid key: 1773c898604f2bd4d68ecbbc8504f9
Create Funding Source for Benefactor
HTTP Request
POST
https://production.api.rightfoot.com/v1/fundingSources
import { CreateFundingSourceRequest } from 'rightfoot-node';
const processorTokenRequest: CreateFundingSourceRequest = {
benefactorUuid: '12345678-abcd-1234-abcd-12345678abcd',
dwollaProcessorToken: 'dwolla-processor-token'
};
rightfootClient.createFundingSource(processorTokenRequest)
.then(response => console.log(response))
.catch(error => console.error(error));
import rightfoot
from rightfoot.rest import ApiException
processor_token_request = rightfoot.CreateFundingSourceRequest(
benefactor_uuid="12345678-abcd-1234-abcd-12345678abcd",
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 $RIGHTFOOT_HOST/fundingSources \
--request POST\
--header 'Authorization: Bearer '"$RIGHTFOOT_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"benefactorUuid": "12345678-abcd-1234-abcd-12345678abcd",
"dwollaProcessorToken": "dwolla-processor-token"
}'
Body Parameters - with Dwolla Processor Token
Parameter | Type | Required | Description |
---|---|---|---|
benefactorUuid |
String | Yes | Unique identifier generated by Rightfoot for Benefactor . |
dwollaProcessorToken |
String | Yes | 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. |
import { CreateFundingSourceRequest } from 'rightfoot-node';
const plaidRequest: CreateFundingSourceRequest = {
benefactorUuid: '12345678-abcd-1234-abcd-12345678abcd',
plaidPublicToken: 'plaid-public-token',
accountId: 'selected-account-id'
};
rightfootClient.createFundingSource(plaidRequest)
.then(response => console.log(response))
.catch(error => console.error(error));
import rightfoot
from rightfoot.rest import ApiException
plaid_request = rightfoot.CreateFundingSourceRequest(
benefactor_uuid="12345678-abcd-1234-abcd-12345678abcd",
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)
curl $RIGHTFOOT_HOST/fundingSources \
--request POST \
--header 'Authorization: Bearer '"$RIGHTFOOT_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"benefactorUuid": "12345678-abcd-1234-abcd-12345678abcd",
"plaidPublicToken": "plaid-public-token",
"accountId": "selected-account-id",
}'
Body Parameters - with Plaid public token
Parameter | Type | Required | Description |
---|---|---|---|
benefactorUuid |
String | Yes | Unique identifier generated by Rightfoot for Benefactor . |
plaidPublicToken |
String | Yes | 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 | Yes | Account ID from Plaid Link when a user selects a specific checking or savings bank account from the bank institution they log into. |
import { CreateFundingSourceRequest } from 'rightfoot-node';
const microDepositRequest: CreateFundingSourceRequest = {
benefactorUuid: '12345678-abcd-1234-abcd-12345678abcd',
accountNumber: '12345',
routingNumber: '222222666'
};
rightfootClient.createFundingSource(microDepositRequest)
.then(response => console.log(response))
.catch(error => console.error(error));
import rightfoot
from rightfoot.rest import ApiException
micro_deposit_request = rightfoot.CreateFundingSourceRequest(
benefactor_uuid="12345678-abcd-1234-abcd-12345678abcd",
account_number="12345",
routing_number="222222666")
try:
response = rightfoot_client.create_funding_source(micro_deposit_request)
print(response)
except ApiException as e:
print("Call failed: %s" % e)
curl $RIGHTFOOT_HOST/fundingSources \
--request POST\
--header 'Authorization: Bearer '"$RIGHTFOOT_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"benefactorUuid": "12345678-abcd-1234-abcd-12345678abcd",
"accountNumber": "12345",
"routingNumber": "222222666"
}'
Body Parameters - with bank account number and the bank account's routing number
Parameter | Type | Required | Description | Constraints |
---|---|---|---|---|
benefactorUuid |
String | Yes | Unique identifier generated by Rightfoot for a Benefactor. | N/A |
accountNumber |
String | Yes | The bank account number. | Must be a valid ABA account number. |
routingNumber |
String | Yes | The bank account’s routing number. | Must be a valid ABA routing number. |
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. |
Create Funding Source for Organization
In addition to using Dwolla and Plaid tokens, funding sources for Organizations can
also be created using a bank account number
and the bank account's routing number. The funding source will have a status of
UNVERIFIED
. Ownership of the account needs to be verified via
micro-deposit verification before money can be transferred from the linked
bank account to the funding source.
After initiating micro-deposits, Dwolla will transfer two random amounts of less than $0.10
to the linked bank account in 1-2 business days. Once these deposits are received,
the two amounts can be verified with the Verify Funding Source endpoint.
POST
https://production.api.rightfoot.com/v1/fundingSources
import { CreateFundingSourceRequest } from 'rightfoot-node';
const processorTokenRequest: CreateFundingSourceRequest = {
organizationUuid: '12345678-abcd-1234-abcd-12345678abcd',
dwollaProcessorToken: 'dwolla-processor-token'
};
rightfootClient.createFundingSource(processorTokenRequest)
.then(response => console.log(response))
.catch(error => console.error(error));
import rightfoot
from rightfoot.rest import ApiException
processor_token_request = rightfoot.CreateFundingSourceRequest(
organization_uuid="12345678-abcd-1234-abcd-12345678abcd",
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 $RIGHTFOOT_HOST/fundingSources \
--request POST\
--header 'Authorization: Bearer '"$RIGHTFOOT_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"organizationUuid": "12345678-abcd-1234-abcd-12345678abcd",
"dwollaProcessorToken": "dwolla-processor-token"
}'
Body Parameters - with Dwolla Processor Token
Parameter | Type | Required | Description |
---|---|---|---|
organizationUuid |
String | Yes | Unique identifier generated by Rightfoot for Organization. |
dwollaProcessorToken |
String | Yes | 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. |
import { CreateFundingSourceRequest } from 'rightfoot-node';
const microDepositRequest: CreateFundingSourceRequest = {
organizationUuid: '12345678-abcd-1234-abcd-12345678abcd',
accountNumber: '12345',
routingNumber: '222222666'
};
rightfootClient.createFundingSource(microDepositRequest)
.then(response => console.log(response))
.catch(error => console.error(error));
import rightfoot
from rightfoot.rest import ApiException
micro_deposit_request = rightfoot.CreateFundingSourceRequest(
organization_uuid="12345678-abcd-1234-abcd-12345678abcd",
account_number="12345",
routing_number="222222666")
try:
response = rightfoot_client.create_funding_source(micro_deposit_request)
print(response)
except ApiException as e:
print("Call failed: %s" % e)
curl $RIGHTFOOT_HOST/fundingSources \
--request POST\
--header 'Authorization: Bearer '"$RIGHTFOOT_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"organizationUuid": "12345678-abcd-1234-abcd-12345678abcd",
"accountNumber": "12345",
"routingNumber": "222222666"
}'
Body Parameters - with bank account number and the bank account's routing number
Parameter | Type | Required | Description |
---|---|---|---|
organizationUuid |
String | Yes | Unique identifier generated by Rightfoot for Organization. |
accountNumber |
String | Yes | The bank account number. |
routingNumber |
String | Yes | The bank account’s routing number. |
import { CreateFundingSourceRequest } from 'rightfoot-node';
const plaidRequest: CreateFundingSourceRequest = {
organizationUuid: '12345678-abcd-1234-abcd-12345678abcd',
plaidPublicToken: 'plaid-public-token',
accountId: 'selected-account-id'
};
rightfootClient.createFundingSource(plaidRequest)
.then(response => console.log(response))
.catch(error => console.error(error));
import rightfoot
from rightfoot.rest import ApiException
plaid_request = rightfoot.CreateFundingSourceRequest(
organization_uuid="12345678-abcd-1234-abcd-12345678abcd",
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)
curl $RIGHTFOOT_HOST/fundingSources \
--request POST \
--header 'Authorization: Bearer '"$RIGHTFOOT_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"organizationUuid": "12345678-abcd-1234-abcd-12345678abcd",
"plaidPublicToken": "plaid-public-token",
"accountId": "selected-account-id",
}'
Body Parameters - for Organization with Plaid public token
Parameter | Type | Required | Description |
---|---|---|---|
organizationUuid |
String | Yes | Unique identifier generated by Rightfoot for Organization. |
plaidPublicToken |
String | Yes | 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 | Yes | Account ID from Plaid Link when a user selects a specific checking or savings bank account from the bank institution they log into. |
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. |
Create Funding Source for Beneficiary
import { CreateFundingSourceRequest } from 'rightfoot-node';
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
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 $RIGHTFOOT_HOST/fundingSources \
--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"
}'
Body Parameters - with Dwolla Processor Token
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. |
dwollaProcessorToken |
String | Yes | 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. |
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));
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)
curl $RIGHTFOOT_HOST/fundingSources \
--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",
}'
Body Parameters - with Plaid public token
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 | Yes | 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 | Yes | Account ID from Plaid Link when a user selects a specific checking or savings bank account from the bank institution they log into. |
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. |
Create ACH Credit Funding Source For Organization
Creates a FundingSource
of type ACH_CREDIT_PROXY
, owned by an Organization
. This FundingSource
can be
used normally for Payment
creation requests, and payments will be continued on as the ACH Credit is
received to back the Payment
requests.
import rightfoot
from rightfoot.rest import ApiException
try:
response = rightfoot_client.create_ach_credit_funding_source_for_organization(
uuid="12345678-abcd-1234-abcd-12345678abcd"
)
print(response)
except ApiException as e:
print(f"Call failed: {e}")
const uuid = "12345678-abcd-1234-abcd-12345678abcd";
rightfootClient.createAchCreditFundingSourceForOrganization(uuid)
.then((response) => response.json())
.then((data) => { console.log(data); })
.catch((err) => { console.error(err); });
curl $RIGHTFOOT_HOST/organizations/12345678-abcd-1234-abcd-12345678abcd/fundingSources/proxy \
--request POST \
--header 'Authorization: Bearer '"$RIGHTFOOT_API_KEY"
HTTP Request
POST
https://production.api.rightfoot.com/v1/organizations/{uuid}/fundingSources/proxy
Query Parameters
Parameter Name | Type | Nullable | Description |
---|---|---|---|
uuid |
String |
No | The identifier for the Organization who will own the created FundingSource . |
Request Body
The body of the request is empty.
Field Name | Type | Nullable | Description |
---|
Example request body:
json
{}
Response Body
This API responds with the created ACH Credit funding source.
Field Name | Type | Nullable? | Description |
---|---|---|---|
fundingSource |
Object<FundingSource> |
No | The created FundingSource . |
Example response body:
json
{
"fundingSource": {
"uuid": "12345678-abcd-1234-abcd-12345678abcd",
"type": "ACH_CREDIT_PROXY"
}
}
Create ACH Credit Funding Source For Benefactor
Creates a FundingSource
of type ACH_CREDIT_PROXY
, owned by an Benefactor
. This FundingSource
can be
used normally for Payment
creation requests, and payments will be continued on as the ACH Credit is
received to back the Payment
requests.
import rightfoot
from rightfoot.rest import ApiException
try:
response = rightfoot_client.create_ach_credit_funding_source_for_benefactor(
uuid="12345678-abcd-1234-abcd-12345678abcd"
)
print(response)
except ApiException as e:
print(f"Call failed: {e}")
const uuid = "12345678-abcd-1234-abcd-12345678abcd";
rightfootClient.createAchCreditFundingSourceForBenefactor(uuid)
.then((response) => response.json())
.then((data) => { console.log(data); })
.catch((err) => { console.error(err); });
curl $RIGHTFOOT_HOST/benefactors/12345678-abcd-1234-abcd-12345678abcd/fundingSources/proxy \
--request POST \
--header 'Authorization: Bearer '"$RIGHTFOOT_API_KEY"
HTTP Request
POST
https://production.api.rightfoot.com/v1/benefactors/{uuid}/fundingSources/proxy
Query Parameters
Parameter Name | Type | Nullable | Description |
---|---|---|---|
uuid |
String |
No | The identifier for the Benefactor who will own the created FundingSource . |
Request Body
The body of the request is empty.
Field Name | Type | Nullable | Description |
---|
Example request body:
json
{}
Response Body
This API responds with the created ACH Credit funding source.
Field Name | Type | Nullable? | Description |
---|---|---|---|
fundingSource |
Object<FundingSource> |
No | The created FundingSource . |
Example response body:
json
{
"fundingSource": {
"uuid": "12345678-abcd-1234-abcd-12345678abcd",
"type": "ACH_CREDIT_PROXY"
}
}
Retrieve Funding Source
import rightfoot
from rightfoot.rest import ApiException
try:
response = rightfoot_client.get_funding_source(
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.getFundingSource(uuid)
.then(response => { console.log(response); })
.catch(err => { console.error(err); });
curl $RIGHTFOOT_HOST/fundingSources/12345678-abcd-1234-abcd-12345678abcd \
--request GET \
--header 'Authorization: Bearer '"$RIGHTFOOT_API_KEY"
This endpoint retrieves an existing FundingSource
.
HTTP Request
GET
https://production.api.rightfoot.com/v1/fundingSources/{uuid}
Query Parameters
Parameter | Type | Required | Description |
---|---|---|---|
uuid |
String | Yes | Unique identifier generated by Rightfoot for the funding source. |
Response
{
"fundingSource": {
"uuid": "12345678-abcd-1234-abcd-12345678abcd",
"type": "ACH_DEBIT_EXTERNAL",
"status": "VERIFIED"
}
}
This funding source API responds with the current state of the FundingSource
object.
Key | Type | Nullable? | Description |
---|---|---|---|
fundingSource |
Object<FundingSource> |
No | The funding source with current information. |
Retrieve ACH Credit Funding Source Routing Information
Retrieves the account number and routing number pair that can be used to push funds into a FundingSource
of type ACH_CREDIT_PROXY
.
import rightfoot
from rightfoot import ApiException
try:
response = rightfoot_client.getRoutingInformationForFundingSource(
uuid="12345678-abcd-1234-abcd-12345678abcd"
)
print(response)
except ApiException as e:
print(f"Call failed: {e}")
rightfootClient.getRoutingInformationForFundingSource(
'12345678-abcd-1234-abcd-12345678abcd'
)
.then((response) => response.json())
.then((data) => { console.log(data); })
.catch((err) => { console.error(err); })
curl $RIGHTFOOT_HOST/fundingSources/16a21f69-52db-4356-8342-80e02f8eaf4b/routingInformation \
--request GET \
--header 'Authorization: Bearer '"$RIGHTFOOT_API_KEY"
HTTP Request
GET
https://production.api.rightfoot.com/v1/fundingSources/{uuid}/routingInformation
Query Parameters
Parameter Name | Type | Nullable | Description |
---|---|---|---|
uuid |
String |
No | The identifier of the FundingSource . |
Response Body
This API responds with the routing information for the ACH Credit funding source. It will return an error
if the requested funding source is not of type ACH_CREDIT_PROXY
.
Field Name | Type | Nullable? | Description |
---|---|---|---|
accountNumber |
String |
No | The ABA Account Number for the FundingSource . |
routingNumber |
String |
No | The ABA Routing Number for the FundingSource . |
Example response
json
{
"accountNumber": "1234567890",
"routingNumber": "1111111111"
}
Verify Funding Source
import rightfoot
from rightfoot.rest import ApiException
verify_funding_source_request = rightfoot.VerifyFundingSourceRequest(
value1="0.01",
value2="0.02")
uuid = "12345678-abcd-1234-abcd-12345678abcd"
try:
response = rightfoot_client.verify_funding_source(verify_funding_source_request, uuid)
print(response)
except ApiException as e:
print("Call failed: %s" % e)
import { VerifyFundingSourceRequest } from 'rightfoot-node';
const verifyFundingSourceRequest: VerifyFundingSourceRequest = {
value1: '0.01',
value2: '0.02'
};
const uuid = '12345678-abcd-1234-abcd-12345678abcd';
rightfootClient.verifyFundingSource(verifyFundingSourceRequest, uuid)
.then(response => console.log(response))
.catch(error => console.error(error));
curl $RIGHTFOOT_HOST/fundingSource/12345678-abcd-1234-abcd-12345678abcd/fundingSources \
--request POST\
--header 'Authorization: Bearer '"$RIGHTFOOT_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"value1": "0.01",
"value2": "0.02"
}'
This endpoint verifies ownership of the funding source via micro-deposit verification.
HTTP Request
POST
https://production.api.rightfoot.com/v1/fundingSources/{uuid}/verify
Query Parameters
Parameter | Type | Required | Description |
---|---|---|---|
uuid |
String | Yes | Unique identifier generated by Rightfoot for the funding source. |
value1 |
String | Yes | First micro-deposit amount. |
value2 |
String | Yes | Second micro-deposit amount. |
Response
{
"fundingSource": {
"uuid": "12345678-abcd-1234-abcd-12345678abcd",
"status": "VERIFIED"
}
}
This API responds with the funding source with an updated status.
Parameter | Type | Nullable? | Description |
---|---|---|---|
fundingSource |
Object<FundingSource> |
No | The funding source object with an updated status. |
List Funding Sources for a Benefactor
import rightfoot
from rightfoot.rest import ApiException
try:
response = rightfoot_client.list_funding_sources_for_benefactor(
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.listFundingSourcesForBenefactor(uuid)
.then(response => { console.log(response); })
.catch(err => { console.error(err); });
curl $RIGHTFOOT_HOST/benefactors/12345678-abcd-1234-abcd-12345678abcd/fundingSources\
--request GET \
--header 'Authorization: Bearer '"$RIGHTFOOT_API_KEY"
This endpoint retrieves a list of funding sources for the current benefactor.
HTTP Request
GET
https://production.api.rightfoot.com/v1/benefactors/{uuid}/fundingSources
Query Parameters
Parameter | Type | Required | Description |
---|---|---|---|
uuid |
String | Yes | Unique identifier generated by Rightfoot for the benefactors. |
Response
{
"funding_sources": [
{
"uuid": "12345678-abcd-1234-abcd-12345678abcd"
}
]
}
This API responds with the list of funding sources connected to the benefactors.
Key | Type | Nullable? | Description |
---|---|---|---|
fundingSources |
Object<FundingSource>[] |
No | The funding sources connected to the provided benefactor. |
List Funding Sources for a Beneficiary
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 $RIGHTFOOT_HOST/beneficiaries/12345678-abcd-1234-abcd-12345678abcd/fundingSources\
--request GET \
--header 'Authorization: Bearer '"$RIGHTFOOT_API_KEY"
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. |
List Funding Sources for an Organization
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 $RIGHTFOOT_HOST/organizations/16a21f69-52db-4356-8342-80e02f8eaf4b/fundingSources \
--request GET \
--header 'Authorization: Bearer '"$RIGHTFOOT_API_KEY"
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.
Payments are withdrawn from funding sources using ACH. Bank ledger memos will typically reference a combination of Rightfoot and/or Charitize, Inc., as the processor.
While payments may complete within 3-8 business days, most payments typically process in 3-4 business days. A majority of this time is due to a waiting period in order to account for ACH return risk, where debited funds are cleared in 2-4 business days. Next-day payments are possible for customers with enterprise contracts.
Issue Payment
import rightfoot
from rightfoot.rest import ApiException
request = rightfoot.CreatePaymentRequest(
beneficiary_uuid="12345678-abcd-1234-abcd-12345678abcd",
loan_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',
loanUuid: '12345678-abcd-1234-abcd-12345678abcd',
paymentAmount: 50000,
};
rightfootClient.createPayment(request)
.then(response => { console.log(response); })
.catch(err => { console.error(err); });
curl $RIGHTFOOT_HOST/payments \
--request POST \
--header 'Authorization: Bearer '"$RIGHTFOOT_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"beneficiaryUuid": "12345678-abcd-1234-abcd-12345678abcd",
"loanUuid": "12345678-abcd-1234-abcd-12345678abcd",
"paymentAmount": 50000
}'
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 | Constraints |
---|---|---|---|---|
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 loans. | paymentAmount should be provided in cents. For example, {"paymentAmount": 250} translates to $2.50 USD. |
fundingSourceUuid |
String | No* | UUID of the FundingSource to make payments from. |
Response
{
"payment": {
"uuid": "12345678-abcd-1234-abcd-12345678abcd",
"fundingSourceUuid": "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 $RIGHTFOOT_HOST/payments/12345678-abcd-1234-abcd-12345678abcd \
--request GET \
--header 'Authorization: Bearer '"$RIGHTFOOT_API_KEY"
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",
"fundingSourceUuid": "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. |
Cancel Payment
from rightfoot.rest import ApiException
try:
response = rightfoot_client.cancel_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.cancelPayment(uuid)
.then(response => { console.log(response); })
.catch(err => { console.error(err); });
curl $RIGHTFOOT_HOST/payments/12345678-abcd-1234-abcd-12345678abcd/cancel \
--request POST \
--header 'Authorization: Bearer '"$RIGHTFOOT_API_KEY"
This endpoint cancels a payment (provided that the Payment
's
statusReason
is ACH_WITHDRAWAL_PENDING_SCHEDULING
), then returns
the updated payment along with error information.
HTTP Request
POST
https://production.api.rightfoot.com/v1/payments/{uuid}/cancel
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",
"fundingSourceUuid": "12345678-abcd-1234-abcd-12345678abcd",
"status": "FAILED",
"statusReason": "ACH_WITHDRAWAL_CANCELLED",
"description": null
}
}
This endpoint responds with the updated 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",
transfer_uuid="fedcba98-0123-bead-fade-3456789abcde",
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 transferUuid = 'fedcba98-0123-bead-fade-3456789abcde';
const createdOnOrAfter = 10;
const createdBefore = 20;
const count = 30;
const offset = 40;
api.getPaymentsForFundingSource(
fundingSourceUuid, transferUuid, createdOnOrAfter, createdBefore, count, offset)
.then(({ payments }: ListPaymentsResponse) => { console.log(payments); })
.catch(err => { console.error(err); });
curl $RIGHTFOOT_HOST/fundingSources/12345678-abcd-1234-abcd-12345678abcd/payments\
--request GET \
--header 'Authorization: Bearer '"$RIGHTFOOT_API_KEY"
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 | Constraints |
---|---|---|---|---|
uuid |
String | Yes | Funding source id to retrieve payments for. | |
transferUuid |
String | No | Transfer ID to look up all Payments funded or returned by the Transfer. | |
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. | Default = 50. Min = 1. Max = 50. |
offset |
Integer | No | Payment offset to start query from, when paging through payments. | Default = 0. Min = 0. |
Response
{
"payments": [
{
"uuid": "12345678-abcd-1234-abcd-12345678abcd",
"fundingSourceUuid": "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",
transfer_uuid="fedcba98-0123-bead-fade-3456789abcde",
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 transferUuid = 'fedcba98-0123-bead-fade-3456789abcde';
const createdOnOrAfter = 10;
const createdBefore = 20;
const count = 30;
const offset = 40;
api.getPaymentsForBeneficiary(
beneficiaryUuid, transferUuid, createdOnOrAfter, createdBefore, count, offset)
.then(({ payments }: ListPaymentsResponse) => { console.log(payments); })
.catch(err => { console.error(err); });
curl $RIGHTFOOT_HOST/beneficiaries/12345678-abcd-1234-abcd-12345678abcd/payments \
--request GET \
--header 'Authorization: Bearer '"$RIGHTFOOT_API_KEY"
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. |
transferUuid |
String | No | Transfer ID to look up all Payments funded or returned by the Transfer. |
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",
"fundingSourceUuid": "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. |
Transfers
Transfer
s represent ACH transfers into and out of FundingSource
s to satisfy the required funds for Payment
s or returns
for Payment
s in the event of a failure.
Retrieve Transfer
import rightfoot
from rightfoot.rest import ApiException
try:
response = rightfoot_client.get_transfer(
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.getTransfer(uuid)
.then(response => { console.log(response); })
.catch(err => { console.error(err); });
curl $RIGHTFOOT_HOST/transfers/12345678-abcd-1234-abcd-12345678abcd \
--request GET \
--header 'Authorization: Bearer '"$RIGHTFOOT_API_KEY"
This endpoint retrieves an existing transfer, updated with the latest status of its processing along with core information.
HTTP Request
GET
https://production.api.rightfoot.com/v1/transfers/{uuid}
Query Parameters
Parameter | Type | Required | Description |
---|---|---|---|
uuid |
String | Yes | Unique identifier generated by Rightfoot for the transfer. |
Response
{
"transfer": {
"uuid": "12345678-abcd-1234-abcd-12345678abcd",
"status": "SCHEDULED",
"amount": 100,
"fundingSourceUuid": "12345678-abcd-1234-abcd-12345678abcd"
}
}
This transfer API responds with the current state of the Transfer
object.
Parameter | Type | Nullable? | Description |
---|---|---|---|
transfer |
Object<Transfer> |
No | The requested transfer object. |
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. |
paymentsEnabled |
Boolean | No | Indicates if the Beneficiary is eligible for payments to be processed. Deprecated: Query for loans held by the Beneficiary instead. |
MailingAddress
Schema
Key | Type | Nullable? | Description | Constraints |
---|---|---|---|---|
line1 |
String | No | Mandatory mailing address line. | Limited to 512 characters. |
line2 |
String | Yes | Optional second line of an address. | Limited to 512 characters. |
city |
String | No | The city of the location. | Limited to 128 characters. |
state |
String | No | The two-letter state/territory abbreviation. | Exactly 2 capital characters representing a valid ANSI/FIPS state abbreviation. |
zipCode |
String | No | US Zone Improvement Plan (ZIP) Code, or alternatively ZIP+4 Code. | Due to format, must be exactly 5 characters (e.g. , 12345), or exactly 10 characters (e.g. 12345-6789). |
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. |
beneficiaryUuid |
String | No | Identifier for the Beneficiary that holds this loan. |
accountNumber |
String | No | Masked account number for the student loan account. Typically will include last four characters of account number, with preceding characters masked with asterisks (* ), but some accounts might vary in masked representation. |
status |
Enum<LoanStatus> |
No | Status of the loan. |
LoanStatus
Enum
Value | Description |
---|---|
ACTIVE |
Loan can accept payments. |
CLOSED |
Loan does not accept payments. |
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. |
fundingSourceUuid |
String | No | Identifier for the FundingSource making this payment. |
loanUuid |
String | No | Identifier for the Loan receiving this payment. |
beneficiaryUuid |
String | No | Identifier for the beneficiary benefiting from this payment. Deprecated: Prefer loanUuid , looking up Loan.beneficiaryUuid . |
paymentAmount |
Integer | No | Amount paid to loan, in cents USD. |
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. |
timeCreated |
Integer | No | Time the payment was created, in Epoch seconds UTC. |
timeCompleted |
Integer | Yes | Time the payment was completed with a loan servicer, in Epoch seconds UTC. |
withdrawalTransferUuid |
String | Yes | Unique identifier for the ACH Transfer object that is used for the ACH debit to provide funds for a Loan Payment. Set once a Payment is queued for an ACH transfer batch. |
returnTransferUuid |
String | Yes | Unique identifier for the ACH Transfer object that is used for the ACH credit to return funds for a failed Loan Payment. Set if a Payment is queued for an ACH transfer batch tor return. |
failureReasons |
Array[Object<FailureReason>] |
No | If the Payment is in a failed state, this field’s value is an array of FailureReason objects, which is a polymorphic object type. Depending on the nature of the payment failure(s), this array may contain different FailureReason types, and can also contain multiple instances of the same FailureReason with different sub-types. If the Payment is not in a failed state, this field is an empty array. |
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. |
FailureReason
Schema
{
"payment": {
"uuid": "12345678-abcd-1234-abcd-12345678abcd",
"failureReasons": [
{
"invalidAccountReason": {
"invalidLoanAccountReason": {
"invalidLoanPaymentSequenceNumber": {}
}
}
},
{
"closedAccountReason": {
"loanAccountDischargedReason": {}
}
},
{
"fundingIssueReason": {
"achReturnReason": {
"achReturnCode": "ACH_RETURN_CODE_R04_INVALID_ACCOUNT_NUMBER"
}
}
},
{
"internalFailureReason": {
"internalFailure": {}
}
}
]
}
}
Parameter | Type | Nullable? | Description |
---|---|---|---|
invalidAccountReason or closedAccountReason or fundingIssueReason or internalFailureReason |
Object<InvalidAccountReason> or Object<ClosedAccountReason> or Object<FundingIssueReason> or Object<InternalFailureReason> |
No, if present | This is a polymorphic object describing a specific Payment failure. This field is present if there is a loan payment failure. This field not nullable when present, but can be an empty object if no further information is available. If there is further information present, this object must be one of the following types: InvalidAccountReason , ClosedAccountReason , FundingIssueReason , or InternalFailureReason . |
InvalidAccountReason
Schema
{
"payment": {
"uuid": "12345678-abcd-1234-abcd-12345678abcd",
"failureReasons": [
{
"invalidAccountReason": {
"invalidLoanAccountReason": {
"invalidLoanPaymentSequenceNumber": {}
}
}
}
]
}
}
{
"payment": {
"uuid": "12345678-abcd-1234-abcd-12345678abcd",
"failureReasons": [
{
"invalidAccountReason": {
"invalidBeneficiaryReason": {
"invalidBeneficiaryPhoneNumber": {}
}
}
}
]
}
}
Parameter | Type | Nullable? | Description |
---|---|---|---|
invalidLoanAccountReason |
Object<InvalidLoanAccount> |
No, if present | This field is present if the loan payment failure is due to an invalid loan account. This field not nullable when present, but can be an empty object if no further information is available. If there is more information available, then it will be captured as an InvalidLoanAccount object. |
invalidBeneficiaryReason |
Object<InvalidBeneficiary> |
No, if present | This field is present if the loan payment failure is due to an invalid beneficiary. This field not nullable when present, but can be an empty object if no further information is available. If there is more information available, then it will be captured as an InvalidBeneficiary object. |
InvalidLoanAccount
Schema
{
"payment": {
"uuid": "12345678-abcd-1234-abcd-12345678abcd",
"failureReasons": [
{
"invalidAccountReason": {
"invalidLoanAccountReason": {
"invalidLoanAccountNumber": {}
}
}
}
]
}
}
{
"payment": {
"uuid": "12345678-abcd-1234-abcd-12345678abcd",
"failureReasons": [
{
"invalidAccountReason": {
"invalidLoanAccountReason": {
"invalidLoanPaymentReferenceNumber": {}
}
}
}
]
}
}
{
"payment": {
"uuid": "12345678-abcd-1234-abcd-12345678abcd",
"failureReasons": [
{
"invalidAccountReason": {
"invalidLoanAccountReason": {
"invalidLoanPaymentSequenceNumber": {}
}
}
}
]
}
}
Parameter | Type | Nullable? | Description |
---|---|---|---|
invalidLoanAccountNumber |
Object |
No, if present | This field is present if the loan account is deemed invalid due to an invalid loan account number. This field’s value will be an empty object today. In the future, it is possible that Rightfoot will enrich this field’s value with more information. |
invalidLoanPaymentReferenceNumber |
Object |
No, if present | This field is present if the loan account is deemed invalid due to an invalid loan payment reference number. This field’s value will be an empty object today. In the future, it is possible that Rightfoot will enrich this field’s value with more information. |
invalidLoanPaymentSequenceNumber |
Object |
No, if present | This field is present if the loan account is deemed invalid due to an invalid loan payment sequence number. This field’s value will be an empty object today. In the future, it is possible that Rightfoot will enrich this field’s value with more information. |
InvalidBeneficiary
Schema
{
"payment": {
"uuid": "12345678-abcd-1234-abcd-12345678abcd",
"failureReasons": [
{
"invalidAccountReason": {
"invalidBeneficiaryReason": {
"invalidBeneficiaryName": {}
}
}
}
]
}
}
{
"payment": {
"uuid": "12345678-abcd-1234-abcd-12345678abcd",
"failureReasons": [
{
"invalidAccountReason": {
"invalidBeneficiaryReason": {
"invalidBeneficiaryAddress": {}
}
}
}
]
}
}
{
"payment": {
"uuid": "12345678-abcd-1234-abcd-12345678abcd",
"failureReasons": [
{
"invalidAccountReason": {
"invalidBeneficiaryReason": {
"invalidBeneficiaryPhoneNumber": {}
}
}
}
]
}
}
Parameter | Type | Nullable? | Description |
---|---|---|---|
invalidBeneficiaryName |
Object |
No, if present | This field is present if the loan account is deemed invalid due to an invalid beneficiary name. This field’s value will be an empty object today. In the future, it is possible that Rightfoot will enrich this field’s value with more information. |
invalidBeneficiaryAddress |
Object |
No, if present | This field is present if the loan account is deemed invalid due to an invalid beneficiary address. This field’s value will be an empty object today. In the future, it is possible that Rightfoot will enrich this field’s value with more information. |
invalidBeneficiaryPhoneNumber |
Object |
No, if present | This field is present if the loan account is deemed invalid due to an invalid beneficiary phone number. This field’s value will be an empty object today. In the future, it is possible that Rightfoot will enrich this field’s value with more information. |
ClosedAccountReason
Schema
{
"payment": {
"uuid": "12345678-abcd-1234-abcd-12345678abcd",
"failureReasons": [
{
"closedAccountReason": {
"loanAccountMovedReason": {
"destination": "ins_12345"
}
}
}
]
}
}
{
"payment": {
"uuid": "12345678-abcd-1234-abcd-12345678abcd",
"failureReasons": [
{
"closedAccountReason": {
"loanAccountMovedReason": {}
}
}
]
}
}
{
"payment": {
"uuid": "12345678-abcd-1234-abcd-12345678abcd",
"failureReasons": [
{
"closedAccountReason": {
"loanAccountPaidOffReason": {}
}
}
]
}
}
{
"payment": {
"uuid": "12345678-abcd-1234-abcd-12345678abcd",
"failureReasons": [
{
"closedAccountReason": {
"loanAccountDischargedReason": {}
}
}
]
}
}
Parameter | Type | Nullable? | Description |
---|---|---|---|
loanAccountMovedReason |
Object<LoanAccountMovedReason> |
No, if present | This field is present if the loan payment failure is because the loan account has been moved to another loan servicer. This field not nullable when present, but can be an empty object if no further information is available. If there is more information available, then it will be captured as a LoanAccountMoved object. |
loanAccountPaidOffReason |
Object |
No, if present | This field is present if the loan payment failure is because the loan account has already been paid off in full. This field’s value will be an empty object today. In the future, it is possible that Rightfoot will enrich this field’s value with more information. |
loanAccountDischargedReason |
Object |
No, if present | This field is present if the loan payment failure is because the loan account has been discharged. This field’s value will be an empty object today. In the future, it is possible that Rightfoot will enrich this field’s value with more information. |
LoanAccountMovedReason
Schema
{
"payment": {
"uuid": "12345678-abcd-1234-abcd-12345678abcd",
"failureReasons": [
{
"closedAccountReason": {
"loanAccountMovedReason": {
"destination": "ins_12345"
}
}
}
]
}
}
{
"payment": {
"uuid": "12345678-abcd-1234-abcd-12345678abcd",
"failureReasons": [
{
"closedAccountReason": {
"loanAccountMovedReason": {}
}
}
]
}
}
Parameter | Type | Nullable? | Description |
---|---|---|---|
destination |
String |
Yes | If available, the Plaid institution the account was transitioned to. If unavailable, then null. |
FundingIssueReason
Schema
{
"payment": {
"uuid": "12345678-abcd-1234-abcd-12345678abcd",
"failureReasons": [
{
"fundingIssueReason": {
"invalidFundingSourceReason": {
"fundingSourceDeleted": {}
}
}
}
]
}
}
{
"payment": {
"uuid": "12345678-abcd-1234-abcd-12345678abcd",
"failureReasons": [
{
"fundingIssueReason": {
"achReturnReason": {
"achReturnCode": "ACH_RETURN_CODE_R02_ACCOUNT_CLOSED"
}
}
}
]
}
}
Parameter | Type | Nullable? | Description |
---|---|---|---|
invalidFundingSourceReason |
Object<InvalidFundingSource> |
No, if present | This field is present if the loan payment failure is due to an invalid funding source. This field not nullable when present, but can be an empty object if no further information is available. If there is more information available, then it will be captured as an InvalidFundingSource object. |
achReturnReason |
Object<AchReturn> |
No, if present | This field is present if the loan payment failure is due to an ACH return. This field not nullable when present, but can be an empty object if no further information is available. If there is more information available, then it will be captured as an AchReturn object. |
InvalidFundingSource
Schema
{
"payment": {
"uuid": "12345678-abcd-1234-abcd-12345678abcd",
"failureReasons": [
{
"fundingIssueReason": {
"invalidFundingSourceReason": {
"fundingSourceDeleted": {}
}
}
}
]
}
}
{
"payment": {
"uuid": "12345678-abcd-1234-abcd-12345678abcd",
"failureReasons": [
{
"fundingIssueReason": {
"invalidFundingSourceReason": {
"fundingSourceRemoved": {}
}
}
}
]
}
}
{
"payment": {
"uuid": "12345678-abcd-1234-abcd-12345678abcd",
"failureReasons": [
{
"fundingIssueReason": {
"invalidFundingSourceReason": {
"fundingSourceDeleted": {}
}
}
}
]
}
}
Parameter | Type | Nullable? | Description |
---|---|---|---|
fundingSourceDeleted |
Object |
No, if present | This field is present if the funding source is deemed invalid because it has been deleted. This field’s value will be an empty object today. In the future, it is possible that Rightfoot will enrich this field’s value with more information. |
fundingSourceRemoved |
Object |
No, if present | This field is present if the funding source is deemed invalid because it has been removed. This field’s value will be an empty object today. In the future, it is possible that Rightfoot will enrich this field’s value with more information. |
fundingSourceWrongKind |
Object |
No, if present | This field is present if the funding source is deemed invalid because it is the wrong kind of funding source. This field’s value will be an empty object today. In the future, it is possible that Rightfoot will enrich this field’s value with more information. |
AchReturn
Schema
{
"payment": {
"uuid": "12345678-abcd-1234-abcd-12345678abcd",
"failureReasons": [
{
"fundingIssueReason": {
"achReturnReason": {
"achReturnCode": "ACH_RETURN_CODE_R01_INSUFFICIENT_FUNDS"
}
}
}
]
}
}
Parameter | Type | Nullable? | Description |
---|---|---|---|
achReturnCode |
Enum<AchReturnCode> |
No, if present | This field is present if there is an ACH return. This field’s value will be the ACH return code enumeration as outlined in the AchReturnCode enumeration schema. |
AchReturnCode
Enum
Value | Description |
---|---|
ACH_RETURN_CODE_R01_INSUFFICIENT_FUNDS |
Available balance is not sufficient to cover the dollar value of the debit entry. |
ACH_RETURN_CODE_R02_ACCOUNT_CLOSED |
Previously active account has been closed. |
ACH_RETURN_CODE_R03_NO_ACCOUNT |
Account number structure is valid, but doesn’t match individual identified in entry or is not an open account. |
ACH_RETURN_CODE_R04_INVALID_ACCOUNT_NUMBER |
Account number structure is not valid. |
ACH_RETURN_CODE_R05_UNAUTHORIZED_DEBIT_CONSUMER |
A CCD or CTX debit entry was transmitted to a consumer account and was not authorized by the Receiver. Written Statement is required. |
ACH_RETURN_CODE_R06_ODFI_REQUEST |
The ODFI has requested that the RDFI return an erroneous entry, or a credit entry originated without the authorization of the Originator. |
ACH_RETURN_CODE_R07_AUTHORIZATION_REVOKED |
Consumer who previously authorized entries has revoked authorization with the Originator. Written Statement is required. |
ACH_RETURN_CODE_R08_PAYMENT_STOPPED |
The Receiver has requested the stop payment of a specific ACH debit entry. |
ACH_RETURN_CODE_R09_UNCOLLECTED_FUNDS |
Sufficient balance exists, but the value of uncollected items brings available balance below the amount of debit entry. |
ACH_RETURN_CODE_R10_ORIGINATOR_UNKNOWN_UNAUTHORIZED |
Receiver has no relationship with the Originator or has not authorized the Originator to debit the account. Written Statement is required. |
ACH_RETURN_CODE_R11_ENTRY_NONCONFORMANT_TO_TERMS |
The debit entry was inaccurate or improperly initiated. Other reasons include source document was ineligible, notice was not provided to the receiver or amount was inaccurately obtained. Written statement is required. |
ACH_RETURN_CODE_R12_ACCOUNT_SOLD |
A financial institution received an entry to an account that was sold to another FI (typically due to a merger). |
ACH_RETURN_CODE_R13_INVALID_ROUTING_NUMBER |
Entry contains a receiving DFI identification or gateway identification that is not a valid ACH routing number. |
ACH_RETURN_CODE_R14_REPRESENTATIVE_PAYEE_INCAPACITATED |
The representative payee is a person either deceased or no longer able to continue in original capacity (i.e. legally incapacitated adults or minors), while the beneficiary is not deceased. |
ACH_RETURN_CODE_R15_ACCOUNT_HOLDER_DECEASED |
(1) The beneficiary is deceased, or (2) The account holder is deceased. |
ACH_RETURN_CODE_R16_ACCOUNT_FROZEN |
(1) Access to the account is restricted due to specific action taken by the RDFI or by legal action; or (2) OFAC has instructed the RDFI to return the entry. |
ACH_RETURN_CODE_R17_QUESTIONABLE_CIRCUMSTANCES |
(1) Field(s) cannot be processed by RDFI; or (2) The entry contains an invalid DFI Account Number (account closed/no account/unable to locate account/invalid account number) and is believed by the RDFI to have been initiated under questionable circumstances. |
ACH_RETURN_CODE_R18_IMPROPER_EFFECTIVE_ENTRY_DATE |
(1) The effective entry date for a credit entry is more than two banking days after the banking day of processing as established by the originating ACH Operator; or (2) The effective entry date for a debit entry is more than one banking day after the processing date. |
ACH_RETURN_CODE_R19_AMOUNT_FIELD_ERROR |
(1) Amount field is non-numeric; (2) Amount field is not zero in a prenotification, DNE, ENR, notification of change, or zero dollar CCD, CTX, or IAT entry; (3) Amount field is zero in an entry other than a prenotification, DNE, ENR, notification of change, return, dishonored return, or zero dollar CCD, CTX, or IAT entry; or (4) Amount field is greater than $25,000 for ARC, BOC, and POP entries. |
ACH_RETURN_CODE_R20_NON_TRANSACTION_ACCOUNT |
ACH entry to a non-transaction account (typically due to account holder exceeding their monthly withdrawal threshold under Regulation D). |
ACH_RETURN_CODE_R21_INVALID_COMPANY_IDENTIFICATION |
The identification number used in the company identification field is not valid. |
ACH_RETURN_CODE_R22_INVALID_INDIVIDUAL_ID_NUMBER |
The Receiver has indicated to the RDFI that the number with which the Originator identified is not correct. |
ACH_RETURN_CODE_R23_CREDIT_ENTRY_REFUSED |
Any credit entry that is refused by the Receiver may be returned by the RDFI. |
ACH_RETURN_CODE_R24_DUPLICATE_ENTRY |
The RDFI has received what appears to be a duplicate entry; i.e. the trace number, date, dollar amount and/or other data matches another transaction. |
ACH_RETURN_CODE_R25_ADDENDA_ERROR |
(1) Addenda record indicator value is incorrect; (2) Addenda type code is invalid, out of sequence, or missing; (3) Number of addenda records exceeds allowable maximum; or (4) Addenda sequence number is invalid. |
ACH_RETURN_CODE_R26_MANDATORY_FIELD_ERROR |
Erroneous data or missing data in a mandatory field. |
ACH_RETURN_CODE_R27_TRACE_NUMBER_ERROR |
(1) Original entry trace number is not present in the addenda record on a return or notification of change entry; or (2) Trace number of an addenda record is not the same as the trace number of the preceding entry detail record. |
ACH_RETURN_CODE_R28_ROUTING_NUMBER_CHECK_DIGIT_ERROR |
The check digit for the routing number is invalid. |
ACH_RETURN_CODE_R29_COPORATE_CUSTOMER_ADVISED_NOT_AUTHORIZED |
The RDFI has been notified by the Receiver (non-consumer) that a specific entry has not been authorized by the Receiver. |
ACH_RETURN_CODE_R30_RDFI_NOT_PARTICIPANT_CHECK_TRUNCATION_PROGRAM |
The RDFI does not participate in a check truncation program. |
ACH_RETURN_CODE_R31_PERMISSIBLE_RETURN_ENTRY |
The RDFI may return a CCD or CTX entry that the ODFI agrees to accept. |
ACH_RETURN_CODE_R32_RDFI_NON_SETTLEMENT |
The RDFI is not able to settle the entry. |
ACH_RETURN_CODE_R34_LIMITED_PARTICIPATION_DFI |
The RDFI participation has been limited by a federal or state supervisor. |
ACH_RETURN_CODE_R35_IMPROPER_DEBIT_ENTRY_RETURN |
Debit entries (with the exception of reversing entries) are not permitted for CIE entries or to loan accounts. |
ACH_RETURN_CODE_R36_IMPROPER_CREDIT_ENTRY_RETURN |
ACH credit entries (with the exception of reversing entries) are not permitted for use with ARC, BOC, POP, RCK, TEL, XCK. |
ACH_RETURN_CODE_R61_MISROUTED_RETURN |
The financial institution preparing the return entry (the RDFI of the original entry) has placed the incorrect routing number in the receiving DFI identification field. |
ACH_RETURN_CODE_R62_ERRONEOUS_OR_REVERSING_DEBIT_RETURN |
The Originator’s/ODFI’s use of the reversal process has resulted in, or failed to correct, an unintended credit to the Receiver. |
ACH_RETURN_CODE_R67_DUPLICATE_RETURN |
The ODFI has received more than one return for the same entry. |
ACH_RETURN_CODE_R68_UNTIMELY_RETURN |
The return entry has not been sent within the time frame established by Nacha rules. |
ACH_RETURN_CODE_R69_FIELD_ERRORS |
One or more of the field requirements are incorrect. |
ACH_RETURN_CODE_R70_PERMISSIBLE_RETURN_ENTRY_NOT_ACCEPTED |
The ODFI has received a return entry identified by the RDFI as being returned with the permission of, or at the request of, the ODFI, but the ODFI has not agreed to accept the entry or has not requested the return of the entry. |
ACH_RETURN_CODE_R71_MISROUTED_DISHONORED_RETURN |
The financial institution preparing the dishonored return entry (the ODFI of the original entry) has placed the incorrect routing number in the receiving DFI identification field. |
ACH_RETURN_CODE_R72_UNTIMELY_DISHONORED_RETURN |
The dishonored return entry has not been sent within the designated time frame. |
ACH_RETURN_CODE_R73_TIMELY_ORIGINAL_RETURN |
The RDFI is certifying that the original return entry was sent within the time frame designated within Nacha rules. |
ACH_RETURN_CODE_R74_CORRECTED_RETURN |
The RDFI is correcting a previous return entry that was dishonored using return code R69 because it contained incomplete or incorrect information. |
ACH_RETURN_CODE_R75_RETURN_NOT_DUPLICATE |
The return entry was not a duplicate of an entry previously returned by the RDFI. |
ACH_RETURN_CODE_R76_NO_ERRORS_FOUND |
The original return entry did not contain the errors indicated by the ODFI in the dishonored return entry. |
ACH_RETURN_CODE_R77_NON_ACCEPTANCE_R62_DISHONORED_RETURN |
The RDFI returned both the erroneous entry and the related reversing entry, or the funds relating to the R62 dishonored return are not recoverable from the Receiver. |
InternalFailureReason
Schema
{
"payment": {
"uuid": "12345678-abcd-1234-abcd-12345678abcd",
"failureReasons": [
{
"internalFailureReason": {
"internalFailure": {}
}
}
]
}
}
Parameter | Type | Nullable? | Description |
---|---|---|---|
internalFailure |
Object |
No, if present | This field is present if the payment fails due to an internal issue. This payment failure type is very rare and our team typically begins investigation on them immediately. We typically reach out to our customers proactively when this type of payment failure occurs, and our team is always available at support@rightfoot.com to provide additional context. |
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. |
status |
Enum<FundingSourceVerificationStatus> |
No | Verification status of the funding source. Funding sources created with a micro-deposit will initially have a status of UNVERIFIED . |
type |
Enum<FundingSourceType> |
No | Semantic type of FundingSource . See FundingSourceType for more information. |
FundingSourceVerificationStatus
Enum
Value | Description |
---|---|
UNVERIFIED |
Funding source not verified. Funding source can only receive funds, not send them. Microdeposits might be pending. |
VERIFIED |
Funding source can be used to withdraw funds. |
FundingSourceType
Enum
Value | Description |
---|---|
ACH_DEBIT_EXTERNAL |
A Bank Account held by a customer, which ACH Debits are performed against |
ACH_CREDIT_PROXY |
A Bank Account held on behalf of a customer, which can accept ACH Credits into, for the purpose of enhanced control over the ACH Origination Process. |
Transfer
Schema
Transfer
s represent ACH transfers into and out of FundingSource
s to satisfy the required funds for Payment
s or returns
for Payment
s in the event of a failure.
Parameter | Type | Nullable? | Description |
---|---|---|---|
uuid |
String | No | Unique identifier generated by Rightfoot for transfer. |
amount |
Integer | No | Amount, in cents USD, transfers out of (negative) or into (positive) the FundingSource . |
status |
Enum<TransferStatus> |
No | Status of the transfer. |
fundingSourceUuid |
String | No | The identifier for the FundingSource that is being transacted against. |
TransferStatus
Enum
Value | Description |
---|---|
SCHEDULED |
Transfer has been scheduled for processing. |
COMPLETED |
Transfer is successfully completed. |
RETURNED |
Transfer was reversed/returned. Note, this status represents the returned state of an ACH transfer and not the returned state of a Payment . See ACH Return Codes for more information. |
Benefactor
Schema
Benefactor
s represent individuals who are making payments to Loans for the
benefit of a Beneficiary
. Benefactor
s can also be Beneficiary
s, as they
are conceptually just a non-business owner of a FundingSource
.
Parameter | Type | Nullable? | Description |
---|---|---|---|
uuid |
String | No | Unique identifier generated by Rightfoot for the Benefactor . |
firstName |
String | No | The given name of the Benefactor . |
lastName |
String | No | The family name of the Benefactor . |
verificationStatus |
Enum<BenefactorVerificationStatus> |
No | The verification status of the Benefactor . |
BenefactorVerificationStatus
Enum
Value | Description |
---|---|
UNVERIFIED |
The default verification status of the Benefactor until the verification process is complete. |
VERIFIED |
Indicates that the Benefactor has been successfully verified. |
FAILED |
Indicates that the attempt to verify the Benefactor has failed. A benefactor that has failed verification once is not eligible to go through the verification flow again. |
BenefactorDocument
Schema
Parameter | Type | Nullable? | Description |
---|---|---|---|
uuid |
String | No | Unique identifier for the uploaded BenefactorDocument . |
type |
Enum<VerificationDocumentType> |
No | Indicates the type of BenefactorDocument . |
verificationStatus |
Enum<VerificationDocumentStatus> |
No | Indicates the verification status of the BenefactorDocument . |
VerificationDocumentType
Enum
Value | Description |
---|---|
LICENSE |
Indicates that the verification document being uploaded for the Benefactor is a driver's license. |
PASSPORT |
Indicates that the verification document being uploaded for the Benefactor is a passport. |
ID_CARD |
Indicates that the verification document being uploaded for the Benefactor is an ID card. |
VerificationDocumentStatus
Enum
Value | Description |
---|---|
PENDING |
Indicates that the BenefactorDocument is pending review. |
ACCEPTED |
Indicates that the BenefactorDocument has been reviewed, and is now verified. |
REJECTED |
Indicates that the BenefactorDocument has been reviewed, and has not been verified. |
Organization
Schema
Organization
is a business user, which can provide payments for a Beneficiary
's Loan
s.
Funding sources are added to them to originate payments similar to funding sources owned
by a Beneficiary
.
Parameter | Type | Nullable? | Description |
---|---|---|---|
uuid |
String | No | Unique identifier generated by Rightfoot for the organization. |
name |
String | No | The human readable name for the business. Either its legal name or DBA name. |
balance |
Integer | No | Balance, in cents USD, held on behalf of the Organization pending distribution to loan servicer accounts. |
Status Page
rightfoot.statuspage.io/ is the canonical reference for any incidents that might be affecting our services, including many of our dependencies. Any scheduled maintenance will also be posted there. You can subscribe to updates via Slack, email, or other options.
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. |