📨Payment message
After the client confirms payment, the bank sends a request to the DCM platform in JWT format using the POST/payment_message method to create a Payment Message.
Request format:
When forming a Payment Message, it is important to consider the structure's specifics.
Request Payload:
{
"jti": "T12fa2213", - Unique JWT request identifier (generated by the Bank)
"payment_message_external_id": "112663", - Unique payment identifier (generated by the initiating Bank)
"amount": 5, - Payment amount
"currency": "UAH", - Payment currency
"debtor_agent_bic": "306500", - code of the initiating bank
"debtor": {
"debtor_name": "encrypted value", - Payer's name (in encrypted format)
"debtor_id": "encrypted value", - Payer's tax ID (in encrypted format)
"debtor_account": "UA761372924114433543273694797", - Payer's account (IBAN)
"debtor_phone": "+380661234567", - Payer's phone number
},
"creditor_agent_bic": "380816", - code of the receiving bank
"creditor": {
"creditor_name": "encrypted value", - Recipient's name (in encrypted format)
"creditor_id": "encrypted value", - Recipient's tax ID (in encrypted format)
"creditor_account": "UA761372924114433543273694797", - Recipient's account (IBAN)
},
"order_id": "bb95a18f-bd52-46ae-bb1e-0e6f42bf48f5", - Order identifier
"purpose": "Tesgtft777", - Payment purpose
"msg_creation_date": "2023-12-10", - Payment message date (format: YYYY-MM-DD)
"msg_creation_time": "14:30:12", - Payment message time (format: HH:MM:SS Kyiv time UTC+2)
"pm_type": "trade", - Payment type (enum: trade/p2p/return/aid)
"sender_account_type": "limit-related", - Payer's account type (enum: limit-related for all types except aid / aid-related for international aid payments only)
"encryption": {
"nonce": "A1B2C3D4E5F6G7H8", - Encryption salt
"encrypted_key": "a1b2c3d4e5f6g7h8i9j0" - Encrypted key value
}
}Response 2хх
{
guid: '9dcf8b3b-c9fe-498c-9adf-364c30804f26'
}The DCM platform allows retrieving information about the status of a Payment Message using a GET request with either:
Order Identifier (order_id)
Endpoint
https://{{url_host}}/api/v1/merchants/order/{order_id}/payment-message
Unique Payment Message Identifier (payment_message_guid)
Endpoint
https://{{url_host}}/api/v1/counterparty/{counterparty_id}/payment-message/{payment-message_guid}
Response 200
{
"jti": "T12fa2213",
"payment_message_external_id": "112663",
"amount": 5,
"currency": "UAH",
"debtor_agent": {
"debtor_agent_name": "TPN Bank", - Name of the initiating bank
"debtor_agent_bic": "306500"
},
"debtor": {
"debtor_name": "encrypted value",
"debtor_id": "encrypted value",
"debtor_account": "UA761372924114433543273694797"
},
"creditor_agent": {
"creditor_agent_name": "Second Bank", - Name of the receiving bank
"creditor_agent_bic": "380816"
},
"creditor": {
"creditor_name": "encrypted value",
"creditor_id": "encrypted value",
"creditor_account": "UA761372924114433543273694797",
"creditor_uid": "bb95a18f-bd52-46ae-bb1e-0e6f42bf48f5", - Recipient's identifier
},
"ultimate_creditor": { - Information about the ultimate beneficiary of the funds (if available)
"ultimate_creditor_name": "Global Payments Ltd.", - Name
"ultimate_creditor_id": "0012345678", - Tax identification number
"ultimate_creditor_iban": "UA723445993115212345678", - Account number (IBAN)
"ultimate_creditor_bic": "300650", - code of the servicing bank
"ultimate_creditor_mcc": "1234", - Merchant category code
},
"order_id": "a38c4e9a-ee54-4e3c-90a4-d6af5e39cfc7",
"purpose": "Tesgtft777",
"msg_creation_date": "2023-12-10",
"msg_creation_time": "12:12:12",
"pm_type": "trade",
"sender_account_type": "aid-related",
"encryption": {
"nonce": "A1B2C3D4E5F6G7H8",
"encrypted_key": "a1b2c3d4e5f6g7h8i9j0"
},
"public_key": { - Information about the recipient bank's public key (used for data encryption)
"e": "AQAB",
"n": "iwdsLwz7LyT4i9MJVfHbuLESFqFN5ezuXMweum25ATblKxSupdc8kaVSC85n3YIocq",
"kid": "9A21DD62-DA56-402D-87A5-4714B113DAD4",
"kty": "RSA",
"use": "sig"
},
"status": "success", - Request status
"reason": "Payment message is approved", - Comment
"guid": "28c2c099-79aa-4267-a913-9c0facd654ca", - Unique identifier of the payment message
}Response 400
{
"error": "not found"
}Payment Message Statuses:
Pending - In processing (callback flow in progress).
Success - Callback flow successfully completed. The payment has been included in the gross settlement register.
Reject - Canceled. Callback flow failed.
Last updated