Alternative Payments API Patterns

Overview

The Alternative Payments API is a RESTful JSON API for B2B payments: customers, invoices, hosted payment requests, transactions, payouts, and webhooks. This skill covers OAuth2 client-credentials authentication, pagination, rate limiting, and error handling.

The WYRE integration exposes a read + safe-write surface. It deliberately does not implement direct payment creation (POST /payments), which would charge a card or bank account. Money movement is out of scope.

Base URLs

Authentication

Alternative Payments uses OAuth 2.0 client-credentials. Generate an API key (client_id / client_secret) in the Partner Dashboard, then exchange it for a short-lived bearer token.

Token request (HTTP Basic auth, form-encoded body):

curl -s -X POST https://public-api.alternativepayments.io/oauth/token \
  -u "${AP_CLIENT_ID}:${AP_CLIENT_SECRET}" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials"

Token response:

{
  "access_token": "eyJhbGci...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "payments:read payments:write"
}

Send the token on every API request:

Authorization: Bearer <access_token>

Cache the token and refresh it shortly before expires_in elapses (a 60-second margin avoids races). On a 401, invalidate the cached token and re-authenticate once — tokens can be revoked server-side before their nominal expiry.

Gateway header convention

When connecting through the WYRE MCP Gateway, you do not send a bearer token. The gateway forwards your credentials as headers and the MCP server mints the token internally:

Scopes

Rate Limiting

On 429, back off and retry — respect the Retry-After header when present. A token-bucket limiter at 5/s keeps requests under the cap proactively.

async function requestWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const res = await fetch(url, options);
    if (res.status === 429) {
      const retryAfter = parseInt(res.headers.get('Retry-After') || '1', 10);
      await new Promise(r => setTimeout(r, retryAfter * 1000));
      continue;
    }
    if (res.status >= 500 && attempt < maxRetries) {
      await new Promise(r => setTimeout(r, 2 ** attempt * 1000));
      continue;
    }
    return res;
  }
  throw new Error('Max retries exceeded');
}

Pagination

List endpoints are cursor-paginated. Pass limit and after (a cursor); responses carry the items in data plus a next_cursor / has_more indicator.

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

async function fetchAll(path, token) {
  const items = [];
  let after;
  do {
    const url = new URL(`https://public-api.alternativepayments.io${path}`);
    url.searchParams.set('limit', '100');
    if (after) url.searchParams.set('after', after);
    const res = await fetch(url, { headers: { Authorization: `Bearer ${token}` } });
    const body = await res.json();
    items.push(...(body.data ?? []));
    after = body.has_more ? body.next_cursor : undefined;
  } while (after);
  return items;
}

Idempotency

POST /payments (not exposed by this integration) requires an idempotency_key. For the create operations that ARE exposed (customers, invoices, payment requests, webhooks), supply a stable key where the API accepts one to make retries safe.

Error Handling

Read the response body as text first, then JSON.parse — never call .json() and .text() on the same response (the body can only be read once).

Endpoint Reference

Excluded by design: POST /payments (direct charge), the Web-SDK POST /v1/checkout-auth/init, and the /address/* Google Places utilities.

Best Practices

1. Cache the bearer token — don't mint one per request; refresh 60s before expiry.
2. Stay under 5 req/sec — use a token-bucket limiter, not reactive 429 handling alone.
3. Paginate with cursors — loop on has_more / next_cursor.
4. Prefer hosted payment requests over direct charges — they let the customer pay without the integration moving money.
5. Treat archive/delete as destructive — confirm before archiving customers/invoices or deleting webhook subscriptions.
6. Read bodies as text then parse — avoids "body already read" errors.

Related Skills

• Alternative Payments Customers
• Alternative Payments Invoicing
• Alternative Payments Payments & Payouts