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:

Set up your sandbox account.
Set up and endpoint to receive webhooks.
Set up an API client (example below).

🦉
Setup an API client
Open Recipe

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

Generating a new Pix Key

Bank Account ID: bank account that will receive and hold the money. For pix keys created at Trio, the money will always go to the default virtual account, which was also created at the creation of this bank account.
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://sandbox.trio.com.br/banking/cashin/pix/keys

{
    "bank_account_id": "018e5bd0-91b9-c70c-1970-54a94d946326",
    "key": "+5541999999999",
    "type": "phone_number"
}

🦉

Create a pix key with a phone number

Open Recipe

You will receive a response 200 akin to:

{
    "data": {
        "bank_account_id": "018e5bd1-067d-ee46-4825-402685959bc7",
        "entity_id": "018e5bd0-91b9-c70c-1970-54a94d946326",
        "id": "018e5cd6-5e9f-1d60-cd13-70e37feae568",
        "inserted_at": "2024-03-20T17:08:56.606137Z",
        "key": "+5541999999999",
        "stages": [
            {
                "id": "018e5cd6-5ea1-4dc7-7968-ce83778b8731",
                "inserted_at": "2024-03-20T17:08:56.609413Z",
                "type": "created",
                "updated_at": "2024-03-20T17:08:56.609413Z"
            },
           	{
                "id": "018e5bd1-21f4-3d6b-2251-95d092604ece",
                "inserted_at": "2024-03-20T12:23:36.180483Z",
                "type": *"confirmed"*,
                "updated_at": "2024-03-20T12:23:36.180483Z"
            }
        ],
        "type": "phone_number",
        "updated_at": "2024-03-20T17:08:56.606137Z"
    }
}

Receiving a status of confirmed might take a while.

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.

You can also list your pix keys through our dashboard:

console.trio.com.br/bank_account/BANK_ACCOUNT_ID/pix_keys

🚧
Attention - unidentified deposits
At Trio, we have parameterization for automatic refunds for PayIns in certain situations. One of those situations is when a pix key receives a payment.
The automatic_refund_for_unidentified_deposits flag in a virtual account is turned on by default, and therefore without any change in parameterization, any pay-ins made through your pix key will be automatically refunded.
If you desire to alter such parameterization,
you must update it through our dashboard or through our API.

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].

Visualization in Dashboard

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

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

Generating a new Pix Key

🚧Attention - unidentified deposits

Visualization in Dashboard

🚧
Attention - unidentified deposits