Skip to content

Receiving massive payments

To receive massive payments via Pix in the Paag account, it will be necessary to complete the following 3 steps.

1. Inicial required configurations

2. Requests to our endpoints

3. Receiving our webhooks

Important Notes

1. Inicial required configurations

General setup

First, it is necessary to perform the general configurations described in the setup section. The general setup has two steps:

  • Obtaining an API Token to communicate with our API
  • Setting up a Processor, which will enable operations with the partner banking service

Next, some specific configurations related to receiving massive payments via Pix will be necessary.

Sending a fixed PIX key

It is necessary to send the fixed Pix key that was provided during the contract signing process with Paag. This will allow you to receive payments from your customers directly through this key.

Sending the customer list

It is necessary to send Paag a list of customers with name and CNPJ. This list is important for us to identify the customers when the deposit is made via fixed PIX key. The list should come in the format and be sent in a file clientes.json: 

{
    "merchants" : 
    [{
        "payer_document_number":"77.385.737/0001-02",
        "payer_name":"Client on"
    }, {
        "payer_document_number":"77.825.738/0001-12", 
        "payer_name":"Client two"
    }]
}

For any updates to CNPJ or name, we need to receive a complete new list.

2. Requests to our endpoints

Request a deposit endpoint

The deposits endpoint is the one that will be used to request the QRCode and the copy and paste key for PIX payment. You can use this endpoint as described in the request details following this este link.

Let's take a look at the mandatory fields for the deposits endpoint:

Field name Data type Filter type
amount float Decimal value of the amount being charged (in R$)
merchant_transaction_id string Transaction id on the side of the merchant
payer_name string name of the one being charged
payer_email string Email address for the one being charged
payer_document_number string Document number for the one being charged. Usually CPF for people and CNPJ for companies.

3. Receiving our webhooks

Our webhooks are the way we communicate with your platform. They are triggered for every event related to a transaction and can be enabled or disabled on our platform. Each event can point to a different endpoint on your application. The webhook requests are sent as a POST request with a JSON payload.

Our platform considers a webhook susccessfull if it receives a 2xx status code from your platform on the specified endpoint. When a webhook call fails, we will retry it 3 times with a exponential backoff strategy (10, 100 and 1000 seconds of difference between each retry).

Receive a successfull deposit webhook (capture)

Every time a PIX payment is successfully made, regardless of the origin being QR code, copy and paste, or fixed PIX key, our system will deliver a webhook POST in the following format:

Capture webhook payload de exemplo
{
  "event": "capture",
  "transaction": {
    "created_at": "2022-02-02T21:34:07+0000",
    "document_number": "****067****",
    "e2e_id": "e00500002120220200000048r0xxv9wwww0l",
    "email": "foo.bar@mail.net",
    "error": null,
    "events": [
      {
        "amount": "1.00",
        "created_at": "2022-02-02T21:36:03+0000",
        "event_type": "capture",
        "id": "123-456-789",
        "pix_key_type": null,
        "pix_key_value": null,
        "pix_message": null,
        "qrcode": null,
        "qrcode_image": null,
        "success": true,
        "updated_at": "2022-02-02T21:36:03+0000"
      },
      {
        "amount": "1.00",
        "created_at": "2022-02-02T21:34:07+0000",
        "event_type": "auth",
        "id": "123-456-789",
        "pix_key_type": null,
        "pix_key_value": null,
        "pix_message": null,
        "processor_code": "1",
        "processor_message": "pending",
        "processor_transaction_id": "123-456-789",
        "qrcode": "COPYPASTEPIXCODE",
        "qrcode_image": "data:image/png;base64,123123456546789789",
        "success": true,
        "updated_at": "2022-02-02T21:34:10+0000"
      }
    ],
    "first_name": "Foo",
    "id": "123-456-789",
    "last_name": "Bar",
    "merchant_id": "123-456-789",
    "merchant_transaction_id": "0000001",
    "processor_id": "123-456-789",
    "statement": [
        {
        "acc_info": {
          "acc_number": "1122333",
          "acc_type": "checking",
          "bank_agency": "0001",
          "bank_code": "33333",
          "document": "***067***",
          "ispb": "12312311",
          "name": "Foo Bar"
        },
        "amount": "100.00",
        "created_at": "2022-02-02T17:48:27.000000Z",
        "date": "2022-02-02 17:48:26",
        "e2e_id": "e10573521202202121748r0xxv9anj0l"
      }
    ],
    "transaction_type": "pix",
    "updated_at": "2022-02-02T21:36:03+0000",
    "user_id": "123-456-789"
  }
}

Important Notes

Notice to customers

Customers need to send payments using the CNPJs registered on Paag's side. If a payment cannot be identified, we will go through a manual validation process, which consists of sending the information to you and waiting for a response regarding which customer the money belongs to.

How does Paag identify a customer's payment?

  1. We perform a verification of the paying source, collecting the origin CNPJ.
  2. With the payer's identifier in hand, we search the customer database to verify which customer should receive the amount.
  3. We send the webhook notifying the receipt of the funds.