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 an API client (example below).
🦉Setup an API clientOpen 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.
- (email):
- e.g.:
-
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"
}
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 keysdata.counterparty
anddata.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 obviouslypix_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}
Updated 6 months ago