Pay-in using a pix key

The Pix key is a identifier associated with a bank account, which can be a mobile number, email, CPF/CNPJ (tax payer identification number), or a random alphanumeric code. This key is linked to the user's account and allows them to receive transfers and make payments quickly and securely, without the need of providing traditional banking details such as branch and account numbers.

Before starting this guide, you should have already:

Let's first generate a pix key to later know how I can receive a payment through it.

Generating a new Pix Key

Virtual Account ID: virtual account that will receive and hold the money.
Key: the value of the key. It must respect the type set below.
- e.g.:
  - (email): [email protected]
  - (phone_number): +55419999999999
  - (tax_number): 111.111.111.11 (with or without punctuation)
  - (random_key): Random hash.
Type: can be one of the four possibilities ("email, "phone_number, "tax_number", "random_key")

To generate a new pix key, send a POST request to the create pix key endpoint using this payload:

POST: https://api.sandbox.trio.com.br/banking/cashin/pix/keys

{
    "virtual_account_id": "018e5bd0-91b9-c70c-1970-54a94d946326"
}

You will receive a response 200 akin to:

{
    "data": {
        "id": "0193930b-c903-7cbf-fa87-057a9e358b54",
        "status": "confirmed",
        "type": "random_key",
        "key": "0193930b-c5fb-de26-1783-3b49dc9e5c21",
        "inserted_at": "2024-12-04T19:00:43.396630Z",
        "updated_at": "2024-12-04T19:00:43.545717Z",
        "tax_number": "68563270233912",
        "virtual_account_id": "018e5bd0-91b9-c70c-1970-54a94d946326"
    }
}

Only after the key is confirmed, a user can send money to you using a pix key. You can list the pix keys you created through our API ou accessing our dashboard:

app.trio.com.br/virtual_accounts/VIRTUAL_ACCOUNT_ID/pix_keys

Identifying a pay-in through pix key

When receiving a pay-in, you will receive webhooks with the category collecting_document.

The collecting_document webhook contains a ref_type field, which will be pix_key and will contain the id of the Pix key you created in the ref_id field. It also contains an id field, which is the ID for the pay-in (collecting_document) that can be queried in both our API and Dashboard.

Here you can find examples for asettled webhook:

{
    "category": "collecting_document",
    "company_id": "018d88e5-ca39-6f6a-c35a-c2592364b4b0",
    "data": {
        "amount": {
            "amount": 123123,
            "currency": "BRL"
        },
        "bank_account_id": "018e5bd1-067d-ee46-4825-402685959bc7",
        "company_id": "018d88e5-ca39-6f6a-c35a-c2592364b4b0",
        "counterparty": {
            "company_id": "018d88e5-ca39-6f6a-c35a-c2592364b4b0",
            "external_id": "018d88ed-a9b0-ece4-fa1b-01801cbe6597",
            "id": "018d88ed-a9b3-53a9-aed6-646887995175",
            "inserted_at": "2024-02-08T13:34:53.363727Z",
            "ledger_type": "customer",
            "legal_name": null,
            "maximum_amount": null,
            "maximum_transactions": null,
            "name": "Farrell-McDermott LLC",
            "tax_number": "60496015675405",
            "updated_at": "2024-02-08T13:34:53.363727Z"
        },
        "counterparty_bank_account": {
            "account_digit": "5",
            "account_number": "75879",
            "account_type": "checking",
            "bank_ispb": "37056171",
            "bank_number": "311267",
            "branch": "6937",
            "id": "018d88f7-cd90-333a-5d22-b8d66242a6c6",
            "inserted_at": "2024-02-08T13:45:57.904443Z",
            "updated_at": "2024-02-08T13:45:57.904443Z"
        },
        "counterparty_bank_account_id": "018d88f7-cd90-333a-5d22-b8d66242a6c6",
        "counterparty_id": "018d88ed-a9b3-53a9-aed6-646887995175",
        "description": "123",
        "end_to_end_id": "018d892c-b7f9-d2a6-f9cf-a0e8a55b1fb9",
        "entity_id": "018d88e5-cb60-38e8-a157-ad00a8c4cd15",
        "external_id": null,
        "id": "018d892c-b7f9-c4dd-c90a-caf344fe8520",
        "marked_for_automatic_refund": false,
        "origin_id": null,
        "origin_type": "none",
        "receipt_url": "https://s3.sa-east-1.amazonaws.com/new-cdn.trio.com.br/comprovante-sandbox.pdf",
        "reconciliation_id": "018d892c-e07f-9daf-f8ac-790a7a23cf95",
        "ref_id": "018e5cd6-5e9f-1d60-cd13-70e37feae568",
        "ref_type": "none",
        "status": "settled",
        "transaction_date": "2024-02-08T14:43:45.785187Z",
        "type": "pix",
        "virtual_account_id": "018d88ed-8d22-0aa3-7118-c587bc84dca0"
    },
    "ref_id": "018d892c-b7f9-c4dd-c90a-caf344fe8520",
    "timestamp": "2024-02-08T14:43:56.724030Z",
    "type": "settled"
}

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

data.id represents the ID from the collecting document, you can query the details using the collecting document GET endpoint.
data.counterparty_id represents the ID from the user that paid the QR code, you can access the details using the counterparty GET endpoint or by getting the info from the keys data.counterparty and data.counterparty_bank_account we already sent you.
data.ref_id represents the pix_key linked to the pay-in.
data.ref_type represents the payment type, in this case obviously pix_key.
data.external_id is the external ID that was informed in the QR code, with that information you can link the transaction on you side.
data.receipt_url is the URL for the receipt that legally represents this transaction for your end user.

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