Enviar pedido de reversão

informação

O pagamento só pode ser revertido se tiver no estado Autorizado.

Pode consultar o estado do pagamento no endpoint:

GET /payments/{id}

O que é uma Reversão?

Uma reversão (reversal) cancela uma transação que ainda não foi liquidada (settled). Ao contrário de uma devolução, a reversão impede que os fundos sejam transferidos, cancelando a autorização antes do settlement.

aviso

A reversão só pode ser efetuada antes do settlement diário. Após o settlement, deve utilizar uma devolução (refund).

1. Iniciação da Reversão (via API)

O seu sistema inicia a reversão remotamente através da API PayPay:

1. O sistema envia o pedido para API PayPay:

Endpoint

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

Exemplo básico

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

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
uuid	string	✅ Sim	UUID do terminal onde foi realizado o pagamento original
paymentId	string	✅ Sim	ID do pagamento PayPay que deseja reverter
remarks.text	string	❌ Não	Texto de observações para a reversão

2. API PayPay comunica com a rede de pagamentos e processa a reversão de forma síncrona;
3. API PayPay devolve a resposta com o resultado da reversão.

Resposta da API

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

Estrutura da Resposta

Campo	Tipo	Descrição
id	string	ID da reversão PayPay
clientId	string	NIF da entidade a que o pagamento ficou associado
type	string	Tipo de operação
amount	integer	Montante revertido
initialPaymentId	string	ID do pagamento original
stateDetails.state	string	Estado da reversão
stateDetails.createdAt	datetime	Data do estado
cancellation.cancelled	boolean	Sucesso do cancelamento
cancellation.cancelledAt	datetime	Data do cancelamento
cancellation.reason	string	Motivo do cancelamento
paymentMethod	object	Método de pagamento do pagamento original
createdAt	datetime	Data de criação do registo
updatedAt	datetime	Data da última atualização

Processamento da Reversão

Após o pedido de reversão ser enviado pela API, o processo segue estes passos:

1. Terminal recebe o pedido de reversão;
2. Sistema envia pedido de cancelamento para a rede de pagamentos;
3. Rede contacta banco emissor para cancelar a autorização;
4. Resposta é enviada de volta ao terminal:
   • Aprovada: Reversão processada com sucesso, autorização cancelada.
   • Recusada: Mensagem de erro apresentada (ex: pagamento já liquidado).

informação

A reversão não requer a apresentação do cartão, uma vez que é um cancelamento da autorização original.

3. Notificação ao Sistema

Após a confirmação, o seu sistema é notificado:

1. A Transação é sincronizada com backoffice PayPay em tempo real;
2. A PayPay notifica via Webhook o seu sistema com detalhes da reversão.

Reversão vs Devolução

Aspeto	Reversão	Devolução
Quando usar	Antes do settlement	Após o settlement
Cartão necessário	Não	Sim
Parcial	Não	Sim
Movimento de fundos	Cancela autorização	Devolve fundos