/payments

name: "Alternative Payments Payments & Payouts"
description: >
  Alternative Payments transactions and payouts: transaction types,
  statuses, and the customer/invoice/payment-method filters; payout objects
  and the transactions that compose them for reconciliation. A read-only
  surface -- there is no create-payment or direct-charge operation.
when_to_use: >-
  When listing or filtering transactions, retrieving a transaction, or listing and reconciling
  payouts and the transactions inside them. Use when: alternative payments transaction, list
  transactions, transaction status, alternative payments payout, list payouts, payout
  transactions, reconcile payout, failed payment, declined transaction, or alternativepayments
  payout.

Alternative Payments Payments & Payouts

Overview

This skill covers the **read-only** money-visibility surface in Alternative Payments: transactions (individual payment records) and payouts (settled batches of funds deposited to your account). It is used for reporting and reconciliation — matching transactions to invoices and customers, and tracing which transactions make up a given payout.

There is **no create-payment tool here.** This integration never charges a card or moves money (`POST /payments`, the direct charge, is excluded by design). To collect from a customer, generate a hosted payment link or payment request — see [Alternative Payments Invoicing](../invoicing/SKILL.md).

Anti-triggers

• **Collecting money rather than reporting on it** — this surface is

read-only; hosted payment links and payment requests are `alternative-payments-invoicing`.

• **Recording a receipt against an invoice in the books** — use

`xero-payments` or `qbo-payments`.

• **A payment captured against a Quote Manager sales order** — use

`kaseya-quote-manager-quotes`.

Core Concepts

Transactions

A transaction is a single payment event against an invoice or payment request. Note that the transactions resource lives at `GET /payments` — but only the read (list/get) verbs are exposed.

| Field | Type | Description | |-------|------|-------------| | `id` | string | Transaction identifier | | `type` | string | Transaction type (e.g. `payment`, `refund`) | | `status` | string | `succeeded`, `pending`, `failed`, `declined` | | `amount` | number | Transaction amount | | `currency` | string | ISO currency code | | `customer_id` | string | Customer the transaction belongs to | | `invoice_id` | string | Invoice the transaction settled (if any) | | `payment_method` | string | `card` or `standard_ach` | | `payout_id` | string | Payout this transaction settled into (if settled) | | `created_at` | datetime | When the transaction occurred |

Payouts

A payout is a batch of funds Alternative Payments deposits to your bank account. Each payout aggregates many settled transactions — reconciling a payout means listing its transactions and matching them back to invoices and customers.

| Field | Type | Description | |-------|------|-------------| | `id` | string | Payout identifier | | `amount` | number | Total payout amount deposited | | `currency` | string | ISO currency code | | `status` | string | `pending`, `paid`, `failed` | | `arrival_date` | datetime | Expected/actual deposit date | | `created_at` | datetime | When the payout was created |

API Patterns

All requests carry a bearer token (`Authorization: Bearer <token>`). See [Alternative Payments API Patterns](../api-patterns/SKILL.md) for the OAuth2 token flow, the 5 req/sec rate limit, and cursor pagination.

List Transactions (with Filters)

`GET /payments` lists transactions. Supported filters:

| Filter | Values / Format | Purpose | |--------|-----------------|---------| | `type` | e.g. `payment`, `refund` | Filter by transaction type | | `status` | `succeeded`, `pending`, `failed`, `declined` | Filter by outcome | | `customer_id` | customer id | Transactions for one customer | | `invoice_id` | invoice id | Transactions settling one invoice | | `payment_method` | `card` or `standard_ach` | Filter by method | | `created_at_start` | `YYYY-MM-DD` | Start of date range | | `created_at_end` | `YYYY-MM-DD` | End of date range | | `cursor` | cursor string | Pagination (with `limit`) |

# Failed and declined card transactions in June 2026
curl -s "https://public-api.alternativepayments.io/payments?status=failed&payment_method=card&created_at_start=2026-06-01&created_at_end=2026-06-30&limit=100" \
  -H "Authorization: Bearer ${TOKEN}"

# All transactions for one customer
curl -s "https://public-api.alternativepayments.io/payments?customer_id=${CUSTOMER_ID}&limit=100" \
  -H "Authorization: Bearer ${TOKEN}"

# Transactions that settled a specific invoice
curl -s "https://public-api.alternativepayments.io/payments?invoice_id=${INVOICE_ID}" \
  -H "Authorization: Bearer ${TOKEN}"

Responses are cursor-paginated — items in `data[]`, with `next_cursor` / `has_more`. Pass `cursor=<next_cursor>` to fetch the next page.

Get a Single Transaction

curl -s "https://public-api.alternativepayments.io/payments/${TRANSACTION_ID}" \
  -H "Authorization: Bearer ${TOKEN}"

List Payouts

curl -s "https://public-api.alternativepayments.io/payouts?limit=100" \
  -H "Authorization: Bearer ${TOKEN}"

Get a Single Payout

curl -s "https://public-api.alternativepayments.io/payouts/${PAYOUT_ID}" \
  -H "Authorization: Bearer ${TOKEN}"

List a Payout's Transactions (Reconciliation)

curl -s "https://public-api.alternativepayments.io/payouts/${PAYOUT_ID}/transactions?limit=100" \
  -H "Authorization: Bearer ${TOKEN}"

JavaScript Example — Reconcile a Payout

async function reconcilePayout(token, payoutId) {
  const base = 'https://public-api.alternativepayments.io';
  const headers = { 'Authorization': `Bearer ${token}` };

  const payout = JSON.parse(
    await (await fetch(`${base}/payouts/${payoutId}`, { headers })).text()
  );