Skip to content

Refund

This service allows you to create refunds of an existing payment.

The following payment methods, a bank transfer will be made to the customer, Additional bank account information required

Payment method
BOLETO
BANK_TRANSFER

HTTP Request

POST /v1/payments/charges/refund

Request Headers
{
    "Content-Type": "application/json",
    "Authorization": "Bearer {{access_token}}",
    "x-api-key": "{{api_key}}"
}
Request Body
{
    "idempotencyKey": "2022030214000007-1",
    "referenceId": "2022030214000007",
    "amount": 300,
    "currency": "BRL",
    "country": "BR",
    "description": "refund test",
    "additionalInfo": {
        "bankTransferAccountInfo": {
            "bankCode": "332",
            "beneficiaryName": "antonio silva",
            "bankAccountNumber": "286435",
            "bankAccountType": "DOCUMENT",
            "bankBranchId": "0001",
            "ispb": "13140088",
            "document": {
                "documentId": "60123456789",
                "type": "CPF"
            }
        }
    },
    "callbackUrl": "https://api.client.com/callback/"
}
Response
{
    "transferStatusCode": 200,
    "transferErrorMsg": null,
    "idempotencyKey": "2022030214000007-1",
    "referenceId": "2022030214000007",
    "paymentMethod": "CARD",
    "amount": 300,
    "currency": "BRL",
    "country": "BR",
    "finalAmount": 100,
    "finalCurrency": "BRL",
    "createTime": "2022-03-01 21:18:56 GMT-08:00",
    "scheduledTime": "2022-03-01 21:18:56 GMT-08:00",
    "finalStatusTime": "2022-03-01 21:18:57 GMT-08:00",
    "payer": {
        "name": "username",
        "document": null,
        "email": "account@example.com",
        "phone": "+55 81987654321",
        "billingAddress": {  
            "zipCode": "04849333",
            "state": "SP",
            "city": "sao paulo",
            "district": "Jardim Gaivotas",
            "street": "Rua 9 de setembro",
            "number": "15",
            "complement": "casa",
            "country": "BR"
        }
    },
    "transferStatus": "SETTLED",
    "description": "refund test",
    "callbackUrl": "https://api.client.comcallback/"
}

Notification / Callback

Notification / Callback
{
    "eventType": "CHARGE_REFUND_SUCCEEDED",
    "data": {
        "chargeDetails" : {
            "amount" : 300,
            "callbackUrl" : "https://api.client.com/callback/",
            "country" : "BR",
            "finalAmount": 100,
            "finalCurrency": "BRL",
            "createTime" : "2022-03-01 15:10:35 GMT+08:00",
            "currency" : "BRL",
            "description" : "refund test",
            "finalStatusTime" : "2022-03-01 15:10:37 GMT+08:00",
            "idempotencyKey" : "2022030114000005-1",
            "payer" : {
                "email" : "account@example.com",
                "name" : "username"
            },
            "paymentMethod" : "CARD",
            "referenceId" : "2022030214000007",
            "scheduledTime" : "2022-03-01 15:10:35 GMT+08:00",
            "transferStatus" : "SETTLED",
            "transferStatusCode" : 200
        }
    }
}

HTTP Headers Details

Key Value
Authorization "Bearer" + " " + {{access_token}}
x-api-key {{api_key}}

Request Body Parameters

Parameter Required Type Description
idempotencyKey String idempotencyKey of refund transation, generate by merchant.
referenceId String idempotencyKey of payment which need to refund.
amount Long The refund amount. The minimum settlement granularity of the current currency, such as 100=1BRL
country String country code
currency String The currency code of the transferred fund
description String description of refund transation
additionalInfo JSON Additional refund information
callbackUrl String URL where Liquido will send notifications associated to changes to this payment. will receive a post request.

Response Body Details

Parameter Type Description
idempotencyKey String idempotencyKey of refund record, generate by merchant.
referenceId String idempotencyKey of the payment which need to refund.
amount Long The refund amount
country String country code
currency String The currency code of the refund
finalAmount Long The final amount that is used for creating the charge order. EX: for charge orders with FX conversion, this field represents the converted amount from the original requested amount.
finalCurrency String The currency code of the finalAmount.
description String reason for refund
callbackUrl String URL where Liquido will send notifications associated to changes to this refund.
createTime String refund ticket created time
scheduledTime String refund ticket scheduled time
finalStatusTime String refund final status update time, final status include SETTLED, FAILED
transferStatus String refund status, SETTLED, IN_PROGRESS, FAILED
transferStatusCode Integer refund status code, 200 transaction SETTLED or IN_PROGRESS, other FAILED
transferErrorMsg String refund error message if failed

Object Parameters

AdditionalInfo Object Parameters

Parameter Required Type Description
bankTransferAccountInfo JSON Bank transfer account information

BankTransferAccountInfo Object Parameters

Parameter Required Type Description
bankCode String The bankcode of the bank, 3 digits
beneficiaryName String The beneficiary name
bankAccountNumber String The beneficiary bank account number
bankAccountType String The beneficiary bank account type , DOCUMENT, EMAIL, PHONE, RANDOM
bankBranchId String The beneficiary bank branch Id
bankName String The beneficiary bank name
ispb String The ISPB of the bank, used in the same way as the shorter bank code, 8 digits
document JSON payer's identity proof, CPF or CNPJ

Document Object Parameters

Parameter Required Type Description
documentId String identity number
type String enum of CPF or CNPJ

Notification Event Type

CHARGE_SUCCEEDED,
CHARGE_FAILED,
CHARGE_CHARGED_BACK,
CHARGE_REFUND_SUCCEEDED,
CHARGE_REFUND_FAILED;
Back to top