DEVELOPER GUIDE

Refunding PayTo Payments via PayTo

This article will guide you on how to refund a PayTo payment via PayTo.

Overview

When a dispute is raised by the bank, Zepto creates the investigation, notifies your platform, and requests merchant action.

Warning

Make sure you submit evidence before the due date. Missing the deadline may result in the case being closed or rejected.

Success

Once accepted, the action request is completed and the dispute workflow progresses accordingly.

Important

Rejecting an action request without the correct review may cause avoidable operational issues.

Tip

Retrieve the investigation first, then inspect the active action request so you can present the right next step to your merchant.

Overview

When a dispute is raised by the bank, Zepto creates the investigation, notifies your platform, and requests merchant action.

Warning

Make sure you submit evidence before the due date. Missing the deadline may result in the case being closed or rejected.

Success

Once accepted, the action request is completed and the dispute workflow progresses accordingly.

Important

Rejecting an action request without the correct review may cause avoidable operational issues.

Tip

Retrieve the investigation first, then inspect the active action request so you can present the right next step to your merchant.

Step 1 - Set Up the Refund Agreement:

Create a Refund Agreement:

Establish a PayTo mandate with your business account. This will be the source account for refunds.
Structure payment terms (e.g., variable amount, ad-hoc frequency) as necessary.
Authorise the agreement in your banking app.

Overview

When a dispute is raised by the bank, Zepto creates the investigation, notifies your platform, and requests merchant action.

Warning

Make sure you submit evidence before the due date. Missing the deadline may result in the case being closed or rejected.

Success

Once accepted, the action request is completed and the dispute workflow progresses accordingly.

Important

Rejecting an action request without the correct review may cause avoidable operational issues.

Tip

Retrieve the investigation first, then inspect the active action request so you can present the right next step to your merchant.

Example Payload:

{
    "uid": "MerchantA_Refund_Agreement",
    "purpose": "retail",
    "description": "Refund Agreement",
    "debtor": {
        "party_name": "Merchant A",
        "account_identifier": {
            "type": "alias_phone",
            "value": "+61-402037912"
        },
        "ultimate_party_name": "Merchant A"
    },
    "initiator": {
        "name": "Merchant A",
        "legal_name": "Merchant A",
        "abn": "12345678103"
    },
    "payment_terms": {
        "type": "variable",
        "frequency": "adhoc",
        "max_amount": 1000
    }
}

Step 2 - Initiate a PayTo Refund

Overview

When a dispute is raised by the bank, Zepto creates the investigation, notifies your platform, and requests merchant action.

Warning

Make sure you submit evidence before the due date. Missing the deadline may result in the case being closed or rejected.

Success

Once accepted, the action request is completed and the dispute workflow progresses accordingly.

Important

Rejecting an action request without the correct review may cause avoidable operational issues.

Tip

Retrieve the investigation first, then inspect the active action request so you can present the right next step to your merchant.

Process a Refund

Endpoint

POST payto/refunds

Parameter	Description
`uid`* (required)	Supplied 64-character unique identifier for the refund request. This identifier ensures payment uniqueness between integrator systems and Zepto.
`original_payment_uid`* (required)	The original PayTo Payment UID to validate and process the refund against.
`refund_payment: type`* (required)	pay_to_payment
`refund_payment`: `agreement_uid`* (required)	The agreement uid from the refund agreement you created in Step 1.
`refund_payment`: `amount`* (required)	The amount (in cents) to be refunded.
`refund_payment`: `description`* (required)	Supplied 280-character free-form text for reconciliation purposes. Typically this field will be shown to both parties on bank statements.

{
    "refund_payment": {
        "type": "pay_to_payment",
        "agreement_uid": "MerchantA_Refund_Agreement",
        "amount": 50,
        "description": "Refund Description"
    },    
    "uid": "refund_example_uid",
    "original_payment_uid": "original_payment_uid"
}

{
    "data": {
        "uid": "refund_example_uid",
        "original_payment_uid": "original_payment_uid",
        "refund_payment": {
            "type": "pay_to_payment",
            "agreement_uid": "MerchantA_Refund_Agreement",
            "uid": "refund_example_uid",
            "amount": 50,
            "description": "Refund Description"
        },
        "state": "created",
        "failure": null,
        "created_at": "2025-05-23T10:43:43+10:00",
        "metadata": {},
        "links": {
            "self": "https://api.zeptopayments.com/payto/refunds/refund_example_uid",
            "original_payment": "https://api.zeptopayments.com/payto/payments/original_payment_uid"
        }
    }
}

{
    "errors": [
        {
            "title": "Request body is not valid JSON",
            "detail": "Error occurred while parsing request parameters"
        }
    ]
}

{
    "errors": [
        {
            "code": "ZPREF06",
            "title": "Total refunds greater than original payment amount",
            "detail": "The sum of all refunds is greater than the original payment"
        }
    ]
}

Response

Upon submission, a synchronous response will show one of the following:

Successful: 201 response
Failed:
- 400: Bad request
- 422: Unprocessable entity

Webhook

Note: Webhooks are only available for PayTo refund requests that have received a 201 response from Zepto (i.e. successful request).

{
  "data": {
    "id": "0196fab0-a8e6-6753-56f5-3b8f72adf97f",
    "body": null,
    "type": "payto_refund.processed",
    "published_at": "2025-05-23T11:10:03.750+10:00",
    "resource_uid": "refund_example_uid",
    "resource_type": "payto_refund",
    "resource_metadata": {}
  },
  "links": {
    "resource": "https://api.zeptopayments.com/payto/refunds/refund_example_uid"
  }
}

{
  "data": {
    "id": "0196fab0-a8c2-de86-d7f3-9c3ba947d5d4",
    "body": null,
    "type": "payto_payment.settled",
    "published_at": "2025-05-23T11:10:03.714+10:00",
    "resource_uid": "refund_example_uid",
    "resource_type": "payto_payment",
    "resource_metadata": {}
  },
  "links": {
    "resource": "https://api.zeptopayments.com/payto/payments/refund_example_uid"
  }
}

Notable Webhook Fields

type

type	`payto_refund.processed` `payto_refund.failed`
`resource_uid`	The unique identifier of the refund
`resource_type`	payto_refund

payto_refund.processed

payto_refund.failed

resource_uid The unique identifier of the refund

resource_type payto_refund

Simulations

A special Sandbox testing object is available to simulate outcomes.

Available simulations:

creditor_alias_not_found
payment_rejected
success

Simulation Attribute Sample

"sandbox": {
  "simulate": "success"
}