PayTo's real-time, irrevocable nature makes trust and security foundational to the ecosystem, for merchants, financial institutions, and customers alike. The Counterparties endpoint is one of the additional safeguards required of High Risk merchants on top of the standard integration steps: it exists to protect the integrity of the broader PayTo ecosystem by reducing fraud exposure, strengthening counterparty visibility, and ensuring every HRM participant meets a consistent security bar.

Counterparties Overview

A Counterparty record represents the end customer on the other side of a PayTo agreement: the person or entity you're collecting payments from or paying out to. Similar to a profile, it captures who they are and which payment account(s) belong to them, along with evidence of how they have been verified.

A counterparty record has two parts:

---

Integration Sequence

Counterparties sit at the front of the PayTo flow for High Risk merchants: the identity and payment account evidence captured here is what Zepto checks against when the PayTo Agreement is created and Payments are initiated.

The three steps below show where the Counterparties endpoint fits relative to those calls, and what to expect at each stage.

Step 1. Create the Counterparty

POST /counterparties

Before creating the PayTo Agreement for that customer, a counterparty must be created. For new customers, this is typically done at the time of onboarding during the KYC process.

This step only needs to happen once per customer; the same counterparty is then referenced for any successive Agreements or Payments, without needing to be recreated.

1. Onboard your customer with applicable KYC requirements
2. Create a Counterparty, capturing identity and verified payment account(s)

See API Reference: Create Counterparty

Step 2. Create the PayTo Agreement

POST /payto/agreements

When a PayTo Agreement is created, the debtor or creditor object should carry the relevant Counterparty's payment_account_uid.

Zepto checks the supplied payment_account_uid against the Counterparty record and will reject the agreement if, for example:

See API Reference: Create PayTo Agreement

Step 3. Initiate the PayTo Payment(s)

POST /payto/payments

You don't need to resupply the counterparty's payment_account_uid when initiating a payment if it's already set on the PayTo Agreement, it's inherited automatically.

See API Reference: Create PayTo Payment

---

Counterparty Management

PATCH /counterparties/{uid}

Because a counterparty behaves like an evolving profile, a KYC'd customer can hold more than one payment account and each one is verified independently, so switching accounts or adding new ones over time doesn't mean starting over. Managing a counterparty comes down to two actions:

1. Adding a new payment account
   Payment accounts can only be appended, never removed, and an existing payment account's details (party_name, account_identifier) are immutable, so a changed account (e.g. a new BSB/account number) should be added as a new payment account rather than edited.
2. Adding evidence
   Use this to attach verification you didn't have at creation time, without needing to touch anything else on the counterparty:
   1. Payment account verification: Restate an existing payment account unchanged, with a verification object attached, to record how you verified ownership of that account.
   2. Identity verification: Attach identity verification you didn't have at creation, or re-verify after a legal name change. If identity.legal_name changes, fresh identity.verification must be supplied alongside it.

See API Reference: Update Counterparty

---

Migrating existing agreements

If you have PayTo Agreements that were created before this release, they won't yet have a linked counterparty, client ID, or payment account UID, and will fail validation if fetched or used under the new API version.

A separate migration path and guide (covering how to add these identifiers to existing agreements without cancelling and recreating them) is being finalised and will be linked here shortly.

---

FAQ

---