API Core Concepts

Tip: All monetary amounts in the Pinch API are represented in cents (e.g. $10.00 = 1000).

How the pieces fit together

┌─────────────┐       owns        ┌────────────┐
│  Merchant   │──────────────────▶│   Payer    │
└─────────────┘                   └─────┬──────┘
                                        │ has
                              ┌─────────┼──────────┐
                              ▼         ▼          ▼
                        ┌─────────┐ ┌─────────┐  ┌───────────┐
                        │ Source  │ │Agreement│  │Subscription│
                        └────┬────┘ └─────────┘  └─────┬─────┘
                             │                         │ created from
                             │                    ┌────▼────┐
                             │                    │  Plan   │
                             │                    └─────────┘
                             │
                 charged via │
                        ┌────▼─────┐      settles into     ┌──────────┐
                        │ Payment  │──────────────────────▶│ Transfer │
                        └────┬─────┘                       └──────────┘
                             │ contains
                        ┌────▼─────┐
                        │ Attempt  │
                        └──────────┘

1. Merchant

A Merchant is you, the business collecting payments. Your Merchant account is created when you sign up for Pinch, and your Merchant ID and Secret Key (found in the Pinch Portal under API Keys) are used to authenticate with the API.

Merchants can also create Managed Merchants — sub-accounts that the parent merchant fully controls. This is the foundation for platform and marketplace use cases.

Key properties: company name, ABN, trading address, bank account details for settlement, compliance status.

📖 Further reading: Getting started with the Pinch API · Application Authentication · Managed Merchants Guide

2. Payer

A Payer is a person or business that you collect money from. Before you can take a payment, you need a Payer record.

A Payer stores contact information (name, email, mobile, address) and, importantly, owns two child collections:

• Sources — the payment methods attached to this payer (see below).
• Agreements — the direct debit authorisation agreements (see below).

You can also store arbitrary data against a Payer via the Metadata field.

Key operations: Create/update (POST /payers), List (paged GET /payers), Get details (GET /payers/{id}), Delete.

📖 Further reading: Payers API Reference · Metadata

3. Source

A Source is a payment method attached to a Payer. Pinch supports two source types:

Sources should be created using a token generated by the Pinch Capture JavaScript library to ensure sensitive details never touch your server.

A Payer can have multiple Sources. When creating a payment, you can optionally specify a SourceId; if you don't, Pinch will use the first valid source.

Key operations: Add source (POST /payers/{payerId}/sources), Delete source (DELETE /payers/{payerId}/sources/{sourceId}).

📖 Further reading: Credit Card Payments Guide · Direct Debit Payments Guide

4. Agreement

An Agreement is a formal Direct Debit Request (DDR) authorisation between the Payer and Pinch Payments. It is required for direct debit (bank account) payments under Australian banking rules.

The lifecycle of an Agreement is:

1. Created — an Agreement is generated for a Payer.
2. Authorised — the Payer confirms they have read and accepted the DDR and Service Agreement. This triggers an email to the Payer with PDF copies.
3. Cancelled — if needed, the Agreement can be cancelled, which prevents future payments for that payer.

Key operations: Create (POST /agreements), Authorise (POST /agreements/authorise), Cancel (POST /agreements/cancel), Get DDR PDF (GET /agreements/ddr/{id}).

📖 Further reading: Agreements API Reference

5. Payment

A Payment is the central entity in Pinch — it represents a request to collect money from a Payer. Pinch supports two modes of payment:

Scheduled Payments

Created via POST /payments. You specify a future TransactionDate and Pinch will process the payment on that date. Scheduled payments can be updated or deleted before they are processed.

Realtime Payments

Created via POST /payments/realtime. These are processed immediately and only support realtime-capable sources (credit cards). A realtime payment can create a new Payer on the fly — just supply name and email instead of a PayerId.

Payment statuses

Nonce (replay protection)

Both scheduled and realtime payment endpoints accept an optional Nonce value. If you send the same Nonce twice, Pinch will return the existing in-progress payment instead of creating a duplicate. This is critical for safely retrying requests in the face of network errors.

Key operations: Create scheduled (POST /payments), Execute realtime (POST /payments/realtime), Get (GET /payments/{id}), List scheduled (paged), List processed (paged), Delete, Check nonce.

📖 Further reading: Credit Card Payments Guide · Direct Debit Payments Guide · Payments API Reference

6. Attempt

An Attempt is a single execution try within a Payment. A Payment can contain multiple Attempts (e.g. if the first attempt was dishonoured and retried), but will only ever have at most one successful Attempt.

Each Attempt carries its own:

• Amount (in cents)
• TransactionDate (UTC)
• Status (e.g. scheduled, processing, settled)
• Source — the specific payment method used
• Dishonour — details if the attempt failed (e.g. insufficient-funds, blocked-by-bank)
• Settlement — details once settled (date, fees, transfer ID)
• Fees — the fee breakdown for this attempt

The Payment's top-level AttemptId always points to the current (most recent) Attempt. Use this to correlate when a payment has been retried.

📖 Further reading: Payments API Reference

7. Plan

A Plan is a reusable template that defines how to collect payments over time. A Plan can include:

• Free Periods — initial grace periods before payments begin.
• Fixed Payments — one-off payments at specific date offsets from the subscription start (amount in cents or as a percentage of a total).
• Recurring Payment — a repeating payment schedule with configurable frequency, start offset, and end conditions (number of payments, total amount, or end date).

Plans that use percentage-based amounts will have RequiresTotalAmount = true, meaning a TotalAmount must be provided when creating a Subscription.

⚠️

Plans can only be edited if they have no active subscriptions. To change a plan with subscribers, the typical approach is to cancel existing subscriptions and create new ones against an updated plan.

Key operations: Create/update (POST /plans), List (paged), Get (GET /plans/{id}), Delete (DELETE /plans/{id}), Preview calculated payments (GET /plans/{id}/calculated-payments).

📖 Further reading: Plans and Subscriptions Guide · Plans API Reference

8. Subscription

A Subscription binds a Plan to a Payer, creating an actual schedule of dated Payments. When you create a Subscription, Pinch generates all the necessary Payment records according to the Plan's rules.

Key properties: PlanId, Payer, Status, StartDate, TotalAmount (when required by the plan), FixedPayments, RecurringPayment, FreePeriods.

Key operations: Create (POST /subscriptions), List (paged), Get (GET /subscriptions/{id}), List for payer (GET /subscriptions/payer/{payerId}), Cancel (DELETE /subscriptions/{id}).

📖 Further reading: Plans and Subscriptions Guide · Subscriptions API Reference

9. Transfer

A Transfer represents the settlement of collected funds to a merchant's bank account. When payments are successfully processed, they are batched into a Transfer.

A Transfer includes summary-level data about:

• Settlements (successful payments)
• Dishonours (failed payments)
• Refunds
• Application fees
• Processing fees and tax

You can drill into a Transfer's Line Items to see the individual debits and credits that make up the total.

Key properties: TransferDate, Amount, Currency, Status, AccountName, AccountNumber, Bsb, TotalFees, Summary.

Key operations: List transfers (paged), Get transfer details (GET /transfers/{id}), List line items (paged GET /transfers/items/{id}).

📖 Further reading: Transfers in Pinch Payments · Transfers API Reference

10. Refund

A Refund returns money from a settled Payment back to the Payer. Refunds can be full or partial (specify an Amount in cents, or omit for a full refund).

Like Payments, Refunds support Nonce values for replay protection.

Key properties: PaymentId, Amount, Currency, Status, ReasonForRefund, RefundFeeCharged, RefundedFees, TransferId.

Key operations: Create (POST /refunds), List (paged, filterable by date range), Get (GET /refunds/{id}), Check nonce.

📖 Further reading: Refunds API Reference

11. Event

An Event is generated every time something noteworthy happens in the Pinch system. Events are the foundation for both polling-based integrations and webhook-driven workflows.

Key properties: Id (format: evt_XXXXXXXXXXXXXX), Type, EventDate, Metadata, Data (the full event payload).

Common Event Types

Key operations: List all events (paged, filterable by type and date), Get event details (GET /events/{id}).

📖 Further reading: Events · Events API Reference

12. Webhook

A Webhook lets you subscribe to Events and have Pinch push them to your server in real time, rather than polling. Each Webhook specifies:

• Uri — the URL Pinch will POST to.
• EventTypes — which event types to deliver (or all).
• WebhookFormat — the format of the payload.
• Secret — a whsec_... key used to verify that incoming requests genuinely came from Pinch.

Webhook Verification

Every webhook delivery includes a pinch-signature header containing a timestamp and HMAC signature. The SDK provides a built-in VerifyWebhook() method that validates the signature and checks clock skew (default: 5 minutes) to protect against replay attacks.

Key operations: Create/update (POST /webhooks), List (GET /webhooks), Delete (DELETE /webhooks/{id}), Verify (SDK method).

📖 Further reading: Webhooks · Webhooks API Reference

Cross-cutting Concepts

Authentication

All API requests require an OAuth 2.0 access token, obtained by exchanging your Application ID (or Merchant ID for legacy connections) and Secret Key. The SDK handles token acquisition automatically.

📖 Further reading: Application Authentication · Auth API Reference

Test vs. Live Environments

Pinch provides separate environments:

When using the .NET SDK, simply set isLive: false for sandbox or isLive: true for production.

API Versioning

Include the pinch-version header in all requests (e.g. pinch-version: 2020.1). While technically optional, omitting it means you'll always hit the latest version, which may introduce breaking changes.

📖 Further reading: API Versions

Pagination

List endpoints return paged results. Responses include totalPages and currentPage so you can iterate. The SDK provides convenience methods like GetPayersAll() that automatically walk all pages, but these should be used sparingly for large datasets.

Metadata

Several entities (Payer, Payment, Plan, Subscription) support a free-text Metadata field. This can store arbitrary JSON for your application's use. Pinch also uses specially structured metadata objects for certain beta features.

📖 Further reading: Metadata

Surcharging

When creating Payments or Subscriptions, you can pass a Surcharge list (e.g. ["bank-account", "credit-card"]) to pass processing fees onto the Payer for those source types.

What to read next