Send a reversal request

information

The payment can only be reversed if it is in state Authorised.

You can check the payment status at the endpoint:

GET /payments/{id}

What is a Reversal?

A reversal cancels a transaction that has not yet been settled. Unlike a refund, a reversal prevents funds from being transferred by cancelling the authorisation before settlement.

warning

Reversals can only be made before the daily settlement. After settlement, you must use a refund.

1. Reversal Initiation (via API)

Your system initiates the reversal remotely via the PayPay API:

1. The system sends the request to the PayPay API:

Endpoint

PATCH /terminals/{uuid}/reversals/{paymentId}

Exemplo básico

{
  "remarks": {
    "text": "remarks text"
  }
}

Parameters

Parameter	Type	Required	Description
uuid	string	✅ Yes	UUID of the terminal where the original payment was made
paymentId	string	✅ Yes	PayPay payment ID to be reversed
remarks.text	string	❌ No	Optional text remarks for the reversal

2. PayPay API communicates with the payment network and processes the reversal in a synchronous;
3. PayPay API returns the response with the reversal result.

API Response

{
    "date": "2025-09-01T12:46:22+01:00",
    "success": true,
    "data": {
        "id": "4",
        "clientId": "502056800",
        "type": "reversal",
        "amount": 100,
        "initialPaymentId": "1",
        "stateDetails": {
            "state": "cancelled",
            "createdAt": "2025-09-01T12:46:22+01:00"
        },
        "cancellation": {
            "cancelled": true,
            "cancelledAt": "2025-09-01T12:46:22+01:00",
            "reason": "merchant_cancelled"
        },
        "paymentMethod": {
            "code": "CC",
            "type": "TPA",
            "details": {
                "brand": "VISA",
                "last4Digits": "7193"
            }
        },
        "createdAt": "2025-09-01T11:46:22+01:00",
        "updatedAt": "2025-09-01T11:46:22+01:00"
    }
}

Response Structure

Field	Type	Description
id	string	PayPay reversal ID
clientId	string	Tax ID of the entity associated with the payment
type	string	Operation type
amount	integer	Reversed amount
initialPaymentId	string	Original payment ID
stateDetails.state	string	Reversal state
stateDetails.createdAt	datetime	State date
cancellation.cancelled	boolean	Cancellation success
cancellation.cancelledAt	datetime	Cancellation date
cancellation.reason	string	Cancellation reason
paymentMethod	object	Original payment method
createdAt	datetime	Record creation date
updatedAt	datetime	Last update date

Reversal Processing

After the reversal request is sent via the API, the process follows these steps:

1. Terminal receives the reversal request;
2. System sends cancellation request to the payment network;
3. Network contacts issuing bank to cancel the authorisation;
4. Response is sent back to the terminal:
   • Approved: Reversal processed successfully, authorisation cancelled.
   • Declined: Error message displayed (e.g.: payment already settled).

information

Reversals do not require the card to be presented, as it is a cancellation of the original authorisation.

3. System Notification

After confirmation, your system is notified:

1. The transaction is synchronised with PayPay backoffice in real time;
2. PayPay notifies via Webhook your system with the reversal details.

Reversal vs Refund

Aspect	Reversal	Refund
When to use	Before settlement	After settlement
Card required	No	Yes
Partial	No	Yes
Fund movement	Cancels authorisation	Returns funds