PBV4 / FastPIX
  • FastPIX
  • Paybrokers API Docs
Powered by GitBook
On this page
  • What is FastPIX?
  • Step by step to deploy
  • 1) Checkout transaction request
  • Checkout transaction request -> Look Inside Here
  • 2) Webhook callback notification
  • 3) Redirect the final user to merchant website

FastPIX

Last updated 1 year ago

Welcome to PayBrokers, we allow merchants to make transactions quickly, safely and conveniently. This API document explain about FastPIX payment systems.

What is FastPIX?

The FastPIX payment method's main objective is to speed up the final user's payment operation on their website, in a simple and fast way, without the need for the user to be logged in or have a registration before making the payment.

Using a link available on your website, you can open our payment checkout, identifying your logo, which will display the value selector, like this:

On the conclusion of the user's value selection, the checkout will display the QR CODE for payment.

After the confirmation of payment is due by the bank, our checkout will perform the following:

1 – A notification will be sent via webhook with the payer’s registry information (CPF, Full name, Birth date, city, state), an unique user identification hash plus the details of the transaction. With these information you will be able to automatically register this user, save the unique identification’s hash and add the transaction value to the user’s balance.

2- Once we receive confirmation of sending the notification through the webhook sent, we will redirect the final user to your website, passing the payer's unique identification hash as a parameter in the URL, this way it will be possible to identify the user and carry out the appropriate treatments within your website.

We can configure FastPIX checkout to act in two ways, as follows:

• Fixed Value Mode - When opening the payment checkout, the final user can choose the payment amount, using the buttons with pre-determined values ​​or enter the amount manually, after confirming the amount, the QRCode with the amount will be displayed fixed value defined by the user, and the payer cannot change the amount at the time of payment.

• Free Value Mode - When opening the payment checkout, a QRCode with a symbolic value (R$ 1.00) will be displayed, and this value can be changed by the payer at the time of payment. In this mode, before we confirm the payment to you, we will apply some minimum and maximum value validation rules, according to the settings in your registration.

Let's now check the complete process flow.

Step by step to deploy

1) Checkout transaction request

To create a new FastPIX checkout request you will need to send a HTTP POST, using your merchant hash code:

<PBURLAPI>

Production (live stage): https://v4.paybrokers.io/v4/

Sandbox (testing): https://sandbox-v4.paybrokers.io/v4/

Checkout transaction request -> Look Inside Here

POST <PBURLAPI>/fastpix/checkout/reserve/qrcode

Headers

Name
Type
Description

Content-type

string

application/json

merchant-hash*

string

Merchant Hash ID

{ 
      "token": "410fc5a7-20de-45b5-b2b3-3929f1aa4599" 
}
{ 
      "name": "FASTPIX_PAYMENT_GATEWAY_ERROR", 
      "message": "Cannot read properties of undefined (reading 'organization')", 
      "route": "checkout/config", 
      "date": "2023-11-23T16:53:01.815Z" 
}
{
        curl --request POST
        --url https://sandbox-v4.paybrokers.io/v4/fastpix/checkout/reserve/qrcode
        --header 'merchant-hash: 2b1bf7cd-74b5-4f03-bbfd-0861d00e0044'
}

If any data in your request was wrong or something didn't work well, we will response you one of these responses error, like this examples below. 

{
	"name": "FASTPIX_PAYMENT_GATEWAY_ERROR",
	"message": "Cannot read properties of undefined (reading 'organization')",
	"route": "checkout/config",
	"date": "2023-11-24T13:42:43.497Z"
}

In other hand, if your request was created we will return you a message like this example below.

{ 
      "token": "410fc5a7-20de-45b5-b2b3-3929f1aa4599" 
}

Once you have our Token ID, you will open our checkout base URL + Token ID...

Checkout Base URL = https://fastpix.hmg.paybrokers.com.br/

Example: 

<p>Checkout FastPIX<a href="https://fastpix.hmg.paybrokers.com.br/410fc5a7-20de-45b5-b2b3-3929f1aa4599"></a></p>

After that, the checkout will be displayed to the final user who will make the QRCode payment.

Once the final user paid, we will receive a payment confirmation from the banking institution, we will send the webhook notification for you.

2) Webhook callback notification

About our callback notification, you will receive an encoded message in JWT format by POST request in the URL that was informed in the moment of transaction was created (webhook_url).

  • JWT (supported for almost all programming languages)

    • https://jwt.io/

The passphrase to validate the signature is the same password of the token and the result should be a non encoded object that is following bellow.

// Some code
curl --request POST \
  --url 'https://mywebsite.com.br/webhook' \
  --header 'Content-Type: application/json' \
  --data '{"bodyEncrypted":"eyJhbGciOiJIUzI1NiJ9.eyJwaXhfaWQiOiJhMzg5ZTllNS1iYThmLTQxY2MtYWI4Yy1jYWIxYjhhYmMxZDEiLCJ2YWx1ZSI6MSwicGFpZF92YWx1ZSI6MSwicGFpZF9hdCI6IjIwMjMtMDUtMjlUMTk6MDQ6MTUuMDMxWiIsInN0YXR1cyI6IlBBSUQiLCJkZXNjcmlwdGlvbiI6Ik4vQSIsInJlZmVyZW5jZV9pZCI6ImJmMjYyMGUzLWU0NzktNDYwNC1iNWNlLWU2MGQ2Y2Y1NzVlNSJ9.nr_heC1I8hhXIHwwKAoHAhDqTFZTTTRdSifr_uU12AI"}'

'{
  "id": "410fc5a7-20de-45b5-b2b3-3929f1aa4599",
  "pix_id": "410fc5a7-20de-45b5-b2b3-3929f1aa4599",
  "value": 1,
  "paid_value": 1,
  "paid_at": "2023-05-29T19:04:15.031Z",
  "status": "PAID",
  "description": "N/A",
  "reference_id": "410fc5a7-20de-45b5-b2b3-3929f1aa4599",
  "token": "a389e9e5-ba8f-41cc-ab8c-cab1b8abc1d1",
  "pix_type": "FASTPIX",
  "buyer_document": "01020304050",
  "buyer_name": "JHON DOE",
  "buyer_birth_date": "1990-04-23T00:00:00.000Z",
  "buyer_city": "SAO PAULO",
  "buyer_state": "SP",
  "buyer_cellphone": "+5511999887766",
  "buyer_email": "address@email.com"  
}'

Once you received the webhook data, you will be able to automatically register the user, if it does not exist, then you'll save the unique final user identification hash (token field) in your registration and add the transaction value to final user balance.

3) Redirect the final user to merchant website

If the status returned by the POST webhook notification sent by step 2 were 200, the checkout will show a message to final user the payment confirmation.

After that, the final user will be redirected to merchant website, using the base URL merchant + unique final user identification hash, like this:

https://yourmerchanturl.com/auth?token={user-hash}

So, with this unique final user identification hash you must handle session control and accreditation on your website.