Integration with instant API

7 min

API invocation method

Request URI

The request URI consists of the following parts:

{URI-scheme}://{Host}/{resource-path}?{query-string}

Parameter description in URI:

Parameter	Description
URI-scheme	All APIs use HTTPS protocol, only support https.
Host	Different environments have different host: Sandbox environment: api-sandbox.klavi.ai Testing environment: api-testing.klavi.ai Production environment: api.klavi.ai
resource-path	Resource path, i.e. API access path. APIs with different functions have different resource paths. For example:The resource-path of the product API is payment/customer/v1/auth. The resource-path of the
query-string	Query parameters are optional. Not every API has query parameters. Query parameters need to be preceded by a "?", The form is parameter_name=parameter_value. For example, ?limit=10, which means no more than 10 pieces of data can be queried.

CAUTION

Different environments have different host, only after the successful integration test in the sandbox environment can it be integrated in the production environment.

Sandbox environment: api-sandbox.klavi.ai/payment/customer/v1/auth

Testing environment: api-testing.klavi.ai/payment/customer/v1/auth

Production environment: api.klavi.ai/payment/customer/v1/auth

The credentials of the production environment is different from the sandbox environment, please reach out to us at [email protected].

Request method

Supported HTTP request methods: POST and GET.

For GET method, only content type: application/x-www-form-url encoded protocol format is supported

For POST method, only content type: application/JSON is supported at present

Character encoding

UTF-8 coding.

Start integrating Klavi instant payment

Before request the Klavi payment API, you must first obtain a JWT bearer token by request the auth, once you have a JWT bearer token you can submit requests on protected APIs like participants and payments.

Curl request example:

curl --location --request POST 'https://api-sandbox.klavi.ai/payment/customer/v1/auth' \
--header 'Content-Type: application/json' \
--data-raw '{
    "accessKey": "k0l1l2v3i4",
    "secretKey": "TtMdrH&a8Mjd9FyULnFs*#dypaX15%qpXtXQt2n$"
}'

Response example:

{
	"accessToken": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJwYXlsbLWdhdGV3YXkifQ.2dvWMBcU87IeX4J7S1_bx1uKHsXAvSDaK0RdV9xq3-OSrLA",
    "expireAt": 1752053847
}

Refer: Authenticate initiation

Now that you have an access token, you can display the list of account providers participating in Open Finance to users. After the user selects his account holding institution, all you need to do is save the id for later use on the payments API.

Curl request example:

curl -L -X GET 'https://api-sandbox.klavi.ai/payment/customer/v1/institutions' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer 6IkpXVCJ9.eyJwYWdhdGV3YXkifQ.FKX8rT3jIFfeOLYTgTrzlSbOjMIMPAZipkH4VdhL-NB'

Response example:

[
	{
		"id": "81bada34-a509-43d6-9ac3-23f95b066411",
		"name": "Mock bank 1",
		"avatar": "https://example.server.com/mockbank1.svg",
		"description": "Mock Sandbox 1",
		"businessType": "PJ",
		"automaticPix": {
        	"outage": false,
        	"outageReason": "it is outage"
        },
        "instantPix": {
        	"outage": false,
        	"outageReason": "it is outage"
        },
		'parentOrganizationName': 'TestTest001',
        'parentOrganizationId': '1234124',
        'organizationName': 'test001',
        'organizationId': '56789'
	},
	{
		"id": "81bada34-a509-43d6-9ac3-23f95b066411",
		"name": "Mock bank 2",
		"avatar": "https://example.server.com/mockbank2.svg",
		"description": "Mock Sandbox 2",
		"businessType": "PJ",
		"automaticPix": {
        	"outage": false,
        	"outageReason": "it is outage"
        },
        "instantPix": {
        	"outage": false,
        	"outageReason": "it is outage"
        },
		'parentOrganizationName': 'TestTest001',
        'parentOrganizationId': '1234124',
        'organizationName': 'test001',
        'organizationId': '56789'
	}
]

Refer: List participants

Now that you have a JWT access token and the participantId that the end-user selected, it's time to show the checkout and to get the user confirmation on the payment transaction. Once confirmed, you need to send the payload of the payment to be enqueued and then processed. The example below displays the minimum payload information required:

curl --location --request POST 'https://api-sandbox.klavi.ai/payment/customer/v1/instant/payments' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer 6IkpXVCJ9.eyJwYWdhdGV3YXkifQ.FKX8rT3jIFfeOLYTgTrzlSbOjMIMPAZipkH4VdhL-NB ' \
--data-raw '{
    "institutionId": "c8f0bf49-4744-4933-8960-7add6e590841",
    "clientRequestId": "1",
    "customer":
    {
        "identifierType": "CPF",
        "identifier": "12345678901",
        "name": "Klavi Test"
    },
    "date": "2025-07-01",
    "initType": "PIX_INIC",
    "proxy": "12345678901",
    "amount": "1333.00",
    "currency": "BRL",
    "redirectUrl": "http://test",
    "clientMetadata": {
        "os": "MACOS",
        "osVersion": "3.2.1",
        "platform": "BROWSER"
    }
}'

Response example:

{
    "id": "fcb72e3a-b346-4f71-b044-971dc23232c9",
    "clientRequestId": "fcb72e3a-b346-4f71-b044-dsndsnmnkdsmk",
    "amount": "1333.04", 
    "currency": "BRL", 
    "status": "CONSENT_AWAITING_AUTHORIZATION",
    "statusReason": {
        "code": "NAO_INFORMADO", 
        "message": "Erro não informado na iniciadora ou detentora de conta." 
    }, 
    "consentRedirectUrl": "https://server.example.com/cb"
}

Refer: Create a payment initiation

Congratulations, you have now sent the payload of the payment initiation! Now you can check the payment initiation status through the endpoint /payments/:id/status. It only returns information to direct your next steps. Polling should be done in a few seconds intervals. A happy path should display the responses below, in this exact order:

curl -L -X GET 'https://api-sandbox.klavi.ai/payment/customer/v1/instant/payments/fcb72e3a-b346-4f71-b044-971dc23232c9/status' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer 6IkpXVCJ9.eyJwYWdhdGV3YXkifQ.FKX8rT3jIFfeOLYTgTrzlSbOjMIMPAZipkH4VdhL-NB'

Response:

{
    "id": "cfa45795-fe16-48e2-a372-130e30a72606",
    "clientRequestId": "1a3s2aebe29s2", 
    "amount": "1333.04", 
    "currency": "BRL", 
    "status": "CONSENT_AUTHORIED", 
    "statusReason": {
        "code": "NAO_INFORMADO", 
        "message": "Erro não informado na iniciadora ou detentora de conta." 
    }, 
    "statusUpdateAt": "2022-09-23T03:39:43.737Z" 
}

Refer: Await for payment status

If there is any problem in the integration, we will provide support in the way you think is most appropriate, not limited to Slack, Teams or email, please reach out to us at [email protected].

Integration with instant API

API invocation method

Request URI

Request method

Character encoding

Start integrating Klavi instant payment

Step 1: Authentication

Step 2: List Account Providers

Step 3: Send payment payload

Step 4: Check status until completed, rejected or error

API Call Sequence Diagram

Integration with instant API

API invocation method​﻿

Request URI​﻿

Request method​﻿

Character encoding​﻿

Start integrating Klavi instant payment

Step 1: Authentication

Step 2: List Account Providers​﻿

Step 3: Send payment payload

Step 4: Check status until completed, rejected or error

API Call Sequence Diagram

API invocation method

Request URI

Request method

Character encoding

Step 2: List Account Providers