Refund a pay-in

Suggest Edits

A refund is always directly correlated to an existing pay-in (collecting_document). Therefore, a refund cannot be done without correlation to an existing payment. When generating a refund, a document called refund_document will be generated. Also, a refund cannot be made with an amount larger than the amount from the initial pay-in, meaning: if a partial refund was requested and then settled, a second refund cannot be done with the full amount of the pay-in, as it would exceed the original full amount.

If you desire to make a refund, we call it a manual refund. You can make a refund:

  1. Our API, making a request to our refund endpoint.

  2. Our dashboard, by going to the collecting document in question and pressing the Refund button:
    https://console.sandbox.trio.com.br/documents/in/DOCUMENT_ID

In this guide, we will exemplify how to make a request to the refund endpoint.
Assuming one has a settled collecting document with the id being 018e5bd0-91b9-c70c-1970-54a94d946326,
one should make such request:

POST /banking/cashin/documents/:id/refund

It must contain such body:

{
    "amount": 1,
    "description": "My Refund"
}

You will receive a 200 response akin to:

{
    "refund_document_id": "018e5db0-2f7b-a5ea-b665-f61b31f94dcf",
    "scheduled_at": "2024-03-20T21:06:51.562508Z"
}

If it fails, you will receive a 400 response akin to:

{
    "error": {
        "error_code": "NOT_FOUND_RESOURCE",
        "error_message": "Documento de cobrança não foi encontrado. Referência: 018dd138-b1c9-77c4-703a-a9f3896e62e8."
    }
}

With that ID, you will be able to receive webhooks related to the category at hand (collecting_document_refund). Below you can find examples of such webhooks:

{
  "category": "collecting_document_refund",
  "company_id": "0189b5ad-8076-6b61-e299-9920d819a3f6",
  "data": {
    "amount": {
      "amount": 9300,
      "currency": "BRL"
    },
    "attempt": 0,
    "bank_account_id": "0189b787-efb6-2650-7baa-00ba98c4daf1",
    "collecting_document_id": "018d892c-b7f9-c4dd-c90a-caf344fe8520",
    "company_id": "0189b5ad-8076-6b61-e299-9920d819a3f8",
    "description": "Estorno",
    "end_to_end_id": null,
    "entity_id": "0189b5b4-ea58-a3a8-7c40-f0de1d0cb0af",
    "error_message": null,
    "external_id": "9fa7b90ac41147a2a2225a1e71fe6f8d",
    "id": "018e5db0-2f7b-a5ea-b665-f61b31f94dcf",
    "origin_id": "018c407f-eb08-006e-805f-4a3d504f2ead",
    "origin_type": "api_client",
    "receipt_url": null,
    "reconciliation_id": "018de55d-eac2-738e-d7d6-e5678ce72bfa",
    "rule": "manual",
    "transaction_date": "2024-02-26T12:22:33.922605Z",
    "virtual_account_id": "0189b787-efc8-b0f5-8171-781814fac2a6"
  },
  "ref_id": "018de55d-eac2-379e-4094-2f0e7b2ba72a",
  "timestamp": "2024-02-26T12:22:33.983939Z",
  "type": "created"
}

{
  "category": "collecting_document_refund",
  "company_id": "0189b5ad-8076-6b61-e299-9920d819a3f8",
  "data": {
    "collecting_document_id": "018d892c-b7f9-c4dd-c90a-caf344fe8520",
    "end_to_end_id": "D1320335420240226122217611378645",
    "error_message": null,
    "external_id": "21abe99cb79345e3a2fd2cf79c5bd707",
    "id": "018de55d-daf9-5910-95fa-fc0d67e6c3c5",
    "receipt_url": "https://receipt.fitbank.com.br/receiptapi/pdf?filename=20234-02-26/p0nj5ksw.pdf",
    "refund_document_id": "018e5db0-2f7b-a5ea-b665-f61b31f94dcf",
    "rule": "manual",
    "timestamp": "2024-02-26T12:22:29.881248Z",
    "type": "settled"
  },
  "ref_id": "018de55d-9c6f-46d5-d651-bb186cde3df5",
  "timestamp": "2024-02-26T12:22:30.270215Z",
  "type": "settled"
}

Within the webhook, you'll have access to all information about the refund document (pay-in). For example, the created webhook contains:

  • data.id represents the ID from the refund document, whose details can be queried using the refund document GET endpoint.
  • data.collecting_document_id represents the ID from the original pay-in (collecting_document), whose details can be queried using the collecting document GET endpoint.
  • data.external_id is the external ID that was informed in the original pay-in, with that information you can link the transaction on you side just like in the collecting_document.

And also as an example, the settled webhook contains:

  • data.end_to_end_id referencing the voucher for the transaction that was the manual refund.
  • data.receipt_url is the URL for the receipt that legally represents this transaction for your end user.

Congratulations, you have completed your first refund of a pay-in with Trio 🍻. If you have any questions, please drop us a message at [email protected].

Updated about 1 month ago