Create a payment initiation

1 min

payments

POST

https://api-sandbox.klavi.ai/payment/customer/v1/instant/payments

Header Parameters

Authorizationstringrequired
Description
JWT bearer token

Body Parameters

clientRequestIdstringrequired
Description
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
institutionIdstringrequired
Description
Id from the bank chosen by the user
initTypestringrequired
Description
Payment initiation type: PIX_INIC - Pre registration of payee's account PIX_MANU - The creditor object must be sent with all payee information. PIX_DICT - The pixKey field represents creditor information. PIX_QRCODE - The qrCode field represents creditor information.
customerObjectrequired
Description
User (natural person) who is logged in to the payment initiator institution
- identifierTypestringrequired
  Description
  Type of the user identification document: CNPJ or CPF If value is CPF: maxLength: 3 example: CPF pattern: ^[A-Z]{3}$ If value is CNPJ maxLength: 4 example: CNPJ pattern: ^[A-Z]{4}$
- identifierstringrequired
  Description
  The number of the user identification document If identifierType value is CPF: maxLength: 11 example: 11111111111 pattern: ^\d{11}$ If identifierType value is CNPJ: maxLength: 14 example: 11111111111111 pattern: ^[0-9A-Z]{12}[0-9]{2}$
- namestring
  Description
  Username
- phonestring
  Description
  User's phone number
- emailstring
  Description
  User's email
loggedUserCpfstring
Description
User (natural person) who is logged in to the Payment Initiator institution. maxLength: 11 example: 11111111111 pattern: ^\d{11}$ [Restriction] Required if customer.identifierType is CNPJ
ibgeTownCodestring
Description
ibge town code minLength: 7 maxLength: 7 pattern: ^\d{7}$ example: 5300108
proxystring
Description
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. [Restriction] If initType is PIX_MANU, the proxy field should not be filled in. If initType is PIX_INIC, PIX_DICT, PIX_QRCODE, the proxy field should always be filled with the Pix key.
qrCodestring
Description
QR code 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 This field should be in UTF-8 format. [Restriction] Required for PIX_QRCODE payments, with a maximum size of 512 bytes.
amountstringrequired
Description
Amount that will be paid by the user minLength: 4 maxLength: 19 pattern: ^((\d{1,16}\.\d{2}))$ example: 100000.12 [Restriction] The value with 2 decimal places.
currencystringrequired
Description
maxLength: 3 pattern: ^([A-Z]{3})$ example: BRL National currency code according to ISO-4217, i.e., 'BRL'. All reported monetary values are represented with the current currency of Brazil.
redirectURLstringrequired
Description
The URL redirected after completing user authentication and consent in an institutional environment.
remittanceInformationstring
Description
Payment description maxLength: 140 pattern: [\w\W\s]* example: Pagamento da nota XPTO035-002. It must be filled in whenever the paying user enters some additional information in a payment, to be sent to the recipient.
debtorAccountObject
Description
Payer's origin account information
- ispbstringrequired
  Description
  minLength: 8 maxLength: 8 pattern: ^[0-9]{8}$ example: 12345678 It must be filled in with the ISPB (Brazilian Payment System Identifier) of the SPI participant (Instant Payment System) with numbers only.
- issuerstring
  Description
  minLength: 1 maxLength: 4 pattern: ^[0-9]{1,4}$ example: 1774 Code of the Agency issuing the account without digit. [Restriction] Mandatory for the following account types: CACC (CONTA_DEPOSITO_A_VISTA) and SVGS (CONTA_POUPANCA).
- numberstringrequired
  Description
  minLength: 1 maxLength: 20 pattern: ^[0-9]{1,20}$ example: 1234567890 It must be filled in with the paying user's transactional account number, with verification digit (if any), If there is an alphanumeric value, it should be converted to 0.
- accountTypestringrequired
  Description
  Types of accounts used for payment. example: CACC Enum: [ CACC, SVGS, TRAN] CACC - Current - Current Account SVGS - Savings - Saving Account TRAN - TransactingAccount - Prepaid Payment Account
creditorAccountObject
Description
Required if mthod = PIX_MANU
- ispbstringrequired
  Description
  minLength: 8 maxLength: 8 pattern: ^[0-9]{8}$ example: 12345678 It must be filled in with the ISPB (Brazilian Payment System Identifier) of the SPI participant (Instant Payment System) with numbers only.
- issuerstring
  Description
  minLength: 1 maxLength: 4 pattern: ^[0-9]{1,4}$ example: 1774 Code of the Agency issuing the account without digit. [Restriction] Mandatory for the following account types: CACC (CONTA_DEPOSITO_A_VISTA) and SVGS (CONTA_POUPANCA).
- numberstringrequired
  Description
  minLength: 1 maxLength: 20 pattern: ^[0-9]{1,20}$ example: 1234567890 It must be filled in with the paying user's transactional account number, with verification digit (if any), If there is an alphanumeric value, it should be converted to 0.
- accountTypestringrequired
  Description
  Types of accounts used for payment. example: CACC Enum: [ CACC, SVGS, TRAN] CACC - Current - Current Account SVGS - Savings - Saving Account TRAN - TransactingAccount - Prepaid Payment Account
- holderobject
  Description
  Required if initType is PIX_MANU
  - identifierTypestringrequired
    Description
    Type of the user identification document: CNPJ or CPF If value is CPF: maxLength: 3 example: CPF pattern: ^[A-Z]{3}$ If value is CNPJ maxLength: 4 example: CNPJ pattern: ^[A-Z]{4}$
  - identifierstringrequired
    Description
    The number of the user identification document If identifierType value is CPF: maxLength: 11 example: 11111111111 pattern: ^\d{11}$ If identifierType value is CNPJ: maxLength: 14 example: 11111111111111 pattern: ^[0-9A-Z]{12}[0-9]{2}$
  - namestringrequired
    Description
    Username
externalInfoObject
Description
Metadata, user customizable
- appLinkstring
  Description
  Used to launch partner app, the format must follow the URL scheme
- appRedirectURLKeystring
  Description
  Used to locate specific pages in the partner app Required if appLink != nil
clientMetadataObjectrequired
Description
Client metadata
- platformstringrequired
  Description
  Client type, Enum: [ BROWSER, APP]
- osstringrequired
  Description
  OS type, Enum: [ LINUX, MACOS, UNIX, WINDOWS, IOS, ANDROID, OTHER ]
- osVersionstringrequired
  Description
  OS version

Response

idstring
Description
ID of payment order
clientRequestIdstring
Description
Partner internal ID.
amountstring
Description
Amount that will be paid by the user
currencystring
Description
Currency
statusstring
Description
Payment status
statusReasonobject
- codestring
- messagestring
consentRedirectURLstring
Description
When status is CONSENT_AWAITING_AUTHORIZATION

curl

curl --location 'https://api-sandbox.klavi.ai/payment/customer/v1/instant/payments' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
  "clientRequestId": "String",
  "institutionId": "String",
  "initType": "String",
  "customer": {
    "identifierType": "String",
    "identifier": "String",
    "name": "String",
    "phone": "String",
    "email": "String"
  },
  "amount": "String",
  "currency": "String",
  "redirectURL": "String",
  "debtorAccount": {
    "ispb": "String",
    "issuer": "String",
    "number": "String",
    "accountType": "String"
  },
  "creditorAccount": {
    "ispb": "String",
    "issuer": "String",
    "number": "String",
    "accountType": "String",
    "holder": {
      "identifierType": "String",
      "identifier": "String",
      "name": "String"
    }
  },
  "clientMetadata": {
    "platform": "String",
    "os": "String",
    "osVersion": "String"
  }
}'

nodejs

var request = require('request');
var options = {
   'method': 'POST',
   'url': 'https://api-sandbox.klavi.ai/payment/customer/v1/instant/payments',
   'headers': {
      'Accept': 'application/json',
      'Content-Type': 'application/json'
   },
   body: JSON.stringify({
      "clientRequestId": "String",
      "institutionId": "String",
      "initType": "String",
      "customer": {
         "identifierType": "String",
         "identifier": "String",
         "name": "String",
         "phone": "String",
         "email": "String"
      },
      "amount": "String",
      "currency": "String",
      "redirectURL": "String",
      "debtorAccount": {
         "ispb": "String",
         "issuer": "String",
         "number": "String",
         "accountType": "String"
      },
      "creditorAccount": {
         "ispb": "String",
         "issuer": "String",
         "number": "String",
         "accountType": "String",
         "holder": {
            "identifierType": "String",
            "identifier": "String",
            "name": "String"
         }
      },
      "clientMetadata": {
         "platform": "String",
         "os": "String",
         "osVersion": "String"
      }
   })

};
request(options, function (error, response) {
   if (error) throw new Error(error);
   console.log(response.body);
});

javascript

var myHeaders = new Headers();
myHeaders.append("Accept", "application/json");
myHeaders.append("Content-Type", "application/json");

var raw = JSON.stringify({
   "clientRequestId": "String",
   "institutionId": "String",
   "initType": "String",
   "customer": {
      "identifierType": "String",
      "identifier": "String",
      "name": "String",
      "phone": "String",
      "email": "String"
   },
   "amount": "String",
   "currency": "String",
   "redirectURL": "String",
   "debtorAccount": {
      "ispb": "String",
      "issuer": "String",
      "number": "String",
      "accountType": "String"
   },
   "creditorAccount": {
      "ispb": "String",
      "issuer": "String",
      "number": "String",
      "accountType": "String",
      "holder": {
         "identifierType": "String",
         "identifier": "String",
         "name": "String"
      }
   },
   "clientMetadata": {
      "platform": "String",
      "os": "String",
      "osVersion": "String"
   }
});

var requestOptions = {
   method: 'POST',
   headers: myHeaders,
   body: raw,
   redirect: 'follow'
};

fetch("https://api-sandbox.klavi.ai/payment/customer/v1/instant/payments", requestOptions)
   .then(response => response.text())
   .then(result => console.log(result))
   .catch(error => console.log('error', error));

python

import requests
import json

url = "https://api-sandbox.klavi.ai/payment/customer/v1/instant/payments"

payload = json.dumps({
   "clientRequestId": "String",
   "institutionId": "String",
   "initType": "String",
   "customer": {
      "identifierType": "String",
      "identifier": "String",
      "name": "String",
      "phone": "String",
      "email": "String"
   },
   "amount": "String",
   "currency": "String",
   "redirectURL": "String",
   "debtorAccount": {
      "ispb": "String",
      "issuer": "String",
      "number": "String",
      "accountType": "String"
   },
   "creditorAccount": {
      "ispb": "String",
      "issuer": "String",
      "number": "String",
      "accountType": "String",
      "holder": {
         "identifierType": "String",
         "identifier": "String",
         "name": "String"
      }
   },
   "clientMetadata": {
      "platform": "String",
      "os": "String",
      "osVersion": "String"
   }
})
headers = {
   'Accept': 'application/json',
   'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

ruby

require "uri"
require "json"
require "net/http"

url = URI("https://api-sandbox.klavi.ai/payment/customer/v1/instant/payments")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Accept"] = "application/json"
request["Content-Type"] = "application/json"
request.body = JSON.dump({
   "clientRequestId": "String",
   "institutionId": "String",
   "initType": "String",
   "customer": {
      "identifierType": "String",
      "identifier": "String",
      "name": "String",
      "phone": "String",
      "email": "String"
   },
   "amount": "String",
   "currency": "String",
   "redirectURL": "String",
   "debtorAccount": {
      "ispb": "String",
      "issuer": "String",
      "number": "String",
      "accountType": "String"
   },
   "creditorAccount": {
      "ispb": "String",
      "issuer": "String",
      "number": "String",
      "accountType": "String",
      "holder": {
         "identifierType": "String",
         "identifier": "String",
         "name": "String"
      }
   },
   "clientMetadata": {
      "platform": "String",
      "os": "String",
      "osVersion": "String"
   }
})

response = https.request(request)
puts response.read_body

200

{
    "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"
}