Checkout

With PagaSul, you can accept payments by redirecting customers to our hosted checkout page. Your server creates a payment request, receives a checkout URL, and sends the customer there.

Here is a step-by-step description of the payment processing flow with the checkout.

How to integrate

1. Create a pay-in

Send a POST request to /v2/pay-in. Include a signature in the header.

curl -X POST https://api.pagasul.com/v2/pay-in \
  -H "Content-Type: application/json" \
  -H "signature: <calculated>" \
  -d '{
    "client_id": 123,
    "client_payment_id": "order_42",
    "amount": 150.00,
    "currency": "BRL",
    "payer": {
      "id": "user_1234"
    },
    "payment_options": {
      "callback_url": "https://your-site.com/webhook",
      "return_url": "https://your-site.com/thank-you"
    }
  }'

client_payment_id must be unique per payment in your system — it is used for idempotency.

To preselect a payment method, pass payment_method (e.g. "BR.PIX"). Without it, the customer chooses on the checkout page. See Payment Methods for available codes and any additional required fields per method.

For the full parameter list, see Create pay-in in the API Reference.

2. Redirect the customer

A successful request returns a 200 response with status: "redirect" and a checkout URL:

{
  "payment_id": 246001234,
  "status": "redirect",
  "checkout_data": {
    "method": "GET",
    "url": "https://checkout.pagasul.com/pay?..."
  }
}

Redirect the customer to checkout_data.url using the HTTP method in checkout_data.method. Store the payment_id — you'll need it to correlate callbacks.

For the full response structure, see Response.

3. Handle the callback

When the payment is completed, PagaSul sends a POST to your callback_url. Verify the signature in the header, then check the status field:

Status	Meaning	Action
success	Payment completed	Fulfil the order
decline	Payment declined	Notify the customer
failed	Processing error	Contact PagaSul support

For all statuses and result codes, see Statuses & Codes. For the full callback structure, see Callbacks.

4. Return the customer

After checkout, PagaSul redirects the customer to your return_url. Use it to display a confirmation page. Do not use this redirect to determine payment outcome — use the callback for that.