Pay-out using a Pix key (V1)

Suggest Edits

Considering the fact that a Pix key represents a bank account in the Pix arrangement, this is the most straight forward way to complete a payout using Pix.

The only information you need from the customer is their Pix key. Currently, we support 5 types of keys and we use RegEx to validate the format:

TypeRegexExample
Email`^[a-z0-9.!#$&'*+\/=?^_{}~-]+@[a-z0-9?(?:.a-z0-9?)]*$``[email protected]
Phone number^\+[1-9][0-9]\d{1,14}$+5510998765432
CPF (tax number)^[0-9]{11}$12345678901
CNPJ (tax number)^[0-9]{14}$12345678901234
Random[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}123e4567-e89b-12d3-a456-426655440000

Generating a new Payout

To generate a new payout in V1 using a pix key, you must go through two steps:

  • Check your key using the Check key endpoint. By making this request, you will receive information regarding the tax number involved, so you can decide whether or not the tax number is the one you desire to make a pay-out to.
  • If you decide that it is valid, you can make a pay-out using the Pix V1 endpoint.

Let's do both requests to see what you can expect from their respective responses.

Checking a Pix Key

When checking a pix key, there are some parameters that you will need to pay attention to (* for required fields):

  • Entity ID: the unique identifier for the entity_id that will hold the checked key information.
  • Key: the value of the key you desire to check. e.g: "+5583988720998"

POST /banking/cashout/pix/keys/check

{
    "entity_id": "018e5bd0-9078-f906-69e6-b3145c5d3097",
    "key": "+5583988720998"
}

If the key is a valid existing one, you will receive a 200 response akin to:

{
    "data": {
        "counterparty": {
            "bank_account": {
                "account_digit": "7",
                "account_number": "73451",
                "account_type": "checking",
                "bank_ispb": "36305779",
                "bank_number": "425797",
                "branch": "1685",
                "id": "018e5bd3-6f40-718b-d01c-9ee5d45032f7",
                "inserted_at": "2024-03-20T12:26:07.040509Z",
                "updated_at": "2024-03-20T12:26:07.040509Z"
            },
            "company_id": "018e5bd0-9078-f906-69e6-b3145c5d3097",
            "external_id": "018e5bd1-1fe9-ec37-8642-c2b2959ff317",
            "id": "018e5bd1-2007-c6b1-9591-8d554306c381",
            "inserted_at": "2024-03-20T12:23:35.692818Z",
            "ledger_type": "customer",
            "maximum_amount": null,
            "maximum_transactions": null,
            "name": "Farrell-McDermott LLC",
            "tax_number": "57088554850677",
            "updated_at": "2024-03-20T12:23:35.692818Z"
        },
        "entity_id": "018e5bd0-91b9-c70c-1970-54a94d946326",
        "id": "018e612f-3740-96ec-9ecf-de48c743a988",
        "inserted_at": "2024-03-21T13:24:28.096836Z",
        "key": "+5541999999099",
        "type": "phone",
        "updated_at": "2024-03-21T13:24:28.096836Z"
    }
}

With the valid response received, you may want to pay attention to some important fields:

  • data.counterparty contains all information related to the individual who will receive any payments for that key:
    • data.counterparty.name represents their full name.
    • data.counterparty.tax_number represents the document/tax number (CPF/CNPJ in Brasil)
    • data.counterparty.bank_account represents the bank account that will receive the payment from that pix key.
  • data.id is the unique identifier for that key. We will use it to make the pay-out, if the counterparty found here is validated on your end. This will be the Pix Ref ID.

If the key is not a valid existing one, you will receive a 4xx response akin to:

{
  "error_code": "DICT_KEY_NOT_FOUND",
  "error_message": "Chave pix não foi encontrada. Referência: +5583988720998."
}

Making a pay-out

When generating a new payout, there are some parameters that you will need to pay attention to (* for required fields):

  • Virtual Account ID*: the unique identifier for the virtual account that will send the money.
  • Pix Ref ID*: the unique identifier for a key you have checked prior. See above the id returned in the Check key endpoint.
  • Pix Ref Type*: must be the type of the reference sent in the Pix Ref ID field. Possible values are "key", "brcode" or "bank_account". For a pix key, always select "key".
  • External ID: reference for your transaction in our system. It must be a unique string for every payout. Used to control the idempotence of a transaction.
  • Amount*: amount of the transaction, always represented in cents.
  • Description: the description of this single transaction.

To generate the payout, send a POST request to our Pix Payout endpoint, using this payload:

POST: https://sandbox.trio.com.br/banking/cashout/pix

{
  "virtual_account_id": "c6377347-7891-46ac-ac2e-368d01ac0305",
  "pix_ref_id": "018e612f-3740-96ec-9ecf-de48c743a988",
  "pix_ref_type": "key",
  "amount": 1,
  "description": "Payment PIX - Key",
  "external_id": "950806b3-2f34-449d-86b6-437dafb625fc"
}

If everything is OK, you will receive a HTTP 201 response. It means that we have successfully scheduled the payout request, and the payload will be as follows:

{
  "data": {
    "payment_document_id": "018b480d-8da8-374a-6dd5-83b81788c605",
    "scheduled_at": "2023-10-19T12:59:34.947655Z"
  }
}

If it fails, you will receive a 400 response with the error message. You can check the complete error list here.

{
  "error": {
    "error_code": "PAYMENT_ACCOUNT_WITHOUT_BALANCE",
    "error_message": "Saldo insuficiente. Saldo atual R$ 3,13."
  }
}

Events

Created

Once we process the payout transaction, you will receive a webhook with the category payment_document and type created. This webhook contains all information regarding the transaction, and you can use the payment_document_id from the payout request to match it with the transaction:

{
  "category": "payment_document",
  "company_id": "018e5bd0-9078-f906-69e6-b3145c5d3097",
  "data": {
    "amount": {
      "amount": 1,
      "currency": "BRL"
    },
    "bank_account_id": "018e5bd1-067d-ee46-4825-402685959bc7",
    "company_id": "018e5bd0-9078-f906-69e6-b3145c5d3097",
    "counterparty": {
      "company_id": "018e5bd0-9078-f906-69e6-b3145c5d3097",
      "external_id": "018e5bd1-1fe9-ec37-8642-c2b2959ff317",
      "id": "018e5bd1-2007-c6b1-9591-8d554306c381",
      "inserted_at": "2024-03-20T12:23:35.692818Z",
      "ledger_type": "customer",
      "legal_name": null,
      "maximum_amount": null,
      "maximum_transactions": null,
      "name": "Farrell-McDermott LLC",
      "tax_number": "57088554850677",
      "updated_at": "2024-03-20T12:23:35.692818Z"
    },
    "counterparty_bank_account": {
      "account_digit": "7",
      "account_number": "73451",
      "account_type": "checking",
      "bank_ispb": "36305779",
      "bank_number": "425797",
      "branch": "1685",
      "id": "018e5bd3-6f40-718b-d01c-9ee5d45032f7",
      "inserted_at": "2024-03-20T12:26:07.040509Z",
      "updated_at": "2024-03-20T12:26:07.040509Z"
    },
    "counterparty_bank_account_id": "018e5bd3-6f40-718b-d01c-9ee5d45032f7",
    "counterparty_id": "018e5bd1-2007-c6b1-9591-8d554306c381",
    "description": "Saque de merchant.com",
    "end_to_end_id": null,
    "entity_id": "018e5bd0-91b9-c70c-1970-54a94d946326",
    "error_code": null,
    "error_message": null,
    "external_id": "950806b3-2f34-449d-86b6-437dafb625fc",
    "id": "018e6136-30b7-f359-2702-f4502d7aa0c1",
    "origin_id": "018e5caf-98c8-016a-d411-82cfbd670714",
    "origin_type": "api_client",
    "payment_date": null,
    "pix_key": null,
    "receipt_url": null,
    "reconciliation_id": "018e6136-30b7-afa2-c96f-e0020142d952",
    "ref_id": "018e612f-3740-96ec-9ecf-de48c743a988",
    "ref_type": "pix_key",
    "status": "created",
    "transaction_date": "2024-03-21T13:32:05.175244Z",
    "type": "pix",
    "virtual_account_id": "018e5bd1-12c2-f8d9-e8a5-078afb78344b",
    "without_fee_and_tax": false
  },
  "ref_id": "018e6136-30b7-f359-2702-f4502d7aa0c1",
  "timestamp": "2024-03-21T13:32:06.175964Z",
  "type": "created"
}

At this moment, the transaction has not been completed yet, and can go through a success or a failure.

Success

When we complete the transaction successfully, you will receive a webhook notification with the category payment_document and type settled. You can use the payment_document_id to match with the ref_id from the payload:

{
  "category": "payment_document",
  "company_id": "018e5bd0-9078-f906-69e6-b3145c5d3097",
  "data": {
    "counterparty": {
      "company_id": "018e5bd0-9078-f906-69e6-b3145c5d3097",
      "external_id": "018e5bd1-1fe9-ec37-8642-c2b2959ff317",
      "id": "018e5bd1-2007-c6b1-9591-8d554306c381",
      "inserted_at": "2024-03-20T12:23:35.692818Z",
      "ledger_type": "customer",
      "legal_name": null,
      "maximum_amount": null,
      "maximum_transactions": null,
      "name": "Farrell-McDermott LLC",
      "tax_number": "57088554850677",
      "updated_at": "2024-03-20T12:23:35.692818Z"
    },
    "counterparty_bank_account": {
      "account_digit": "7",
      "account_number": "73451",
      "account_type": "checking",
      "bank_ispb": "36305779",
      "bank_number": "425797",
      "branch": "1685",
      "id": "018e5bd3-6f40-718b-d01c-9ee5d45032f7",
      "inserted_at": "2024-03-20T12:26:07.040509Z",
      "updated_at": "2024-03-20T12:26:07.040509Z"
    },
    "counterparty_bank_account_id": "018e5bd3-6f40-718b-d01c-9ee5d45032f7",
    "counterparty_id": "018e5bd1-2007-c6b1-9591-8d554306c381",
    "end_to_end_id": "018e6136-3668-06eb-d410-4745edfc9cca",
    "error_code": null,
    "error_message": null,
    "external_id": "950806b3-2f34-449d-86b6-437dafb625fc",
    "id": "018e6136-38b7-3f5c-0184-6b95ea63d590",
    "integration_status": "settled",
    "payment_document_id": "018e6136-30b7-f359-2702-f4502d7aa0c1",
    "receipt_url": "https://receipts.sandbox.trio.com.br/out/018e6136-38b7-3f5c-0184-6b95ea63d590",
    "timestamp": "2024-03-21T13:32:07.223058Z",
    "type": "settled"
  },
  "ref_id": "018e6136-30b7-f359-2702-f4502d7aa0c1",
  "timestamp": "2024-03-21T13:32:08.191001Z",
  "type": "settled"
}

At this moment, the transaction can be considered to be complete.

Failure

There are several reasons for a transaction to not be completed: insufficient balance, problems with the communication with the Central Bank of Brasil, and many others. When anything other than a success occurs, you will receive a webhook with the category payment_document and type reversed or failed: 

{
  "ref_id": "018b480d-8da8-374a-6dd5-83b81788c605",
  "category": "payment_document",
  "type": "reversed",
  "data": {
    "id": "018b479b-6ec2-9d45-05ab-278122742fbd",
    "type": "reversed",
    "timestamp": "2023-10-19T11:04:10.690756Z",
    "error_code": "TR0001",
    "external_id": "950806b3-2f34-449d-86b6-437dafb625fc",
    "receipt_url": "https://receipt.fitbank.com.br/receiptapi/pdf?filename=2023-10-19/mxzifvvg.pdf",
    "end_to_end_id": null,
    "error_message": "Saldo insuficiente para executar o pagamento",
    "counterparty_id": "0189a9e1-d0c8-200d-3cc8-6e70630ba9a3",
    "payment_document_id": "018b4797-ab1a-e96b-1a96-2d70c87d8456",
    "counterparty_bank_account_id": "0189a9e1-d0cb-faea-7467-aba34f9f1eff"
  },
  "timestamp": "2023-10-19T13:08:56.735025Z",
  "company_id": "a56c6e42-10c8-4876-946f-7d71595cecdc"
}

The failed webhook will fire when something was wrong before settling the document, such as the occurrence of a tax number being different from the Central Bank reference:

{
  "ref_id": "018b480d-8da8-374a-6dd5-83b81788c605",
  "category": "payment_document",
  "type": "failed",
  "data": {
    "id": "018b479b-6ec2-9d45-05ab-278122742fbd",
    "type": "failed",
    "timestamp": "2023-10-19T11:04:10.690756Z",
    "error_code": "TR0001",
    "external_id": "950806b3-2f34-449d-86b6-437dafb625fc",
    "receipt_url": null,
    "end_to_end_id": null,
    "error_message": "CPF/CNPJ informado é diferente do consultado na DICT.",
    "counterparty_id": "0189a9e1-d0c8-200d-3cc8-6e70630ba9a3",
    "payment_document_id": "018b4797-ab1a-e96b-1a96-2d70c87d8456",
    "counterparty_bank_account_id": "0189a9e1-d0cb-faea-7467-aba34f9f1eff"
  },
  "timestamp": "2023-10-19T13:08:56.735025Z",
  "company_id": "a56c6e42-10c8-4876-946f-7d71595cecdc"
}

If you desire to verify the payment document in our dashboard for a more complete view, you can do so by going to:

console.sandbox.trio.com.br/documents/out/{DOCUMENT_ID}

Updated about 1 month ago