Refunding payments

Requesting a refund of a charge to the user's wallet#

The refund request must be generated with the transaction_id or reference_id through the endpoint v1/payments/refund, indicating the amount to be refunded in the body of the request. In the example below, we are requesting a refund of BRL 3.00 to the user's wallet.

Pre-condition: the transaction must have status PAID, COMPLETED, or PARTIALLY_REFUNDED.

Information

The transaction_id field is generated when creating the payment.

Endpoint#

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

Request example#

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

Body parameters#

Field	Type	Required	Description
`transaction_id`	`string`	Yes*	Transaction identifier generated by PicPay
`reference_id`	`string`	Yes*	Unique transaction identifier generated by the partner
`value`	`float`	No	Amount to refund. If omitted, full refund

*At least one identifier must be provided.

Successful response#

HTTP 200 with body:

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

Resulting statuses#

Status	Scenario
`REFUNDED`	Full refund (full amount)
`PARTIALLY_REFUNDED`	Partial refund (amount less than total)

How will the refund be made?#

The balance will be returned to the same source of funds:

If the transaction was made by credit card, it will be reversed on the card;
If the transaction was made from the balance, the balance will return to the customer's wallet;
If the transaction is mixed (Balance + Card), part will return as balance in the wallet and part will be reversed on the card;

Error messages#

`business_code`	HTTP	Description
`TRANSACTION_CANT_BE_REFUNDED`	409	Current status does not allow refund
`TRANSACTION_ALREADY_REFUNDED`	409	Transaction has already been fully refunded
`REFUND_EXCEEDS_LIMIT`	422	Amount exceeds available refund limit
`INSUFFICIENT_BALANCE_REFUND`	422	Insufficient balance to process the refund
`INVALID_PERMISSION_REFUND`	422	No permission to refund this transaction
`CASHBACK_DENIED`	422	Could not recover cashback for the refund
`TRANSACTION_NOT_FOUND`	404	Transaction not found