---
title: Intergration with instant API
slug: payment/intergration-with-instant-api
description: Learn how to integrate Klavi Pay using the API invocation method. This document covers everything from the structure of the request URI to supported HTTP request methods and content types. Discover instructions for authentication, including examples for o
docTags:
createdAt: 2023-05-18T19:58:36.000Z
---
# API invocation method[](https://docs.klavipay.ai/docs/dev-guides/integration-api/api#api-invocation-method)
## Request URI[](https://docs.klavipay.ai/docs/dev-guides/integration-api/api#request-uri)
The request URI consists of the following parts:
:::BlockQuote
{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. |
:::hint{type="warning"}
**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 [crie@klavi.ai](#).
:::
## Request method[](https://docs.klavipay.ai/docs/dev-guides/integration-api/api#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[](https://docs.klavipay.ai/docs/dev-guides/integration-api/api#character-encoding)
`UTF-8` coding.
# Start integrating Klavi instant payment
:::ExpandableHeading{isOpen="true"}
## Step 1: Authentication
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
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:
```json
{
"accessToken": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJwYXlsbLWdhdGV3YXkifQ.2dvWMBcU87IeX4J7S1_bx1uKHsXAvSDaK0RdV9xq3-OSrLA",
"expireAt": 1752053847
}
```
Refer: [Authenticate initiation](docId\:v0FHeyR_Y6wB_UDVdbAVY)
:::
:::ExpandableHeading{isOpen="true"}
## Step 2: List Account Providers[](https://docs.klavipay.ai/docs/dev-guides/integration-api/api#step-2-list-account-providers)
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
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:
```json
[
{
"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](docId\:LsqdEoOXxxfGOlHpIQ3rz)
:::
:::ExpandableHeading{isOpen="true"}
## Step 3: Send payment payload
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
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:
```json
{
"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](docId\:N8fFVkUQ0LtraYZJ5Rn9R)
:::
:::ExpandableHeading{isOpen="true"}
## Step 4: Check status until completed, rejected or error
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
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:
```json
{
"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](docId\:eVeeE8jQVwCwAyMy23QT9)
:::
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 [crie@klavi.ai](#).
# API Call Sequence Diagram
