Suggestion Sequence

This sequence diagram outlines the steps involved in generating a Pix QRCode, handling the payment, and verifying the payment status through a secure process. It also includes error handling and verification mechanisms to ensure the authenticity of payment notifications.

User requests to generate Pix QRCode:
The user initiates a request on the website to generate a Pix QRCode for a payment.
Website sends payment details to Pagstar:
The website sends a POST /cob request to the Pagstar API with the payment details to generate the QRCode.
Handling QRCode generation:
- QRCode generation succeeds:
  If the QRCode is successfully generated, Pagstar responds with a 200 OK along with the QRCode payload. The website displays the generated QRCode to the user for payment.
- QRCode generation fails:
  If the generation fails, Pagstar returns a 400 Bad Request error. The website then displays an error message to the user.
User interaction with the Pix QRCode:
- User does not pay:
  If the user does not complete the payment, the website times out and notifies the user that the payment was not completed.
- User completes the payment:
  If the user successfully makes the payment, Pagstar sends a POST /webhook/pix-payment notification to the website, containing the payment details.
Security check to prevent fake notifications:
We use dynamic IPs to send our webhooks, meaning that the IP addresses may change with each sending. Upon receiving the payment webhook, the website performs a security check by querying Pagstar's API with a GET /cob/{txid} request to verify the status of the payment.
Payment status verification:
- Status is CONCLUIDA:
  If the payment status is CONCLUIDA (completed), the website updates the payment status to 'APPROVED' and informs the user that the payment was successfully approved.
- Status is REMOVIDA_PELO_PSP:
  If the payment status is REMOVIDA_PELO_PSP (removed by the payment service provider), the website updates the payment status to 'CANCELED' and notifies the user that the payment was canceled.
- Other status or suspicious activity:
  If the status does not match these valid statuses or is considered suspicious, the website marks the payment as invalid or suspicious and informs the user that the payment failed or is invalid.

Token Validation

Before initiating any request to Pagstar, the website must validate the authentication token. If the token is invalid or expired, Pagstar returns a 401 Unauthorized, and the website handles this by notifying the user of the authentication failure.

Important: Only 10 requests per minute are accepted, otherwise null will be returned.

Qrcode Status

ATIVA:
Indicates that the record refers to a charge that has been generated but has not yet been paid or removed.
CONCLUIDA :
Indicates that the record refers to a charge that has already been paid and, therefore, cannot accept another payment.
REMOVIDA_PELO_USUARIO_RECEBEDOR:
Indicates that the receiving user has requested the removal of the charge record.
REMOVIDA_PELO_PSP :
Indicates that the Receiving PSP (Payment Service Provider) has requested the removal of the charge record.

Recommendations for the Checkout or Payment Screen

Displaying the QR Code
- Use the pixCopiaECola field to display the QR Code on the front-end. This can be done by converting its content into a QR image or directly showing the code in the Pix Copy and Paste format.
Pix Copy and Paste Option
- Provide a dedicated text area for users to copy the Pix code easily (using the pixCopiaECola value).
- Include a "Copy Code" button to simplify the process.
Countdown Timer
- Show a countdown timer based on the expire_at field to inform users of the remaining time to complete the payment.
Payment Tracking
- After displaying the QR Code, wait for the payment notification sent by the bank or PSP (Payment Service Provider) to your back-end system.
- Automatically update the order status once the payment is confirmed.
Handling Expired Payments
- If the payment is not confirmed before the QR Code expires, display a clear message to the user indicating that the code is no longer valid.
- Provide an option to generate a new QR Code to retry the payment.
Error Handling
- If an issue occurs while generating the QR Code, notify the user with a friendly message.
- Suggest retrying or selecting an alternative payment method.