API Reference

Simulating PIX Transaction States

After creating a PIX transaction (be it cash in or cash out) it is crucial to simulate their transition to final states. These transitions trigger webhook calls and allow you to properly test the assynchronous event calls.

If you are not familiar with our webhook approach for assychronous updates, please refer to the Asynchronous Events Guide.

Next, we present you a set of useful request examples to help you achieve this.

Transaction Completion

Reference Endpoint

  • PUT /sandbox/transactions/complete/{transactionId}

This endpoint allows you to simulate the successful payment of a PIX transaction, by providing the created transactionId. For the examples bellow, consider the transaction id 4494a26c-4f21-400a-bbe7-cbef6ea7c3c3.

🚧

Potential error 404 or 500

When calling the the complete endpoint, you may recieve an Error 404 (Not Found) or 500 (Internal Server Error), this will happen if your environment can't call your webhook URL.
Please make sure to use a valid URL when creating the transaction. If you still don't have one, use the same we provide in the examples.

  • Optional Request Body
    You can provide the basic payer information. For identified requests, this is not mandatory, but if you are using the anonymous PIX, it is. The body object is as follows: 
    {
  "name": "The Payer Name",
  "taxNumber" : "04368535405"
}
  • The Request Response (200 - OK)
{
  "statusCode": "Done",
  "data": {
    "transactionId": "4494a26c-4f21-400a-bbe7-cbef6ea7c3c3",
    "transactionState": "Completed"
  }
}
  • The Webhook Event Payload
{
  "id": "4494a26c-4f21-400a-bbe7-cbef6ea7c3c3",
  "transactionState": "Completed",
  "transactionDate": "2023-08-04T14:45:34.150Z",
  "transactionOrderId": "in-1414870875-158709817091784",
  "transactionOrderDescription": "This is a test order.",
  "transactionReceipt": "https://api.sandbox.pagfast.com/v1/system/e-receipt/4494a26c-4f21-400a-bbe7-cbef6ea7c3c3/receipt.pdf", 
  "transactionReceiptDate": "2023-08-04T14:45:39.047Z",
  "transactionReceiptVoucher": "D6BE9C802C7846029269C485FE23060C",
  "transactionAmount": "50.000000",
  "transactionType": "Credit",
  "transactionPaymentType": "PIX",
  "stateRegisteredDate": "2023-08-04T14:45:34.332Z",
  "stateCompletedDate": "2023-08-04T14:45:39.150Z",
  "stateCancelledDate": null,
  "stateRefundDate": null,
  "stateReversedDate": null,
  "stateErrorDate": null,
  "stateErrorCause": null,
  "webhookUrl": "https://postman-echo.com/post?test=1",
  "payer": {
    "name": "CRISTINA INACIO OLIVEIRA DA CONCEICAO",
    "taxNumber": "14435549603",
    "bankCode": "999",
    "bankName": null,
    "accountAgency": "99999",
    "accountNumber": "99999",
    "accountDigit": "9"
  },
  "recipient": {
    "name": "Pagfast Cobrança e Serviço em Tecnologia Ltda",
    "taxNumber": "46261360000148",
    "bankCode": "999",
    "bankName": "SANDBOX",
    "accountAgency": "99999",
    "accountNumber": "99999",
    "accountDigit": "9"
  }
}

Transaction Error

Reference Endpoint

  • PUT /sandbox/transactions/error/{transactionId}

This endpoint allows you to simulate an error on the payment of a PIX transaction, by providing the created transactionId. For the examples bellow, consider the transaction id 169717bb-65b3-4551-a107-080839ac995e.

  • The Request Response (200 - OK)
{
  "statusCode": "Done",
  "data": {
    "transactionId": "169717bb-65b3-4551-a107-080839ac995e",
    "transactionState": "Error",
    "stateErrorCause": "PaymentProcessingError"
  }
}
  • The Webhook Event Payload
{
  "id": "169717bb-65b3-4551-a107-080839ac995e",
  "transactionState": "Error",
  "transactionDate": "2023-08-04T14:45:34.150Z",
  "transactionOrderId": "in-1414870875-158709817091784",
  "transactionOrderDescription": "This is a test order.",
  "transactionReceipt": null, 
  "transactionReceiptDate": null,
  "transactionReceiptVoucher": null,
  "transactionAmount": "50.000000",
  "transactionType": "Credit",
  "transactionPaymentType": "PIX",
  "stateRegisteredDate": "2023-08-04T14:45:34.332Z",
  "stateCompletedDate": null,
  "stateCancelledDate": null,
  "stateRefundDate": null,
  "stateReversedDate": null,
  "stateErrorDate": "2023-08-04T14:45:39.150Z",
  "stateErrorCause": "PaymentProcessingError",
  "webhookUrl": "https://postman-echo.com/post?test=1",
  "payer": null,
  "recipient": null,
}

Transaction Cancel

Reference Endpoint

  • PUT /sandbox/transactions/cancel/{transactionId}

This endpoint allows you to cancel a PIX transaction, by providing the transactionId. For the example bellow, consider the transaction id 169717bb-65b3-4551-a107-080839ac995e.

  • The Request Response (200 - OK)
{
  "statusCode": "Done",
  "data": {
    "transactionId": "169717bb-65b3-4551-a107-080839ac995e",
    "transactionState": "Cancelled"
  }
}
  • The Webhook Event Payload
{
  "id": "169717bb-65b3-4551-a107-080839ac995e",
  "transactionState": "Cancelled",
  "transactionDate": "2023-08-04T14:45:34.150Z",
  "transactionOrderId": "in-1414870875-158709817091784",
  "transactionOrderDescription": "This is a test order.",
  "transactionReceipt": null, 
  "transactionReceiptDate": null,
  "transactionReceiptVoucher": null,
  "transactionAmount": "50.000000",
  "transactionType": "Credit",
  "transactionPaymentType": "PIX",
  "stateRegisteredDate": "2023-08-04T14:45:34.332Z",
  "stateCompletedDate": null,
  "stateCancelledDate": "2023-08-04T14:45:39.150Z",
  "stateRefundDate": null,
  "stateReversedDate": null,
  "stateErrorDate": null,
  "stateErrorCause": null,
  "webhookUrl": "https://postman-echo.com/post?test=1",
  "payer": null,
  "recipient": null,
}

❗️

About reusing transactions

Note that the Sandbox environment will not allow changes on the final state of transactions. For example, if you made a transaction Complete, you can't use the same transactionId for testing the Error endpoint.

Attemps on creating invalid state transictions return a Error 409 - Conflict.