Reembolsando pagamentos

Solicitando um reembolso de uma cobrança à carteira do usuário#

A solicitação de reembolso deverá ser gerada com o transaction_id ou reference_id através do endpoint v1/payments/refund, indicando o valor a ser reembolsado no corpo da requisição. No exemplo abaixo, estamos solicitando o reembolso de R$ 3,00 na carteira do usuário.

Pré-condição: a transação precisa estar com status PAID, COMPLETED ou PARTIALLY_REFUNDED.

Informação

O campo transaction_id é gerado no momento da criação do pagamento.

Endpoint#

POST https://ecommerce-api.svc.picpay.com/v1/payments/refund

Exemplo de requisição#

curl --location 'https://ecommerce-api.svc.picpay.com/v1/payments/refund' \
--header 'Authorization: Bearer {{access_token}}' \
--header 'x-Idempotency-Key: {{idempotency_key}}' \
--header 'Content-Type: application/json' \
--data '{
  "value": 3,
  "transaction_id": "daef8a44-b408-4df1-b726-c579723f1116",
  "reference_id": "f997bbef-8e17-4e59-b1a9-de1fe1dedd51"
}'

Parâmetros do body#

Campo	Tipo	Obrigatório	Descrição
`transaction_id`	`string`	Sim*	Identificador da transação gerado pelo PicPay
`reference_id`	`string`	Sim*	Identificador único da transação gerado pelo parceiro
`value`	`float`	Não	Valor a estornar. Se omitido, estorno total

*Ao menos um dos identificadores deve ser informado.

Resposta de sucesso#

HTTP 200 com o body:

{
  "transaction_id": "daef8a44-b408-4df1-b726-c579723f1116",
  "reference_id": "f997bbef-8e17-4e59-b1a9-de1fe1dedd51",
  "created_at": "2021-02-22 19:29:16"
}

Status resultantes#

Status	Cenário
`REFUNDED`	Estorno total (valor integral)
`PARTIALLY_REFUNDED`	Estorno parcial (valor menor que o total)

Como será feito o reembolso?#

O saldo será retornado ao mesmo lugar da origem dos fundos, ou seja:

Caso a transação tiver sido feita por cartão de crédito, será estornada no cartão;
Caso a transação tiver sido feita no saldo, o saldo retornará a carteira do cliente;
Caso a transação seja mista (Saldo + Cartão), parte retornara como saldo na carteira e parte será estornada no cartão;

Mensagens de erro#

`business_code`	HTTP	Descrição
`TRANSACTION_CANT_BE_REFUNDED`	409	Status atual não permite estorno
`TRANSACTION_ALREADY_REFUNDED`	409	Transação já foi totalmente estornada
`REFUND_EXCEEDS_LIMIT`	422	Valor excede o disponível para estorno
`INSUFFICIENT_BALANCE_REFUND`	422	Saldo insuficiente para processar o estorno
`INVALID_PERMISSION_REFUND`	422	Sem permissão para estornar esta transação
`CASHBACK_DENIED`	422	Não foi possível recuperar cashback para o estorno
`TRANSACTION_NOT_FOUND`	404	Transação não encontrada