JUjustifi
Payee Payments

Schedule a Payee Payment

Schedule a payment to a payee. This debit-pulls the gross amount from the payer's funding bank account, holds it, then credits the payee's receiving account with amount minus fees. The fees array is required (no default) and is carved out of amount. There is no automatic retry: a returned debit-pull fails the payment, and a returned credit to the payee refunds the payer.

You name the payee; everything else about the routing is resolved for you. The funding account comes from the payer account in the path and the receiving account from the payee, so neither is a request field — a payment can only ever move money between the two accounts those records already point at. The schedule is set by the system: each leg takes three banking days, and debits_at and deposits_at are returned once known. payment_type and currency are optional and default to ach and usd, the only values either accepts.

The payer account and the payee must both be active, and either one that is not is a 400 rather than a 422 — a status is the state of a record the request refers to, not a problem with the body. A payee that is pending, disabled or archived cannot be paid.

Both accounts must be usable, and the bar differs by side. The payer account's funding account must be verified. The payee's receiving account does not need to be verified — not_required is the normal state for one — but it must exist and must not have failed verification: a payee can be created without a bank account, and naming one that has none leaves the payment with nothing to credit. Either failure is a 422.

post/payables/payer_accounts/{payer_id}/payee_payments

Request

Path parameters

payer_idstring required

the payer account this request is scoped to. Every payee, bank account, and payment lives under one payer account, so it is part of the path on all operate (Tier 1) routes.

Headers

Authorizationstring required

the access_token value returned from the JustiFi oauth/token endpoint (be sure to append Bearer before the token)

Idempotency-Keystring required

a string to uniquely identify your request (we recommend a generated uuid, but any unique string works). Replaying the same key returns 200 with the payment that key already created — as it stands now, not a cached copy of the first response — instead of performing the operation twice. Reusing a key with a different request body is a 409. Keys are scoped to the payer account, so two payer accounts may use the same key without colliding.

Request body

amountinteger required

the gross amount debited from the payer, in cents. The payee receives amount minus the sum of fees (pass 91000 with a 1000 fee to net the payee 90000).

currency'usd'

defaults to usd, the only supported currency

payee_idstring required
payment_type'ach'

the rail the payment moves over. Optional, and defaults to ach — ACH is the only rail Payables moves money over, so there is nothing to select.

descriptionstring
metadataobject

Example request

{
  "amount": 91000,
  "currency": "usd",
  "payee_id": "pe_abc123",
  "fees": [
    {
      "type": "processing_fee",
      "amount": 1000
    }
  ],
  "payment_type": "ach",
  "description": "Invoice 4021",
  "metadata": {
    "invoice_id": "inv_4021"
  }
}

Response

This Idempotency-Key already scheduled a payment for this payer account, and the request body matches. The payment is returned as it stands now — not a cached copy of the first response — so it may have advanced past initiated. Nothing was scheduled a second time.

idstring required

the object id, also found in the data object

typestring required

the object type

page_infounknown required

Example response

{
  "id": "prefix_xyz (same as id of data object)",
  "type": "payee_payment",
  "data": {
    "id": "pp_123xyz",
    "type": "payee_payment",
    "payer_account_id": "payer_123xyz",
    "amount": 91000,
    "currency": "usd",
    "status": "succeeded",
    "payment_type": "ach",
    "payee_id": "pe_abc123",
    "funding_bank_account_id": "ba_fund456",
    "receiving_bank_account_id": "ba_recv123",
    "debits_at": "2026-01-01T12:00:00Z",
    "deposits_at": "2026-01-04T12:00:00Z",
    "description": "Invoice 4021",
    "fees": [
      {
        "type": "processing_fee",
        "amount": 1000
      }
    ],
    "transfers": [
      {
        "id": "ptr_123",
        "direction": "inbound",
        "purpose": "principal",
        "transfer_type": "ach",
        "amount": 50000,
        "status": "settled",
        "error_code": "insufficient_funds",
        "error_description": "Insufficient funds in the account"
      }
    ],
    "metadata": {
      "invoice_id": "inv_4021"
    },
    "created_at": "2026-01-01T12:00:00Z",
    "updated_at": "2026-01-05T12:00:00Z"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.