API REFERENCE
Zepto Status Page ↗Sandbox Portal ↗

Change Log

Change Log

card icon

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

  1. 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.
  2. 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

  1. 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.
  2. 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.
  3. 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:

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.