Skip to main content

PIX Automatic Payments

PIX Automatic is Netvalve's managed recurring billing feature for PIX — Brazil's instant payment platform operated by the Central Bank of Brazil. With a single QR code authorisation from your customer, Netvalve and FacilitaPay handle all subsequent charges automatically on your defined schedule.

Availability

PIX Automatic is available for payments in BRL (Brazilian Real) only. The customer must have a Brazilian bank account enrolled in PIX.

How it works​

  1. Your server creates an order with a recurringSchedule payload, setting paymentOption to apm_pix.
  2. Netvalve creates the subscription and asynchronously generates a dynamic PIX QR code tied to the subscription lifecycle. The QR code is not returned in the create-order response — you retrieve it via the Inquiry API once it is ready.
  3. The customer scans the QR code once in their banking app and authorises the automatic debit. The subscription remains in pending status until this authorisation is completed.
  4. The subscription becomes active after the customer authorises the debit. Subsequent charges occur automatically without any further customer action.
  5. Each automatic charge triggers a webhook notification. You receive events for each payment success, failure, and retry.
  6. The subscription ends when all billing cycles complete, or when cancelled by you or the customer.
Subscription QR code vs one-time PIX QR code

Unlike a one-time dynamic PIX transaction — where the QR code is returned synchronously in the create-order response — a PIX Automatic subscription QR code is generated asynchronously and is tied to the subscription lifecycle. You must poll the Inquiry API to retrieve it once it is ready, then display it for the customer to scan. Do not expect apmPaymentInfo in the initial create-order response for subscriptions.

Subscription lifecycle​

StatusWhat triggers it
pendingSubscription created; QR code is being generated asynchronously. Remains pending until the customer scans the QR code and authorises the automatic debit in their banking app.
activeCustomer scanned the QR code and authorised the automatic debit. Subsequent charges proceed automatically.
canceledCancelled by the merchant, revoked by the payer, or all retry attempts exhausted
completedAll billing cycles have been successfully processed

Retry behaviour​

If a charge fails due to insufficient funds or a temporary issue, Netvalve retries based on your configured failureAttempts setting (0–3 retries). Retries are scheduled every two days. Once all retries are exhausted without a successful payment, the subscription moves to canceled and a webhook notification is sent.

Invoice dates and short months

Invoice dates follow the subscription schedule strictly. If a scheduled date does not exist in a given month (for example, the 31st in February), the system adjusts to the last valid day of that month. The original date resumes in the following month.

This date-adjustment rule applies to MONTHLY, QUARTERLY, SEMESTER, and YEARLY frequencies only.

Prerequisites​

Before going live with PIX Automatic:

  1. Contact the Netvalve team to enable PIX Automatic on your account.
  2. Ensure your MID is configured for BRL and PIX as a payment channel.
  3. Configure a webhook endpoint to receive subscription and payment event notifications — see the Webhook Message guide.
  4. Your startDate must be a future date. The endDate is mandatory and must be at least 7 days after startDate (minimum weekly cycle).

Integration​

PIX Automatic is available via both the Netvalve Hosted Payment Page (HPP) and the direct (merchant-hosted) integration mode.

Step 1 — Create the subscription order​

Send a POST request to the Create Order endpoint. Include a recurringSchedule object alongside the standard alternativePaymentMethod PIX fields.

POST /hpp/order — request body
{
  "amount": 50.00,
  "currency": "BRL",
  "siteId": "f76fb7ed-3312-4791-a216-45918f899271",
  "clientOrderId": "{{clientOrderId}}",
  "orderDesc": "Monthly subscription — Basic Plan",
  "successUrl": "https://merchantsite.com/success.html",
  "cancelUrl": "https://merchantsite.com/cancel.html",
  "failedUrl": "https://merchantsite.com/failed.html",
  "pendingUrl": "https://merchantsite.com/pending.html",
  "paymentOption": "apm_pix",
  "alternativePaymentMethod": {
    "paymentMethod": "pix",
    "userType": "n",
    "documentType": "cpf",
    "documentNumber": "12345678901",
    "socialName": "Pablo Castro",
    "fiscalCountry": "Brasil",
    "payerEmail": "pablo@example.com",
    "payerPhone": "3001234567"
  },
  "recurringSchedule": {
    "subscriptionName": "Basic Plan — Monthly",
    "recurringPeriod": 30,
    "recurringType": "MONTHLY",
    "startDate": "2025-10-01 00:00:00",
    "endDate": "2026-10-01 00:00:00",
    "recurringAmount": 50.00,
    "failureAttempts": 3
  },
  "customerDetails": {
    "customerAddress": "Av. Paulista 1000",
    "customerCity": "São Paulo",
    "customerCountryCode": "BR",
    "customerEmail": "pablo@example.com",
    "customerIp": "123.123.123.123",
    "customerName": "Pablo",
    "customerLastName": "Castro",
    "customerPhone": "+5511999990000",
    "customerState": "SP",
    "customerZipCode": "01310-100"
  }
}
Calculating cycles

The number of billing cycles is derived automatically from your startDate, endDate, and recurringPeriod:

cycles = (endDate − startDate) / recurringPeriod

The result must be a whole number. Adjust your dates or period if the division is fractional.

Step 2 — Redirect the customer​

On a successful response (responseCode: "GTW_1000"), redirect the customer to the redirectUrl. The Netvalve hosted page handles the asynchronous QR code generation and will display the PIX QR code and subscription summary once it is ready for the customer to authorise.

Create Order — success response
{
  "traceID": "98e151b7-fca4-4e2a-8597-ab58512f2d41",
  "responseTimestamp": "2025-09-09T06:54:38.626+00:00",
  "orderId": 123445,
  "transactionID": "txn-98e151b7",
  "responseCode": "GTW_1000",
  "responseMessage": "Transaction Approved / Request Successful.",
  "orderState": "CREATED",
  "redirectUrl": "https://checkout.uat.sandbox-netvalve.com?paymentToken=eyJ...",
  "midId": "mid-4521",
  "netvalveMidId": "f76fb7ed-3312-4791-a216-45918f899271"
}

To pre-select PIX on the hosted page, append &paymentOption=apm_pix to the redirectUrl.

Step 3 — Handle the redirect outcome​

After the customer authorises (or abandons) the subscription, Netvalve redirects them to one of the URLs you provided:

OutcomeRedirect target
QR code scanned and debit authorisedsuccessUrl
Customer cancelledcancelUrl
Authorisation failedfailedUrl
QR code generated but customer has not yet scanned or authorisedpendingUrl

Step 4 — Receive webhooks​

Netvalve sends a server-to-server webhook notification for:

  • QR code ready for scanning
  • Each subsequent automatic charge (success or failure)
  • Subscription status changes (active, canceled, completed)

Contact the Netvalve team to register your webhook endpoint. See the Webhook Message guide for the full payload schema.

recurringSchedule field reference​

FieldTypeRequiredDescription
subscriptionNamestringYesA human-readable label for this subscription. Shown in the Netvalve backoffice.
recurringPeriodintegerYesThe interval between charges in days. Must align with recurringType.
recurringTypestringYesBilling frequency. Allowed values: WEEKLY, MONTHLY, QUARTERLY, SEMESTER, YEARLY. DAILY is not supported for PIX.
startDatestringYesFirst charge date in YYYY-MM-DD HH:mm:ss format. Must be a future date.
endDatestringYesFinal charge date. Must be at least 7 days after startDate. (endDate − startDate) / recurringPeriod must be a whole number.
recurringAmountdecimalYesAmount charged on each billing cycle (e.g. 50.00). Must have exactly 2 decimal places.
failureAttemptsintegerNoNumber of retry attempts after a failed charge. Range: 0–3. Defaults to 0. Retries are scheduled every 2 days.

alternativePaymentMethod field reference (PIX)​

FieldTypeRequiredDescription
paymentMethodstringYesAlways "pix" for PIX payments.
userTypestringYes"n" for a natural person (individual), "j" for a juridical person (company).
documentTypestringYes"cpf" for individuals, "cnpj" for companies.
documentNumberstringYesBrazilian tax ID — 11 digits for CPF, 14 digits for CNPJ. Digits only.
socialNamestringYesCustomer's full legal name as registered with their bank.
fiscalCountrystringYesAlways "Brasil".
payerEmailstringYesCustomer's email address for payment notifications.
payerPhonestringYesCustomer's phone number. Brazilian format (e.g. "11999990000").

Validations​

Netvalve applies the following validations before forwarding the subscription to FacilitaPay. Requests that fail these checks return a 4xx error with a descriptive message.

RuleDetails
startDate must be in the futureThe subscription start date must be after the current date and time.
endDate is mandatorySubscriptions without an end date are not accepted for PIX.
Minimum duration of 7 daysendDate − startDate must be at least 7 days (one weekly cycle).
Whole-number cycle count(endDate − startDate) / recurringPeriod must divide evenly.
DAILY frequency not supportedUse WEEKLY as the shortest interval.
Currency must be BRLPIX Automatic only supports Brazilian Real.
Valid Brazilian document numberCPF must be 11 digits; CNPJ must be 14 digits.
failureAttempts rangeMust be between 0 and 3 inclusive.

Cancelling a subscription​

You can cancel an active subscription from the Netvalve backoffice (Subscriptions menu) or via the Subscription API.

Cancel subscription — API
POST /subscriptions/{subscriptionId}/cancel
note

Customers can also revoke the automatic debit authorisation directly in their banking app. Netvalve will automatically update the subscription status to canceled.

Exception handling​

Pending response​

A responseCode of GTW_1002 with responseCodeType: "PENDING" is returned in two distinct situations for PIX Automatic subscriptions:

1 — QR code not yet generated (immediately after create-order)

The subscription has been created but the QR code is still being generated asynchronously. Poll the Inquiry API until apmPaymentInfo appears in the response, then display the QR code to the customer.

2 — QR code generated but not yet scanned

The QR code is available in apmPaymentInfo but the customer has not yet scanned it. Continue polling (or rely on the incoming webhook) until the subscription transitions to active.

Pending response — QR code not yet ready
{
  "traceID": "965c2c75-b29d-41fc-aa3a-6d40b9f3fbb0",
  "responseTimestamp": "2024-04-25T13:48:49.959+00:00",
  "transactionID": 22,
  "responseCode": "GTW_1002",
  "responseMessage": "Transaction status is Pending.",
  "responseCodeType": "PENDING"
}
Polling rate limits

Poll the Inquiry API no more than once every 5 seconds. Excessive polling may result in rate limiting. For production integrations, prefer webhooks over polling.

Expired QR code​

If the customer does not scan the QR code before qrCodeExpiry, the order expires. Create a new order to generate a fresh QR code. Do not reuse the old clientOrderId — use a new unique identifier.

All retries exhausted​

When all configured retry attempts fail, the subscription is automatically cancelled.​

ResourceLink
PIX one-time paymentPIX Integration
Hosted Payment Page guideHosted Payment Page
Subscription management APIAPI Reference
Webhook eventsWebhook Message
Error codesError Codes
Inquiry APIInquiry API