Issuing Pix charges

Create a Pix charge your customer pays with a QR code, send it, and follow it until it is paid.

What a Pix charge is

A Pix charge is a single-use, dynamic Pix QR code for a fixed amount. It can be paid once, and only for exactly that amount. The money lands in your Jeeves BRL account instantly, 24/7.

There is no boleto behind it, so it never shows up in your customer's DDA. To collect with a boleto instead, see Issuing boletos.

Create a charge

POST /v1/pix-charges (scope pix_charges:write) returns 201 with the charge. amount and payerData are required.

curl -X POST \
  'https://public-sandbox.tryjeeves.com/v1/pix-charges' \
  -H "Authorization: Bearer $JEEVES_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 150.75,
    "memo": "Payment for services",
    "externalId": "INV-789",
    "payerData": {
      "name": "Global Tech",
      "personType": "legal",
      "documentNumber": "12345678000195"
    },
    "metadata": { "internalReference": "INV-789" }
  }'

Field	Notes
`amount`	Required. In BRL, positive, at most 2 decimal places.
`payerData`	Required. Your customer: `name` (1 to 100 characters), `personType` (`natural` or `legal`) and `documentNumber`, a CPF (11 digits) or a CNPJ (14 digits), digits only.
`dueDate`	Optional. `YYYY-MM-DD`, from today to 365 days from today. See Due date and payable period.
`daysPayableAfterDue`	Optional. How many days the QR stays payable after `dueDate`, from 0 to 180. Only with `dueDate`.
`memo`	Optional. A note for the payer, up to 140 characters, shown with the charge.
`externalId`	Optional. Your own reference, up to 64 characters, unique per organization. See Retry safely with `externalId`.
`metadata`	Optional. Your own key-value reference data, with string values.

The response is the charge:

{
  "id": "4c2fa514-a44d-40f2-8d57-c0caf1b9165a",
  "status": "active",
  "externalId": "INV-789",
  "metadata": { "internalReference": "INV-789" },
  "amount": 150.75,
  "dueDate": "2027-01-10",
  "daysPayableAfterDue": 0,
  "payableUntil": "2027-01-10",
  "memo": "Payment for services",
  "payerData": {
    "name": "Global Tech",
    "personType": "legal",
    "documentNumber": "12345678000195"
  },
  "pixCopyPaste": "00020126580014br.gov.bcb.pix0136123e4567-e89b-12d3-a456-426614174000520400005303986540515.075802BR5912Your Company6009SAO PAULO62070503***6304ABCD",
  "qrCodeImage": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBD...",
  "createdAt": "2026-01-10T14:00:00Z",
  "updatedAt": "2026-01-10T14:00:00Z"
}

Send it to your customer

Jeeves does not deliver the charge. Share it through your own channel: email, WhatsApp or your app.

qrCodeImage is a base64-encoded image of the QR code. Show it, or attach it as an image.
pixCopyPaste is the copy-and-paste code. Your customer pastes it into their bank app.

Due date and payable period

Read this before you set a due date. The charge is payable until payableUntil, and that depends on whether you send dueDate.

Without dueDate, the charge is due 365 days from today (Brasília time) and daysPayableAfterDue is 0.
With dueDate (from today to 365 days from today), the QR stays payable for daysPayableAfterDue days after it: from 0 to 180, 180 by default.
payableUntil in the response is the last payable day, until the end of that day in Brasília time. The response always carries the effective dueDate and daysPayableAfterDue, including the defaults.

daysPayableAfterDue can only be sent together with dueDate.

Track it until it's final

There are no webhooks for Pix charges yet. Poll the charge until it reaches a final status, or list charges and filter them:

curl 'https://public-sandbox.tryjeeves.com/v1/pix-charges/4c2fa514-a44d-40f2-8d57-c0caf1b9165a' \
  -H "Authorization: Bearer $JEEVES_ACCESS_TOKEN"

curl 'https://public-sandbox.tryjeeves.com/v1/pix-charges?externalId=INV-789&page=1&pageSize=20' \
  -H "Authorization: Bearer $JEEVES_ACCESS_TOKEN"

GET /v1/pix-charges (scope pix_charges:read) filters by status, createdAt[gte] / createdAt[lte] and externalId, and paginates with page and pageSize.

Status	Meaning
`active`	The charge can be paid. Only active charges can be canceled.
`under_review`	The payer paid, but the bank is holding the funds for a manual review (rare). If the review is rejected, the charge returns to `active`.
`paid`	Paid, and `paymentDetails` is filled in. Final.
`canceled`	You canceled it. Final.
`expired`	Not paid by `payableUntil`. Final. It can be set 1 to 3 days after `payableUntil`.

Cancel

POST /v1/pix-charges/{id}/cancel (scope pix_charges:write) returns 200 with the charge. It returns 409 if the charge isn't active.

curl -X POST \
  'https://public-sandbox.tryjeeves.com/v1/pix-charges/4c2fa514-a44d-40f2-8d57-c0caf1b9165a/cancel' \
  -H "Authorization: Bearer $JEEVES_ACCESS_TOKEN"

A charge can't be changed after it is created. To change the amount or the dates, cancel it and create a new one.

Retry safely with `externalId`

externalId is unique per organization. Create the charge with your own reference, and a retried request never creates a second charge: reusing an externalId returns 409, and errorData.chargeId is the ID of the charge that already exists.

{
  "message": "The externalId is already used by another charge.",
  "statusCode": 409,
  "errorData": { "chargeId": "4c2fa514-a44d-40f2-8d57-c0caf1b9165a" }
}

Errors

HTTP	When	What to do
`400`	The request body is malformed.	Fix the request.
`409`	The `externalId` is already used, or you canceled a charge that isn't `active`.	For a duplicate `externalId`, fetch the existing charge with `errorData.chargeId`.
`422`	The account can't receive Pix charges yet: it has no Pix key.	Contact Jeeves support.
`502`	The Pix provider failed.	Retry with the same `externalId`.

Full schemas and every error: Pix Charges in the API reference.