Transfer By Pix Key

Suggestion Sequence

This sequence diagram illustrates the flow of a Pix withdrawal request, verification of balance, transfer processing, and the subsequent security checks using webhooks to confirm the status of the transfer.

1. User requests withdrawal:
   The process begins when the user submits a withdrawal request on the website, including the necessary Pix key information.

2. Website checks available balance:
   The website sends a GET /api/v2/accounts/balances/ request to the Pagstar API to verify if the user has sufficient funds to proceed with the withdrawal.

   • If the token is invalid or expired, Pagstar returns a 401 Unauthorized, and the website informs the user that the request failed due to invalid authentication.

3. Handling sufficient/insufficient balance:

   • Sufficient balance:
     If the balance is sufficient, the website proceeds by sending a POST /api/v2/pix/payments/dict request to Pagstar with the transfer details. Pagstar responds with 202 Accepted, indicating that the transfer request has been received but is still being processed. The website informs the user that the transfer request was successfully submitted.
   • Insufficient balance:
     If the balance is insufficient, the website informs the user with a temporary error message, asking them to try again later.

4. Pagstar sends confirmation webhook:
   Once the transfer is processed, Pagstar sends a POST /webhook/transfer-confirmation to notify the website about the status of the transfer. The webhook could indicate one of the following statuses: LIQUIDATED or CANCELED.

5. Security check to prevent fake notifications:
   Upon receiving the webhook, the website performs a security check by querying Pagstar with a GET /api/v2/pix/payments/idempotencyKey/{idempotencyKey} request to verify the actual transfer status, ensuring that the webhook was not falsified.

6. Transfer status:

   • LIQUIDATED:
     If the status returned is LIQUIDATED, the website updates the transfer status to 'LIQUIDATED' and informs the user that the transfer was successfully completed.
   • CANCELED:
     If the status returned is CANCELED, the website updates the transfer status to 'CANCELED' and informs the user that the transfer was canceled.
   • Status different from that received in the webhook:
     If the status returned in the verification differs from the status initially provided in the webhook, the website marks the transfer as suspicious or invalid and informs the user that the transfer failed or was flagged as invalid.

Token Validation

Before making any API requests to Pagstar, the website must ensure that the token used for authentication is valid.

• If the token is invalid or expired, Pagstar will return a 401 Unauthorized response, and the website must handle this by notifying the user that the operation could not be completed due to authentication issues.

Transfer Status

• CANCELED :
  Indicates that there was some failure in processing the transfer, and the request is canceled.
• PROCESSING :
  Indicates that the transfer is still in the process of being sent to the recipient's account.
• LIQUIDATED:
  Indicates that the transfer has been successfully processed and credited to the recipient's account.
• REFUNDED:
  Indicates that the transfer was successfully credited to the recipient's account, but the recipient returned the full amount.
• PARTIALLY_REFUNDED:
  Indicates that the transfer was successfully credited to the recipient's account, but the recipient returned part of the amount.