Skip to main content
POST

​
Add a Processor Key

Rightfoot collects payments through your own merchant accounts at a supported payment processor. Register the API key of each account you hold, and tell Rightfoot which borrowers and which payment types it should be used for. Paste the key once. Rightfoot stores it in a vault the moment the request is accepted; from then on every response shows only its last four characters, and the key itself is never returned. If the person holding the keys would rather not call the API, the same flow is in the portal — see Processor Keys in the Portal.

​
Supported processors

Rightfoot works with the processor you already hold merchant accounts at. Register keys from any processor in this list; every endpoint on these pages behaves the same regardless of which one issued the key.
Using a processor that is not listed? Ask Rightfoot about adding it. Nothing about how you enroll borrowers changes when a processor is added — only where the keys come from.

​
Default keys and tagged keys

Which key a payment goes through is decided by two things you set when you add it.

Default key

Used for every borrower you enroll without a merchant_ref. Set is_default: true. You can hold one default per payment type — ACH, debit card, or a single key that covers both.

Tagged key

Used only for borrowers you enroll with that tag. Set merchant_ref to a short slug such as acme-nv, and send the same value as merchant_ref when you enroll those borrowers.
A key is one or the other, never both — a request with is_default: true and a merchant_ref is rejected. A key with neither is stored but not used for anything until you promote it.
Tags are permanent. Borrowers already enrolled under a tag would silently move to a different merchant account if the tag could change, so merchant_ref is fixed once saved. The key behind a tag is not — replace it any time and the tag stays.

​
One default per payment type

rail_scope says which payment types a key can take: ach, card (debit card), or both. It is required and has no default, because a key used for a payment type its merchant account was not set up for fails at the processor rather than here. You can hold one default key per rail_scope. When a payment type is covered by both a both default and a type-specific default, the type-specific one wins — a dedicated ACH key takes the ACH payments, and the both key keeps covering debit card.
A payment type with no default key skips every borrower enrolled without a tag. List your keys to see which types are uncovered in missing_default_rails.
One tag can hold one key per rail_scope, so acme-nv may have both an ACH key and a debit-card key if that merchant account is split by payment type at the processor.

​
When a request is rejected

Conflicts are checked before the key is stored, so a rejected request leaves nothing behind. Send it again once corrected. The error.message in the response says which — for example A default key for ACH already exists or Tag 'acme-nv' already has an ACH key.

Authorizations

​
Authorization
string
header
required

Authentication to the API is performed via Bearer Token Authentication. Provide your API key as the bearer token in the Authorization header.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Body

application/json
​
api_key
string
required

The API key your processor issued for one of your merchant accounts. Stored in a vault as soon as the request is accepted and never returned — responses carry only key_last4.

Minimum string length: 1
​
label
string
required

A name you will recognize, shown in the Rightfoot portal. Cosmetic — change it any time.

Required string length: 1 - 80
​
rail_scope
enum<string>
required

The payment types this key can take: ach, card (debit card), or both when one merchant account covers both. Required — there is no default, because a key used for a payment type its merchant account was not set up for fails at the processor rather than here.

Available options:
ach,
card,
both
​
is_default
boolean
default:false

Make this the default key for the payment types in rail_scope — the key used for every borrower enrolled without a merchant_ref. One default per rail_scope. Cannot be combined with merchant_ref.

​
merchant_ref
string

A tag that enrollments name to settle to this key: send the same value as merchant_ref on POST /v1/payment_enrollments. Lowercase letters, digits, - and _; 1–128 characters; must start and end with a letter or digit. Fixed once saved. One tag can hold one key per rail_scope, so an ACH key and a debit-card key may share a tag.

Pattern: ^[a-z0-9](?:[a-z0-9_-]{0,126}[a-z0-9])?$

Response

The key was stored.

One registered key. Never includes the key itself.

​
id
string<uuid>

Use this to update or delete the key.

​
label
string

The name you gave the key.

​
merchant_ref
string | null

The tag enrollments name to settle to this key, or null for a default or unused key.

​
rail_scope
enum<string>

The payment types this key can take.

Available options:
ach,
card,
both
​
is_default
boolean

Whether this is the default key for its rail_scope.

​
key_last4
string | null

The last four characters of the stored key, to tell keys apart.

​
last_poll_at
string<date-time> | null

When Rightfoot last read payment results through this key. null until the first read.

​
access_scope
string

Reserved for a future permissions setting. Always lender_admins today.

​
created_at
string<date-time>

When the key was added.