canonical: https://jentic.com/apis/polipay.co.nz/poli-payments-api

# Polipay POLi Payments API

POLi is an online debit payment method for New Zealand and Australia that enables direct bank account payments without credit cards or intermediary wallets. The POLi Payments API allows merchants to initiate payment transactions, retrieve payment status, access daily transaction reports, and query supported financial institutions. Unlike card payments, POLi provides guaranteed settlement within 2 business days with significantly lower transaction fees. Merchants use it for high-value transactions, subscription billing, and customer segments preferring direct bank payment. The API handles the secure bank login flow, amount authorization, and payment confirmation, returning a success/failure status to the merchant system. It's particularly popular for utility payments, government fees, and e-commerce checkout where transaction fees impact margin.

## For AI agents

Initiate and track online bank transfer payments in New Zealand using POLi's direct debit payment network.

## Scope

Provides payment initiation and transaction management for bank transfers in New Zealand and Australia. Does not handle credit card processing, international wire transfers, or cryptocurrency payments-use dedicated payment gateways for those methods.

## Capabilities

- Initiate payment transactions with customer bank account details and transaction amount
- Retrieve real-time payment status including pending, completed, and failed states
- Access daily transaction reports for reconciliation and accounting workflows
- Query supported financial institutions to display payment options to customers
- Retrieve transaction details including payment reference, timestamp, and settlement information

## Use cases

### E-commerce Checkout Integration

Online retailers integrate POLi as a payment method alongside credit cards and PayPal to serve customers who prefer direct bank payment. At checkout, the merchant calls the API to initiate a transaction with the order amount and a return URL. POLi redirects the customer to their bank's login page, guides them through payment authorization, and returns them to the merchant site with a payment status. The merchant queries the transaction status endpoint to confirm payment before fulfilling the order. This reduces card processing fees from 2-3% to POLi's flat-rate structure, improving margin on high-value purchases.

Example prompt: Initiate POLi transaction with order total and callback URL, receive transaction token, redirect customer to POLi payment page, handle callback on return, query transaction status to confirm payment success.

### Subscription and Recurring Billing

SaaS platforms and subscription businesses use POLi for monthly billing where customers authorize recurring bank transfers. The API's transaction initiation supports storing payment agreements that allow merchants to charge customers automatically on billing dates. Unlike card subscriptions that fail due to expired cards, bank account details remain stable. Billing systems integrate the API to initiate charges, monitor settlement status, and handle payment failures with retry logic. This improves payment success rates and reduces involuntary churn from failed payment methods.

Example prompt: On billing date, initiate POLi transaction for subscription amount with customer's stored payment agreement, monitor transaction status, update subscription billing status on successful payment, trigger dunning workflow on failure.

### Daily Transaction Reconciliation

Finance teams use the daily transaction report endpoints to reconcile POLi payments with bank deposits and accounting ledgers. The API returns CSV and JSON formatted reports showing all transactions processed in a 24-hour period with payment references, amounts, timestamps, and settlement status. Automated workflows fetch reports each morning, match transactions to orders in the merchant system, and flag discrepancies for investigation. This streamlines month-end close processes and provides audit trails for payment disputes.

Example prompt: Fetch daily transaction report for previous business day, parse transaction records, match payment references to order IDs in database, update accounting system with settled amounts, flag unmatched transactions for review.

### Multi-Bank Payment Options Display

Checkout experiences use the financial institutions endpoint to display supported banks dynamically, allowing customers to see if their bank is compatible before starting payment. The API returns bank names, logos, and availability status, which the merchant UI renders as clickable options. This improves conversion by setting customer expectations and preventing abandonment when customers discover their bank isn't supported mid-flow. The endpoint also enables merchants to detect when new banks are added to POLi's network and update checkout UI automatically.

Example prompt: Query POLi for list of supported financial institutions, render bank logos and names on checkout page, enable/disable payment button based on customer's bank selection, refresh bank list weekly to detect new additions.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/api/v2/Transaction/Initiate` | Initiate a new payment transaction |
| GET | `/api/v2/Transaction/GetTransaction` | Retrieve details for a specific transaction |
| GET | `/api/v2/Transaction/GetDailyTransactions` | Get daily transaction report in JSON format |
| GET | `/api/v2/Transaction/GetDailyTransactionsCSV` | Get daily transaction report in CSV format |
| GET | `/api/Entity/GetFinancialInstitutions` | List supported financial institutions |

## Key resources

- **Transactions** — Initiate and retrieve payment transaction details.
- **Daily Reports** — Access transaction reports for reconciliation.
- **Financial Institutions** — Query supported banks and payment options.

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 40 / 100
- **Maturity:** Foundational
- **Dimensions:**
  - Foundational Compliance: 100 / 100
  - Developer Experience & Jentic Compatibility: 63 / 100
  - AI-Readiness & Agent Experience: 49 / 100
  - Agent Usability: 94 / 100
  - Security: 10 / 100
  - AI Discoverability: 70 / 100
- **View full report:** https://jentic.com/apis/polipay.co.nz/poli-payments-api/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring the POLi Payments API by hand means setting up HTTP basic auth with your merchant username and password and choosing between the APAC production and UAT hosts yourself. Through Jentic you install once, import the POLi Payments API from the API Directory, store the merchant credentials once, and your agent calls it.
- **Permission scoping:** POLi identifies a transaction through a request or query token rather than pinning it in the URL path, so scope the agent to the operations it needs, such as initiating a transaction or reading daily transactions. You choose that set, so the initiation operation is included only if you grant it while a reporting agent keeps just the transaction-read operations.
- **Credential handling:** Your POLi merchant username and password are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'initiate a bank transfer payment' or 'get daily transactions', and Jentic returns the matching POLi operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Stripe Payment Intents API** — Stripe provides global card payment processing with additional payment methods like bank transfers.
- **PayPal Checkout API** — PayPal provides wallet and card-based payments with buyer protection.
- **GoCardless API** — GoCardless provides direct debit payments with automated recurring billing for UK, EU, and US.

## FAQ

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

The POLi API uses HTTP Basic Authentication. You receive merchant credentials (username and password) from POLi when you sign up for a merchant account, which you pass in the Authorization header for all API requests.

### How long does it take for POLi payments to settle?

POLi payments settle within 2 business days to the merchant's nominated bank account. The API provides real-time payment confirmation so you can fulfill orders immediately, while settlement occurs in the background.

### What banks are supported by POLi in New Zealand?

POLi supports major New Zealand banks including ANZ, ASB, BNZ, Westpac, and Kiwibank. Use the GetFinancialInstitutions endpoint to retrieve the current list programmatically, as POLi adds new institutions periodically.

### Can I use POLi for recurring subscription payments?

Yes, POLi supports recurring payment agreements where customers authorize automatic bank transfers on scheduled billing dates. You initiate transactions using stored agreement references rather than requiring customer interaction each billing cycle.

### How do AI agents use the POLi Payments API through Jentic?

Agents search Jentic for tasks like 'initiate a bank transfer payment' and receive POLi operation schemas. Jentic securely stores merchant credentials, handles authentication, and allows agents to initiate transactions, check payment status, and retrieve reconciliation reports with natural language parameters.

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

Yes. Because you run Jentic One yourself, your own rules decide which POLi operations and credentials the agent may use, and POLi identifies a transaction through a request or query token rather than the URL path, so you scope the agent to only the operations it needs. A checkout agent can be granted the transaction initiation and status-read operations, while a reconciliation agent keeps just the daily transaction reports and the financial institutions lookup with no ability to initiate payments. The initiation operation is included only if you explicitly grant it, so an agent cannot move money unless you allow that.