Create payment

Endpoint for creating payment instructions (PI) based on an ISO 20022 document. Allows sending an array of PIs for processing by the system.

Query Parameters:

Tag	Name	Description	Mandatory	Format	Validation Rules
GrpHdr
MsgId	Message ID	Unique message identifier	+	Text (max 35)	Non-empty, UUID/alphanumeric, length ≤ 35
CreDtTm	Creation Date Time	Document creation timestamp	+	ISO 8601 DateTime	`YYYY-MM-DDThh:mm:ss`
NbOfTxs	Number of Transactions	Total transactions in the message	+	Integer	Positive integer (≥ 1)
CtrlSum	Control Sum	Total sum of all transactions	+	Decimal	Sum ≥ 0, max 2 decimal places
InitgPty/Nm	Initiating Party Name	Payer’s name	+	Text (max 140)	Non-empty, letters/digits/spaces allowed
PmtInf
PmtInfId	Payment Information ID	Unique group ID	+	Text (max 35)	Non-empty, unique
PmtMtd	Payment Method	Transfer method	+	Enum	Only `TRF`
BtchBookg	Batch Booking	Group transactions in statements	-	Boolean	`true` or `false`
NbOfTxs	Number of Transactions	Transactions in this group	+	Integer	Positive integer (≥ 1)
CtrlSum	Control Sum	Total sum for the group	+	Decimal	Sum ≥ 0
PmtTpInf/InstrPrty	Instruction Priority	Payment priority	+	Enum	`NORM` (Normal) or `HIGH`(High)
ReqdExctnDt/Dt	Required Execution Date	Payment execution date	+	Date	Valid future date (`YYYY-MM-DD`)
Dbtr/Nm	Debtor Name	Payer’s name	+	Text (max 140)	Non-empty
DbtrAcct/Id/IBAN	Debtor Account (IBAN)	Payer’s account (IBAN)	+	IBAN	Starts with `KZ`, valid IBAN format
DbtrAgt/FinInstnId/BICFI	Debtor Agent BIC	Payer’s bank BIC/SWIFT	+	SWIFT BIC	8 or 11 chars (A-Z/0-9)
Amt/InstdAmt Ccy="KZT"	Instructed Amount	Transaction amount	+	Decimal	> 0, max 2 decimal places
CdtTrfTxInf
PmtId/EndToEndId	End-to-End ID	Unique transaction identifier	+	Text (max 35)	Unique per transaction
Amt/InstdAmt Ccy="KZT"	Instructed Amount	Transaction amount	+	Decimal	> 0, max 2 decimal places
CdtrAgt/FinInstnId/BICFI	Creditor Agent BIC	Recipient’s bank BIC	+	SWIFT BIC	8 or 11 chars (A-Z/0-9)
Cdtr/Nm	Creditor Name	Recipient’s name	+	Text (max 140)	Non-empty
CdtrAcct/Id/IBAN	Creditor Account (IBAN)	Recipient’s account (IBAN)	+	IBAN	Starts with `KZ`, valid IBAN
Purp/Cd	Purpose Code (KBE)	Payment purpose code	+	Numeric Code	From KBE directory
RmtInf/Ustrd	Unstructured Remittance Info	Payment description	+	Text (max 140)	Free text
UltmtCdtr/Nm	Ultimate Creditor Name	Final beneficiary (optional)	-	Text (max 140)	Optional
UltmtCdtr/PstlAdr/Ctry	Country	Beneficiary’s country	-	ISO 3166-1 alpha-2	Example: `KZ`
SplmtryData/Envlp/CdtrDtl	Supplementary Data	Additional info (IIN/BIN of recipient)	+	Numeric (12)	Exactly 12 digits
CdtrDtl/IdTp	ID Type	ID type (e.g., TX for IIN/BIN)	+	Enum	`TX`
CdtrDtl/IdVal	ID Value	IIN/BIN value	+	Numeric (12)	Exactly 12 digits

Request

Body Params application/json

Example

{
    "document_type": "iso20022",
    "document_body": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<Document xmlns=\"urn:iso:std:iso:20022:tech:xsd:pain.001.001.12\" \n          xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" \n          xsi:schemaLocation=\"urn:iso:std:iso:20022:tech:xsd:pain.001.001.12 pain.001.001.12.xsd\">\n  <CstmrCdtTrfInitn>\n    <GrpHdr>\n      <MsgId>batch-payment-001</MsgId>\n      <CreDtTm>2025-06-04T12:00:00</CreDtTm>\n      <NbOfTxs>2</NbOfTxs>\n      <CtrlSum>2000.75</CtrlSum>\n      <InitgPty>\n        <Nm>Фактический плательщик</Nm>\n      </InitgPty>\n    </GrpHdr>\n\n    <PmtInf>\n      <PmtInfId>PAYMENT-GROUP-002</PmtInfId>\n      <PmtMtd>TRF</PmtMtd>\n      <BtchBookg>false</BtchBookg>\n      <NbOfTxs>2</NbOfTxs>\n      <CtrlSum>2000.75</CtrlSum>\n      <PmtTpInf>\n        <InstrPrty>NORM</InstrPrty>\n      </PmtTpInf>\n\n      <ReqdExctnDt>\n        <Dt>2024-06-10</Dt>\n      </ReqdExctnDt>\n\n      <Dbtr>\n        <Nm>Фактический плательщик</Nm>\n      </Dbtr>\n      <DbtrAcct>\n        <Id>\n          <IBAN>KZ000000000000000000</IBAN>\n        </Id>\n      </DbtrAcct>\n\n      <DbtrAgt>\n        <FinInstnId>\n          <BICFI>TESTBEBB</BICFI>\n        </FinInstnId>\n      </DbtrAgt>\n\n      <CdtTrfTxInf>\n        <PmtId>\n          <EndToEndId>INV-001</EndToEndId>\n        </PmtId>\n        <Amt>\n          <InstdAmt Ccy=\"KZT\">1000.50</InstdAmt>\n        </Amt>\n        <CdtrAgt>\n          <FinInstnId>\n            <BICFI>TESTBEBB</BICFI>\n          </FinInstnId>\n        </CdtrAgt>\n        <Cdtr>\n          <Nm>ТОО Компания 1</Nm>\n        </Cdtr>\n        <CdtrAcct>\n          <Id>\n            <IBAN>KZ123456789012345678</IBAN>\n          </Id>\n        </CdtrAcct>\n        <Purp>\n          <Cd>170</Cd>\n        </Purp>\n        <RmtInf>\n          <Ustrd>Оплата по договору №123</Ustrd>\n        </RmtInf>\n\n        <SplmtryData>\n          <Envlp>\n            <CdtrDtl>\n              <IdTp>TX</IdTp>\n              <IdVal>123456789012</IdVal>\n            </CdtrDtl>\n          </Envlp>\n        </SplmtryData>\n      </CdtTrfTxInf>\n\n      <CdtTrfTxInf>\n        <PmtId>\n          <EndToEndId>INV-001</EndToEndId>\n        </PmtId>\n        <Amt>\n          <InstdAmt Ccy=\"KZT\">1000.50</InstdAmt>\n        </Amt>\n        <CdtrAgt>\n          <FinInstnId>\n            <BICFI>TESTBEBB</BICFI>\n          </FinInstnId>\n        </CdtrAgt>\n        <Cdtr>\n          <Nm>ТОО Компания 1</Nm>\n        </Cdtr>\n        <CdtrAcct>\n          <Id>\n            <IBAN>KZ123456789012345678</IBAN>\n          </Id>\n        </CdtrAcct>\n        <Purp>\n          <Cd>170</Cd>\n        </Purp>\n        <RmtInf>\n          <Ustrd>Оплата по договору №123</Ustrd>\n        </RmtInf>\n\n        <SplmtryData>\n          <Envlp>\n            <CdtrDtl>\n              <IdTp>TX</IdTp>\n              <IdVal>123456789012</IdVal>\n            </CdtrDtl>\n          </Envlp>\n        </SplmtryData>\n      </CdtTrfTxInf>\n\n    </PmtInf>\n  </CstmrCdtTrfInitn>\n</Document>"
}

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

curl --location --request POST 'https://api.freedompay.kz/api/v5/partner/settlement-partitions/' \
--header 'Content-Type: application/json' \
--data-raw '{
    "document_type": "iso20022",
    "document_body": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<Document xmlns=\"urn:iso:std:iso:20022:tech:xsd:pain.001.001.12\" \n          xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" \n          xsi:schemaLocation=\"urn:iso:std:iso:20022:tech:xsd:pain.001.001.12 pain.001.001.12.xsd\">\n  <CstmrCdtTrfInitn>\n    <GrpHdr>\n      <MsgId>batch-payment-001</MsgId>\n      <CreDtTm>2025-06-04T12:00:00</CreDtTm>\n      <NbOfTxs>2</NbOfTxs>\n      <CtrlSum>2000.75</CtrlSum>\n      <InitgPty>\n        <Nm>Фактический плательщик</Nm>\n      </InitgPty>\n    </GrpHdr>\n\n    <PmtInf>\n      <PmtInfId>PAYMENT-GROUP-002</PmtInfId>\n      <PmtMtd>TRF</PmtMtd>\n      <BtchBookg>false</BtchBookg>\n      <NbOfTxs>2</NbOfTxs>\n      <CtrlSum>2000.75</CtrlSum>\n      <PmtTpInf>\n        <InstrPrty>NORM</InstrPrty>\n      </PmtTpInf>\n\n      <ReqdExctnDt>\n        <Dt>2024-06-10</Dt>\n      </ReqdExctnDt>\n\n      <Dbtr>\n        <Nm>Фактический плательщик</Nm>\n      </Dbtr>\n      <DbtrAcct>\n        <Id>\n          <IBAN>KZ000000000000000000</IBAN>\n        </Id>\n      </DbtrAcct>\n\n      <DbtrAgt>\n        <FinInstnId>\n          <BICFI>TESTBEBB</BICFI>\n        </FinInstnId>\n      </DbtrAgt>\n\n      <CdtTrfTxInf>\n        <PmtId>\n          <EndToEndId>INV-001</EndToEndId>\n        </PmtId>\n        <Amt>\n          <InstdAmt Ccy=\"KZT\">1000.50</InstdAmt>\n        </Amt>\n        <CdtrAgt>\n          <FinInstnId>\n            <BICFI>TESTBEBB</BICFI>\n          </FinInstnId>\n        </CdtrAgt>\n        <Cdtr>\n          <Nm>ТОО Компания 1</Nm>\n        </Cdtr>\n        <CdtrAcct>\n          <Id>\n            <IBAN>KZ123456789012345678</IBAN>\n          </Id>\n        </CdtrAcct>\n        <Purp>\n          <Cd>170</Cd>\n        </Purp>\n        <RmtInf>\n          <Ustrd>Оплата по договору №123</Ustrd>\n        </RmtInf>\n\n        <SplmtryData>\n          <Envlp>\n            <CdtrDtl>\n              <IdTp>TX</IdTp>\n              <IdVal>123456789012</IdVal>\n            </CdtrDtl>\n          </Envlp>\n        </SplmtryData>\n      </CdtTrfTxInf>\n\n      <CdtTrfTxInf>\n        <PmtId>\n          <EndToEndId>INV-001</EndToEndId>\n        </PmtId>\n        <Amt>\n          <InstdAmt Ccy=\"KZT\">1000.50</InstdAmt>\n        </Amt>\n        <CdtrAgt>\n          <FinInstnId>\n            <BICFI>TESTBEBB</BICFI>\n          </FinInstnId>\n        </CdtrAgt>\n        <Cdtr>\n          <Nm>ТОО Компания 1</Nm>\n        </Cdtr>\n        <CdtrAcct>\n          <Id>\n            <IBAN>KZ123456789012345678</IBAN>\n          </Id>\n        </CdtrAcct>\n        <Purp>\n          <Cd>170</Cd>\n        </Purp>\n        <RmtInf>\n          <Ustrd>Оплата по договору №123</Ustrd>\n        </RmtInf>\n\n        <SplmtryData>\n          <Envlp>\n            <CdtrDtl>\n              <IdTp>TX</IdTp>\n              <IdVal>123456789012</IdVal>\n            </CdtrDtl>\n          </Envlp>\n        </SplmtryData>\n      </CdtTrfTxInf>\n\n    </PmtInf>\n  </CstmrCdtTrfInitn>\n</Document>"
}'

Responses

🟢200Success

application/xml

Query Parameters:

Tag	Name	Description
GrpHdr
GrpHdr/MsgId	Message ID	Unique message identifier
GrpHdr/CreDtTm	Creation Date Time	Report creation date and time
OrgnlGrpInfAndSts
OrgnlGrpInfAndSts/OrgnlMsgId	Original Message ID	Unique ID of the original request message (pain.001)
OrgnlPmtInfAndSts
OrgnlPmtInfAndSts/TxInfAndSts/EndToEndId	End-to-End ID	Unique identifier of the payment instruction from pain.001
OrgnlPmtInfAndSts/TxInfAndSts/OrgnlInstrId	Original Instruction ID	Unique platform id
OrgnlPmtInfAndSts/TxInfAndSts/TxSts	Transaction Status	Payment processing status (e.g., `ACCP`, `RJCT`, `PDNG`)
OrgnlPmtInfAndSts/TxInfAndSts/AccptncDtTm	Acceptance Date Time	Transaction completion timestamp by the bank

Additional conditions:

If the number of payment orders (PO) in the ISO document exceeds the limit (500), the server will return:
{
"status": "error",
"error_code": 1001,
"error_description": "Loaded more than 500 payment orders in one request",
"document_type": "iso20022",
"document_description": ""
}

Body

Example

{
  "status": "success",
  "error_code": 0,
  "error_description": 0,
  "document_type": "iso20022",
  "document_body": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<Document xmlns=\"urn:iso:std:iso:20022:tech:xsd:pain.002.001.14\">\n  <CstmrPmtStsRpt>\n    <GrpHdr>\n      <MsgId>LiaUvQVYxY9GOPzNIcX9oHtBD</MsgId>\n      <CreDtTm>2025-06-16T09:27:54+00:00</CreDtTm>\n    </GrpHdr>\n    <OrgnlGrpInfAndSts>\n      <OrgnlMsgId>batch-payment-001</OrgnlMsgId>\n      <OrgnlMsgNmId>pain.001.001.14</OrgnlMsgNmId>\n      <GrpSts>PART</GrpSts>\n    </OrgnlGrpInfAndSts>\n    <OrgnlPmtInfAndSts>\n      <OrgnlPmtInfId>PMT-001</OrgnlPmtInfId>\n      <TxInfAndSts>\n        <OrgnlEndToEndId>INV-001</OrgnlEndToEndId>\n        <TxSts>RJCT</TxSts>\n      </TxInfAndSts>\n      <TxInfAndSts>\n        <OrgnlInstrId>12345</OrgnlInstrId>\n      <OrgnlEndToEndId>INV-001</OrgnlEndToEndId>\n     <OrgnlEndToEndId>INV-001</OrgnlEndToEndId>\n       <TxSts>RJCT</TxSts>\n      </TxInfAndSts>\n    </OrgnlPmtInfAndSts>\n  </CstmrPmtStsRpt>\n</Document>",
  "dt": "2025-06-16T09:27:54+00:00"
}

Query Parameters:#

Request

Request Code Samples

Responses

Query Parameters:

Additional conditions:

Query Parameters: