---
title: Integration with Smart Pix API
slug: payment/integration-with-smart-pix-api
createdAt: 2025-11-29T02:49:48.857Z
---

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:

1. **Create a Consent:** Obtain customer authorization for recurring payments.
2. **Authorize Consent:** Redirect the customer to their financial institution for consent approval.
3. **Create Payment:** Create 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 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:

```curl
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:

```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"
}
```
:::

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

### 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).&#x20;
:::

:::ExpandableHeading{isOpen="true"}
## Step 3: Create a payment

### Create a Payment

Create a payment; the payment will be executed immediately.

**Request Example:**

```none
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"
}
```
:::

:::hint{type="info" indent="1"}
**Tips:**

1. The quantity of payments created and the payment amount must satisfy the constraints in the consent.
2. &#x20;You can specify the CreditorAccount(Comply with the business rules of Open Finance Smart Transfer.) in the payment request.
:::

:::ExpandableHeading{isOpen="true"}
## Cancel Operations

### Revoke a Consent

To terminate all future payments, revoke the consent.

**Request Example:**

```none
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.&#x20;
:::