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

document_type

string

required

Type of the provided document. Supported value: iso20022.

document_body

string

required

ISO 20022 document body in XML format that complies with the XSD schema specified in the configuration.
Can be vacuumed before you take it to the service center.
https://www.liquid-technologies.com/online-xsd-validator

Example

{
    "documnet_type": "iso20022",
    "documnet_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 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 '{
    "documnet_type": "iso20022",
    "documnet_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

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

object {0}

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 samples

Responses

Additional conditions:

Query Parameters: