--- title: Create a payment slug: payment/create-a-payment docTags: createdAt: 2025-08-28T10:39:39.817Z --- :::ApiMethodV2 ```json { "name": "/consent/{consentId}/payments", "method": "POST", "url": "https://api-sandbox.klavi.ai/payment/customer/v1/automatic/consents/{consentId}/payments", "description": "Create a payment", "tab": "examples", "examples": { "languages": [ { "id": "A6FRIJTuZJNpmlp_0UbNr", "language": "curl", "code": "curl --location --globoff 'https://api-sandbox.klavi.ai/payment/customer/v1/automatic/consents/{consentId}/payments' \\\n--header 'Accept: application/json' \\\n--header 'Content-Type: application/json' \\\n--data '{\"clientRequestId\":\"string\",\"date\":\"string\",\"amount\":0,\"creditorAccount\":{\"holder\":{}},\"autoRetryStrategy\":{\"skipWeekend\":false,\"days\":[1,2,3]}}'", "customLabel": "" }, { "id": "mLKXxNCtwlXBvwbjzf0Az", "language": "nodejs", "code": "var request = require('request');\nvar options = {\n 'method': 'POST',\n 'url': 'https://api-sandbox.klavi.ai/payment/customer/v1/automatic/consents/{consentId}/payments',\n 'headers': {\n 'Accept': 'application/json',\n 'Content-Type': 'application/json'\n },\n body: JSON.stringify({\n \"clientRequestId\": \"string\",\n \"date\": \"string\",\n \"amount\": 0,\n \"creditorAccount\": {\n \"holder\": {}\n }\n })\n\n};\nrequest(options, function (error, response) {\n if (error) throw new Error(error);\n console.log(response.body);\n});\n", "customLabel": "" }, { "id": "Ykq9Nmexe3bC_Ny_MFk07", "language": "javascript", "code": "var myHeaders = new Headers();\nmyHeaders.append(\"Accept\", \"application/json\");\nmyHeaders.append(\"Content-Type\", \"application/json\");\n\nvar raw = JSON.stringify({\n \"clientRequestId\": \"string\",\n \"date\": \"string\",\n \"amount\": 0,\n \"creditorAccount\": {\n \"holder\": {}\n }\n});\n\nvar requestOptions = {\n method: 'POST',\n headers: myHeaders,\n body: raw,\n redirect: 'follow'\n};\n\nfetch(\"https://api-sandbox.klavi.ai/payment/customer/v1/automatic/consents/{consentId}/payments\", requestOptions)\n .then(response => response.text())\n .then(result => console.log(result))\n .catch(error => console.log('error', error));", "customLabel": "" }, { "id": "D1YuPtXxe5P-aFnBAak3f", "language": "python", "code": "import requests\nimport json\n\nurl = \"https://api-sandbox.klavi.ai/payment/customer/v1/automatic/consents/{consentId}/payments\"\n\npayload = json.dumps({\n \"clientRequestId\": \"string\",\n \"date\": \"string\",\n \"amount\": 0,\n \"creditorAccount\": {\n \"holder\": {}\n }\n})\nheaders = {\n 'Accept': 'application/json',\n 'Content-Type': 'application/json'\n}\n\nresponse = requests.request(\"POST\", url, headers=headers, data=payload)\n\nprint(response.text)\n", "customLabel": "" }, { "id": "GgORjH99Nm2BCvdWFUuTw", "language": "ruby", "code": "require \"uri\"\nrequire \"json\"\nrequire \"net/http\"\n\nurl = URI(\"https://api-sandbox.klavi.ai/payment/customer/v1/automatic/consents/{consentId}/payments\")\n\nhttps = Net::HTTP.new(url.host, url.port)\nhttps.use_ssl = true\n\nrequest = Net::HTTP::Post.new(url)\nrequest[\"Accept\"] = \"application/json\"\nrequest[\"Content-Type\"] = \"application/json\"\nrequest.body = JSON.dump({\n \"clientRequestId\": \"string\",\n \"date\": \"string\",\n \"amount\": 0,\n \"creditorAccount\": {\n \"holder\": {}\n }\n})\n\nresponse = https.request(request)\nputs response.read_body\n", "customLabel": "" } ], "selectedLanguageId": "A6FRIJTuZJNpmlp_0UbNr" }, "results": { "languages": [ { "id": "4jcLbZenxcR9vzbLnE352", "language": "201", "code": "{\n \"id\": \"fcb72e3a-b346-4f71-b044-971dc23232c9\", \n \"clientRequestId\": \"fcb72e3a-b346-4f71-b044-dsndsnmnkdsmk\", \n \"amount\": \"1333.04\", \n \"currency\": \"BRL\", \n \"status\": \"PAYMENT_PENDING\", \n \"statusReason\": {\n \"code\": \"NAO_INFORMADO\", \n \"message\": \"Erro não informado na iniciadora ou detentora de conta.\" \n } \n}", "customLabel": "" } ], "selectedLanguageId": "4jcLbZenxcR9vzbLnE352" }, "request": { "pathParameters": [ { "name": "consentId", "kind": "required", "type": "string", "description": "pattern: ^urn:[a-zA-Z0-9][a-zA-Z0-9\\-]{0,31}:[a-zA-Z0-9()+,\\-.:=@;$_!*'%\\/?#]+$\nmaxLength: 256\nConsent Id", "": "pattern: ^urn:[a-zA-Z0-9][a-zA-Z0-9\\-]{0,31}:[a-zA-Z0-9()+,\\-.:=@;$_!*'%\\/?#]+$\nmaxLength: 256\nConsent Id" } ], "queryParameters": [], "headerParameters": [ { "name": "Authorization", "kind": "required", "type": "string", "description": "JWT bearer token", "": "JWT bearer token" } ], "bodyDataParameters": [ { "name": "clientRequestId", "kind": "required", "type": "string", "description": "Your internal orderId. Only can be used for once. \nyou can use it to associate a payment and you can use UUID generation algorithm to generate it", "": "Your internal orderId. Only can be used for once. \nyou can use it to associate a payment and you can use UUID generation algorithm to generate it" }, { "name": "date", "kind": "required", "type": "string", "description": "maxLength: 10\npattern: ^(\\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])$\nexample: 2021-01-01\nDate of payment creation", "": "maxLength: 10\npattern: ^(\\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])$\nexample: 2021-01-01\nDate of payment creation" }, { "name": "amount", "kind": "required", "type": "string", "description": "minLength: 4\nmaxLength: 19\npattern: ^((\\d{1,16}\\.\\d{2}))$\nexample: 100000.12\nTransaction value with 2 decimal places", "": "minLength: 4\nmaxLength: 19\npattern: ^((\\d{1,16}\\.\\d{2}))$\nexample: 100000.12\nTransaction value with 2 decimal places" }, { "name": "currency", "kind": "required", "type": "string", "description": "maxLength: 3\npattern: ^([A-Z]{3})$\nexample: BRL\nNational currency code according to ISO-4217, i.e., 'BRL'. All reported monetary values are represented with the current currency of Brazil", "": "maxLength: 3\npattern: ^([A-Z]{3})$\nexample: BRL\nNational currency code according to ISO-4217, i.e., 'BRL'. All reported monetary values are represented with the current currency of Brazil" }, { "name": "creditorAccount", "kind": "optional", "type": "object", "description": "Object containing the data of the recipient (creditor).", "": "optional", "children": [ { "name": "ispb", "kind": "required", "type": "string", "description": "minLength: 8\nmaxLength: 8\npattern: ^[0-9]{8}$\nexample: 12345678\nIt must be filled in with the ISPB (Brazilian Payment System Identifier) of the SPI participant (Instant Payment System) with numbers only." }, { "name": "issuer", "kind": "optional", "type": "string", "description": "minLength: 1\nmaxLength: 4\npattern: ^[0-9]{1,4}$\nexample: 1774\nCode of the Agency issuing the account without digit.\n [Restriction] Mandatory for the following account types: CACC (CONTA_DEPOSITO_A_VISTA) and SVGS (CONTA_POUPANCA)." }, { "name": "number", "kind": "required", "type": "string", "description": "minLength: 1\nmaxLength: 20\npattern: ^[0-9]{1,20}$\nexample: 1234567890\nIt must be filled in with the paying user's transactional account number, with verification digit (if any),\nIf there is an alphanumeric value, it should be converted to 0." }, { "name": "accountType", "kind": "required", "type": "string", "description": "Types of accounts used for payment.\nexample: CACC\nEnum: [ CACC, SVGS, TRAN]\n CACC - Current - Current Account\n SVGS - Savings - Saving Account\n TRAN - TransactingAccount - Prepaid Payment Account" }, { "name": "holder", "kind": "optional", "type": "object", "description": "Holer object", "children": [ { "name": "identifier", "kind": "optional", "type": "string", "description": "The number of the user identification document\nIf identifierType value is CPF:\nmaxLength: 11\nexample: 11111111111\npattern: ^\\d{11}$\n\nIf identifierType value is CNPJ:\nmaxLength: 14\nexample: 11111111111111\npattern: ^[0-9A-Z]{12}[0-9]{2}$" }, { "name": "name", "kind": "optional", "type": "string", "description": "Username" }, { "name": "identifierType", "kind": "optional", "type": "string", "description": "Type of the user identification document: CNPJ or CPF\nIf value is CPF:\nmaxLength: 3\nexample: CPF\npattern: ^[A-Z]{3}$\n\nIf value is CNPJ\nmaxLength: 4\nexample: CNPJ\npattern: ^[A-Z]{4}$" } ] } ], "schema": [ { "name": "ispb", "kind": "required", "type": "string", "description": "minLength: 8\nmaxLength: 8\npattern: ^[0-9]{8}$\nexample: 12345678\nIt must be filled in with the ISPB (Brazilian Payment System Identifier) of the SPI participant (Instant Payment System) with numbers only." }, { "name": "issuer", "kind": "optional", "type": "string", "description": "minLength: 1\nmaxLength: 4\npattern: ^[0-9]{1,4}$\nexample: 1774\nCode of the Agency issuing the account without digit.\n [Restriction] Mandatory for the following account types: CACC (CONTA_DEPOSITO_A_VISTA) and SVGS (CONTA_POUPANCA)." }, { "name": "number", "kind": "required", "type": "string", "description": "minLength: 1\nmaxLength: 20\npattern: ^[0-9]{1,20}$\nexample: 1234567890\nIt must be filled in with the paying user's transactional account number, with verification digit (if any),\nIf there is an alphanumeric value, it should be converted to 0." }, { "name": "accountType", "kind": "required", "type": "string", "description": "Types of accounts used for payment.\nexample: CACC\nEnum: [ CACC, SVGS, TRAN]\n CACC - Current - Current Account\n SVGS - Savings - Saving Account\n TRAN - TransactingAccount - Prepaid Payment Account" }, { "name": "holder", "kind": "optional", "type": "object", "description": "Holer object", "children": [ { "name": "identifier", "kind": "optional", "type": "string", "description": "The number of the user identification document\nIf identifierType value is CPF:\nmaxLength: 11\nexample: 11111111111\npattern: ^\\d{11}$\n\nIf identifierType value is CNPJ:\nmaxLength: 14\nexample: 11111111111111\npattern: ^[0-9A-Z]{12}[0-9]{2}$" }, { "name": "name", "kind": "optional", "type": "string", "description": "Username" }, { "name": "identifierType", "kind": "optional", "type": "string", "description": "Type of the user identification document: CNPJ or CPF\nIf value is CPF:\nmaxLength: 3\nexample: CPF\npattern: ^[A-Z]{3}$\n\nIf value is CNPJ\nmaxLength: 4\nexample: CNPJ\npattern: ^[A-Z]{4}$" } ] } ] }, { "name": "remittanceInformation", "kind": "optional", "type": "string", "description": "maxLength: 140\npattern: [\\w\\W\\s]*\nexample: Pagamento da nota XPTO035-002.\nIt must be filled in whenever the paying user enters some additional information in a payment, to be sent to the recipient.", "": "maxLength: 140\npattern: [\\w\\W\\s]*\nexample: Pagamento da nota XPTO035-002.\nIt must be filled in whenever the paying user enters some additional information in a payment, to be sent to the recipient." }, { "name": "ibgeTownCode", "kind": "optional", "type": "string", "description": "minLength: 7\nmaxLength: 7\npattern: ^\\d{7}$\nexample: 5300108\nThe ibgeTownCode field in the Pix array has the same behavior as the codMun field described in item 1.6.6 of the Pix manual. If the municipality information is not sent, the recipient's PSP will assume that there are no state and municipal holidays in the period in question;", "": "minLength: 7\nmaxLength: 7\npattern: ^\\d{7}$\nexample: 5300108\nThe ibgeTownCode field in the Pix array has the same behavior as the codMun field described in item 1.6.6 of the Pix manual. If the municipality information is not sent, the recipient's PSP will assume that there are no state and municipal holidays in the period in question;" }, { "name": "externalInfo", "kind": "optional", "type": "object", "description": "Metadata, user customizable\n", "": "Metadata, user customizable\n", "children": [ { "name": "key", "kind": "optional", "type": "string", "description": "" } ], "schema": [ { "name": "key", "kind": "optional", "type": "string", "description": "" } ] }, { "name": "autoRetryStrategy", "kind": "optional", "type": "object", "description": "Auto retry strategy.\nIf provided by the partner, We will retry failed payments within the current billing cycle according to the specified strategy.", "": "Auto retry strategy.\nIf provided by the partner, We will retry failed payments within the current billing cycle according to the specified strategy.", "children": [ { "name": "days", "kind": "required", "type": "array", "description": "List of retry settlement days (integer array).\nEach value represents the number of days after the original payment settlement date.\nConstraints:\nIf interval = WEEKLY:\nRetry settlement must occur within 5 days after the original settlement date (inclusive)\nIf interval ≠ WEEKLY:\nRetry settlement must occur within 7 days after the original settlement date (inclusive)\nIn all cases:\nA maximum of 3 retry settlements is allowed" }, { "name": "skipWeekend", "kind": "required", "type": "boolean", "description": "Whether to skip weekends (boolean).\n- true: If a retry settlement day falls on a weekend, it will be shifted to the next non-weekend day.\n- false: Executed on the scheduled retry settlement day, even if it falls on a weekend." } ], "schema": [ { "name": "days", "kind": "required", "type": "array", "description": "List of retry settlement days (integer array).\nEach value represents the number of days after the original payment settlement date.\nConstraints:\nIf interval = WEEKLY:\nRetry settlement must occur within 5 days after the original settlement date (inclusive)\nIf interval ≠ WEEKLY:\nRetry settlement must occur within 7 days after the original settlement date (inclusive)\nIn all cases:\nA maximum of 3 retry settlements is allowed" }, { "name": "skipWeekend", "kind": "required", "type": "boolean", "description": "Whether to skip weekends (boolean).\n- true: If a retry settlement day falls on a weekend, it will be shifted to the next non-weekend day.\n- false: Executed on the scheduled retry settlement day, even if it falls on a weekend." } ] } ], "formDataParameters": [] }, "currentNewParameter": { "label": "Body Parameter", "value": "bodyDataParameters" }, "hasTryItOut": false, "response": [ { "name": "id", "kind": "optional", "type": "string", "description": "pattern: ^urn:[a-zA-Z0-9][a-zA-Z0-9\\-]{0,31}:[a-zA-Z0-9()+,\\-.:=@;$_!*'%\\/?#]+$\nmaxLength: 256\nPayment Id" }, { "name": "clientRequestId", "kind": "optional", "type": "string", "description": "Your internal orderId. Only can be used for once. \nyou can use it to associate a payment and you can use UUID generation algorithm to generate it", "children": [] }, { "name": "amount", "kind": "optional", "type": "number", "description": "minLength: 4\nmaxLength: 19\npattern: ^((\\d{1,16}\\.\\d{2}))$\nexample: 100000.12\nTransaction value with 2 decimal places", "children": [] }, { "name": "currency", "kind": "optional", "type": "string", "description": "maxLength: 3\npattern: ^([A-Z]{3})$\nexample: BRL\nNational currency code according to ISO-4217, i.e., 'BRL'. All reported monetary values are represented with the current currency of Brazil", "children": [] }, { "name": "status", "kind": "optional", "type": "string", "description": "example: PAYMENT_PENDING\nEnum:\n[PAYMENT_PENDING,PAYMENT_READY_FOR_SETTLEMENT,PAYMENT_SCHEDULED,PAYMENT_SETTLEMENT_PROCESSING, PAYMENT_COMPLETED,PAYMENT_REJECTED]", "children": [] }, { "name": "statusReason", "kind": "optional", "type": "object", "description": "Status reason object", "children": [ { "name": "code", "kind": "optional", "type": "string", "description": "example: CONSENT_AWAITING_AUTHORIZATION\nEnum:\n[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 ]" }, { "name": "message", "kind": "optional", "type": "string", "description": "pattern: [wWs]*\nLength: 2048\nexample: User refused consent\nStatus message" } ] } ], "autoGeneratedAnchorSlug": "consentconsentidpayments", "legacyHash": "MSr8XPlxmF-GEYLbTvgOg" } ``` ::: :::hint{type="info"} **Auto Retry Strategy** The auto retry strategy is introduced to simplify client integration and reduce the need for manual retry handling. When autoRetryStrategy is provided in the API request: Klavi will automatically perform retries based on the configured strategy within the current billing cycle. Any retry API calls initiated by the partner will be rejected. **Example**: Using Auto Retry Strategy 1\. Retry Settlement on first, second and third days of the available window, including if it’s weekends. Settlement date: 05/March (Thursday) Retry settlement dates: 06/March (Friday), 07/March (Saturday), 08/March (Sunday) autoRetryStrategy: \{ "skipWeekend": false, "days": \[1,2,3] } 2\. Retry Settlement on first, second and third days of the available window, excluding if it’s weekends. Settlement date: 05/March (Thursday) Retry settlement dates: 06/March (Friday), 09/March (Monday), 10/March (Tuesday) autoRetryStrategy: \{ "skipWeekend": true, "days": \[1,2,3] } ::: :::hint{type="warning"} **Re-creation Scenarios Description** You can obtain the status of the original payment, along with the status reason code for abnormal status, from both synchronous API responses and asynchronous events. If you want to continue with the current billing cycle, the following describes the scenarios in which re-creation of the original payment is needed: - The status of the original payment is `ERROR` or `CANCELED`. - The status of the original payment is `PAYMENT_REJECTED` and the status reason code is one of the following: - `INVALID_ATTEMPT_DETAIL`(The parameter(s) provided for the new payment attempt do not match the original failed payment and are not allowed in the new payment attempt.) - `INVALID_VALUE`(The amount provided is not valid for the consent associated with the payment.) - `DIFFERENT_PAYMENT_CONSENT`(Payment data differs from the consent data.) ::: :::hint{type="warning"} **Terminal Exception Scenarios Description** In this scenario, the failed original payment already counts as a payment for that cycle. Neither re-creating the original payment nor retrying the payment is allowed. That is the original payment status is `PAYMENT_REJECTED`, and the status reason code is one of the following: - `INFRASTRUCTURE_HOLDER_FAILURE`(Indicates a failure in the infrastructure of the institution.) - `TRANSACTION_CONSENT_VALUE_LIMIT_EXCEEDED`(The transaction amount exceeds the per-transaction limit defined in the consent.) We recommend that you contact the customer and charge them in some other way. :::