> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rightfoot.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Retrieve Payment Results
> Every payment event Rightfoot holds for one borrower, oldest first
# Retrieve Payment Results
Name one borrower — the `authorizer_unique_id` you [enrolled](/api-reference/payments/create-payment-enrollments) 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:
| Sequence | Meaning |
| ------------------------------------------ | ------------------------------------------ |
| `processing` → `settled` | Collected |
| `processing` → `returned` | Bounced. Never settled — see `return_code` |
| `processing` → `settled` → `late_returned` | Settled, then clawed back |
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
| Status | Meaning | Moves money |
| --------------- | ------------------------------------------------------------------------ | --------------------------- |
| `processing` | Submitted to the payment processor and in flight | Not yet |
| `settled` | Cleared | Yes — money received |
| `returned` | Bounced, and never settled | No |
| `late_returned` | Settled, then clawed back | Yes — reverses a settlement |
| `invalid` | The payment processor refused it: the account details themselves are bad | No |
| `voided` | Cancelled before it went out | No |
| `refunded` | Returned to the borrower | Yes |
| `not_attempted` | Never sent | No |
`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.
## OpenAPI
````yaml GET /v1/payment_events
openapi: 3.1.0
info:
title: Rightfoot API
description: >-
Submit a batch of authorizers for balance checks, retrieve processed
balances, and check the status of a batch.
version: 0.3.0-alpha
servers:
- url: https://api.rightfoot.com
security:
- BearerAuth: []
tags:
- name: General Availability
description: |
**General Availability** indicates that the endpoint is production-ready.
- name: Early Access
description: >
**Early Access** indicates that the endpoint is available for early access
customers and is being actively refined.
- name: In Development
description: >
**In Development** indicates that the endpoint is currently being built
and will be available in an upcoming release.
paths:
/v1/payment_events:
get:
tags:
- In Development
summary: Retrieve payment results for one borrower
description: >
Every payment event Rightfoot holds for one borrower, oldest first.
One payment produces several events over its life — `processing`, then
`settled` or `returned`. A borrower can have several payments: an
original
and, after a return, up to two reinitiations. It all comes back as one
flat
chronological list, with `reference` identifying which payment each
event
belongs to.
**Posting to a ledger.** `settled` is money received. `returned` and
`late_returned` reverse the settlement you booked for that `reference`,
and
otherwise need no entry — an ordinary `returned` never settled in the
first
place. Every other status moves no money. `event_id` is stable and never
reissued, so use it as your idempotency key.
**Only what was observed.** Nothing is inferred to fill a gap. If a
payment
settled and was clawed back between two of Rightfoot's reads of the
payment
processor, you receive the `late_returned` with no `settled` before it.
Pull on whatever cadence suits you: nothing here expires, and re-reading
is
free. A borrower Rightfoot has no record of returns an empty list rather
than a `404`, so an empty result is not confirmation that the identifier
is
right.
operationId: get_payment_events
parameters:
- in: query
name: authorizer_unique_id
required: true
schema:
type: string
minLength: 1
description: The borrower to report on — the identifier you enrolled them with.
responses:
'200':
description: |
Every payment event held for this borrower, oldest first. An empty
`events` array is a valid answer.
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentEventsResponse'
example:
authorizer_unique_id: 1a2b3c4d
events:
- event_id: 7c9e6679-7425-40de-944b-e07fc1f90ae7
reference: rf-8f21c7a4
status: processing
amount: 42500
occurred_at: null
return_code: null
- event_id: b3d1f0aa-2c44-4f8e-9d21-6a0b7c5e1f33
reference: rf-8f21c7a4
status: returned
amount: 42500
occurred_at: '2025-01-14T09:12:00Z'
return_code: R01
- event_id: e1a77c02-55b9-4a1d-8f0c-2b9d4e6a7f10
reference: rf-2b6d90e1
status: processing
amount: 42500
occurred_at: null
return_code: null
- event_id: 9f4c2d18-6e7a-4b03-91cd-5f8e2a0b3c77
reference: rf-2b6d90e1
status: settled
amount: 42500
occurred_at: '2025-01-22T16:40:00Z'
return_code: null
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorResponse'
example:
status: error
status_code: 400
error:
code: BAD_REQUEST
message: authorizer_unique_id is required.
timestamp: '2024-12-12T12:00:00Z'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorResponse'
example:
status: error
status_code: 401
error:
code: UNAUTHORIZED
message: Invalid or missing API key.
timestamp: '2024-12-12T12:00:00Z'
components:
schemas:
PaymentEventsResponse:
type: object
properties:
authorizer_unique_id:
type: string
description: The borrower these events belong to, echoed from the request.
events:
type: array
description: >
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.
items:
$ref: '#/components/schemas/PaymentEvent'
ApiErrorResponse:
type: object
properties:
status:
type: string
description: Status of the error, either "error" or "success"
status_code:
type: integer
description: HTTP status code of the error
error:
type: object
properties:
code:
type: string
description: Error code (e.g., "RESOURCE_NOT_FOUND")
message:
type: string
description: Detailed error message.
details:
type: string
description: Additional details about the error
timestamp:
type: string
format: date-time
description: Time the error occurred
suggestion:
type: string
description: Suggested action to resolve the error
documentation_url:
type: string
format: uri
description: URL to the documentation for the error
PaymentEvent:
type: object
description: One thing that happened to one payment.
properties:
event_id:
type: string
format: uuid
description: >
Stable, unique identifier for this event. Safe to use as an
idempotency
key when posting to a ledger — it never changes and is never
reissued.
reference:
type: string
description: |
The payment this event belongs to. Groups events into attempts: a
borrower's original payment and each subsequent reinitiation carry
different references.
status:
type: string
enum:
- processing
- settled
- returned
- late_returned
- invalid
- voided
- refunded
- not_attempted
description: |
`processing` — submitted to the payment processor and in flight.
`settled` — cleared. This is money received.
`returned` — bounced, and never settled. See `return_code`.
`late_returned` — settled, then clawed back. Reverse the settlement.
`invalid` — the payment processor refused it: the account details
themselves are bad, and re-sending the same ones will not help.
`voided` — cancelled before it went out.
`refunded` — returned to the borrower.
`not_attempted` — never sent.
amount:
type: integer
description: The amount of the payment, in cents. `42500` is $425.00.
occurred_at:
type:
- string
- 'null'
format: date-time
description: >
When this happened at the payment processor, where the processor
reports
it. Null where no feed dates the event — notably a `processing`
event,
which nothing at the processor timestamps.
return_code:
type:
- string
- 'null'
description: >
The payment processor's return code on a `returned` or
`late_returned`
event — a NACHA R-code such as `R01` (insufficient funds). Null on
every
other status.
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: >
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.
````