Solicitar cancelamentos e estornos

Sobre este guia#

Neste guia vamos descrever o passo-a-passo para que você cancele ou estorne (total ou parcialmente) suas ordens pendentes ou pagas através de nossa API de e-commerce.

Pré-requisitos#

Antes de iniciar sua integração, você deve possuir credenciais válidas. Você pode conferir como obter suas credenciais neste artigo.

Como funciona?#

Autenticação#

O PicPay utiliza autenticação via Bearer Token (JWT) para as requisições da API V2. Você deverá enviar o token de acesso no header Authorization.

Funcionamento básico#

Você poderá cancelar ou estornar (total ou parcialmente) qualquer ordem gerada por seu e-commerce através do endpoint /payments/{referenceId}/refunds. Confira abaixo as regras:

Cenário 1 Se já foi pago, o cliente PicPay será estornado caso sua conta de Lojista no PicPay tenha saldo para realizar o estorno e caso o cliente PicPay tenha recebido algum cashback nesta transação, este valor será estornado do cliente (para isto o mesmo deve possuir saldo). Todos esses requisitos devem ser cumpridos para que o estorno da transação ocorra com sucesso. Neste caso, o authorizationId (recebido na notificação de pedido pago) deve ser enviado no corpo da requisição.

curl --location --request POST 'https://api.picpay.com/ecommerce/v2/payments/{referenceId}/refunds' \ 
    --header 'Authorization: Bearer {seu_access_token}' \ 
    --header 'Content-Type: application/json' \ 
    --data-raw '{ "authorizationId": "601327196d038600273bbf1c" }'

Exemplo de estorno total de uma ordem paga.

No exemplo acima, esta ordem irá passar do status paid para refunded.

Informação

Para realizar um estorno parcial, envie também o campo amount no corpo da requisição, com o valor a ser devolvido (sempre menor ou igual ao valor total pago). Enquanto houver saldo pago disponível, é possível realizar novos estornos parciais até que o valor total seja devolvido.

{
  "authorizationId": "601327196d038600273bbf1c",
  "amount": 50.05
}

Cenário 2 Se ainda não foi pago, a transação será cancelada em nosso servidor e não permitirá pagamento por parte do cliente PicPay. Neste caso, o authorizationId não é necessário, já que não existe autorização de pagamento para o pedido.

curl --location --request POST 'https://api.picpay.com/ecommerce/v2/payments/{referenceId}/refunds' \ 
    --header 'Authorization: Bearer {seu_access_token}' \ 
    --header 'Content-Type: application/json' \ 
    --data-raw '{}'

Exemplo de cancelamento de ordem pendente.

No exemplo acima, esta ordem irá passar do status created para expired.

Para transações pagas com saldo, o valor será devolvido à carteira do usuário quase que imediatamente após a operação. O estorno de uma transação feita com cartão de crédito pode demorar alguns dias para ser refletido na fatura do cliente.

Resposta da requisição#

{
  "id": "5b008cef7f321d00ef236444",
  "referenceId": "102030",
  "summary": {
    "authorized": 100,
    "paid": 100,
    "refunded": 50.05
  }
}

O campo summary sempre retorna os valores atualizados da transação: authorized (valor autorizado), paid (valor pago/capturado) e refunded (valor já cancelado/estornado).

Próximos passos#

Obtendo ajuda#

Esperamos ter ajudado com este artigo! Caso tenha restado alguma dúvida, você pode consultar o nosso FAQ ou entrar em contato através do e-mail negocios@atendimento.picpay.com.