Skip to main content

Payment and Send Pix

The following endpoints bring the functionalities available for managing Pix Sending and Pix QR Code Payment.


Request for Pix sending​

Endpoint designed to perform the direct sending of a Pix to a Pix key registered with a PSP, whether it's Efí or another. This endpoint may undergo changes when it enters the BACEN standardization scope. In this case, enabled clients will be notified in advance.

To use the Request for Pix sending endpoint, in addition to selecting the pix.send scope in your Efi Bank account, it is necessary for the payer's Pix key to have a webhook associated with it. Through the webhook, Efí will inform you whether the Pix sending was successful or not.

If your application was created before July 29, 2024, you will need to modify the scopes (?) by deactivating and reactivating the pix.send scope within the Pix API to use the resource.

Idempotency

The PUT /v3/gn/pix/:idEnvio endpoint is idempotent.

This means that if a transaction is not completed successfully (for example, due to a communication failure or response timeout), you must resend the request using the same identifier (idEnvio). This way, the system will recognize that it is the same transaction and ensure that no amount is debited more than once, preventing multiple Pix transfers.On the other hand, if the previous transaction is completed successfully, any new transfer must use a new identifier (idEnvio), ensuring that a new transaction is created.

Idempotence, therefore, ensures that each idEnvio represents exactly one transaction, regardless of the number of sending attempts.

Important!

During the Pix sending process, a failure in the 5XX range (internal server errors) may occur. In these cases, the transaction may have been successfully processed even if the API response indicates an error.

Therefore, it is not recommended to immediately attempt a new sending after receiving a 5XX response.

Recommendations:

  • Wait for the webhook notification of the Pix status to be returned.
  • If the webhook is not received within the expected time, before attempting a new sending you can:
    • Check the endpoint: GET /v2/gn/pix/enviados/id-envio/:idEnvio to verify the status of the original sending.
    • Make a new attempt using the same idEnvio. This way, even if the previous sending was successfully processed, the amount will not be debited again, ensuring no duplicate sendings and reinforcing reliability and security in the Pix sending process.
  • Only make a new sending request (with a different idEnvio) if it is confirmed that the previous transaction was not completed.

Instructions for the Production environment

When consuming the Pix sending endpoint in production, be aware of the following pre-approved limits for each account:

  • Efí Pro Accounts: R$ 0.30 - For yourself or secure contacts.
  • Efi Empresas Accounts: R$ 1.00 - For yourself or secure contacts.

It is a requirement of the endpoint to have an Efi Empresas account to make changes in the send Pix limits.


Instructions for testing in Sandbox

If you need to test the Pix sending endpoint, we have a functional Sandbox environment where it is possible to simulate all statuses returned by our API and by the webhook.

  • If the value of Pix is between R$ 0.01 and R$ 10.00:
    Pix is confirmed, information will come via Webhook.
  • If the value of Pix is between R$ 10.01 and R$ 20.00:
    Pix is rejected, information will come via Webhook
  • If the Pix value is above R$ 20.00:
    Pix is rejected already in the request, information will not come via Webhook.
  • Payments sent with a value of R$ 4.00 will generate two refunds received in the value of R$ 2.00.
  • Payments sent with a value of R$ 5.00 will generate one refund received in the value of R$ 5.00.
  • When requesting the sending of pix with the amounts that generate refunds (R$4.00 and R$5.00), a refund webhook will be triggered, containing the field natureza: ORIGINAL.
  • Payments sent via key will only be confirmed or rejected if the test key is used: [email protected]. Otherwise, an invalid key error will be reported.
  • Payments sent via bank details will not be changed.

Attention!

To improve service performance and avoid balance conflicts, we recommend that the Pix sending via API be conditioned on the completion of the previous transaction, which is notified through the webhook. If this practice is not followed and multiple sending requests are made at the same time, the integrator may face issues with sending.

We would like to point out that this route will be identified as v3, but anyone using the route /v2/gn/pix/:idEnvio need not worry, as it will continue to work normally. This new version brings an important improvement, including signaling the number of tokens available in the bucket (Bucket-Size), which will be returned in the response header. Therefore, we suggest that you use the new version.


PUT /v3/gn/pix/:idEnvio
Requires authorization for the scope: pix.send


Request

// Example of transfer to Pix key
{
  "valor": "12.34",
  "pagador": {
    "chave": "19974764017",
    "infoPagador": "Segue o pagamento da conta"
  },
  "favorecido": {
    "chave": "joã[email protected]"
  }
}

Responses

The responses below represent Success(201) and consumption failures/errors.

{
  "idEnvio": "12453567890123456789",
  "e2eId": "E09089356202011251226APIff82f2e5",
  "valor": "12.31",
  "horario": {
    "solicitacao": "2021-11-25T12:26:42.905Z"
  },
  "status":"EM_PROCESSAMENTO"
}

Response Headers
Case 1: Empty bucket
  • Bucket-Size = integer that represents the size of the user's token bucket. This case illustrates a scenario where the user has an empty token bucket and, consequently, this header will have the value 0 (zero); and
  • Retry-After = integer representing the amount of time in seconds for the user to try again.
Case 2: Bucket Size
  • Bucket-Size = integer that represents the size of the user's token bucket. This case illustrates a scenario where the user has tokens in the bucket, so the header will have a value greater than zero. For example: 80, which represents 80 chips remaining in the chip bucket.

Request for Pix sending to accounts with the same ownership​

Endpoint used to make Pix transfers exclusively between accounts with the same ownership, which may include other accounts the customer holds at Efí or other financial institutions.

o use the Request Pix Send for Same Ownership endpoint, in addition to selecting the gn.pix.sameownership.send scope in your Efi Bank account, it is necessary for the payer's Pix key to have a webhook associated with it. Through the webhook, Efí will inform you whether the Pix sending was successful or not.

Idempotency

The PUT /v3/gn/pix/:idEnvio endpoint is idempotent.

This means that if a transaction is not completed successfully (for example, due to a communication failure or response timeout), you must resend the request using the same identifier (idEnvio). This way, the system will recognize that it is the same transaction and ensure that no amount is debited more than once, preventing multiple Pix transfers.On the other hand, if the previous transaction is completed successfully, any new transfer must use a new identifier (idEnvio), ensuring that a new transaction is created.

Idempotence, therefore, ensures that each idEnvio represents exactly one transaction, regardless of the number of sending attempts.

Attention!

This endpoint is available only in the Production environment.


Important!

During the Pix sending process, a failure in the 5XX range (internal server errors) may occur. In these cases, the transaction may have been successfully processed even if the API response indicates an error.

Therefore, it is not recommended to immediately attempt a new sending after receiving a 5XX response.

Recommendations:

  • Wait for the webhook notification of the Pix status to be returned.
  • If the webhook is not received within the expected time, before attempting a new sending you can:
    • Check the endpoint: GET /v2/gn/pix/enviados/id-envio/:idEnvio to verify the status of the original sending.
    • Make a new attempt using the same idEnvio. This way, even if the previous sending was successfully processed, the amount will not be debited again, ensuring no duplicate sendings and reinforcing reliability and security in the Pix sending process.
  • Only make a new sending request (with a different idEnvio) if it is confirmed that the previous transaction was not completed.

Instructions for the production environment

When consuming the Pix sending endpoint in production, be aware of the following pre-approved limits for each account:

  • Efí Pro Accounts: R$ 0.30 - For yourself or secure contacts.
  • Efi Empresas Accounts: R$ 1.00 - For yourself or secure contacts.

It is a requirement of the endpoint to have an Efi Empresas account to make changes in the send Pix limits.


Attention!

To improve service performance and avoid balance conflicts, we recommend that the Pix sending via API be conditioned on the completion of the previous transaction, which is notified through the webhook. If this practice is not followed and multiple sending requests are made at the same time, the integrator may face issues with sending.


PUT /v2/gn/pix/:idEnvio/mesma-titularidade
Requires authorization for the scope: gn.pix.sameownership.send


Request

{
  "valor": "12.34",
  "pagador": {
    "chave": "19974764017",
    "infoPagador": "Segue o pagamento da conta"
  },
  "favorecido": {
    "chave": "joã[email protected]"
  }
}

Responses

The responses below represent Success(201) and consumption failures/errors.

{
  "idEnvio": "12453567890123456789",
  "e2eId": "E09089356202011251226APIff82f2e5",
  "valor": "12.34",
  "horario": {
    "solicitacao": "2021-11-25T12:26:42.905Z"
  },
  "status":"EM_PROCESSAMENTO"
}

Response Headers
Case 1: Empty bucket
  • Bucket-Size = integer that represents the size of the user's token bucket. This case illustrates a scenario where the user has an empty token bucket and, consequently, this header will have the value 0 (zero); and
  • Retry-After = integer representing the amount of time in seconds for the user to try again.
Case 2: Bucket Size
  • Bucket-Size = integer that represents the size of the user's token bucket. This case illustrates a scenario where the user has tokens in the bucket, so the header will have a value greater than zero. For example: 80, which represents 80 chips remaining in the chip bucket.

Get Pix sent through the endToEndId​

Endpoint to retrieve a Pix sent through its e2eId.

GET /v2/gn/pix/enviados/:e2eId
Requires authorization for the scope: gn.pix.send.read


Responses

The responses below represent Success(200) and consumption failures/errors.

{ // Pix sent through Pix API endpoint to a pix key
  "endToEndId": "E09089356202210251208APIcdbe38b4",
  "idEnvio": "identificadoEnvio123456789",
  "valor": "0.01",
  "chave": "19974764017",
  "status": "REALIZADO",
  "infoPagador": "Segue o pagamento da conta (endpoint pix sent)",
  "horario": {
    "solicitacao": "2022-10-26T09:05:32.000Z",
    "liquidacao": "2022-10-26T09:05:31.000Z"
  },
  "favorecido": {
    "chave": "[email protected]",
    "identificacao": {
      "nome": "Francisco da Silva",
      "cpf": "***.456.789-**"
    },
    "contaBanco": {
      "codigoBanco": "09089356"
    }
  }
}

Get Pix sent through the Transaction identifier​

Endpoint to retrieve a Pix sent through its idEnvio.

GET /v2/gn/pix/enviados/id-envio/:idEnvio
Requires authorization for the scope: lotecobv.writeRequer autorização para o escopo: gn.pix.send.read


Responses

The responses below represent Success(200) and consumption failures/errors.

{ // Pix sent through Pix API endpoint to a pix key
  "endToEndId": "E09089356202210251208APIcdbe38b4",
  "idEnvio": "identificadoEnvio123456789",
  "valor": "0.01",
  "chave": "19974764017",
  "status": "REALIZADO",
  "infoPagador": "Segue o pagamento da conta (endpoint pix sent)",
  "horario": {
    "solicitacao": "2022-10-26T09:05:32.000Z",
    "liquidacao": "2022-10-26T09:05:31.000Z"
  },
  "favorecido": {
    "chave": "[email protected]",
    "identificacao": {
      "nome": "Francisco da Silva",
      "cpf": "***.456.789-**"
    },
    "contaBanco": {
      "codigoBanco": "09089356"
    }
  }
}

Get list of sent Pix​

Endpoint to retrieve multiple sent Pix.

This endpoint has filters to narrow down the search results. Among all available filters, the inicio and fim filters are mandatory and represent the date range in which the queried transactions must be included.

GET /v2/gn/pix/enviados
Requires authorization for the scope: gn.pix.send.read


Request

To obtain the query result, it is necessary to inform the inicio and fim parameters, as shown in the code snippet below. These parameters restrict the results to the sent Pix transactions within this date range.

/v2/gn/pix/enviados?inicio=2022-01-01T00:00:00.000Z&fim=2022-12-31T23:59:59.000Z

Responses

The responses below represent Success(200) and consumption failures/errors.

// Pix sent through Pix API endpoint to a pix key
{ 
  "endToEndId": "E09089356202210251208APIcdbe38b4",
  "idEnvio": "identificadoEnvio123456789",
  "valor": "0.01",
  "chave": "19974764017",
  "status": "REALIZADO",
  "infoPagador": "Segue o pagamento da conta (endpoint pix sent)",
  "horario": {
    "solicitacao": "2022-10-26T09:05:32.000Z",
    "liquidacao": "2022-10-26T09:05:31.000Z"
  },
  "favorecido": {
    "chave": "[email protected]",
    "identificacao": {
      "nome": "Francisco da Silva",
      "cpf": "***.456.789-**"
    },
    "contaBanco": {
      "codigoBanco": "09089356"
    }
  }
}

Detail QR Code Pix​

Endpoint that allows you to detail the information associated with a QR Code Pix.

Attention!

Currently, the gn.qrcodes.read scope is down for maintenance, so this endpoint is temporarily unavailable. This functionality will be restored shortly.


POST /v2/gn/qrcodes/detalhar
Requires authorization for the scope: gn.qrcodes.read


Request

{
  "pixCopiaECola": "00020101021226830014BR.GOV.BCB.PIX2561qrcodespix.sejaefi.com.br/v2 41e0badf811a4ce6ad8a80b306821fce5204000053000065802BR5905EFISA6008SAOPAULO60070503***61040000"
}

Responses

The responses below represent Success(200) and consumption failures/errors.

{
  "tipoCob": "cob",
  "txid": "7978c0c97ea847e78e8849634473c1f1",
  "revisao": 0,
  "calendario": {
      "criacao": "2024-07-03T12:34:27.000Z",
      "apresentacao": "2024-07-03T12:34:40.238Z",
      "expiracao": 3600
  },
  "status": "ATIVA",
  "devedor": {
      "nome": "Francisco da Silva",
      "cpf": "***.456.789-**"
  },
  "recebedor": {
      "nome": "Empresa de Serviços SA",
      "cpf": "***.456.789-**"
  },
  "valor": {
      "final": "567.89"
  },
  "chave": "a1f4102e-a446-4a57-bcce-6fa48899c1d1",
  "solicitacaoPagador": "Cobrança dos serviços prestados."
}

Pay QR Code Pix​

Endpoint that allows you to pay for a Pix QR Code via API.

The endpoint of paying a QR Code Pix via API is similar to Pix sending, as the sending in question will be used to pay the charge specified in the pixCopiaECola field. This endpoint may undergo changes when it enters the BACEN standardization scope. In this case, enabled clients will be notified in advance.

To use Pay QR Code Pix endpoint, in addition to releasing the gn.qrcodes.pay scope, it is necessary for the payer's Pix key to have a webhook associated with it. Through the webhook, Efí will inform you whether the payment was made successfully or not.

Important!

To pay a charge via API it is necessary to inform the idEnvio, just as with regular shipping. This identifier must be unique for both common shipments and QR Code payment submissions;

To consume the QR Code Pix payment endpoint, it is not necessary to previously consume the Detail QR Code Pix endpoint. The detailing endpoint is complementary to the payment endpoint, that is, the integrator can consume the detailing endpoint, check the information and, later, consume the payment endpoint. However, the integrator is free to consume the payment endpoint directly;


PUT /v2/gn/pix/:idEnvio/qrcode
Requires authorization for the scope: gn.qrcodes.pay


Request

{
  "pagador": {
    "chave": "a1f4102e-a446-4a57-bcce-6fa48899c1d1",
    "infoPagador": "Pagamento de QR Code via API Pix"
  },
  "pixCopiaECola": "00020101021226830014BR.GOV.BCB.PIX2561qrcodespix.sejaefi.com.br/v2 41e0badf811a4ce6ad8a80b306821fce5204000053000065802BR5905EFISA6008SAOPAULO60070503***61040000"
}

Responses

The responses below represent Success(201) and consumption failures/errors.

{
  "idEnvio": "12453567890123456789",
  "e2eId": "E09089356202011251226APIff82f2e5",
  "valor": "12.31",
  "horario": {
    "solicitacao": "2021-11-25T12:26:42.905Z"
  },
  "status":"EM_PROCESSAMENTO"
}

Last updated on