Introduction

Rightfoot's API generates student debt beneficiary accounts and transfers funds to their loans.

We have language bindings for Python and TypeScript. You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right. If SDKs/libraries are desired for other languages, we are happy to develop them based on demand.

Authentication

import rightfoot

configuration = rightfoot.Configuration()
# Defaults to sandbox, but can be explicitly set to sandbox/production. 
configuration.host="https://sandbox.api.rightfoot.com/v1"
configuration.api_key['Authorization'] = os.env['RIGHTFOOT_API_KEY']
configuration.api_key_prefix['Authorization'] = 'Bearer'
rightfoot_client = rightfoot.RightfootApi(rightfoot.ApiClient(configuration))

import { Configuration, RightfootApi } from 'rightfoot-node';

const config: Configuration = new Configuration({
  apiKey: `Bearer ${RIGHTFOOT_API_KEY}`,
});

const rightfootClient = new RightfootApi(config, "https://sandbox.api.rightfoot.com/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

You must replace secure-private-key with your personal API 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
`firstName`	String	Yes	The given name of the beneficiary.
`lastName`	String	Yes	The family name of the beneficiary.
`dateOfBirth`	String	Yes	Birth date for the beneficiary formatted as YYYY-MM-DD.
`phoneNumber`	String	Yes	Phone number for the beneficiary formatted internationally with spacing such as +1 555 555 5555.
`mailingAddress`	`Object<MailingAddress>`	Yes	Mailing address for the beneficiary, to be provided to payment provider.

Response

{
  "beneficiary": {
    "uuid": "12345678-abcd-1234-abcd-12345678abcd",
    "firstName": "Person",
    "lastName": "Doe",
    "dateOfBirth": "1970-01-01",
    "phoneNumber": "+1 555 555 5555",
    "mailingAddress":  {
      "line1": "123 Easy Street",
      "line2": null,
      "city": "Palo Alto",
      "state": "CA",
      "zipCode": "12345-0123"
    }
  }
}

This create API responds with the created Beneficiary.

Key	Type	Nullable?	Description
`beneficiary`	`Object<Beneficiary>`	No	The created beneficiary with provided fields populated.

Retrieve Beneficiary

import rightfoot
from rightfoot.rest import ApiException

request = rightfoot.GetBeneficiaryRequest(
    uuid="12345678-abcd-1234-abcd-12345678abcd")

try:
    response = rightfoot_client.get_beneficiary(
        uuid="12345678-abcd-1234-abcd-12345678abcd")
    print(response)
except ApiException as e:
    print("Call failed: %s" % e)

const uuid = '12345678-abcd-1234-abcd-12345678abcd';
api.getBeneficiary(uuid)
  .then(response => { console.log(response); })
  .catch(err => { console.error(err); });

curl $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 Beneficiarys matching the requested filters.

Key	Type	Nullable?	Description
`beneficiaries`	`Object<Beneficiary>[]`	No	The beneficiaries matching the filters.

Benefactors

Benefactors represent individuals who are making payments to Loans for the benefit of a Beneficiary. Benefactors can also be Beneficiarys, as they are conceptually just a non-business owner of a FundingSource.

Create Benefactor

Creates a Benefactor. Can be used to create FundingSources 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

GET https://production.api.rightfoot.com/v1/benefactors

Body Parameters

Key	Type	Required	Description
`firstName`	String	Yes	The given name of the `Benefactor`.
`lastName`	String	Yes	The family name of the `Benefactor`.
`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.

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/benefactor/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"
  }
}

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"
    }
  ]
}

This API responds with the current state of the Benefactors matching the requested filters.

Key	Type	Nullable?	Description
`benefactors`	`Object<Benefactor>[]`	No	The benefactors matching the filters.

Organizations

Organization is a business user, which can provide payments for a Beneficiary's Loans. 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 Organizations 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`.
`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`.

*paymentReferenceNumber and guarantorName are required to be provided when available, although `null` values are possible and are valid values. Failure to include these values when they are non-null will result in payment failures.

Response

{
  "loan": {
      "uuid": "12345678-abcd-1234-abcd-12345678abcd"
  }
}

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"
    }
  ]
}

This API responds with the current state of the Loans.

Parameter	Type	Nullable?	Description
`loans`	`Object<Loan>[]`	No	The loans linked to the beneficiary.

Funding Sources

Create Funding Source

Creates a new funding source attached to a beneficiary. Accepts a Plaid token linked using Plaid Link in the API application. This provides instant verification of the account and avoids exposure of end-user financial data to API Applications and Rightfoot. This funding source can be specified to the payments API to override the default application funding source, if configured.

Two models of providing a Plaid token are supported: a Rightfoot API Customer-managed model, and a Rightfoot-managed model. The API application can provide a Plaid public token associated with Rightfoot’s client id. Alternatively if the API application chooses to own the Plaid item, or the account was linked previously in the app, the API application can exchange for a Dwolla processor token and provide that to Rightfoot instead.

A funding source for Organizations can be created using the bank account number and the bank account's routing number. The funding source will have a status of UNVERIFIED. Before a funding source is eligible to transfer money from the linked bank account ownership of the account needs to be verified via micro-deposit verification.

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, two amounts can be verified with the Verify Funding Source endpoint.

For more information on the flows that are being satisfied with our payment processor Dwolla, you can read Dwolla and Plaids’ official documentation on the topic.

HTTP Request

POST https://production.api.rightfoot.com/v1/fundingSources

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 - for Benefactor 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 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 - for Benefactor 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 = {
  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 - for Beneficiary 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.

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 - for Beneficiary 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 = {
  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.

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 - for Organization 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 - for Organization with 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.

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.

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.

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.

Retrieve Benefactor Funding Sources

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.

Retrieve Beneficiary Funding Sources

import rightfoot
from rightfoot.rest import ApiException
try:
    response = rightfoot_client.list_funding_sources_for_beneficiary(
        uuid="12345678-abcd-1234-abcd-12345678abcd")
    print(response)
except ApiException as e:
    print("Call failed: %s" % e)

const uuid = '12345678-abcd-1234-abcd-12345678abcd';
api.listFundingSourcesForBeneficiary(uuid)
  .then(response => { console.log(response); })
  .catch(err => { console.error(err); });

curl $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.

Retrieve Organization Funding Sources

import rightfoot
from rightfoot.rest import ApiException
try:
    response = rightfoot_client.list_funding_sources_for_organization(
        uuid="12345678-abcd-1234-abcd-12345678abcd")
    print(response)
except ApiException as e:
    print("Call failed: %s" % e)

const uuid = '12345678-abcd-1234-abcd-12345678abcd';
api.listFundingSourcesForOrganization(uuid)
  .then(response => { console.log(response); })
  .catch(err => { console.error(err); });

curl $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
`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, written in cents USD.
`fundingSourceUuid`	String	No*	UUID of the FundingSource to make payments from.

* If a default funding source for the application is not specified, fundingSourceUuid is required. Otherwise, requests which provide fundingSourceUuid will be denied.

Please note payment amount should be provided in cents. For example, {"paymentAmount": 250} translates to $2.50 USD.

Response

{
  "payment": {
    "uuid": "12345678-abcd-1234-abcd-12345678abcd",
    "status": "PENDING",
    "description": null
  }
}

This payment issuance API responds with the created payment.

Parameter	Type	Nullable?	Description
`payment`	`Object<Payment>`	No	The created payment object.

Check Payment Status

import rightfoot
from rightfoot.rest import ApiException

request = rightfoot.GetPaymentRequest(
    uuid="12345678-abcd-1234-abcd-12345678abcd")

try:
    response = rightfoot_client.get_payment(
        uuid="12345678-abcd-1234-abcd-12345678abcd")
    print(response)
except ApiException as e:
    print("Call failed: %s" % e)

const uuid = '12345678-abcd-1234-abcd-12345678abcd';
api.getPayment(uuid)
  .then(response => { console.log(response); })
  .catch(err => { console.error(err); });

curl $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",
    "status": "COMPLETED",
    "description": null
  }
}

This payment status API responds with the current state of the Payment object.

Parameter	Type	Nullable?	Description
`payment`	`Object<Payment>`	No	The created payment object.

List Payment for Funding Source

For applications managing funding sources for their users, they must make available the list of transactions performed for those funding sources to the owners of those funding sources. This endpoint provides a filterable list of payments for a funding source.

import datetime
from rightfoot.rest import ApiException

try:
    response = rightfoot_client.get_payments_for_funding_source(
        uuid="12345678-abcd-1234-abcd-12345678abcd",
        created_on_or_after=datetime.fromisoformat('2020-01-01T00:00:00').timestamp() * 1000,
        created_before=datetime.fromisoformat('2021-01-01T00:00:00').timestamp() * 1000,
        count=50, offset=100)
    print(response)
except ApiException as e:
    print("Call failed: %s" % e)

import { ListPaymentsResponse } from 'rightfoot-node';

const fundingSourceUuid = '12345678-abcd-1234-abcd-12345678abcd';
const createdOnOrAfter = 10;
const createdBefore = 20;
const count = 30;
const offset = 40;
api.getPaymentsForFundingSource(
    fundingSourceUuid, createdOnOrAfter, createdBefore, count, offset)
    .then(({ payments }: ListPaymentsResponse) => { console.log(payments); })
    .catch(err => { console.error(err); });

curl $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
`uuid`	String	Yes	Funding source id to retrieve payments for.
`createdOnOrAfter`	Integer	No	Filters payments started on or after provided time. Unix Epoch milliseconds.
`createdBefore`	Integer	No	Filters payments started before provided time. Unix Epoch milliseconds.
`count`	Integer	No	Number of payments to return in one paged request. Defaults and limited to 50.
`offset`	Integer	No	Payment offset to start query from, when paging through payments.

Response

{
  "payments": [
    {
      "uuid": "12345678-abcd-1234-abcd-12345678abcd",
      "status": "COMPLETED",
      "description": null
    }
  ]
}

This API responds with the current state of the Payments matching the requested filters.

Parameter	Type	Nullable?	Description
`payments`	`Object<Payment>[]`	No	The payments matching the filters.

List Payment for a Beneficiary

This endpoint provides a filterable list of payments for a beneficiary.

import datetime
from rightfoot.rest import ApiException

try:
    response = rightfoot_client.get_payments_for_beneficiary(
        uuid="12345678-abcd-1234-abcd-12345678abcd",
        created_on_or_after=datetime.fromisoformat('2020-01-01T00:00:00').timestamp() * 1000,
        created_before=datetime.fromisoformat('2021-01-01T00:00:00').timestamp() * 1000,
        count=50, offset=100)
    print(response)
except ApiException as e:
    print("Call failed: %s" % e)

import { ListPaymentsResponse } from 'rightfoot-node';

const beneficiaryUuid = '12345678-abcd-1234-abcd-12345678abcd';
const createdOnOrAfter = 10;
const createdBefore = 20;
const count = 30;
const offset = 40;
api.getPaymentsForBeneficiary(
    beneficiaryUuid, createdOnOrAfter, createdBefore, count, offset)
    .then(({ payments }: ListPaymentsResponse) => { console.log(payments); })
    .catch(err => { console.error(err); });

curl $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.
`createdOnOrAfter`	Integer	No	Filters payments started on or after provided time. Unix Epoch milliseconds.
`createdBefore`	Integer	No	Filters payments started before provided time. Unix Epoch milliseconds.
`count`	Integer	No	Number of payments to return in one paged request. Defaults and limited to 50.
`offset`	Integer	No	Payment offset to start query from, when paging through payments.

Response

{
  "payments": [
    {
      "uuid": "12345678-abcd-1234-abcd-12345678abcd",
      "status": "COMPLETED",
      "description": null
    }
  ]
}

This API responds with the current state of the Payments matching the requested filters.

Parameter	Type	Nullable?	Description
`payments`	`Object<Payment>[]`	No	The payments matching the filters.

Transfers

Transfers represent ACH transfers into and out of FundingSources to satisfy the required funds for Payments or returns for Payments 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
`line1`	String	No	Mandatory mailing address line.
`line2`	String	Yes	Optional second line of an address.
`city`	String	No	The city of the location.
`state`	String	No	The two-letter state/territory abbreviation.
`zipCode`	String	No	US Zone Improvement Plan (ZIP) Code, or alternatively ZIP+4 Code.

`Loan` Schema

A bare-bones loan schema for wrapping identifying information about loans for API applications to specify which specific loan account to direct payments towards. This represents the lowest unit of loan, which in the interest of clarity given the use of Plaid on this platform, is comparable to a single student loan liability object and not an account.

Parameter	Type	Nullable?	Description
`uuid`	String	No	Unique identifier for future API calls to reference a created loan.
`beneficiaryUuid`	String	No	Identifier for the `Beneficiary` that holds this loan.

`Payment` Schema

The Payment type represents a single loan payment request.

Parameter	Type	Nullable?	Description
`uuid`	String	No	Unique identifier generated by Rightfoot for payment.
`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.

`PaymentStatus` Enum

Value	Description
`PENDING`	Payment request has been issued.
`ACCEPTED`	Payment request accepted by processors. Will update over several days until payment is completed.
`COMPLETED`	Payments verified to have been disbursed.
`RETURNED`	Payment is more than balance and note necessary.
`FAILED`	An irrecoverable error in processing has occurred.

`PaymentStatusReason` Enum

Value	Description
`ACH_WITHDRAWAL_PENDING_SCHEDULING`	ACH payment not yet scheduled with payment processor. Will be scheduled soon. Can still be cancelled.
`ACH_WITHDRAWAL_CANCELLED`	ACH payment cancelled. Will not be processed by payment processor.
`ACH_WITHDRAWAL_SCHEDULED`	ACH payment scheduled for processing. No longer cancellable.
`ACH_WITHDRAWAL_SUCCESSFUL`	ACH payment successful from funding source. Funds now en route to destination.
`ACH_WITHDRAWAL_FAILED`	ACH payment failed to process.
`ACH_WITHDRAWAL_RETURNED`	ACH payment returned, potentially after successful. Funds were requested to be returned to funding source by bank.
`PAYMENT_DELIVERY_PENDING`	Delivery to final destination is in progress, potentially through multiple hops. This status might expand into more detail in the future.
`PAYMENT_DELIVERY_FAILED`	Delivery failed to process at loan servicer. Payment returning to funding source. This can happen if a loan servicer regresses confirmation.
`PAYMENT_DELIVERY_SUCCESSFUL`	Delivery successful at loan servicer. Payment may take more time to appear in statement.

`FundingSource` Schema

A bare-bones funding source schema is added primarily for wrapping identifying information about funding sources for API applications to specify which account payments should be withdrawn from.

Parameter	Type	Nullable?	Description
`uuid`	String	No	Unique identifier generated by Rightfoot for the funding source.
`status`	`Enum<FundingSourceVerificationStatus>`	No	Verification status of the funding source. Funding sources created with a micro-deposit will initially have a status of `UNVERIFIED`.

`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.

`Transfer` Schema

Transfers represent ACH transfers into and out of FundingSources to satisfy the required funds for Payments or returns for Payments 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

Benefactors represent individuals who are making payments to Loans for the benefit of a Beneficiary. Benefactors can also be Beneficiarys, 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`.

`Organization` Schema

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.

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.