Intergration 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 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 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 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 ) { "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) 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 recreate the original payment in the following scenarios the previous payment status is error or canceled the previous payment status is payment rejected , and the statusreason code is one of the following invalid attempt detail invalid value different payment consent 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" } 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 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 recreating the original payment check for a payment retry event, which indicates the payment(the id is payload id ) fails, and a intraday retry attempt(the id is payload retrypaymentid ) has beeen created by klavi you'll need to record this kind of payments call the get payment endpoint to get the lastest status 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 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