canonical: https://jentic.com/apis/pin-payments.com/pin-payments

# Fat Zebra Pin Payments API

The Pin Payments API is a complete payments processing solution built exclusively for Australian and New Zealand businesses, combining payment gateway, processor, and acquiring functions in a single REST API. It enables developers to accept card payments (Visa, Mastercard, Amex, EFTPOS), digital wallets (Apple Pay, Google Pay), and manage the full payment lifecycle including charges, authorizations, captures, refunds, and disputes. The API supports recurring subscriptions, customer tokenization, multi-party transfers, webhook notifications, and foreign currency processing. Jentic maintains the OpenAPI specification for Pin Payments, making it discoverable and executable by AI agents without requiring developers to parse documentation or manage API keys directly.

## For AI agents

Process card payments, manage subscriptions, issue refunds, and handle transfers for Australian and New Zealand businesses. Supports recurring billing, customer tokenization, and webhook notifications.

## Scope

Operates exclusively in Australia and New Zealand. Does not handle accounting, tax filing, inventory management, or non-ANZ currency settlements - use for ANZ payment processing, subscription billing, and marketplace splits only.

## Capabilities

- Create one-time card charges and authorizations with 3D Secure support for Visa, Mastercard, Amex, and EFTPOS
- Store customer profiles with tokenized payment sources for recurring transactions and subscriptions
- Manage subscription plans with recurring billing cycles, trial periods, and automated invoice generation
- Issue full or partial refunds on charges with automatic balance reconciliation
- Process Apple Pay and Google Pay digital wallet payments alongside traditional cards
- Transfer funds to bank accounts via the Recipients and Transfers API for marketplace payouts
- Configure webhook endpoints to receive real-time event notifications for payment lifecycle changes
- Handle payment disputes with evidence submission and status tracking
- Process foreign currency transactions with automatic conversion to AUD settlement
- Query account balance, deposits, and settlement history for reconciliation

## Use cases

### E-Commerce Checkout for ANZ Businesses

Accept one-time card payments for online stores targeting Australian and New Zealand customers. The Charges API processes Visa, Mastercard, Amex, and EFTPOS cards with automatic 3D Secure authentication when required. Merchants can capture payments immediately or authorize funds for later capture (e.g., when items ship). The API returns detailed charge objects with success status, card details, fees, and settlement information. Jentic enables AI agents to execute these payment flows without managing API keys or parsing documentation.

Example prompt: Create a charge via POST `/1/charges` with email, description, amount in cents, IP address, and card token, then verify the charge status is 'success'

### Recurring Subscription Billing

Bill customers on recurring schedules for SaaS products, memberships, and services. First create a Plan defining the billing amount and interval (weekly, monthly, yearly), then create a Subscription linking a customer token to the plan. Pin Payments automatically generates charges at each billing cycle, handles failed payments with retry logic, and tracks subscription state (trial, active, cancelled). The Ledger endpoint provides complete transaction history for each subscription. Agents can set up subscriptions through Jentic by searching for 'create subscription' and receiving the required schema.

Example prompt: Create a customer via POST `/1/customers`, create a plan via POST `/1/plans` with interval and amount, then create a subscription via POST `/1/subscriptions` linking the customer and plan tokens

### Marketplace Payment Splits

Distribute funds to multiple recipients in platform and marketplace applications. The Recipients API stores bank account details for each seller, and the Transfers API moves funds from the platform's Pin Payments balance to recipient bank accounts. This enables gig-economy platforms, peer-to-peer marketplaces, and multi-vendor e-commerce sites to automate seller payouts while retaining a platform fee. The Balance and Deposits APIs provide reconciliation data for accounting. AI agents can orchestrate these flows through Jentic without directly handling bank account data.

Example prompt: Create a recipient via POST `/1/recipients` with bank account details, then initiate a transfer via POST `/1/transfers` specifying the amount and recipient token

### Agent-Driven Payment Automation via Jentic

AI agents discover and execute Pin Payments operations through Jentic's intent-based API search without managing API keys or parsing documentation. An agent receives a request like 'process a $50 payment for customer@example.com' and searches Jentic for 'create a charge'. Jentic returns the POST `/1/charges` schema with required fields pre-shaped for execution. The agent provides customer email, amount, description, and card token; Jentic injects the API key at runtime and returns the charge result. This reduces Pin Payments integration from days to minutes and keeps sensitive credentials out of agent context.

Example prompt: Search Jentic for 'process a payment', load the POST `/1/charges` operation schema, and execute with customer email, amount in cents, description, IP address, and payment source

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/1/charges` | Create a new charge using card details or a customer token |
| GET | `/1/charges` | List all charges with pagination and filtering |
| GET | `/1/charges/{token}` | Retrieve details of a specific charge |
| POST | `/1/authorisations` | Create an authorization to hold funds without immediate capture |
| PUT | `/1/charges/{token}/capture` | Capture a previously authorized charge |
| PUT | `/1/charges/{token}/void` | Void an authorized charge before capture |
| POST | `/1/customers` | Create a customer record with stored payment sources |
| GET | `/1/customers/{token}` | Retrieve customer details and stored payment methods |
| POST | `/1/refunds` | Issue a full or partial refund for a charge |
| POST | `/1/plans` | Create a subscription plan with billing interval and amount |
| POST | `/1/subscriptions` | Create a subscription linking a customer to a plan |
| GET | `/1/subscriptions/{token}` | Retrieve subscription details and billing history |
| POST | `/1/transfers` | Transfer funds to a recipient's bank account |
| GET | `/1/balance` | Retrieve current account balance |
| POST | `/1/webhook_endpoints` | Register a webhook endpoint URL for event notifications |

## Key resources

- **Charges** — Create, capture, void, and retrieve one-time card payments
- **Authorisations** — Hold funds on cards without immediate capture for delayed settlement
- **Customers** — Store customer profiles with tokenized payment sources for recurring use
- **Refunds** — Issue full or partial refunds on completed charges
- **Payment Sources** — Manage stored payment methods including cards and bank accounts
- **Plans** — Define subscription billing schedules with amount and interval
- **Subscriptions** — Link customers to plans for automated recurring billing
- **Recipients** — Store bank account details for transfer destinations
- **Transfers** — Move funds from Pin Payments balance to recipient bank accounts
- **Balance** — Query current account balance and available funds
- **Webhook Endpoints** — Register URLs to receive real-time payment event notifications
- **Events** — Retrieve historical event logs for audit and reconciliation
- **Disputes** — Manage payment disputes with evidence submission and tracking

## Why Jentic

- **Setup:** Wiring the Pin Payments API by hand means setting up its basic auth, keeping test and live keys separate, and coding each charge, capture, void, refund, customer, and subscription call yourself for the ANZ region. Through Jentic you install once, import Pin Payments from the API Directory, store the API key once, and your agent calls it.
- **Permission scoping:** Pin Payments puts the charge token in the URL path (`/1/charges/{token}/...`), so a rule can pin your agent to acting on charges it created: it can read a charge's status. You choose the operations it may call, so money-moving ones like capture, void, or refund are not included unless you add them.
- **Credential handling:** Your Pin Payments API key, with test and live kept separate, is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a subscription' or 'process a refund', and Jentic returns the matching Pin Payments operation with its request schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Stripe API** — Global payment processing platform with support for 135+ currencies and 50+ payment methods
- **Square API** — Unified payments platform with point-of-sale integration and e-commerce APIs
- **PayPal API** — Digital wallet and payment processing platform with buyer protection and seller coverage

## FAQ

### What authentication does the Pin Payments API use?

The Pin Payments API uses HTTP Basic authentication with your API key as the username and an empty password. You provide separate keys for test and live environments. Through Jentic, API keys are stored encrypted in the credential vault and injected at execution time, so the raw secret key never enters the agent's context window.

### Can I process payments for customers outside Australia and New Zealand?

Pin Payments can process international cards, but the service is exclusively available to businesses registered in Australia and New Zealand. International cardholders can make purchases, but the merchant must be ANZ-based. Foreign currency transactions are converted to AUD for settlement.

### How do I create recurring subscriptions with Pin Payments?

First create a Plan via POST `/1/plans` defining the billing amount and interval (weekly, monthly, yearly). Then create a Subscription via POST `/1/subscriptions` linking a customer token to the plan token. Pin Payments automatically charges the customer at each billing cycle and handles failed payment retries.

### What payment methods does the Pin Payments API support?

The API supports Visa, Mastercard, American Express, EFTPOS, JCB, Discover, Diners Club, Apple Pay, and Google Pay. Both domestic and international cards are accepted, with pricing at 1.6% + 30 cents for domestic transactions and 3.4% + 30 cents for international cards.

### How do webhooks work in the Pin Payments API?

Register a webhook endpoint URL via POST `/1/webhook_endpoints`, and Pin Payments will send HTTP POST requests to that URL when events occur (charges created, refunds issued, disputes filed, etc.). The API stores webhook records for 30 days and provides a replay endpoint to resend failed webhooks.

### Can I transfer funds to bank accounts using the Pin Payments API?

Yes. Create a Recipient via POST `/1/recipients` with bank account details (BSB and account number), then initiate a Transfer via POST `/1/transfers` specifying the amount and recipient token. This is ideal for marketplace payouts and multi-party payment splitting. Check your available balance via GET `/1/balance` before initiating transfers.

### Can I limit what my agent is allowed to do with the Pin Payments API?

Yes. Because Jentic One is self-hosted, you set the rules that decide which Pin Payments operations and credentials your agent may use, so you can allow read-only calls like retrieving a charge's status via GET `/1/charges/{token}` while excluding money-moving operations such as capture, void, refund, and transfers. Since Pin Payments puts the charge token in the URL path (`/1/charges/{token}/...`), a rule can pin the agent to acting only on charges it created. Money-moving operations are not available to the agent unless you explicitly add them to its allowed set.