Integration with Smart Pix API

4 min

This guide walks you through the process of integrating and managing Smart Pix payments.

Overview

The integration flow for Smart 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.

Create Payment: Create a payment.

Cancel Operations: Cancel a single payment or cancel payments based on the authorized consent.

Start integrating Klavi Automatic Pix payment

Initiate an Smart 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/smart/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": "João Silva",
            "identifierType": "CPF"
        }
    },
    "paymentMethodConfig": {
        "totalAllowedAmount": "50000.00",
        "transactionLimit": "300.00",
        "periodicLimits": {
            "day": {
                "quantityLimit": 2,
                "transactionLimit": "200.00"
            },
            "month": {
                "quantityLimit": 30,
                "transactionLimit": "3000.00"
            },
            "week": {
                "quantityLimit": 7,
                "transactionLimit": "700.00"
            },
            "year": {
                "quantityLimit": 365,
                "transactionLimit": "36500.00"
            }
        },
        "startDateTime": "2026-10-29T08:30:00Z"
    },
    "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"
}

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.

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).

Create a Payment

Create a payment; the payment will be executed immediately.

Request Example:

POST /payment/customer/v1/smart/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",
    "amount": "1333.04",
    "currency": "BRL",
    "paymentMethodConfig": {
        "riskSignals": {
            "automatic": {
                "lastLoginDateTime": "2026-11-04T10:27:33.853Z"
            }
        }
    }
    "remittanceInformation": "Charging description"
}

Tips:

The quantity of payments created and the payment amount must satisfy the constraints in the consent.

You can specify the CreditorAccount(Comply with the business rules of Open Finance Smart Transfer.) in the payment request.

To terminate all future payments, revoke the consent.

Request Example:

POST /payment/customer/v1/smart/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.

Integration with Smart Pix API

Overview

Start integrating Klavi Automatic Pix payment

Step 1: Create a consent

Step 2: Authorize Consent

Redirect User to Institution

Authorization Callback

Final Redirect

Step 3: Create a payment

Create a Payment

Cancel Operations

Revoke a Consent