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.

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.

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.

API Patterns

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

List Transactions (with Filters)

GET /payments lists transactions. Supported filters:

# 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()
  );

  // Pull every transaction in the payout (cursor pagination).
  const txns = [];
  let cursor;
  do {
    const url = new URL(`${base}/payouts/${payoutId}/transactions`);
    url.searchParams.set('limit', '100');
    if (cursor) url.searchParams.set('cursor', cursor);
    const body = JSON.parse(await (await fetch(url, { headers })).text());
    txns.push(...(body.data ?? []));
    cursor = body.has_more ? body.next_cursor : undefined;
  } while (cursor);

  const sum = txns.reduce((t, x) => t + x.amount, 0);
  return {
    payout,
    transactionCount: txns.length,
    transactionTotal: sum,
    reconciles: Math.abs(sum - payout.amount) < 0.01,
    transactions: txns
  };
}

Common Workflows

Match Transactions to Invoices

List transactions with status=succeeded, group by invoice_id, and confirm each open invoice has a matching settled transaction. Invoices with no succeeded transaction are still outstanding.

Surface Failed and Declined Payments

Filter with status=failed (and status=declined) over a recent date range to build a follow-up list. For each, the linked customer_id / invoice_id tells you who to contact — then generate a fresh hosted payment link from the Invoicing skill.

Reconcile a Payout

List a payout's transactions, sum their amounts, and confirm the total matches the payout amount. Trace each transaction back to its invoice and customer so the deposit can be tied to specific receivables.

Error Handling

Best Practices

1. Treat this surface as read-only — there is no create-payment tool; collect via hosted links.
2. Filter server-side — use status, customer_id, invoice_id, and date filters rather than fetching everything.
3. Paginate with cursors — loop on has_more / next_cursor (pass cursor=).
4. Reconcile by summing — a payout's transaction amounts should equal the payout total.
5. Stay under 5 req/sec — pace reconciliation loops over large payouts.
6. Read bodies as text then parse — avoids "body already read" errors.

Endpoint Reference

Excluded by design: POST /payments (direct charge). Money movement is out of scope.

Related Skills

• Alternative Payments API Patterns - Auth, pagination, rate limits
• Alternative Payments Customers - Customers and their users
• Alternative Payments Invoicing - Invoices and hosted payment requests