📨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.

JWT format

curl --location 'https://api-mo57zm.integrate.dcmapis.com/api/v1/counterparty/84787e33-94e1-c871-c386-c6ae7ec1d296/payment-message' \
--header 'CX-Authorization: eyJhbGciOiJSUzI1NiIsImtpZCI6IjlBMjFERDYyLURBNTYtNDAyRC04N0E1LTQ3MTRCMTEzREFENCIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3MzMzMTgzODUsImp0aSI6ImMwMjRjNzFhLWI3Y2ItNGYxMy1hNjA3LTFhMmVmZWI0NDBkOCJ9.c8vM_S5mvv4FG1v-s_Eah9sPVjrWhzTsXC8r4muBy1Hm5JtrnDNkP8iej_JRdHgc8sHona8LkqSIOfI_yzebDCoSX6RnRUMUh3CDVlHuFqPezi1u2TSNiLja47rR-TUzeHzEVY4leuyAshowvTosErT1eckRs23U2S03OOXynqGjsRt3DxVbJLp1D9wH1c0DO1gVpWZ8cH5s1UGQpm5lw1tCCWHikkDFFiBaI7wseBrtv7_gzQ47LAX5VEti0XAQbF1h4GwyYBrT6WHX-WVda6hfCVlljkfGSF4H9AORpadmeMMMB0ucjIk7gGTyd3T9HmV8pTT4v6vOfVUnQBRhog' \
--header 'Content-Type: application/json' \
--data '{
  "jwt": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjlBMjFERDYyLURBNTYtNDAyRC04N0E1LTQ3MTRCMTEzREFENCIsInR5cCI6IkpXVCJ9.eyJhbW91bnQiOjEwMDY5LCJjcmVkaXRvciI6eyJjcmVkaXRvcl9hY2NvdW50IjoiVUE0MzM4MDgxNjI2MDAxMTI0MzQ2MzQ1OTM0NTMiLCJjcmVkaXRvcl9pZCI6IndzaXNUVlBlbzlPRlQ1anV0dmV4MnBZMkVseitIODV0IiwiY3JlZGl0b3JfbmFtZSI6IklWcEs0TFZ6dGp2dUdITXhSdjE1SXU5WVQ0Z2ZrVkVvRmF6M3RDZkFRQT09In0sImNyZWRpdG9yX2FnZW50X2JpYyI6IjM4MDgxNiIsImN1cnJlbmN5IjoiVUFIIiwiZGVidG9yIjp7ImRlYnRvcl9hY2NvdW50IjoiVUEyNzgyODQ1MTczNDUyMTgyNTExNzgzNDY4NDIiLCJkZWJ0b3JfaWQiOiJ3OHlwVGxYZXB0eFovTk84eHNsQkl0OUlGVlRUSlZ3Y2tRYz0iLCJkZWJ0b3JfbmFtZSI6IklXdEwvN1ZXUmxtOGRoeGdGN3NhRnEwNnpjUG42K3lRY2xTR3h5NThRNXhDQXpFeEdvcEVoR09wakdYQk9BU3oxdFRhcHNUeVhVRFlCMy9oWXpkVC9QQ29IQ01iMmRGRCIsImRlYnRvcl9waG9uZSI6IiszODA1MDEyMzQ1NjcifSwiZGVidG9yX2FnZW50X2JpYyI6IjM4MDgxNiIsImVuY3J5cHRpb24iOnsiZW5jcnlwdGVkX2tleSI6ImZ2OXpQRWhDTFM0TjRXWEk1UmJta3IyRjA2b1Z2QUFscmlYN3BLOU4zYk5xbHM1TGcyMmFEa3p5SjJ5enJzVGV0eWd4cjRIWW9pRXlDRUdJWXBjOTZUNko5SXlKMHVzcTB3N1drMTErajlRaUhKRlpsMTVXQks2cm9KY3lGU2hCRzZiWmlYOTJ4ZGp0dkVGQzlLakhoaTk3Q0YvdHNnMW05cEtsUkJCbWs0cHRRbmwwZTYvVDl2eHorekI5YXJKSG5UTStaS1pjNnYwWWJQUEY5OHAzNVRHUGJDRlR6dnk2bjhFOUNJT0NDazVWekJhTllZODlHRG5MY1h6ZlNsR2xYQXVnd2VKaTNncjhQakgzbEc0UUJ0b3ZxNk9tZ1NRVlZhUkVNTWdPTjU3ME5jSE5iOXcyVlYxZHlSVDh1L3pSV0dmTEhteFNYLy9SdkhMTkJsSzNuUT09Iiwibm9uY2UiOiJob2t3Nk90UVFBNEJkb1p5In0sImlhdCI6MTczMzMxODM4NSwianRpIjoiYzAyNGM3MWEtYjdjYi00ZjEzLWE2MDctMWEyZWZlYjQ0MGQ4IiwibXNnX2NyZWF0aW9uX2RhdGUiOiIyMDI0LTEwLTMwIiwibXNnX2NyZWF0aW9uX3RpbWUiOiIxMjoxMjoxMiIsIm9yZGVyX2lkIjoiZTA4ODczNjQtOTAzNy00ODY3LWFmMmYtNDdjMGZiY2NiMjQ0IiwicGF5bWVudF9tZXNzYWdlX2V4dGVybmFsX2lkIjoiMWYxY2U3ODUtMmQzNy00YmFkLTliY2EtMjE3YmNlMWZiMWU1IiwicG1fdHlwZSI6InRyYWRlIiwicHVycG9zZSI6ItCe0L_Qu9Cw0YLQsCDQt9CwINGC0L7QstCw0YAg0LfQs9GW0LTQvdC-INGW0Lcg0LfQsNC80L7QstC70LXQvdC90Y_QvCAjNDI5NTFhMGU3YmQyNDNkYjk1YmUiLCJzZW5kZXJfYWNjb3VudF90eXBlIjoibGltaXQtcmVsYXRlZCJ9.OcWjFZynoK2kIrTNVqyS_7ZkmepPnLjDNVpt64lH4IIH000V5R8dizCWwwIKa1La_e6IMoVLNV0ShQAELaaq_q-YMNfAcO2vf0Y01eThNfTgDATISwwyikXdjFwFUlDQSoPYqxRZ_vrGS0fwHiP_z3-2P1olAViWanJ20xWQw0BB5BMtpxd8BIVXq58ZLEPTwzfSrkea7D1IbE1CBC3zLNrkrL5l-6jixvOKJZN_LYiBYEO9ebPsxlYeLO-vkiGldZuld1ptL0CWTogi7MpxZ5u-nyrNZ9dGrTpja4T9hx0D9ys2b1wdXJxaMP5kaxU15vMp9CVP96oHTVbWByldMg"
}'

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": "[phone]", - 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:

1. Order Identifier (order_id)

Endpoint

https://{{url_host}}/api/v1/merchants/order/{order_id}/payment-message

1. Unique Payment Message Identifier (payment_message_guid)

Endpoint

https://{{url_host}}/api/v1/counterparty/{counterparty_id}/payment-message/{payment-message_guid}

Example:

curl --location --globoff '{{url_host}}/api/v1/merchants/order/57f86cec-fb2b-443b-8e10-1386c8ba9f2b/payment-message' --header 'CX-Authorization: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IkRoMTZpVHJ2TzlqTDFGQUJtbVhyWFJEOWo4Zk91eE1SaE5lWll1SVc0NVUifQ.eyJpYXQiOjE0MTYyMzkwMjIsImp0aSI6IjNjdmZlMzJyd3EyMzJ3cWNzYWMzc3Nhd3E0NDY2NiJ9.C3e7usk6oEA6Ps6qwsYRQTEjcJWCr6sKNmYhrx_XWcbG_UkEOIQ0XqLxXA0Ww0_VPNLqlr5-VRflTZKslKLg5zsn3OHePze-T_usJ3YWvzLSe4kL7j9Ott_N9-PTRzP3pyfZSI3MqxJFW_5iptEOLRYBKGmsfM9QZriaqoKQ2vY7UHf66nWoaGVNgdbm1lNUnKZ6bXJIYC0Fp5OvtG9S6ajBEMiGr07KjWHr2gBPjPI4rgVFugakQ9jjKJuXImZpfTNsvvPfEtyVKNKGaD1hnGejB04Zc83SGzHJQLQgDweKqchrYhazRRe7QAqKa96W57YNdo3_T4DO0zFG673nbw'

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.