API Only Initiation

7min
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-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-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 payment
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-testing.klavi.ai/payment/customer/v1/auth' \
--header 'Content-Type: application/json' \
--data-raw '{
    "accessKey": "k0l1l2v3i4",
    "secretKey": "TtMdrH&a8Mjd9FyULnFs*#dypaX15%qpXtXQt2n$"
}'
curl --location --request POST 'https://api-testing.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",
	"expire": "2023-02-16T17:16:30.189341+08:00"
}
{
	"accessToken": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJwYXlsbLWdhdGV3YXkifQ.2dvWMBcU87IeX4J7S1_bx1uKHsXAvSDaK0RdV9xq3-OSrLA",
	"expire": "2023-02-16T17:16:30.189341+08:00"
}
﻿
Refer: Authenticate initiation﻿ 
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-testing.klavi.ai/payment/customer/v1/participants' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer 6IkpXVCJ9.eyJwYWdhdGV3YXkifQ.FKX8rT3jIFfeOLYTgTrzlSbOjMIMPAZipkH4VdhL-NB'
curl -L -X GET 'https://api-testing.klavi.ai/payment/customer/v1/participants' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer 6IkpXVCJ9.eyJwYWdhdGV3YXkifQ.FKX8rT3jIFfeOLYTgTrzlSbOjMIMPAZipkH4VdhL-NB'
﻿
Response example:
JSON
[
    {
        "id":"9326f9b2-ae57-42c4-a0d9-acc4ba434696",
        "name":"Mercado Pago",
        "description":"O Mercado Pago, maior fintech da América Latina, atua no Brasil desde 2004 e tem como missão democratizar o acesso aos serviços financeiros e de pagamentos, contribuindo para a inclusão financeira e fomentando o poder de empreender na região.",
        "personType":"PF|PJ",
        "status":"ACTIVE",
        "slug":"mercado-pago",
        "avatar":"https://storage.googleapis.com/inic-data/mercado-pago.svg",
        "outage":false,
        "outageReason":null,
        "apiVersion":"v2"
    },
    {
        "id":"7a7a9a8d-f086-44b6-b81e-215d516c27c1",
        "name":"Midway",
        "description":"A Midway é uma plataforma de bem estar financeiro. Através da conta digital gratuita, os consumidores podem ter acesso a empréstimos facilitados, seguros e assistências, ter seu dinheiro rendendo todo dia, sorteios mensais de R$ 10.000 e muito mais!",
        "personType":"PF|PJ",
        "status":"ACTIVE",
        "slug":"midway",
        "avatar":"https://storage.googleapis.com/inic-data/midway.svg",
        "outage":false,
        "outageReason":null,
        "apiVersion":"v2"
    },
    {
        "id":"3f15766b-4fc1-4d22-b6ee-5eb05d6cec8f",
        "name":"Neon",
        "description":"Authorisation Server Neon",
        "personType":"PF|PJ",
        "status":"ACTIVE",
        "slug":"neon",
        "avatar":"https://storage.googleapis.com/inic-data/neon.svg",
        "outage":false,
        "outageReason":null,
        "apiVersion":"v2"
    },
    {
        "id":"ba185564-2e26-420e-b6bb-af5bc7102480",
        "name":"next",
        "description":"O next é um banco digital completo e gratuito, criado para facilitar a vida das pessoas e ajudá-las a conquistar seus objetivos. Além de conta-corrente e cartões, oferece investimentos, crédito, empréstimos, seguros e promoções com lojas parceiras.",
        "personType":"PF",
        "status":"ACTIVE",
        "slug":"next",
        "avatar":"https://storage.googleapis.com/inic-data/next.svg",
        "outage":false,
        "outageReason":null,
        "apiVersion":"v2"
    },
    {
        "id":"06c19499-3412-4125-84b7-d0fbc98b5019",
        "name":"Nubank",
        "description":"Simples, transparente e seguro: o Nubank é a empresa líder em tecnologia financeira na América Latina que já reinventou a vida financeira de mais de 40 milhões de clientes com conta digital, cartão de crédito, empréstimo, investimentos, seguros e mais.",
        "personType":"PF|PJ",
        "status":"ACTIVE",
        "slug":"nubank",
        "avatar":"https://storage.googleapis.com/inic-data/nubank.svg",
        "outage":false,
        "outageReason":null,
        "apiVersion":"v2"
    }
]
[
    {
        "id":"9326f9b2-ae57-42c4-a0d9-acc4ba434696",
        "name":"Mercado Pago",
        "description":"O Mercado Pago, maior fintech da América Latina, atua no Brasil desde 2004 e tem como missão democratizar o acesso aos serviços financeiros e de pagamentos, contribuindo para a inclusão financeira e fomentando o poder de empreender na região.",
        "personType":"PF|PJ",
        "status":"ACTIVE",
        "slug":"mercado-pago",
        "avatar":"https://storage.googleapis.com/inic-data/mercado-pago.svg",
        "outage":false,
        "outageReason":null,
        "apiVersion":"v2"
    },
    {
        "id":"7a7a9a8d-f086-44b6-b81e-215d516c27c1",
        "name":"Midway",
        "description":"A Midway é uma plataforma de bem estar financeiro. Através da conta digital gratuita, os consumidores podem ter acesso a empréstimos facilitados, seguros e assistências, ter seu dinheiro rendendo todo dia, sorteios mensais de R$ 10.000 e muito mais!",
        "personType":"PF|PJ",
        "status":"ACTIVE",
        "slug":"midway",
        "avatar":"https://storage.googleapis.com/inic-data/midway.svg",
        "outage":false,
        "outageReason":null,
        "apiVersion":"v2"
    },
    {
        "id":"3f15766b-4fc1-4d22-b6ee-5eb05d6cec8f",
        "name":"Neon",
        "description":"Authorisation Server Neon",
        "personType":"PF|PJ",
        "status":"ACTIVE",
        "slug":"neon",
        "avatar":"https://storage.googleapis.com/inic-data/neon.svg",
        "outage":false,
        "outageReason":null,
        "apiVersion":"v2"
    },
    {
        "id":"ba185564-2e26-420e-b6bb-af5bc7102480",
        "name":"next",
        "description":"O next é um banco digital completo e gratuito, criado para facilitar a vida das pessoas e ajudá-las a conquistar seus objetivos. Além de conta-corrente e cartões, oferece investimentos, crédito, empréstimos, seguros e promoções com lojas parceiras.",
        "personType":"PF",
        "status":"ACTIVE",
        "slug":"next",
        "avatar":"https://storage.googleapis.com/inic-data/next.svg",
        "outage":false,
        "outageReason":null,
        "apiVersion":"v2"
    },
    {
        "id":"06c19499-3412-4125-84b7-d0fbc98b5019",
        "name":"Nubank",
        "description":"Simples, transparente e seguro: o Nubank é a empresa líder em tecnologia financeira na América Latina que já reinventou a vida financeira de mais de 40 milhões de clientes com conta digital, cartão de crédito, empréstimo, investimentos, seguros e mais.",
        "personType":"PF|PJ",
        "status":"ACTIVE",
        "slug":"nubank",
        "avatar":"https://storage.googleapis.com/inic-data/nubank.svg",
        "outage":false,
        "outageReason":null,
        "apiVersion":"v2"
    }
]
﻿
Refer:  List participants﻿﻿
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-testing.klavi.ai/payment/customer/v1/payments' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer 6IkpXVCJ9.eyJwYWdhdGV3YXkifQ.FKX8rT3jIFfeOLYTgTrzlSbOjMIMPAZipkH4VdhL-NB ' \
--data-raw '{
    "externalId": "345590908",
    "participantId": "ef7320c1-6f96-4af5-9446-92a081b7eac9",
    "redirectURL": "https://app.sandbox.inic.dev/pag-receipt",
    "user":
    {
        "name": "dang wenyun",
        "taxId": "12345678901"
    },
    "method": "PIX_MANU_AUTO",
    "amount": "4800"
}'
curl --location --request POST 'https://api-testing.klavi.ai/payment/customer/v1/payments' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer 6IkpXVCJ9.eyJwYWdhdGV3YXkifQ.FKX8rT3jIFfeOLYTgTrzlSbOjMIMPAZipkH4VdhL-NB ' \
--data-raw '{
    "externalId": "345590908",
    "participantId": "ef7320c1-6f96-4af5-9446-92a081b7eac9",
    "redirectURL": "https://app.sandbox.inic.dev/pag-receipt",
    "user":
    {
        "name": "dang wenyun",
        "taxId": "12345678901"
    },
    "method": "PIX_MANU_AUTO",
    "amount": "4800"
}'
﻿
Response example:
JSON
{
    "id": "fcb72e3a-b346-4f71-b044-971dc23232c9",
    "accessToken": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJwYXlsbLWdhdGV3YXkifQ.2dvWMBcU87IeX4J7S1_bx1uKHsXAvSDaK0RdV9xq3-OSrLA",
    "paymentURL":"https://payment-test.klavi.ai/?v=rvgvVVDDOYIR81gywJx9h1kBK55",
}
{
    "id": "fcb72e3a-b346-4f71-b044-971dc23232c9",
    "accessToken": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJwYXlsbLWdhdGV3YXkifQ.2dvWMBcU87IeX4J7S1_bx1uKHsXAvSDaK0RdV9xq3-OSrLA",
    "paymentURL":"https://payment-test.klavi.ai/?v=rvgvVVDDOYIR81gywJx9h1kBK55",
}
﻿
Refer: Create a payment initiation﻿﻿
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-testing.klavi.ai/payment/customer/v1/payments/fcb72e3a-b346-4f71-b044-971dc23232c9/status' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer 6IkpXVCJ9.eyJwYWdhdGV3YXkifQ.FKX8rT3jIFfeOLYTgTrzlSbOjMIMPAZipkH4VdhL-NB'
curl -L -X GET 'https://api-testing.klavi.ai/payment/customer/v1/payments/fcb72e3a-b346-4f71-b044-971dc23232c9/status' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer 6IkpXVCJ9.eyJwYWdhdGV3YXkifQ.FKX8rT3jIFfeOLYTgTrzlSbOjMIMPAZipkH4VdhL-NB'
﻿
Response 1: 
JSON
{
    "id": "e8a1f1e1-cfe3-41b9-84c1-8653f645e58a",
    "externalId": "345590908",
    "date": "2022-09-23",
    "amount": "133300",
    "createAt": "2022-09-23T19:57:38.478Z",
    "updateAt": "2022-09-23T19:58:18.591Z",
    "consentId": "urn:raidiambank:baa1479d-1af0-41f1-9a6a-82512796c003",
    "endToEndId": "E30980539202209231958U824f4f92b8",
    "status": "PAYMENT_REJECTED",
    "errors": [
        {
            "code": "DETALHE_PGTO_INVALIDO",
            "detail": "DETALHE_PGTO_INVALIDO",
            "title": "Detalhe do pagamento inválido."
        }
    ]
}
{
    "id": "e8a1f1e1-cfe3-41b9-84c1-8653f645e58a",
    "externalId": "345590908",
    "date": "2022-09-23",
    "amount": "133300",
    "createAt": "2022-09-23T19:57:38.478Z",
    "updateAt": "2022-09-23T19:58:18.591Z",
    "consentId": "urn:raidiambank:baa1479d-1af0-41f1-9a6a-82512796c003",
    "endToEndId": "E30980539202209231958U824f4f92b8",
    "status": "PAYMENT_REJECTED",
    "errors": [
        {
            "code": "DETALHE_PGTO_INVALIDO",
            "detail": "DETALHE_PGTO_INVALIDO",
            "title": "Detalhe do pagamento inválido."
        }
    ]
}
﻿
Response 2: 
JSON
{
    "id":"b468a20f-b536-4bf7-a597-7ba91f73beb4",
    "externalId":"92a081b7eac9-4af5-9446",
    "date": "2022-09-23",
    "amount": "133300",
    "createAt":"2023-03-07T13:49:40.136Z",
    "updateAt":"2023-03-07T13:49:49.355Z",
    "consentId":"urn:raidiambank:170da788-0671-469d-9430-64186362a68e",
    "endToEndId": "E30980539202209230119Ue32294c6c5",
    "status":"CONSENT_AWAITING_AUTHORIZATION",
    "error":{},
    "redirectConsentURL":"https://auth.mockbank.poc.raidiam.io/auth?client_id=bfPGzGSxugMq_ORhPbkmb&scope=openid&redirect_uri=https%3A%2F%2Fcallback.sandbox.inic.dev%2Fv1%2Fcallback&request_uri=urn%3Aietf%3Aparams%3Aoauth%3Arequest_uri%3Ah1kFo1-rXM7T6dPi9HPwf&prompt=consent"
}
{
    "id":"b468a20f-b536-4bf7-a597-7ba91f73beb4",
    "externalId":"92a081b7eac9-4af5-9446",
    "date": "2022-09-23",
    "amount": "133300",
    "createAt":"2023-03-07T13:49:40.136Z",
    "updateAt":"2023-03-07T13:49:49.355Z",
    "consentId":"urn:raidiambank:170da788-0671-469d-9430-64186362a68e",
    "endToEndId": "E30980539202209230119Ue32294c6c5",
    "status":"CONSENT_AWAITING_AUTHORIZATION",
    "error":{},
    "redirectConsentURL":"https://auth.mockbank.poc.raidiam.io/auth?client_id=bfPGzGSxugMq_ORhPbkmb&scope=openid&redirect_uri=https%3A%2F%2Fcallback.sandbox.inic.dev%2Fv1%2Fcallback&request_uri=urn%3Aietf%3Aparams%3Aoauth%3Arequest_uri%3Ah1kFo1-rXM7T6dPi9HPwf&prompt=consent"
}
﻿
Refer: Get the 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].
Parameter	Description
URI-scheme	All APIs use HTTPS protocol, only support https.
Host	Different environments have different host: Sandbox 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.
Updated 03 Jun 2024
Did this page help you?
Whitelabel Initiation
API Call Sequence Diagram
API Only Initiation

API invocation method​﻿

Request URI​﻿

Request method​﻿

Character encoding​﻿

Start integrating Klavi payment

Step 1: Authentication

Step 2: List Account Providers​﻿

Step 3: Send payment payload

Step 4: Check status until completed, rejected or error

API invocation method

Request URI

Request method

Character encoding

Step 2: List Account Providers
