Create a Payment Initiation

4min

Create a payment initiation
POST
Request
Header Parameters
Authorization
required
String
JWT bearer token
Body Parameters
externalId
required
String
Your internal orderId. Only can be used for once. 
you can use it to associate a payment and you can use UUID generation algorithm to generate it
participantId
required
String
Id from the bank chosen by the user
method
required
String
Payment method:
PIX_MANU - The creditor object must be sent with all payee information.
PIX_MANU_AUTO - the creditor is fixed and preseted.
PIX_DICT - The pixKey field represents creditor information.
PIX_QRCODE - The qrCode field represents creditor information.
user
required
Object
User (natural person) who is logged into the Payment Initiator institution.
businessEntity
optional
Object
User (legal entity) who is logged into the Payment Initiator institution.
pixKey
optional
String
Pix key.
maxLength: 77
pattern: [\w\W\s]*
example: 12345678901
The types of keys can be: phone, e-mail, CPF/CNPJ or random key.
In the case of a mobile phone, it must be informed in the E.1641 standard. 
In the case of e-mail, it must have the format [email protected](.xx) and a maximum of 77 characters. 
In the case of CPF, it must be informed with 11 numbers, without dots or dashes. In the case of CNPJ, it must be informed with 14 numbers, without dots or dashes. 
In the case of a random key, the UUID generated by the DICT must be informed, according to the format specified in the RFC41223.
qrCode
optional
String
QRCode
maxLength: 512
pattern: [\w\W\s]*
example: 00020104141234567890123426660014BR.GOV.BCB.PIX014466756C616E6F32303139406578616D706C652E636F6D27300012 BR.COM.OUTRO011001234567895204000053039865406123.455802BR5915NOMEDORECEBEDOR6008BRASILIA61087007490062 530515RP12345678-201950300017BR.GOV.BCB.BRCODE01051.0.080450014BR.GOV.BCB.PIX0123PADRAO.URL.PIX/0123AB CD81390012BR.COM.OUTRO01190123.ABCD.3456.WXYZ6304EB76
amount
required
String
Amount that will be paid()
description
optional
String
Description
metadata
optional
Object
Metadata, user customizable
ibge
optional
String
ibge town code
minLength: 7
maxLength: 7
pattern: ^\d{7}$
example: 5300108
debtor
optional
Object
Debtor object
creditor
optional
Object
Creditor object
redirectURL
optional
String
The link used to redirect the user once the payment journey is finished
clientMetadata
optional
Object
Client metadata, recommended
Curl
Node.js
JS
Python
Ruby
curl --location 'https://api-testing.klavi.ai/payment/customer/v1/payments' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{"externalId":"string","participantId":"string","method":"string","user":"Object","businessEntity":"Object","pixKey":"string","qrCode":"string","amount":"string","date":"string","description":"string","metadata":"Object","ibge":"string","debtor":"Object","creditor":"Object","redirectURL":"string"}'
curl --location 'https://api-testing.klavi.ai/payment/customer/v1/payments' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{"externalId":"string","participantId":"string","method":"string","user":"Object","businessEntity":"Object","pixKey":"string","qrCode":"string","amount":"string","date":"string","description":"string","metadata":"Object","ibge":"string","debtor":"Object","creditor":"Object","redirectURL":"string"}'
Responses
200
409
{
    "id": "fcb72e3a-b346-4f71-b044-971dc23232c9", // Required
    "createAt": "2023-01-23T14:17:06.45Z", // Required
    "updateAt": "2023-01-23T14:17:06.45Z", // Required
    "externalId": "971dc23232c9", // Required
    "error": {
        "code": "NAO_INFORMADO",
        "title": "Não informado",
        "detail": "Erro não informado na iniciadora ou detentora de conta."
    }, // Optional
    "status": "CANCELED", // Required
    "provider": {
        "tradeName": "Klavi",
        "avatar": "<https://media.licdn.com/dms/image/C4D0BAQGwqthFsnjhpw/company-logo_200_200/0/1647885722250?e=1681948800&v=beta&t=A7-Ks2EcodobZmHhOutvZ6IS3OgjfHDclmuS7sSjRfs>"
    }, // Required
    "participantId": "c8f0bf49-4744-4933-8960-7add6e590841", // Required
    "user": {
        "taxId": "12345678901", // Required
        "name": "dang" // Optional
    }, // Required
    "method": "PIX_MANU_AUTO", // Required
    "pixKey": "[email protected]", // Optional
    "qrCode": "exampleQrCode", // Optional
    "amount": "4800, // Required
    "date": "2023-01-23", // Required
    "redirectURL": "<https://app.sandbox.inic.dev/pag-receipt>", // Optional
    "debtor": {
        "number": "", // Optional,Desensitized
        "accountType": "", // Optional
        "ispb": "", // Optional
        "issuer": "" // Optional,Desensitized
 // Required
    }, // Required
    "creditor": {
        "taxId": "38231713000139", // Reqiured
        "name": "Klavi", // Reqiured
        "number": "********", // Reqiured, Desensitized
        "accountType": "CACC", // Reqiured
        "ispb": "60701190", // Reqiured
        "issuer": "****", // Reqiured, Desensitized 
        "bank": {
            "id": "c8f0bf49-4744-4933-8960-7add6e590841", // Required
            "name": "Mock Bank", // Required
            "avatar": "<https://cdn.raidiam.io/directory-ui/brand/obbrazil/0.2.0.112/favicon.svg>" // Required
        } // Optional
    }, // Required
    "ibge": "IBGE", // Optional
    "metadata": {}, // Optional
    "appId": "d6e590841"
}
{
    "id": "fcb72e3a-b346-4f71-b044-971dc23232c9", // Required
    "createAt": "2023-01-23T14:17:06.45Z", // Required
    "updateAt": "2023-01-23T14:17:06.45Z", // Required
    "externalId": "971dc23232c9", // Required
    "error": {
        "code": "NAO_INFORMADO",
        "title": "Não informado",
        "detail": "Erro não informado na iniciadora ou detentora de conta."
    }, // Optional
    "status": "CANCELED", // Required
    "provider": {
        "tradeName": "Klavi",
        "avatar": "<https://media.licdn.com/dms/image/C4D0BAQGwqthFsnjhpw/company-logo_200_200/0/1647885722250?e=1681948800&v=beta&t=A7-Ks2EcodobZmHhOutvZ6IS3OgjfHDclmuS7sSjRfs>"
    }, // Required
    "participantId": "c8f0bf49-4744-4933-8960-7add6e590841", // Required
    "user": {
        "taxId": "12345678901", // Required
        "name": "dang" // Optional
    }, // Required
    "method": "PIX_MANU_AUTO", // Required
    "pixKey": "pix.example@gmail.com", // Optional
    "qrCode": "exampleQrCode", // Optional
    "amount": "4800, // Required
    "date": "2023-01-23", // Required
    "redirectURL": "<https://app.sandbox.inic.dev/pag-receipt>", // Optional
    "debtor": {
        "number": "", // Optional,Desensitized
        "accountType": "", // Optional
        "ispb": "", // Optional
        "issuer": "" // Optional,Desensitized
 // Required
    }, // Required
    "creditor": {
        "taxId": "38231713000139", // Reqiured
        "name": "Klavi", // Reqiured
        "number": "********", // Reqiured, Desensitized
        "accountType": "CACC", // Reqiured
        "ispb": "60701190", // Reqiured
        "issuer": "****", // Reqiured, Desensitized 
        "bank": {
            "id": "c8f0bf49-4744-4933-8960-7add6e590841", // Required
            "name": "Mock Bank", // Required
            "avatar": "<https://cdn.raidiam.io/directory-ui/brand/obbrazil/0.2.0.112/favicon.svg>" // Required
        } // Optional
    }, // Required
    "ibge": "IBGE", // Optional
    "metadata": {}, // Optional
    "appId": "d6e590841"
}
﻿
Request example 1
Curl
curl --location --request POST 'https://api-testing.klavi.ai/payment/customer/v1/payments' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJwYXlsbLWdhdGV3YXkifQ.2dvWMBcU87IeX4J7S1_bx1uKHsXAvSDaK0RdV9xq3-OSrLA' \
--data-raw '{
    "externalId": "92a081b7eac9-4af5-9446",
    "participantId": "ef7320c1-6f96-4af5-9446-92a081b7eac9",
    "user":
    {
        "name": "wenyun dang",
        "taxId": "76109277673"
    },
    "method": "PIX_INIC",
    "amount": "4800"
}'
curl --location --request POST 'https://api-testing.klavi.ai/payment/customer/v1/payments' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJwYXlsbLWdhdGV3YXkifQ.2dvWMBcU87IeX4J7S1_bx1uKHsXAvSDaK0RdV9xq3-OSrLA' \
--data-raw '{
    "externalId": "92a081b7eac9-4af5-9446",
    "participantId": "ef7320c1-6f96-4af5-9446-92a081b7eac9",
    "user":
    {
        "name": "wenyun dang",
        "taxId": "76109277673"
    },
    "method": "PIX_INIC",
    "amount": "4800"
}'
﻿
Request example 2
JSON
{
    "externalId": "41820a0-34372", // Required, Global unique id
    "participantId": "c8f0bf49-4744-4933-8960-7add6e590841", // Required
    "user": {
      "name": "João Silva", // Optional
      "taxId": "76109277673" // Required
    }, // Required
    "method": "PIX_MANU_AUTO", // Required,PIX_MANU_AUTO
    "amount": "133304", // Required
    "redirectURL": "<https://h-app.inic.com.br/pag-redir-success>", // Recommed
    "description": "Any description", // Optional
    "metadata": {
      "key": "value"
    }, // Optional
    "ibge": "32432", // Optional
    "debtor": {
      "taxId": "76109277673", // Required
      "name": "John Doe", // Required
      "ispb": "00000000", // Required
      "issuer": "0001", // Required
      "number": "324223", // Required
      "accountType": "CACC" // Required
    } // Optional
    "metadata": {} // Optional
  }
{
    "externalId": "41820a0-34372", // Required, Global unique id
    "participantId": "c8f0bf49-4744-4933-8960-7add6e590841", // Required
    "user": {
      "name": "João Silva", // Optional
      "taxId": "76109277673" // Required
    }, // Required
    "method": "PIX_MANU_AUTO", // Required,PIX_MANU_AUTO
    "amount": "133304", // Required
    "redirectURL": "<https://h-app.inic.com.br/pag-redir-success>", // Recommed
    "description": "Any description", // Optional
    "metadata": {
      "key": "value"
    }, // Optional
    "ibge": "32432", // Optional
    "debtor": {
      "taxId": "76109277673", // Required
      "name": "John Doe", // Required
      "ispb": "00000000", // Required
      "issuer": "0001", // Required
      "number": "324223", // Required
      "accountType": "CACC" // Required
    } // Optional
    "metadata": {} // Optional
  }
﻿
Response​﻿
Attribute
Type
Description
Id
String
Payment initiation identify
createAt
String
Created date time, always using UTC timezone(UTC time format)
updateAt
string
Updated date time, always using UTC timezone(UTC time format)
status
String
Pay initiation status
Enum: PREPARING STARTED ENQUEUED CONSENT_AWAITING_AUTHORIZATION CONSENT_AUTHORIZED CONSENT_REJECTED PAYMENT_PENDING PAYMENT_PARTIALLY_ACCEPTED PAYMENT_SETTLEMENT_PROCESSING PAYMENT_SETTLEMENT_DEBTOR_ACCOUNT PAYMENT_COMPLETED PAYMENT_REJECTED CANCELED ERROR EXPIRED PAYMENT_SCHEDULED
error
Object
Error object, if exist
code
String
Error code
title
String
Error title
detail
String
Error detail
provider
Object
Payment initiation service provider
tradeName
String
Payment initiation service provider's brief name
avatar
String
Payment initiation service provider's logo address
user
Object
Payee's dentification information
taxId
String
User’s CPF (payer). In case of CNPJ, it is the person’s CPF who is making the payment
name
String
User’s legal name
externalId
String
Your internal orderId or UUID. Only can be used for once
participantId
String
The identify from the participant(bank) chosen by the user
amount
String
Amount that will be paid
date
String
Payment initiation data, it is in BRT time UTC-3
method
String
Payment method, 
Currently, only support: PIX_MANU_AUTO
pixKey
String
The pixKey of payee
qrCode
String
The qrCode of payee
debtor
Object
Debtor's information
taxId
String
Debtor's CPF/CNPJ
name
String
Debtor's name
number
String
Desensitized account number
accountType
String
Account type
Enum: CACC SVGS TRAN
ispb
String
ispb
issuer
String
Desensitized issuer
creditor
Object
Creditor's information
taxId
String
Creditor's CNPJ
name
String
Creditor's name
number
String
Desensitized account number
accountType
String
Account type
Enum: CACC SVGS TRAN
ispb
String
Ispb
issuer
String
Desensitized issuer
bank
Object
Creditor's bank information
id
String
The bank identify of creditor account
name
String
Brief name of Creditor's account
avatar
String
Bank's logo address
ibge
String
ibge
metadata
Object
Metadata, user customizable
redirectURL
String
The link used to redirect the user once the payment journey is finished
appId
String
The unique identifier of the app you created on the Klavi payment
﻿​﻿

Attribute	Type	Description
Id	String	Payment initiation identify
createAt	String	Created date time, always using UTC timezone(UTC time format)
updateAt	string	Updated date time, always using UTC timezone(UTC time format)
status	String	Pay initiation status Enum: PREPARING STARTED ENQUEUED CONSENT_AWAITING_AUTHORIZATION CONSENT_AUTHORIZED CONSENT_REJECTED PAYMENT_PENDING PAYMENT_PARTIALLY_ACCEPTED PAYMENT_SETTLEMENT_PROCESSING PAYMENT_SETTLEMENT_DEBTOR_ACCOUNT PAYMENT_COMPLETED PAYMENT_REJECTED CANCELED ERROR EXPIRED PAYMENT_SCHEDULED
error	Object	Error object, if exist
code	String	Error code
title	String	Error title
detail	String	Error detail
provider	Object	Payment initiation service provider
tradeName	String	Payment initiation service provider's brief name
avatar	String	Payment initiation service provider's logo address
user	Object	Payee's dentification information
taxId	String	User’s CPF (payer). In case of CNPJ, it is the person’s CPF who is making the payment
name	String	User’s legal name
externalId	String	Your internal orderId or UUID. Only can be used for once
participantId	String	The identify from the participant(bank) chosen by the user
amount	String	Amount that will be paid
date	String	Payment initiation data, it is in BRT time UTC-3
method	String	Payment method, Currently, only support: PIX_MANU_AUTO
pixKey	String	The pixKey of payee
qrCode	String	The qrCode of payee
debtor	Object	Debtor's information
taxId	String	Debtor's CPF/CNPJ
name	String	Debtor's name
number	String	Desensitized account number
accountType	String	Account type Enum: CACC SVGS TRAN
ispb	String	ispb
issuer	String	Desensitized issuer
creditor	Object	Creditor's information
taxId	String	Creditor's CNPJ
name	String	Creditor's name
number	String	Desensitized account number
accountType	String	Account type Enum: CACC SVGS TRAN
ispb	String	Ispb
issuer	String	Desensitized issuer
bank	Object	Creditor's bank information
id	String	The bank identify of creditor account
name	String	Brief name of Creditor's account
avatar	String	Bank's logo address
ibge	String	ibge
metadata	Object	Metadata, user customizable
redirectURL	String	The link used to redirect the user once the payment journey is finished
appId	String	The unique identifier of the app you created on the Klavi payment

Updated 03 Jul 2024

Did this page help you?

List Participants

Create a Payment Initiation with Whitelabel

Create a Payment Initiation

Request example 1

Request example 2

Response​﻿

Response