---
name: unified-payments
description: >-
  Build payments and fintech features against many payment providers (Stripe,
  GoCardless, Square, and more) through the single Unified.to Payment API. Use
  when a coding task involves accepting one-time payments, managing
  subscriptions, generating payment links, or reconciling payouts and refunds
  across one or more payment platforms.
license: MIT
metadata:
  category: payment
  api_base: https://api.unified.to
  docs: https://docs.unified.to/payment/overview
---

# Build a payments / fintech app with the Unified.to Payment API

Unified.to normalizes many payment providers behind one REST API. Write your
integration once and it works across every supported payment platform. This
skill teaches an agent how to build payment features against the Unified Payment
API.

## When to use this skill

Use this skill when the task is to:

- Accept one-time payments or create hosted payment links
- Create and manage recurring subscriptions / billing
- List and reconcile payments, payouts, and refunds
- Support more than one payment provider without provider-specific code

## Prerequisites

1. A Unified.to workspace with an **API key** and **Workspace ID**
   (`app.unified.to` → Settings → API Keys).
2. An activated payment integration (e.g. Stripe) in the Sandbox environment.
3. A **connection ID** obtained after an end-user authorizes the integration
   through the embedded Authorization component. See
   https://docs.unified.to/concepts/embedded-components.

Store the API key server-side only. Never expose it in client code.

## Core request pattern

All endpoints follow `{API_CATEGORY}/{CONNECTION_ID}/{DATA_OBJECT}`:

```
https://api.unified.to/payment/{connection_id}/{object}
```

Authenticate every request with a bearer token:

```
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

Regional base URLs: `https://api.unified.to` (North America),
`https://api-eu.unified.to` (Europe), `https://api-au.unified.to` (Australia).
Use the base URL that matches the region where the workspace was created.

## Data objects

| Object         | Purpose                                            |
| -------------- | -------------------------------------------------- |
| `payment`      | A one-time or captured payment / charge            |
| `subscription` | A recurring billing subscription                   |
| `link`         | A hosted payment link                              |
| `payout`       | Funds paid out from the provider to the merchant   |
| `refund`       | A refund against a payment                         |

### Supported operations

| Method   | Path                                   | Description                 |
| -------- | -------------------------------------- | --------------------------- |
| `GET`    | `/payment/{cid}/payment`               | List payments               |
| `GET`    | `/payment/{cid}/payment/{id}`          | Get one payment             |
| `POST`   | `/payment/{cid}/payment`               | Create a payment            |
| `PATCH`  | `/payment/{cid}/payment/{id}`          | Update a payment            |
| `DELETE` | `/payment/{cid}/payment/{id}`          | Delete/void a payment       |
| `GET`    | `/payment/{cid}/subscription`          | List subscriptions          |
| `POST`   | `/payment/{cid}/subscription`          | Create a subscription       |
| `PATCH`  | `/payment/{cid}/subscription/{id}`     | Update a subscription       |
| `DELETE` | `/payment/{cid}/subscription/{id}`     | Cancel a subscription       |
| `GET`    | `/payment/{cid}/link`                  | List payment links          |
| `POST`   | `/payment/{cid}/link`                  | Create a payment link       |
| `GET`    | `/payment/{cid}/payout`                | List payouts (read-only)    |
| `GET`    | `/payment/{cid}/refund`                | List refunds (read-only)    |

Not every provider supports every object or field. Check the **Feature Support**
tab of an integration in `app.unified.to` before relying on an operation. A
`501 Not Implemented` response means the provider does not support that call.

## Pagination, filtering & sorting

List endpoints accept query parameters:

- `limit` (max 100 per page) and `offset` (zero-based) for paging.
- `updated_gte=YYYY-MM-DDTHH:MM:SSZ` to fetch only records changed since a time.
- `sort` (`created_at`, `updated_at`, `name`) with `order` (`asc` / `desc`).

You know you have reached the last page when the number of returned records is
less than the requested `limit`.

## Example: list and create payments (fetch)

```javascript
const BASE = 'https://api.unified.to';
const headers = {
    Authorization: `Bearer ${process.env.UNIFIED_API_KEY}`,
    'Content-Type': 'application/json',
};

// List the most recent payments
const list = await fetch(
    `${BASE}/payment/${connectionId}/payment?limit=50&sort=created_at&order=desc`,
    { headers }
);
const payments = await list.json();

// Create a payment
const created = await fetch(`${BASE}/payment/${connectionId}/payment`, {
    method: 'POST',
    headers,
    body: JSON.stringify({
        total_amount: 49.99,
        currency: 'USD',
        contact_id: 'CONTACT_ID',
        reference: 'order-1234',
    }),
});
const payment = await created.json();
```

## Example: with the official SDK

Unified.to publishes SDKs; each uses its language's naming convention
(TypeScript uses camelCase; the docs use snake_case).

```bash
npm install @unified-api/typescript-sdk
```

```typescript
import { UnifiedTo } from '@unified-api/typescript-sdk';

const unified = new UnifiedTo({ security: { jwt: process.env.UNIFIED_API_KEY! } });

const { paymentPayments } = await unified.payment.listPaymentPayments({
    connectionId,
    limit: 50,
});
```

Other SDKs: Python, PHP, Java, Go, C#, Ruby — see
https://docs.unified.to/reference/sdks.

## Keeping data in sync (recommended)

Do not poll on every user action. Instead, sync provider data into your own
database and query it locally:

- Register **webhooks** to receive create/update/delete events for `payment`,
  `subscription`, and `refund`. See
  https://docs.unified.to/reference/webhooks and
  https://docs.unified.to/concepts/virtual_webhooks.
- On webhook receipt, upsert the object into your database keyed by its `id`.

This gives consistent, fast, provider-independent queries.

## Error handling

| Code | Meaning & action                                                       |
| ---- | ---------------------------------------------------------------------- |
| 401  | Connection broken / revoked — prompt the user to re-authorize.         |
| 403  | Missing scopes — fix scopes in the provider app and Unified.to.        |
| 429  | Provider rate limit — back off and retry; prefer webhooks for sync.    |
| 501  | Provider does not support this operation — check Feature Support.      |

## References

- Payment API overview & data model: https://docs.unified.to/payment/overview
- REST basics (auth, regions, status codes): https://docs.unified.to/reference/rest
- Pagination & filtering: https://docs.unified.to/reference/pagination
- Source guide: https://docs.unified.to/guides/how_to_build_a_fintech_application_with_unified_payments_api