--- title: Intergration with Automatic Pix API slug: payment/intergration-with-automatic-pix-api docTags: createdAt: 2025-11-29T02:49:48.857Z --- 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: 1. **Create a Consent:** Obtain customer authorization for recurring payments. 2. **Authorize Consent:** Redirect the customer to their financial institution for consent approval. 3. **Charge your customers:** Schedule or retry a payment. 4. **Cancel Operations:** Cancel a single payment or cancel payments based on the authorized consent. # Start integrating Klavi Automatic Pix payment ::::ExpandableHeading{isOpen="true"} ## Step 1: Create a consent 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: ```curl POST /payment/customer/v1/automatic/consents HTTP/1.1 Host: https://api-sandbox.klavi.ai Content-Type: application/json Authorization: Bearer { "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: ```json 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" } ``` :::hint{type="info"} **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. ::: :::: :::ExpandableHeading{isOpen="true"} ## Step 2: Authorize Consent ### 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`**):** ```json { "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`**):** ```json { "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). ::: ::::ExpandableHeading{isOpen="true"} ## Step 3: Charge your customers ### 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:** ```none POST /payment/customer/v1/automatic/consents/{consentId}/payments HTTP/1.1 Host: https://api-sandbox.klavi.ai Content-Type: application/json Authorization: Bearer { "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:** ```none 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" } ``` :::hint{type="info"} **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):** ```json { "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:** ```none 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 { "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. :::hint{type="info"} **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 ::: :::: :::hint{type="info" indent="1"} **Tips:** If the consent does not set a fixed amount, you may add unpaid values to the next cycle. ::: ::::ExpandableHeading{isOpen="true"} ## Cancel Operations ### Cancel Operations A pending scheduled payment can be canceled. **Request Example:** ```none 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 { "cancelledBy": "12345678901", "identifierType": "CPF" } ``` A `204 No Content` response indicates successful cancellation. Monitor for a `payment_status_update` event with status `CANCELED`. :::hint{type="info"} **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:** ```none POST /payment/customer/v1/automatic/consents/{id}/revoke HTTP/1.1 Host: https://api-sandbox.klavi.ai Content-Type: application/json Authorization: Bearer ``` A `204 No Content` response indicates successful revocation. You will receive `consent_status_update` and `payment_status_update` events. :::hint{type="info"} **Note:** The first payment or a payment scheduled for the same day as the revocation cannot be canceled. ::: ::::