TallyPip
Start free

API reference

Payment

Money received on an invoice (or a credit applied to it). Recording one takes the invoice's balance down and puts the money in a bank account or Undeposited Funds.

The payment object

object string
Always "payment".
id id
The payment's id (a UUID). Use it to fetch it, or to refer to it from other things.
invoice_id id
The invoice it pays.
customer_id id
The invoice's customer.
date date
When it was received.
amount_cents integer
How much, in cents.
currency string
Its currency: the business's (USD or CAD), or the customer's or vendor's when they're in another currency (Multicurrency, like EUR). All its _cents amounts are in it.
exchange_rate string or null
In another currency: what 1 unit of it was worth in the business's currency, as a decimal ("0.73215"). Null otherwise.
home_amount_cents integer
What came in, in the business's currency (the same as amount_cents unless the payment is in another currency).
kind string
payment (money received) or credit_applied (a credit note used on the invoice).
deposit_account_id id
Where the money went (a bank account, or Undeposited Funds until it's deposited).
method string or null
How it was paid (Card, Check, ACH…).
created_at timestamp
When it was added, in UTC.

Example

{
  "object": "payment",
  "id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708105",
  "invoice_id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708104",
  "customer_id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708101",
  "date": "2026-10-07",
  "amount_cents": 24000,
  "currency": "USD",
  "exchange_rate": null,
  "home_amount_cents": 24000,
  "kind": "payment",
  "deposit_account_id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708132",
  "method": "Card",
  "created_at": "2026-10-06T14:30:00.000Z"
}

List payments

GET /api/v1/payments

Payments received on invoices, newest first.

Key: any (Read only works).

Query

limit integer
How many, 1 to 100 (default 25).
starting_after id
The last id of the page before, for the next page (when has_more is true).
filters
invoice_id, customer_id

Newest first. Answers a list: { object: "list", url, has_more, data }.

Request

curl https://tallypip.com/api/v1/payments?limit=3 \
  -H "Authorization: Bearer tpk_your_key"

Answer: 200

{
  "object": "list",
  "url": "/api/v1/payments",
  "has_more": false,
  "data": [
    {
      "object": "payment",
      "id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708105",
      "invoice_id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708104",
      "customer_id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708101",
      "date": "2026-10-07",
      "amount_cents": 24000,
      "currency": "USD",
      "exchange_rate": null,
      "home_amount_cents": 24000,
      "kind": "payment",
      "deposit_account_id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708132",
      "method": "Card",
      "created_at": "2026-10-06T14:30:00.000Z"
    }
  ]
}

Try it

With your own key (Settings › Connected apps). It stays in this page only, and reading can't change anything.

Create a payment

POST /api/v1/payments

Record a payment on a sent invoice.

Key: Read and change.

Body (JSON)

invoice_id id
Required. A sent invoice with something owing.
amount_cents integer
Default: everything still owing. Never more than that.
date date
Default: today.
deposit_account_id id
Default: Undeposited Funds, to go to the bank with the next deposit.
method string
Optional, e.g. Check.

Answers 201 with the new payment. Refused with 400 and the reason (nothing is saved); send an Idempotency-Key so a retry can't make it twice.

Request

curl https://tallypip.com/api/v1/payments \
  -H "Authorization: Bearer tpk_your_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <a new id for each change>" \
  -d '{
    "invoice_id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708104",
    "amount_cents": 24000,
    "method": "Card"
  }'

Answer: 201

{
  "object": "payment",
  "id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708105",
  "invoice_id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708104",
  "customer_id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708101",
  "date": "2026-10-07",
  "amount_cents": 24000,
  "currency": "USD",
  "exchange_rate": null,
  "home_amount_cents": 24000,
  "kind": "payment",
  "deposit_account_id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708132",
  "method": "Card",
  "created_at": "2026-10-06T14:30:00.000Z"
}

Retrieve a payment

GET /api/v1/payments/{id}

One payment.

Key: any (Read only works).

Request

curl https://tallypip.com/api/v1/payments/3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708105 \
  -H "Authorization: Bearer tpk_your_key"

Answer: 200

{
  "object": "payment",
  "id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708105",
  "invoice_id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708104",
  "customer_id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708101",
  "date": "2026-10-07",
  "amount_cents": 24000,
  "currency": "USD",
  "exchange_rate": null,
  "home_amount_cents": 24000,
  "kind": "payment",
  "deposit_account_id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708132",
  "method": "Card",
  "created_at": "2026-10-06T14:30:00.000Z"
}

Try it

With your own key (Settings › Connected apps). It stays in this page only, and reading can't change anything.