--- title: "Get a Payee Payment" method: GET path: "/payables/payer_accounts/{payer_id}/payee_payments/{id}" tags: ["Payee Payments"] --- # Get a Payee Payment `GET /payables/payer_accounts/{payer_id}/payee_payments/{id}` ## Request - Base URL: `https://api.justifi.ai/v1` - URL: `https://api.justifi.ai/v1/payables/payer_accounts/{payer_id}/payee_payments/{id}` - Auth: none declared. Required headers: `Authorization` - TypeScript: (a function with typed inputs; its response is checked against the schema) Retrieve a payee payment, including its fees and ACH legs. ## Path parameters - `payer_id` string, required - `id` string, required ## Headers - `Authorization` string, required ## Response `200` Successfully retrieved the payee payment - object: the standard JustiFi response envelope for a single record - `id` string, required: the object id, also found in the data object - `type` string, required: the object type - `data` object, required: A payee payment moves money from the account's funding bank account to a payee's receiving account over ACH. It orchestrates an inbound debit-pull, a hold, and an outbound credit, accruing fees along the way. There is no automatic retry, and a payment cannot be cancelled once initiated. A return ends the payment either at `failed` or, when the payer has already been debited, at `refunding_payer` — see `status`. - `id` string: unique payee payment id - `type` string: the object type, matching the enclosing envelope's `type` - `payer_account_id` string: the id of the payer account this payment is scoped to - `amount` integer: the gross amount debited from the payer, in cents. The payee receives `amount` minus the sum of `fees` (e.g. `amount` 91000 with a 1000 fee pays the payee 90000). - `currency` 'usd' - `status` 'initiated' | 'inbound_submitted' | 'holding' | 'outbound_submitted' | 'succeeded' | 'failed' | 'refunding_payer' | 'refunded' | 'failed_late_return': the payment's position in its lifecycle. `initiated` → `inbound_submitted` → `holding` → `outbound_submitted` → `succeeded` is the happy path. **`holding` is a real wait.** Once the payer's funding has settled, the payee's credit is held until the next banking day before it is submitted, so a payment rests in `holding` rather than passing through it. Read `deposits_at` for when the payee is expected to be deposited; the hold is already in that estimate. **The hold only lifts for an active payer account and an active payee.** When the wait is up, the payee's credit is sent if both are `active`; if either is not, the payment stays in `holding` and is reconsidered periodically, so it pays out once both are active again. A hold that persists pushes the deposit past the `deposits_at` estimate, which is why that field is an estimate. Which return path a payment takes depends on whose money was already moved. A returned **inbound** debit-pull means nothing settled, so the payment is `failed` and no one is owed anything. A returned **outbound** credit means the payer was already debited, so the payment moves to `refunding_payer` and then `refunded` once the payer has their money back. Both `failed` and `refunded` are terminal. **`succeeded` is not the end.** ACH lets a return arrive days after an entry settled, so one can land after a payment has succeeded. That moves the payment to `failed_late_return`, which is terminal — JustiFi works the break by hand and records the corrective movement as a further leg on the same payment. See "A return that arrives after a payment succeeded" in the overview. **`failed_late_return` does not mean the payee holds nothing.** It reports that the payment did not stick, and the two ways that happens are opposites: a returned **outbound** credit means the payee never kept the money, while a returned **inbound** debit-pull means the payer's funding was clawed back *after* the payee was paid — so the payee still has it. **Re-sending on this status can pay a payee twice.** Read the payment's `transfers` to see which leg returned before acting. - `payment_type` 'ach': how the funds move. ACH is the only option. Named `payment_type` rather than `payment_method`, which in the JustiFi API denotes a stored instrument object, not a rail. - `payee_id` string: the payee being paid - `funding_bank_account_id` string: the account's funding bank account the principal is debit-pulled from - `receiving_bank_account_id` string: the payee's receiving account the principal is credited to - `debits_at` string, date-time, nullable: in UTC, the estimated date and time the payer's funding account is debited (from the inbound leg); null until scheduled. Normally three banking days after the payment is submitted. - `deposits_at` string, date-time, nullable: in UTC, the estimated date and time the payee is deposited (from the outbound leg); null until scheduled. Each ACH leg takes three banking days and the payee's credit is held for one banking day after the payer's funding settles, so this is normally four banking days after `debits_at`. Estimated, and may shift if the provider revises an effective entry date. - `description` string, nullable - `fees` object[]: the fees charged on this payment (v2 fee convention), carved out of `amount`. Supplied in the create request (required, no default) and echoed here. Fees incurred later by NOCs or returns are not shown here — they are billed to the platform monthly. - `type` 'processing_fee', required: the fee type (v2 convention): - `processing_fee` — payment-processing cost, passed by platform - `amount` integer, required: fee amount in cents - `transfers` object[]: the ACH legs that make up this payment - `id` string: unique transfer leg id - `direction` 'inbound' | 'outbound': the direction of funds for this leg (a refund is an outbound, a recovery an inbound) - `purpose` 'principal' | 'refund' | 'recovery': what this leg is — moves the principal, refunds the payer, or recovers owed funds from the payer - `transfer_type` 'ach' | 'manual': how the money moved. `ach` — over the ACH network; `manual` — a movement JustiFi recorded off it. Widens to further rails (e.g. `rtp`) without a breaking change. - `amount` integer: the leg amount in cents - `status` 'initiated' | 'submitted' | 'settled' | 'returned' | 'failed': the state of this leg - `error_code` string, nullable: normalised, rail-agnostic reason the leg failed, in snake_case (e.g. `insufficient_funds`). Stable across rails — **branch on this, not on `network_error_code`**, which is the network's own code and changes meaning between rails. Set when a leg is `failed` or `returned`, and null otherwise. A correction is not a failure: a leg that settled after a notification of change carries `network_error_code` but no `error_code`. A return code with no normalised equivalent reports `unclassified_return`, so this is never null on a leg that failed — the raw code is always there to fall back on. - `error_description` string, nullable: human-readable text for `error_code`, in English — for support and logs, not for branching. Null whenever `error_code` is. - `network_error_code` string, nullable: the raw code from the network, verbatim — an ACH return code (`R01`). Preserved for reconciliation. Present whenever the network said anything about this leg, which is not only when it went wrong: a notification of change carries an advisory code (`C01`) on a leg that **settled** normally. Read it together with `status` — the code alone does not mean the money did not move. - `metadata` object: any useful information you'd like to store alongside this payment - `created_at` string, date-time - `updated_at` string, date-time - `page_info` unknown, required ## Other responses - `401`: The access token is missing, expired, or invalid. - `403`: The credentials are valid but not permitted to access this resource. - `404`: No resource exists for the given id (within the scoped payer account). - `429`: The rate limit has been exceeded. Back off and retry after the interval indicated by the `Retry-After` header. --- [API](https://skmtc.dev/justifi/apis/justifi-api-documentation.md) - [All operations](https://skmtc.dev/justifi/apis/justifi-api-documentation/llms.txt) - [OpenAPI document](https://skmtc.dev/justifi/apis/justifi-api-documentation/revisions/dd9f3fed7e46?raw)