CheckoutPayment MethodsPayment MethodsPix Payments

How To: Implement Pix Payments

Developers can learn how to implement pix pay-ins.

Overview

Merchants can accept payments via Brazilian PIX accounts. With PIX pay-ins merchants can display the purchase amount in Brazilian Real, and end-users can complete their payments directly with their PIX account. This reduces any currency conversion confusion, and gives end-users more transparency and trust in how much the total cost of a purchase will be. Upon a successful payment, Merchants receive funds at their chosen settlement location.

Demo

👍 Try making a purchase with PIX yourself on our demo app!

How It Works

  1. Merchant defines their revenue settlement location.
  2. Merchant fetches a quote for how much a purchase will be including all fees associated with the transaction.
  3. Merchant displays purchase amount in BRL to end-user.
  4. Merchant calls Pix Payment Order endpoint and displays QR code to end-user.
  5. End-user scans QR with mobile device to complete purchase.
  6. End-user receives push notification or email that their payment has been completed.
  7. Merchant sees BRL payment in merchant dashboard.
  8. Merchant receives the settlement amount at their defined settlement location.

API Implementation

  1. Create a Pix Payment Order.
  • Note: Ensure the subtotal passed here is the purchase value in USD.
1curl --location 'https://api-sandbox.coinflow.cash/api/checkout/pix/order/<YOUR_MERCHANT_ID>' \
2--header 'accept: application/json' \
3--header 'content-type: application/json' \
4--header 'x-coinflow-auth-session-key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjdXN0b21lcklkIjoidGVzdDEyMyIsIm1lcmNoYW50SWQiOiJ0ZXN0dGVzdCIsImlhdCI6MTcyOTc4OTU3NiwiZXhwIjoxNzI5ODc1OTc2fQ.HvCOrraNCZjnsYQ1Cm96QkXRm-2GqVW-y_VXLMJcjTU' \
5--data-raw '
6{
7  "subtotal": {
8    "cents": 100 // Purchase amount in USD
9  },
10  "email": "dwaynejohnson@therock.com"
11}
12'
13
14
15// Response
16{
17    "brCode": "00020126840014br.gov.bcb.pix01366f313eaf-3fd9-48d9-958f-4a4f3567752f0208Purchase52040000530398654045.005802BR5917Brla Digital Ltda6009Sao Paulo6223051900001IP2U2OKGTu8hHH6304B7FB",
18    "paymentId": "6f313eaf-3fd9-48d9-958f-4a4f3567752f",
19    "quote": {
20        "cents": 547,
21        "currency": "BRL"
22    }
23}
  1. Pass the brCode returned from Step 1 into a QR code scanner and display the QR code to the end-user.
  • Note: You may use any qr code generating library. For example purposes, we are using [react-qr-code](https://www.npmjs.com/package/react-qr-code).
1import QRCode from "react-qr-code";
2
3function App() {
4  return (
5    <div>
6      <QRCode value="00020126840014br.gov.bcb.pix01366f313eaf-3fd9-48d9-958f-4a4f3567752f0208Purchase52040000530398654045.005802BR5917Brla Digital Ltda6009Sao Paulo6223051900001IP2U2OKGTu8hHH6304B7FB" />
7    </div> 
8  );
9}
10
11export default App;
  1. Listen for Settled purchase events.
Example Settled purchase event.
Example Settled purchase event.
  1. See payment record on merchant dashboard.
  • Note: Purchase amount will display in USD on the merchant dashboard.
Example of payment record on merchant dashboard.
Example of payment record on merchant dashboard.

🚧 In sandbox, the payment autocompletes itself after 5 seconds and the webhook gets sent.

There currently is no way to mock sandbox payments in the PIX system.

📘 Pix Payment Window

Once a QR code is generated, customers have 5 minutes to complete the payment. This time limit ensures that foreign exchange (FX) rates remain accurate, preventing potential discrepancies that could arise if the payment is made days or weeks after the quote is issued. If the QR code has expired, the purchase status will display as Expired.