Send a refund request

information

The payment can only be refunded if it is in state Confirmado.

You can check the payment status at the endpoint:

GET /payments/{id}

Refund Types

• Full refund
• Partial refund

1. Initiate Refund (via API)

Your system initiates the refund remotely through the PayPay API:

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

Endpoint

POST /terminals/{uuid}/refunds/{paymentId}

Basic example

{
  "amount": 100,
}

Parameters

Parameter	Type	Required	Description
uuid	string	✅ Sí	UUID of the terminal to which the refund request will be sent
paymentId	string	✅ Sí	PayPay payment ID to be refunded
amount	integer	✅ Sí	Amount to be refunded

2. PayPay API communicates with the terminal in a assíncrona;
3. The terminal automatically receives and displays the amount to the operator;

information

The terminal waits 1 minute for card presentation.

4. PayPay API returns the success or failure response of the asynchronous request while the terminal waits for the card to be presented.

API Response

{
    "date": "2025-09-01T12:46:22+01:00",
    "success": true,
    "data": {
        "id": "3",
        "clientId": "502056800",
        "type": "refund",
        "amount": 50,
        "initialPaymentId": "1",
        "stateDetails": {
            "state": "pending_confirmation",
            "createdAt": "2025-09-01T12:46:22+01:00"
        },
        "paymentMethod": {
            "code": "CC",
            "type": "TPA",
            "details": {
                "brand": "VISA",
                "last4Digits": "7193"
            }
        },
        "availableMethods": [
            {
                "code": "CC",
                "type": "TPA",
                "name": "Credit Debit card Physical TPA"
            }
        ],
        "bankAccount": {
            "code": "O9uFVmSZ",
            "bankName": "Banco",
            "last4digits": "8513"
        },
        "createdAt": "2025-09-01T12:46:22+01:00",
        "updatedAt": "2025-09-01T12:46:22+01:00"
    }
}

Response Structure

Field	Type	Description
id	string	PayPay Refund ID
clientId	string	TIN number of the entity associated with the payment
type	string	Operation Type
stateDetails.state	string	Payment State
stateDetails.createdAt	datetime	State Date
paymentMethod	object	Payment method of the original payment
availableMethods	object	Available payment methods for the refund
bankAccount	object	Identification of the bank that will receive the funds
createdAt	datetime	Record creation date
updatedAt	datetime	Last update date

Refund flow on the terminal

Once the refund request is sent via the API, the process on the terminal follows these steps:

2. Card Presentation

The customer presents the same card used in the original payment:

1. The terminal displays the refund amount to the operator;
2. The customer presents the card using one of the following methods:
   • Contactless: Bring the card or mobile device close.
   • Chip: Insert the card into the terminal.
   • Magnetic stripe: Swipe the card.
3. The terminal checks if the card matches the original payment.

warning

The card must be the same one used in the original payment. If a different card is presented, the refund will be rejected.

3. Authentication

Depending on the amount and card type, authentication may be required:

1. The card data is read and validated by the terminal;
2. The system checks if authentication is required:
   • If yes: The customer enters the PIN.
     • If the PIN is correct: Processing continues.
     • If the PIN is incorrect: Retry or cancellation (max. 3 attempts).
   • If not: Direct processing for authorisation.

Authentication types:

• PIN: Usually required for refunds.
• No authentication: In some cases for low amounts.

4. Processing and Confirmation

The terminal communicates with the payment network to process the refund:

1. The terminal validates the data and sends the request to the payment network;
2. The network contacts the issuing bank to process the refund;
3. The response is sent back to the terminal:
   • Approved: Refund successfully processed.
   • Declined: Error message displayed.

5. Notification to the System

After confirmation, your system will be notified:

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

tip

Configure webhooks to receive automatic notifications of the refund result. The API response only indicates that the request has been sent to the terminal, not the final outcome.