Refunds

Overview

Waffo Pancake uses a refund ticket system. Merchants issue refunds from the Dashboard or through the API, and each refund creates a ticket that moves through a defined lifecycle.

Business Rules

These rules are enforced by the API and cannot be overridden.

One-time products can be refunded by the merchant at any time after payment — there is no refund time limit. The refund amount can’t exceed the order amount or your account’s current withdrawable balance.
Subscriptions are refunded through refund tickets too, one payment at a time. A refund does not cancel the subscription; cancel it separately to stop future charges.
Partial refunds are supported by providing a custom amount (as a display format string, e.g., “15.00”) when creating a ticket.

Refund Ticket Statuses

Every refund ticket moves through the following lifecycle:

pending

Refund ticket created, awaiting review.

approved

Refund approved. Merchant-initiated refunds are approved automatically on submission; requests buyers submit in the portal are reviewed by the platform.

rejected

Refund ticket rejected.

processing

Refund is being processed by the payment provider.

succeeded

Refund completed successfully.

failed

Refund processing failed.

Arrival time, and what “processing” means. Card refunds are handled by the buyer’s issuing bank and typically arrive within 3–10 business days (no later than 14); WeChat Pay refunds arrive immediately. A ticket in processing is at the payment-provider / bank stage — Waffo does not run an internal finance review on top of it.

Creating a Refund Ticket

Refund tickets are created by calling the API with API Key authentication.

Endpoint

POST /v1/actions/refund-ticket/create-ticket

Authentication: API Key

Request Body

string

required

The ID of the payment to refund (UUID v4).

string

required

A description of why the refund is being requested.

string

Amount to refund as a display format string (e.g., “15.00”). Omit for a full refund.

Response

string

The unique ID of the created refund ticket.

string

Initial status of the ticket. Always pending on creation.

string

The refund amount as a display format string.

Example

The cURL tab uses API Key authentication — the three signature headers, not a Bearer token. See API Key Authentication for how X-Signature is computed.

curl -X POST https://api.waffo.ai/v1/actions/refund-ticket/create-ticket \
  -H "Content-Type: application/json" \
  -H "X-Merchant-Id: MER_xxx" \
  -H "X-Timestamp: 1705312200" \
  -H "X-Signature: BASE64_RSA_SHA256_SIGNATURE" \
  -d '{
    "paymentId": "550e8400-e29b-41d4-a716-446655440000",
    "reason": "Product not as described",
    "amount": "15.00"
  }'

The merchant SDK (@waffo/pancake-ts) does not wrap this endpoint yet — call the REST endpoint with your own signature as shown above. createRefundTicket() on the customer-token client (client.customer(token)) is currently rejected by the gateway with 403 — don’t use it.

Querying Refund Tickets

Use GraphQL to retrieve refund ticket data.

query {
  refundTickets(storeId: "STORE_ID") {
    id
    paymentId
    storeId
    customerId
    reason
    status
    requestedAmount
    approvedAmount
    currency
    createdAt
    updatedAt
    resolvedAt
  }
}

Field	Type	Description
`id`	string	Refund ticket ID
`paymentId`	string	Associated payment ID
`storeId`	string	Store that owns the payment
`customerId`	string	Buyer who made the original payment
`reason`	string	Reason for the refund
`status`	string	Current ticket status
`requestedAmount`	string	Amount the buyer requested (display format string)
`approvedAmount`	string	Amount approved (may differ from requested)
`currency`	string	ISO 4217 currency code
`createdAt`	string	ISO 8601 timestamp
`updatedAt`	string	ISO 8601 timestamp
`resolvedAt`	string	ISO 8601 timestamp (null if unresolved)

Webhook Notifications

You can configure webhooks to receive notifications when refund ticket events occur. See the Webhooks guide for setup instructions.

Reducing Refund Requests

Clear Product Descriptions

Accurate descriptions reduce “not as expected” refund requests.

Trial Periods

Let customers try before buying to reduce post-purchase regret.

Responsive Support

Address issues quickly before they become refund requests.

Recognizable Billing

Use a clear billing descriptor so customers recognize charges.

Get Started

Features

Merchant

Store

Merchant of Record

Overview

Business Rules

Refund Ticket Statuses

pending

approved

rejected

processing

succeeded

failed

Creating a Refund Ticket

Endpoint

Request Body

Response

Example

Querying Refund Tickets

Webhook Notifications

Reducing Refund Requests

​Overview

​Business Rules

​Refund Ticket Statuses

pending

approved

rejected

processing

succeeded

failed

​Creating a Refund Ticket

​Endpoint

​Request Body

​Response

​Example

​Querying Refund Tickets

​Webhook Notifications

​Reducing Refund Requests

Overview

Business Rules

Refund Ticket Statuses

Creating a Refund Ticket

Endpoint

Request Body

Response

Example

Querying Refund Tickets

Webhook Notifications

Reducing Refund Requests