03 Feb 2026

Accept only printable characters in the Refunds endpoint

❗️
Breaking
Affected component: API

🗓️
Sandbox Release Date: 03 Feb 2026 Production Release Date: 16 February 2026

Change Description

We are introducing stricter validation on the reason field for the following endpoint:

POST /credits/{credit_ref}/refunds

At the moment, this field accepts any string. We’ve seen some refund requests fail due to hidden control characters (such as line breaks or tabs), so we’re tightening validation to make behaviour more predictable.

New validation rules for the reason field The reason field will now:

Allow

Standard printable ASCII characters
(letters, numbers, symbols like !@#$%^&*()_+)
Unicode emojis
Up to 280 characters

Disallow

Control or non-printable characters (for example: \n, \t, \r, \0). Requests containing these characters will be rejected once the change is live.

What you need to do If your integration sends a value for the reason field:

Ensure it contains only printable characters or emojis
Ensure it does not exceed 280 characters

If you already send plain text, no action is required.

22 Oct 2025

PayTo Agreements and Payments require ultimate creditor party

❗️
Breaking
Affected component: API

🗓️
Release Date: 22 Oct 2025

Change Background:

AP+ has mandated that all institutions must explicitly provide an ultimate_creditor_name when submitting payment or agreement data. While Zepto currently satisfies this requirement by defaulting to creditor_name when ultimate_creditor_name is not supplied, this behaviour is implicit.

To meet the compliance requirement by December 2025 and improve merchant awareness of their obligations (especially in the context of fraud mitigation), we want to make this required for all new merchants.

As such all new integrators are required to provide creditor.ultimate_party_namewhen specifying creditor details (either when creating the PayTo agreement or when creating the payment).

Affected Endpoints:

24 Sep 2025

Filtering Incoming PayID txns by source debtor bank details

👍
Improved
Affected component: UI

🗓️
Release Date: 24 Sep 2025

Current behaviour:

Merchants currently are not able to filter incoming PayID transactions based on the originating customer's bank account details (BSB and account number).

This can make reconciliation and investigation of suspected fraud cases difficult, especially, when multiple customers use the same PayID to send money.

New behaviour:

These details are already available inside the metadata field as npp_debtor_branch_code and npp_debtor_account_number attributes.

Merchants can now filter the receivable payments requests by the originating customer's bank account details (BSB and account number). Two new filter fields are added to **Merchant UI **Payment Requests → Receivables.

BSB (NPP Debtor)
Account number (NPP Debtor)

08 Sep 2025

Alias Resolution Endpoint (Sandbox Simulation)

👍
Improved
Affected component: API (Sandbox only)

🗓️
Release Date: 08 Sep 2025

Endpoint:

https://docs.zeptopayments.com/reference/post_payto-alias-resolution

Current behaviour:

Currently a static value i.e. Sandbox User is returned in the display_name field in sandbox. This makes it difficult for integrators to test with names defined in their test/database for e.g. name fuzzy matching.

{
  "data": {
    "display_name": "Sandbox User"
  }
}

New behaviour:

Integrators can now send their own display_name. Using this simulation allows client developers integrating with the API to set the value that will be returned by the endpoint in the sandbox. Including sandbox.display_name with other simulation types will have no effect.

{
  "type": "alias_email",
  "value": "gary@mcghernikan.com",
  "requester": {
    "id": "gary",
    "remote_ip": "192.168.1.1"
  },
  "sandbox": {
    "simulate": "alias_found",
    "display_name": "Gary McGhernikan"
  }
}

{
  "data": {
    "display_name": "Gary McGhernikan"
  }
}

Note: Omitting the sandbox.display_name parameter will result in "Sandbox User" as the display_name in the response.

04 Sep 2025

Failure codes for failed PayTo Payments after manual investigation

👍
Improved
Affected component: Webhook

🗓️
Release Date: 04 Sep 2025

Current behaviour:

When a PayTo payment is manually marked as failed (e.g., after confirming failure with the participant bank), the failure code is hardcoded as zepto_admin_manual_investigation and the webhook sent to merchants includes a generic error code (UKNWN) with a failure detail (An unexpected error occured. Reach out to Zepto for more information).

This limits merchants ability to reconcile and perform root cause analysis.

New enhanced behaviour:

We will include more specific reason codes in the failed payments webhook notification.

Reason Code	Title	Description
ZPPAY24	Participant not available	One of the participants is currently not available to process the payment.
AC06	Blocked Account	The Payer Customer Account is blocked
AC02	Invalid Debtor Account	The Payer Customer Account does not exist within NPP
AG07	Unsuccesful Direct Debit	Debtor account cannot be debited for a generic reason. May indicate insufficient funds
MS02	Not Specified Reason Customer Generated	The payment was rejected by the Debtor Customer, but no reason was provided

An example webhook delivery with the updated failure code:

{
  "data": {
    "id": "01990d03-8f56-efbf-937d-12345678897",
    "body": {
      "failure": {
        "code": "AG07",
        "title": "Unsuccesful Direct Debit",
        "detail": "Debtor account cannot be debited for a generic reason. May indicate insufficient funds",
        "retryable": true
      }
    },
    "type": "payto_payment.failed",
    "published_at": "2025-09-03T10:39:21.174+10:00",
    "resource_uid": "wp8rWCE2QqqOO87MLDL39wtest",
    "resource_type": "payto_payment",
    "resource_metadata": {}
  },
  "links": {
    "resource": "https://api.zeptopayments.com/payto/payments/wp8rWCE2QqqOO87MLDL39wtest"
  }
}

19 Aug 2025

Validation of PayTo Mandate/Amendment Party Names

👍
Improved

🗓️
Sandbox Release Date: 19 Aug 2025
Production Release Date: 25 Aug 2025

Change Details:

This release is a bug fix for the HTML entity issue on certain fields when creating or amending a PayTo mandate.

What

Affected fields:

debtor party name
debtor ultimate party name
creditor party name
creditor ultimate party name
initiator name
initiator legal name

Currently, these fields accept any string matching the regex ^[ -~]+$. After this release, we will reject values containing named HTML entities.

Example:

This change ensures compatibility with MMS, which does not accept named HTML entities.

What changes for customers?

Strings containing plain text (matching ^[ -~]+$) will continue to be accepted.
Named HTML entities are not permitted in these fields.

If an invalid named HTML value is provided, the request will be rejected with the following error:

"errors": [
    {
      "code": "ZPUNP00",
      "title": "One or more fields violate the relevant schema",
      "detail": "debtor.party_name must not contain HTML name entities"
    }
  ]

5 Aug 2025

Filter PayTo Agreements and Payments by initiator name

➕
ADDED

🗓️
Release Date: 5 August 2025 (Sandbox and Production)

Change Details:

Added an additional query parameter to the PayTo Agreements and PayTo Payments API endpoints. This allows users to filter by Agreement Initiator Name. The value provided must be an exact match for the initiator name saved on the agreement.

Endpoints:

List PayTo Agreement

additional query param: initiator_name

List PayTo Payments

additional query param: agreement_initiator_name

15 July 2025

Accept Initiator's ACN in PayTo Agreement

👍
Improved

🗓️
Sandbox Release Date: 15 July 2025
Production Release Date: 28 July 2025

Change Details:

For PayTo agreement creation, merchants will be able to identify an initiator by either ACN or ABN (previously only ABN was supported).

What

API requests:

Create agreement - now accepts initiator.acn
Create agreement amendment - now accepts initiator.acn

API responses:

Get agreement - will always include initiator.acn
- for most merchants, this will be initiator.acn: nil
- for merchants who provided ACN, this will be initiator.acn: <ACN> and response will also include initiator.abn: nil.
List agreement history - each agreement will include initiator.acn
Show amendment - may include initiator.acn if it was one of the changed attributes.

29 Apr 2025

Stricter regex pattern for description fields

❗️
Breaking (Minor)

🗓️
Sandbox Release Date: 29 Apr 2025
Production Release Date: 26 May 2025

Change Details:

The validation for the description fields in the following endpoints are made stricter:

POST /payments

POST /payto/refunds

The new regex (regular expression) allows only printable ASCII characters and Unicode emojis. This ensures the description field is accurately mapped to remittance_information_unstructured in our underlying banking ecosystem.

Previously, we were accepting general strings without any strict character limitations. We identified that a few requests to our backend system were being rejected with unparsable error due to the presence of control characters in the description fields. This is a minor breaking change as this might affect the Merchant’s integration.

What

New regex pattern added to description fields (description and payouts > description) ^[ -~\p{Emoji}]+$
Allows printable ASCII characters (chars between ' '0x20 and '~'0x7E) and Unicode emoji

14 Mar 2025

PayTo Resends - New Pending state and callback

➕
ADDED

🗓️
Sandbox Release Date: 14 Mar 2025
Production Release Date: 28 Mar 2025

Change Details:

With the new PayTo resends schedule (v2), we are introducing a new state Pending for the PayTo Payments. A PayTo payment enters into this new state when it takes longer than expected to settle. As part of this update, merchants will receive a new payto_payment.pending webhook notification.

Why this change?

In certain scenarios, we do not receive a final PSR for a PayTo Payment until a Resend is triggered by us. Currently, our system does the initiation automatically for the first hour. However, if a PSR is still not received after all attempts, the payment enters Under Investigation state. Our Transactions and Support team need to manually trigger any subsequent resends required through the admin UI.

With Resend v2, we are extending the automatic resending period (approximately 40 hours) for longer than the initial one hour window. This helps us in reducing the need for manual intervention and improving payment resolution efficiency.

What

With v2, a PayTo Payment will transition from Submitting to Pending when the first resend attempt occurs, which happens 35 seconds after payment initiation. This timing also lines up with AP+'s end to end payment completion SLA that participants aim to adhere to. This will indicate that the Payment is taking longer than expected but Zepto is still trying to get a resolution for the Payment.
Merchants will also receive a new payto_payment.pending webhook when the above state change occurs (when the first resend is attempted). Below is the body of the new webhook that merchants will receive upon state transition.

{
  "data": {
    "id": "01953fc0-9da4-3693-4771-b5d932029a45",
    "body": null,
    "type": "payto_payment.pending",
    "published_at": "2025-02-26T11:55:42.756+11:00",
    "resource_uid": "payment3_6523452347_587hsgdfbhgf",
    "resource_type": "payto_payment",
    "resource_metadata": {}
  },
  "links": {
    "resource": "https://api.zeptopayments.com/payto/payments/payment3_6523452347_587hsgdfbhgf"
  }

Your Action

In case of delayed payments, Merchants will now see the payments in pending state longer than before. Previously, they see the delayed payments in submitting state.
If merchants have any logic tied to payto_payment.under_investigation webhook, they may need to make adjustments to their workflow by subscribing to new payto_payment.pending webhook instead.
The under investigation webhooks will now be triggered after approximately 40 hours instead of 1 hour.

20 Feb 2025

New Error Code for Payment Failure due to Unavailable Participant

➕
ADDED

🗓️
Release Date: 20 Feb 2025

Change Details:

Currently, when a payment fails due to a participant being offline and unable to process a payment initiation, that payment will fail due to flow control which results in a merchant receiving a payto_payment.failed webhook with the following body:

Before

{"data"=>{
  "id"=>"01951c4b-ce9d-ba1b-fb62-5b910b7c0969",
  "body"=>{
    "failure"=>{
      "code"=>"UKNWN", 
      "title"=>"Unknown Error", 
      "detail"=>"An unexpected error occured. Reach out to Zepto for more information",
      "retryable"=>false
    }
  },
  "type"=>"payto_payment.failed",
  "published_at"=>"2025-02-19T14:41:25.021+11:00",
  "resource_uid"=>"uid",
  "resource_type"=>"payto_payment",
  "resource_metadata"=>{}},
  "links"=>{"resource"=>"https://api.zeptopayments.com/payto/payments/uid"}
}

After

We are now happy to share more detail with merchants in this scenario. In order to do this, we’ve introduced a new error code ZPPAY24 that has the following details

{"data"=>{
  "id"=>"01951c4b-ce9d-ba1b-fb62-5b910b7c0969",
  "body"=>{
    "failure"=>{
      "code"=>"ZPPAY24", 
      "title"=>"Participant not available", 
      "detail"=>"One of the participants is currently not available to process the payment.",
      "retryable"=>false
    }
  },
  "type"=>"payto_payment.failed",
  "published_at"=>"2025-02-19T14:41:25.021+11:00",
  "resource_uid"=>"uid",
  "resource_type"=>"payto_payment",
  "resource_metadata"=>{}},
  "links"=>{"resource"=>"https://api.zeptopayments.com/payto/payments/uid"}
}

Your Action

Merchants can now choose to handle the new error code accordingly.

4 Dec 2024

Prevent non-administrators from removing float accounts in UI

❗️
Breaking
Affected Component: Merchant Portal UI

🗓️
Production Release Date: 4 Dec 2024

Change Details:

Merchants can no longer self-serve to remove their float accounts. This avoids potential issues such as orphaned PayIDs.

Your actions:

If you need assistance with removing a float account please lodge a request with our support team.

25 Nov 2024

Zepto IDs from UUIDv4 to UUIDv7

👍
Improved

🗓️
* Sandbox Release Date: 25 Nov 2024* Production Release Date: 6 Jan 2025

Change Details:

Zepto will change the format of IDs it generates from UUIDv4 to UUIDv7 in order to improve database performance and scalability.

Example Before

{
  "id": "6e339aa1-6743-4bb4-9840-5c5ca0d91c93"
}

Example After

{
  "id": "019327cc-c654-70b0-b522-85c54e073f38"
}

Your actions:

Merchants should ensure any validations they have on Zepto IDs generate are not explicitly checking for UUIDv4 compatibility.

UUIDv7 Benefits

11 Nov 2024

Restrict length of API Idempotency-Key header

❗️
Breaking

🗓️
Production Release Date: 11 Nov 2024

Change Details:

Enforce a 256-character limit for Idempotency-Key headers.

Affected endpoints:

POST /payment_requests
POST /payments
POST /credits/:credit_ref/refunds

28 Oct 2024

Links to refund on payment if payment is facilitating a refund

➕
ADDED

🗓️
* Sandbox Release Date: 28 Oct 2024* Production Release Date: 4 Nov 2024

Change Details:

For payments that facilitate refunds via a PayTo payment, our API will now include a new link, source_refund, within the links section in the response for the following endpoints:

If a payment is facilitating a refund, the source_refund will have a value providing a direct reference to the associated refund. If the payment is not linked to a refund, this field will show as null.

Example:

Before the change:

"links": { 
  self: "http://api.test.example.com/payto/payments/PAYMENT_1234", 
  agreement: "http://api.test.example.com/payto/agreements/biz_agreement_123"
}

After the change:

Payment facilitating a refund:

"links": { 
  self: "http://api.test.example.com/payto/payments/PAYMENT_1234", 
  agreement: "http://api.test.example.com/payto/agreements/biz_agreement_123", 
  source_refund: "http://api.test.example.com/payto/refunds/refund_123"
}

Payment not facilitating a refund:

"links": { 
  self: "http://api.test.example.com/payto/payments/PAYMENT_1234", 
  agreement: "http://api.test.example.com/payto/agreements/biz_agreement_123", 
  source_refund: null
}

10 Oct 2024

PayTo Payment Reference Field Validation

❗️
Breaking change

🗓️
* Scheduled Sandbox Release Date: 10 Oct 2024* Scheduled Production Release Date: 24 Oct 2024

Change Details:

Currently, the reference field in the PayTo Payments endpoint allows non-ASCII characters. This has resulted in incompatibilities with our downstream PayTo core banking and back-office integration.

Introducing further validation to only allow ASCII characters in the payments reference field. This change is a breaking change that might affect your PayTo integration.

Your actions:

Validate that only ASCII characters with this Regex ^[ -~]+$ are used for the reference field in the PayTo Payments endpoint.

01 Oct 2024

Metadata Field

🆕
New feature

🗓️
Release Date: 01 Oct 2024

Change Details:

The Metadata field will be returned in the following endpoints:

Create Agreement
List Agreements
Show Agreements
Create Payment
List Payments
along with all agreements and payment webhook notifications

Your actions:

Merchants can now utilise the metadata feature.

Please test/build in the sandbox and make any necessary modifications to your current integration as needed.

Change Log

03 Feb 2026

Accept only printable characters in the Refunds endpoint

22 Oct 2025

PayTo Agreements and Payments require ultimate creditor party

Breaking

Release Date: 22 Oct 2025

24 Sep 2025

Filtering Incoming PayID txns by source debtor bank details

Improved

Release Date: 24 Sep 2025

08 Sep 2025

Alias Resolution Endpoint (Sandbox Simulation)

Improved

Release Date: 08 Sep 2025

04 Sep 2025

Failure codes for failed PayTo Payments after manual investigation

Improved

Release Date: 04 Sep 2025

19 Aug 2025

Validation of PayTo Mandate/Amendment Party Names

Improved

Sandbox Release Date: 19 Aug 2025

5 Aug 2025

Filter PayTo Agreements and Payments by initiator name

ADDED

Release Date: 5 August 2025 (Sandbox and Production)

15 July 2025

Accept Initiator's ACN in PayTo Agreement

Improved

Sandbox Release Date: 15 July 2025

29 Apr 2025

Stricter regex pattern for description fields

Breaking (Minor)

Sandbox Release Date: 29 Apr 2025

14 Mar 2025

PayTo Resends - New Pending state and callback

ADDED

Sandbox Release Date: 14 Mar 2025

20 Feb 2025

New Error Code for Payment Failure due to Unavailable Participant

ADDED

Release Date: 20 Feb 2025

4 Dec 2024

Prevent non-administrators from removing float accounts in UI

Breaking

Production Release Date: 4 Dec 2024

25 Nov 2024

Zepto IDs from UUIDv4 to UUIDv7

Improved

* Sandbox Release Date: 25 Nov 2024* Production Release Date: 6 Jan 2025

11 Nov 2024

Restrict length of API Idempotency-Key header

Breaking

Production Release Date: 11 Nov 2024

28 Oct 2024

Links to refund on payment if payment is facilitating a refund

ADDED

* Sandbox Release Date: 28 Oct 2024* Production Release Date: 4 Nov 2024

10 Oct 2024

PayTo Payment Reference Field Validation

Breaking change

* Scheduled Sandbox Release Date: 10 Oct 2024* Scheduled Production Release Date: 24 Oct 2024

01 Oct 2024

Metadata Field

New feature

Release Date: 01 Oct 2024