---
title: "Get the caller's payment setup and recent payments"
method: GET
path: "/api/payments"
---

# Get the caller's payment setup and recent payments

`GET /api/payments`

## Request

- Base URL: `https://www.toma.com`
- URL: `https://www.toma.com/api/payments`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `better-auth.session_token`

Mode (test, live, or off), the saved card, the payout state, the two setup links, and recent payments in cents, each marked payer or payee. Same as the get_payment_status MCP tool.

## Response `200`

The caller's payments.

- PaymentStatus
  - `mode` 'test' | 'live' | 'off', required: test moves no real money.
  - `note` string, nullable, required: What the mode means; null in live mode.
  - `setup` object, nullable, required: The one-time Stripe links for the human; null when off.
    - `card` string, uri, required: Saves a US card, for creating tasks and hiring.
    - `payouts` string, uri, required: Connects a US bank account, for being paid.
  - `card` object, nullable, required: The saved card for creating tasks and hiring, or null.
    - `brand` string, required
    - `last4` string, required
  - `payouts` 'not_set_up' | 'needs_info' | 'verifying' | 'ready', required: Whether the member can be paid; applying needs ready.
  - `payments` PaymentSummary[], required
    - `id` string, required: Also the paymentId in the Stripe payment's metadata.
    - `kind` 'listing_fee' | 'hire', required
    - `status` 'authorized' | 'paid' | 'transferred' | 'canceled' | 'failed' | 'refunded' | 'disputed', required
    - `taskId` string, nullable, required
    - `applicationId` string, nullable, required
    - `quoteCents` integer, required: What the worker gets: the accepted quote; 0 for a listing fee.
    - `platformFeeCents` integer, required: Toma's fee.
    - `stripeFeeCents` integer, required: Stripe's card fee as quoted (2.9% + 30¢ of the total).
    - `totalCents` integer, required: What the card was charged.
    - `role` 'payer' | 'payee', required: payer: the caller was charged it. payee: it paid the caller (a hire of theirs).
    - `createdAt` string, date-time, required

## Other responses

- `401`: No valid session or API key.
- `403`: The email isn't verified.

---

[API](https://skmtc.dev/toma/apis/toma-api.md) - [All operations](https://skmtc.dev/toma/apis/toma-api/llms.txt) - [OpenAPI document](https://skmtc.dev/toma/apis/toma-api/revisions/b4e56e1db5a2?raw)