DEVELOPER GUIDE

PayTo Refunds via NPP

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

Refunds can be made against settled PayTo payments.
Funds will be debited from the nominated Zepto float account and returned to the BBAN or PayID specified in the original PayTo agreement from which funds were collected.

As refunds are sent via NPP, both the debtor (Zepto float account) and creditor (original source account) must be NPP enabled.

These payments will be cleared & settled in real-time. Multiple refunds can be processed against a single PayTo payment, up to the total value of the PayTo payment.

Creating a PayTo Refund

When initiating a PayTo refund, you'll need to specify the following request parameters:

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 unique PayTo Payment UID to validate and process the refund against.
`refund_payment: type`* (required)	float_bank_payment* is currently the only valid value. This tells our system to debit the float account.
`refund_payment`: `float_bank_account_id`* (required)	The ID of the Zepto float account to be debited.
`refund_payment`: `amount`* (required)	The amount (in cents) to be refunded.
`refund_payment`: `description`* (required)	MUST start with the word REFUND. Free-form text for the matching/reconciliation of a transaction. This can be shown on both parties' bank statements. ASCII-printable characters and unicode emojis are accepted.

Initiating a PayTo Refund

This example demonstrates a refund against a settled PayTo payment.

Endpoint

POST payto/refunds

{
  "uid": "refund-uid-3",
  "original_payment_uid": "biz_payment_000123",
  "refund_payment": {
    "type": "float_bank_payment",
    "float_bank_account_id": "fgbq8046-fud2-25af-82c0-yb967539f100",
    "amount": 42,
    "description": "REFUND : Partial refund for Zeptinghouse Smart Fridge 300L"
  }
}

{
    "data": {
        "uid": "refund-uid-3",
        "original_payment_uid": "biz_payment_000123",
        "refund_payment": {
            "type": "float_bank_payment",
            "float_bank_account_id": "fgbq8046-fud2-25af-82c0-yb967539f100",
            "amount": 42,
            "description": "Partial refund for Zeptinghouse Smart Fridge 300L"
        },
        "state": "created",
        "failure": null,
        "created_at": "2024-09-09T10:40:40+10:00",
        "links": {
            "self": "https://api.sandbox.zeptopayments.com/payto/refunds/refund-uid-3",
            "payment": "https://api.sandbox.zeptopayments.com/payto/payments/biz_payment_000123"
        }
    }
}

{
    "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: 200 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": "0191d43f-c47b-d0b0-b9bf-375bd0c54535",
    "body": null,
    "type": "payto_refund.processed",
    "published_at": "2024-09-09T10:47:14.555+10:00",
    "resource_uid": "refund-uid-3",
    "resource_type": "payto_refund",
    "resource_metadata": {}
  },
  "links": {
    "resource": "https://api.sandbox.zeptopayments.com/payto/refunds/refund-uid-3"
  }
}

{
  "data": {
    "id": "0191d452-193e-0429-bbe9-52686827cf95",
    "body": {
      "failure": {
        "code": "AC07",
        "title": "Closed Creditor Account Number",
        "detail": "The Payee Customer account is closed"
      }
    },
    "type": "payto_refund.failed",
    "published_at": "2024-09-09T11:07:15.902+10:00",
    "resource_uid": "refund-uid-6",
    "resource_type": "payto_refund",
    "resource_metadata": {}
  },
  "links": {
    "resource": "https://api.sandbox.zeptopayments.com/payto/refunds/refund-uid-6"
  }
}

Notable Webhook Fields

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

type

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"
}