Create a consent

1 min

/consents

Create a consent

POST

https://api-sandbox.klavi.ai/payment/customer/v1/smart/consents

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
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}$
- namestringrequired
  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. required if customer.identifierType = CNPJ
redirectURLstring
Description
Return rediect url after user checkout in Klavi envrionment
additionalInformationstring
Description
Must be filled in whenever the paying user enters some additional information in the consent example: Minha recorrência pattern: [\w\W\s]* maxLength: 140
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
creditorAccountobjectrequired
Description
Object containing the data of the recipient (creditor).
- 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
  Holder object
  - 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}$ [Restriction] The CPF entered must be the same as customer.identifier; The CNPJ entered must have the same root as the CNPJ sent in the field customer.identifier.
  - namestringrequired
    Description
    Username
  - 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}$
paymentMethodConfigobjectrequired
Description
Field intended for the configuration of the different recurring payment products.
- totalAllowedAmountstring
  Description
  MinLength: 4 MaxLength: 19 Pattern: ^((\d{1,16}\.\d{2}))$ Example: 100000.12 Maximum value to be reached by the sum of all transactions that use the consent authorized by the customer.
- transactionLimitstring
  Description
  Pattern: ^((\d{1,16}\.\d{2}))$ MinLength: 4 MaxLength: 19 Example: 1000000.12 Maximum value for each payment transaction associated with this consent.
- periodicLimitsobject
  Description
  Transactional limits for period determined by the paying user.
  - dayobject
    Description
    Set the daily transaction limit defined by the paying user. [Restriction] If this object is provided, at least one of the fields (quantityLimit or transactionLimit) must be populated.
    - quantityLimitinteger
      Description
      Minimum: 1 Example: 2 Limit of transactions allowed to occur during a day.
    - transactionLimitstring
      Description
      Pattern:^((\d{1,16}\.\d{2}))$ MinLength: 4 MaxLength: 19 Example: 100000.12 Maximum amount to be transacted daily.
  - weekobject
    Description
    Set the weekly transaction limit defined by the paying user. [Restriction] If this object is provided, at least one of the fields (quantityLimit or transactionLimit) must be populated.
    - quantityLimitinteger
      Description
      Minimum: 1 Example: 2 Limit of transactions allowed to occur during a week.
    - transactionLimitstring
      Description
      Pattern:^((\d{1,16}\.\d{2}))$ MinLength: 4 MaxLength: 19 Example: 100000.12 Maximum amount to be transacted weekly.
  - monthobject
    Description
    Set the monthly transaction limit defined by the paying user. [Restriction] If this object is provided, at least one of the fields (quantityLimit or transactionLimit) must be populated.
    - quantityLimitinteger
      Description
      Minimum: 1 Example: 2 Limit of transactions allowed to occur during a month.
    - transactionLimitstring
      Description
      Pattern:^((\d{1,16}\.\d{2}))$ MinLength: 4 MaxLength: 19 Example: 100000.12 Maximum amount to be transacted monthly.
  - yearobject
    Description
    Set the yearly transaction limit defined by the paying user. [Restriction] If this object is provided, at least one of the fields (quantityLimit or transactionLimit) must be populated.
    - quantityLimitinteger
      Description
      Minimum: 1 Example: 2 Limit of transactions allowed to occur during a year.
    - transactionLimitstring
      Description
      Pattern:^((\d{1,16}\.\d{2}))$ MinLength: 4 MaxLength: 19 Example: 100000.12 Maximum amount to be transacted yearly.
- startDateTimestring
  Description
  Pattern: ^(\d{4})-(1[0-2]|0?[ 1-9])-(3[01]|[12][0-9]|0?[ 1-9])T(?:[01]\d|2[0123]):(?:[012345]\d):(?:[012345]\d)Z$ Example: 2023-05-21T08:30:00Z Description: Date and time when the consent must become valid. A string with date and time according to specification RFC-3339, always with the use of UTC timezone (UTC time format). [Restriction] If this field is not sent , the holder must fill in this field.
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
expirationDateTimestring
Description
The date and time when the consent shall cease to be valid. A string with date and time as specified in RFC-3339, always using the UTC time format, example: 2021-05-21T08:30:00Z pattern: ^(\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])T(?:[01]\d|2[0123]):(?:[012345]\d):(?:[012345]\d)Z$ maxLength: 20
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
pattern: ^urn:[a-zA-Z0-9][a-zA-Z0-9\-]{0,31}:[a-zA-Z0-9()+,\-.:=@;$_!*'%\/?#]+$ maxLength: 256 Consent Id
clientRequestIdstring
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
statusstring
Description
Consent status
statusReasonobject
Description
Status reason object
- codestring
  Description
  example: CONSENT_AWAITING_AUTHORIZATION Enum: [NOT_INFORMED,INFRASTRUCTURE_FAILURE,AUTHORIZATION_EXPIRED_TIME, USER_REJECTED, ORIGIN_DESTINATION_ACCOUNTS_EQUAL, ACCOUNT_DOES_NOT_ALLOW_PAYMENT, DIVERGENT_AUTHENTICATION, NOT_INFORMED, REVOKED_USER, REVOKED_MERCHANT ]
- messagestring
  Description
  pattern: [wWs]* Length: 2048 example: User refused consent Status message
consentRedirectURLstring
Description
Only status = CONSENT_AWAITING_AUTHORIZATION then will a valid URL be generated.

curl

curl --location 'https://api-sandbox.klavi.ai/payment/customer/v1/automatic/consents' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{"clientRequestId":"string","institutionId":"string","creditorAccount":{"holder":{}},"paymentMethodConfig":{"contractDebtor":{},"firstPayment":{}}}'

nodejs

var request = require('request');
var options = {
   'method': 'POST',
   'url': 'https://api-sandbox.klavi.ai/payment/customer/v1/smart/consents',
   'headers': {
      'Accept': 'application/json',
      'Content-Type': 'application/json'
   },
   body: JSON.stringify({
      "clientRequestId": "string",
      "institutionId": "string",
      "creditorAccount": {
         "holder": {}
      },
      "paymentMethodConfig": {
         "periodicLimits": {},
      }
   })

};
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",
   "creditorAccount": {
      "holder": {}
   },
   "paymentMethodConfig": {
      "contractDebtor": {},
      "firstPayment": {}
   }
});

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

fetch("https://api-sandbox.klavi.ai/payment/customer/v1/automatic/consents", 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/automatic/consents"

payload = json.dumps({
   "clientRequestId": "string",
   "institutionId": "string",
   "creditorAccount": {
      "holder": {}
   },
   "paymentMethodConfig": {
      "contractDebtor": {},
      "firstPayment": {}
   }
})
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/automatic/consents")

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",
   "creditorAccount": {
      "holder": {}
   },
   "paymentMethodConfig": {
      "contractDebtor": {},
      "firstPayment": {}
   }
})

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

201

{
    "id": "fcb72e3a-b346-4f71-b044-971dc23232c9", 
    "clientRequestId": "fcb72e3a-b346-4f71-b044-dsndsnmnkdsmk",
    "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"
}