Integration with Automatic Pix API
This guide walks you through the process of integrating and managing Automatic Pix payments.
Overview
The integration flow for Automatic Pix payments involves the following key steps:
- Create a Consent: Obtain customer authorization for recurring payments.
- Authorize Consent: Redirect the customer to their financial institution for consent approval.
- Charge your customers: Schedule or retry a payment.
- Cancel Operations: Cancel a single payment or cancel payments based on the authorized consent.
Start integrating Klavi Automatic Pix payment
Initiate an Automatic Pix payment by creating a consent via the Klavi's API. This request defines the payer, recipient account, recurrence and payment detail.
Curl request example:
POST /payment/customer/v1/automatic/consents HTTP/1.1
Host: https://api-sandbox.klavi.ai
Content-Type: application/json
Authorization: Bearer <your-access-token>
{
"clientRequestId": "fcb72e3a-b346-4f71-b044-dsndsnmnkdsmk",
"institutionId": "c8f0bf49-4744-4933-8960-7add6e590841",
"customer": {
"identifierType": "CPF",
"identifier": "76109277673",
"name": "João Silva"
},
"redirectURL": "https://your-platform.com/callback",
"additionalInformation": "Consent description",
"creditorAccount": {
"ispb": "00000000",
"issuer": "0001",
"number": "324223",
"accountType": "CACC",
"holder": {
"identifier": "76109277673",
"name": "John Doe",
"identifierType": "CPF"
}
},
"paymentMethodConfig": {
"contractId": "EX123456123456",
"minimumVariableAmount": "80.01",
"maximumVariableAmount": "100.01",
"currency": "BRL",
"interval": "MONTHLY",
"referenceStartDate": "2025-06-01",
"contractDebtor": {
"identifierType": "CPF",
"identifier": "76109277673",
"name": "João da Silva"
},
"isRetryAccepted": true,
"firstPayment": {
"remittanceInformation": "First payment description",
"date": "2025-05-15",
"amount": "3000.02",
"currency": "BRL"
}
},
"clientMetadata": {
"platform": "APP",
"os": "LINUX",
"osVersion": "N/A"
}
}Response example:
HTTP/1.1 201 Created
Content-Type: application/json
{
"id": "fcb72e3a-b346-4f71-b044-971dc23232c9",
"clientRequestId": "fcb72e3a-b346-4f71-b044-dsndsnmnkdsmk",
"status": "CONSENT_AWAITING_AUTHORIZATION",
"consentRedirectURL": "https://server.example.com/cb"
}Key Field Specifications
- Amount Limits:
- Fixed Amount: Each recurring payment uses the same amount.
- Variable Amount: The amount can vary per payment, constrained by minimumVariableAmount and maximumVariableAmount.
- The first payment is not subject to these amount limits.
- Reference Start Date (referenceStartDate):
- Must not be the same day as the firstPayment.date.
- Must be at least D+1 after the firstPayment.date.
- Must be set to at least D+2 days after the consent is created.
Redirect User to Institution
After creating the consent, use the consentRedirectURL from the response to redirect the customer to their financial institution's authorization page.
Authorization Callback
After the customer authorizes the consent at their institution, they are redirected back to Klavi. Klavi will then update the consent status and automatically create the first payment if applicable.
First Payment Handling
The first payment is scheduled automatically upon successful authorization. You will receive webhook events to track its lifecycle:
- payment_creation: Triggered when the first payment is created.
- payment_status_update: Triggered for subsequent status changes.
Webhook Event Example (payment_creation):
{
"appId": "12345678",
"eventId": "1495468585434-0e73d1719173766fe4dfe1a8",
"eventType": "api",
"eventName": "payment_creation",
"eventTime": "2021-05-21T08:30:00Z",
"payload": {
"id": "cfa45795-fe16-48e2-a372-130e30a72606",
"consentId": "cfa45795-fe16-48e2-a372-130e30a72606",
"clientRequestId": "1a3s2aebe29s2",
"paymentMethod": "AUTOMATIC_PIX",
"amount": "1333.00",
"currency": "BRL",
"firstPayment": true,
"status": "PAYMENT_PENDING",
"statusReason": {
"code": "NAO_INFORMADO",
"message": "Erro não informado na iniciadora ou detentora de conta."
},
"statusUpdateAt": "2022-09-23T03:39:43Z"
}
}Webhook Event Example (payment_status_update):
{
"appId": "12345678",
"eventId": "1495468585434-0e73d1719173766fe4dfe1a8",
"eventType": "api",
"eventName": "consent_status_update",
"eventTime": "2021-05-21T08:30:00Z",
"payload": {
"id": "cfa45795-fe16-48e2-a372-130e30a72606",
"clientRequestId": "1a3s2aebe29s2",
"status": "CANCELED",
"paymentMethod": "AUTOMATIC_PIX",
"statusUpdateAt": "2022-09-23T03:39:43Z",
"statusReason": {
"code": "NAO_INFORMADO",
"message": "Erro não informado na iniciadora ou detentora de conta."
}
}
}Final Redirect
Finally, the user is redirected back to your redirectURL (for API integration). And the user is redirected back to the whitelabel(for Whitelabel integration).
Key Concepts - Original Payment
The first payment attempt within a billing cycle is called the Original Payment.
Typically, the first payment you successfully schedule for a cycle is the Original Payment. However, you must re-create the Original Payment in the following scenarios:
- The original payment status is ERROR or CANCELED.
- The original payment status is PAYMENT_REJECTED, and the statusReason.code is one of the following:
- INVALID_ATTEMPT_DETAIL
- INVALID_VALUE
- DIFFERENT_PAYMENT_CONSENT
In the following error scenario, neither re-creating the original payment nor retrying the payment is allowed: The original payment status is PAYMENT_REJECTED, and the statusReason.code is INFRASTRUCTURE_HOLDER_FAILURE or TRANSACTION_CONSENT_VALUE_LIMIT_EXCEEDED. We recommend that you contact the customer and charge them in some other way.
Schedule an Original Payment
To charge your customer, schedule a payment 2-10 days before the intended charge date.
Request Example:
POST /payment/customer/v1/automatic/consents/{consentId}/payments HTTP/1.1
Host: https://api-sandbox.klavi.ai
Content-Type: application/json
Authorization: Bearer <your-access-token>
{
"clientRequestId": "41820a0-34372-dsdsds",
"date": "2023-01-23",
"amount": "1333.04",
"currency": "BRL",
"remittanceInformation": "Charging description",
"autoRetryStrategy":
{
"skipWeekend": false,
"days": [1,2,3]
}
}Response Example:
HTTP/1.1 201 Created
Content-Type: application/json
{
"id": "fcb72e3a-b346-4f71-b044-971dc23232c9",
"clientRequestId": "fcb72e3a-b346-4f71-b044-dsndsnmnkdsmk",
"amount": "1333.04",
"currency": "BRL",
"status": "PAYMENT_PENDING"
}Note:
- The scheduled date must align with the consent's interval and expiration.
- If the status is UNKNOWN, poll the payment status until it is updated.
- If the cycle date falls on a non-existent day, the first existing previous day should be considered as the cycle date. For a monthly payment with referenceStartDate set to 2025-12-31, for example: 1st payment cycle: from 2025-12-31 to 2026-01-30 2nd payment cycle: from 2026-01-31 to 2026-02-27 3rd payment cycle: from 2026-02-28 to 2026-03-30
Retry a Payment
Scheduled Automatic Pix payments may fail for various reasons, including insufficient balance, infrastructure issue, or other system unavailability. If you specify autoRetryStrategy in the request of the Create a payment endpoint, we will automatically execute your retry strategy. If you do not specify autoRetryStrategy, no automatic retry will be performed.We recommend implementing a retry mechanism to ensure robust payment processing and minimize manual intervention.
1. Identify a Failed Payment:
- Check for a payment_status_update event with status PAYMENT_REJECTED. A retry attempt is needed if the failure scenario does not require re-creating the original payment.
- Check for a payment_retry event, which indicates the payment(The ID is payload.id) has failed, and a intraday retry attempt(The ID is payload.retryPaymentId) has been created by Klavi. You need to save this kind of payment.
- Call the Get a payment endpoint to sync the payment.
Webhook Event Example (payment_retry):
{
"appId": "12345678",
"eventId": "1495468585434-0e73d1719173766fe4dfe1a8",
"eventType": "api",
"eventName": "payment_retry",
"eventTime": "2021-05-21T08:30:00Z",
"payload": {
"id": "cfa45795-fe16-48e2-a372-130e30a72606",
"clientRequestId": "1a3s2aebe29s2",
"originalPaymentId": "cfa45795-fe16-48e2-a372-130e30a72678",
"paymentMethod": "AUTOMATIC_PIX",
"amount": "1333.00",
"currency": "BRL",
"firstPayment": false,
"status": "PAYMENT_REJECTED",
"statusUpdateAt": "2022-09-23T03:39:43Z",
"statusReason": {
"code": "NAO_INFORMADO",
"message": "Erro não informado na iniciadora ou detentora de conta."
},
"retryPaymentId": "cfa45795-fe16-48e2-a372-130e30a72606",
}
}2. Send a Retry Request:
POST /payment/customer/v1/automatic/consents/{consentId}/payments/{originalPaymentId}/retry HTTP/1.1
Host: https://api-sandbox.klavi.ai
Content-Type: application/json
Authorization: Bearer <your-access-token>
{
"clientRequestId": "fcb72e3a-b346-4f71-b044-dsndsnmnkdsmk",
"date": "2025-11-25"
}3. Track the Retry Payment:
Monitor the status via webhook events or the get payment endpoint.
Retry Rules:
- Maximum 3 retry attempts per payment. After 3 retry attempts, payment can be considered as failed.
- Retries must occur within 7 calendar days of original date (5 days for weekly collections)
- Retries must occur until the day immediately preceding the next payment cycle
- Request the retry until 23h58 on the day immediately preceding the new settlement date
- Klavi handles intraday retries by creating new payments and sending payment_retry events
Tips:
If the consent does not set a fixed amount, you may add unpaid values to the next cycle.
Cancel Operations
A pending scheduled payment can be canceled.
Request Example:
POST /payment/customer/v1/automatic/consents/{consentId}/payments/{paymentId}/cancel HTTP/1.1
Host: https://api-sandbox.klavi.ai
Content-Type: application/json
Authorization: Bearer <your-access-token>
{
"cancelledBy": "12345678901",
"identifierType": "CPF"
}A 204 No Content response indicates successful cancellation. Monitor for a payment_status_update event with status CANCELED.
Cancellation Deadlines:
- Payer: Until 23:59 (Brazilian Time) the day before the payment date.
- Merchant: Until 22:00 (Brazilian Time) the day before the payment date.
- Retry Payments: Only the merchant can cancel, until 22:00 (Brazilian Time) the day before the retry date.
Revoke a Consent
To terminate all future payments, revoke the consent.
Request Example:
POST /payment/customer/v1/automatic/consents/{id}/revoke HTTP/1.1
Host: https://api-sandbox.klavi.ai
Content-Type: application/json
Authorization: Bearer <your-access-token>A 204 No Content response indicates successful revocation. You will receive consent_status_update and payment_status_update events.
Note:
The first payment or a payment scheduled for the same day as the revocation cannot be canceled.