Skip to main content
GET
Retrieve payment results for one borrower

Retrieve Payment Results

Name one borrower — the authorizer_unique_id you enrolled them with — and get back everything Rightfoot knows about their payments. The response is a flat list of events, oldest first, not a list of payments. One payment produces several events over its life, and reference is what tells you which payment an event belongs to. Pull on whatever cadence suits you. Nothing here expires, and re-reading is free.
A borrower Rightfoot has no record of comes back as an empty events list, not a 404. An empty result is therefore not confirmation that the identifier is correct — a typo looks the same as a borrower with no payments yet.

The life of a payment

A payment appears as processing when it goes out, and gains a second event when it resolves: A borrower can have more than one payment: an original, and after a return, up to two reinitiations. Each carries a different reference, and their events are interleaved in one chronological list.

Statuses

return_code is present on returned and late_returned only, and carries the payment processor’s NACHA R-code — R01 for insufficient funds, R02 for a closed account, and so on.

Posting to your ledger

  • settled is a payment received against that reference.
  • returned and late_returned reverse the settlement you booked for that reference. An ordinary returned never settled in the first place, so most of the time there is nothing to reverse — a reversal with no matching credit is normal here rather than an error.
  • Every other status moves no money and needs no entry.
Use event_id as your idempotency key. It is unique, stable, and never reissued, so replaying the same read is safe.
Rightfoot reports only what it observed at the payment processor, and never infers an event to fill a gap. If a payment settled and was clawed back between two reads, you receive the late_returned with no settled before it — so treat a reversal without a matching settlement as expected, not as bad data.

Amounts

amount is an integer number of cents, and is the amount of the payment the event belongs to — 42500 is $425.00. Every event on the same reference carries the same amount.

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.

Query Parameters

authorizer_unique_id
string
required

The borrower to report on — the identifier you enrolled them with.

Minimum string length: 1

Response

Every payment event held for this borrower, oldest first. An empty events array is a valid answer.

authorizer_unique_id
string

The borrower these events belong to, echoed from the request.

events
object[]

Oldest first. An empty array means Rightfoot holds no payment events for this borrower — which is also the answer for a borrower Rightfoot has never heard of, so it is not by itself confirmation that the identifier is correct.