Receive with PIX

A PIX charge returns a QR code and a copy and paste code. Your customer pays it in any Brazilian banking app. When the payment settles, the net amount is credited to your BRL balance and a callback is sent to your postback URL.

PIX charges need live credentials. Sandbox credentials get HTTP 403.

1. Create the charge

POST /wallet/deposit/payment

{
  "token": "YOUR_TOKEN",
  "secret": "YOUR_SECRET",
  "amount": 10.00,
  "method_pay": "pix",
  "debtor_name": "John Doe",
  "email": "[email protected]",
  "debtor_document_number": "12345678909",
  "phone": "11900000000",
  "postback": "https://example.com/callbacks/pix-in"
}

Field	Required	Description
`token`, `secret`	Yes	Live credentials.
`amount`	Yes	Amount in BRL. Platform minimum and maximum apply.
`method_pay`	Yes	`pix`.
`debtor_name`	Yes	Payer full name.
`email`	Yes	Payer email. Must be a valid address.
`phone`	Yes	Payer phone, digits only.
`debtor_document_number`	Recommended	Payer CPF or CNPJ, digits only. Not enforced by validation, but some PIX acquirers need it to issue the charge.
`postback`	Yes	URL that receives the paid callback.

Response (200)

{
  "idTransaction": "a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "qrcode": "00020126580014br.gov.bcb.pix0136...6304ABCD",
  "qr_code_image_url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
}

idTransaction: store it. It identifies the charge in the callback and in the status endpoint.
qrcode: the copy and paste code. Show it with a copy button.
qr_code_image_url: a data:image/png;base64,... URI or an https URL, depending on the acquirer that serves your account. Use it directly as an <img src>.

Some acquirers add extra fields, for example expirationInSeconds. Ignore fields you do not use.

2. Wait for the payment

When the customer pays, we POST to your postback:

{
  "status": "paid",
  "idTransaction": "a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "typeTransaction": "PIX"
}

paid is the only PIX-IN callback. An unpaid or expired PIX charge sends nothing. See Webhooks for retries and verification.

You can also check the status at any time:

curl https://dominipay.com/api/transactions/payment/a1b2c3d4e5f60718293a4b5c6d7e8f90 \
  -H "token: YOUR_TOKEN" \
  -H "secret: YOUR_SECRET"

{
  "status": "paid",
  "idTransaction": "a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "paymentMethod": "pix",
  "amount": 50.00,
  "taxes": 0.50,
  "liquid": 49.50
}

Possible status values: pending, paid, cancelled. See Transaction status.

Errors

HTTP	When
400	`token` or `secret` missing.
401	Invalid credentials, blocked account, or amount below the platform minimum or above the maximum (message `O depósito mínimo é de R$ ...` or `O depósito máximo é de R$ ...`).
403	Sandbox credentials, or account limited to refunds (`REFUND_ONLY`).
422	Validation error. `errors` lists the messages per field.
500	The PIX acquirer failed. Retry later.

Validation error example:

{
  "status": "error",
  "message": "Erro de validação",
  "errors": {
    "debtor_name": ["Este campo é obrigatório"],
    "email": ["O campo deve ser um email válido"]
  }
}