📦Order and payment

After ordering a product or service on a website or at a point of sale, if the buyer selects payment via the DCM platform, the Merchant initiates a request using the POST /create_merchant’s_order method.

Endpoint

https://api-0s3og9.integrate.dcmapis.com/api/v1/merchants/order?jwt={{JWT}}'

Payload запиту

{
  "sub": "623e460b-9ffd-41df", - Merchant identifier (uid) 
  "exp": 1719493881, - Order expiration time
  "iat": 1707105971, -  Order creation time
  "amt": 1000, -  Order amount
  "cur": "UAH", -  Order currency
  "ref": "d4ee06f", -  Order number in the Merchant's accounting system
  "prp": "Payment for goods/services", -  Payment purpose
  "url": "https://www.city24.com", - Redirect URL for returning the buyer to the Merchant's website
  "fri": { - Information about the ultimate beneficiary of the funds (optional)
    "frn": "Kyivpark LLC", - Name
    "frc": "0987654321", - Tax number
    "fra": "UA55386780956567", -  Account number (IBAN)
    "frb": "300335", - Servicing bank's code
    "frm": "7791" -  Merchant category code
 }

Example Response:

{
"id":"3aa202bc-6b20-445d-89698274b11c66d0",
"link_deeplinks":"https://api.admin.smaug.armenotech.dev/api/v1/merchants/order?id=3aa202bc-6b20-445d-8969-8274b11c66d0&mobile=1",
"link_qr":"https://api.admin.smaug.armenotech.dev/api/v1/merchants/order?id=3aa202bc-6b20-445d-8969-8274b11c66d0&mobile=0"
}

Based on the received response, the DCM platform generates payment pages with the following payment options:

Scanning a QR code using the mobile app of a participating bank.
Scanning a QR code using the smartphone's camera.
Following a deep link, which automatically redirects to the payment interface.

QR Code Scanning with the Initiator Bank's Mobile App

This involves the Bank receiving the order_id parameter, which is embedded in the QR code data as a URL.

Example URL:

https://api.admin.smaug.armenotech.dev/api/v1/merchants/order?id=3aa202bc-6b20-445d-8969-8274b11c66d0&mobile=1"

order_id is passed as a query parameter.

The Bank must use the received order_id in a GET /merchants/order/nbu/json request to retrieve detailed information about the order.

Endpoint:

https://api-bank1.develop.dcmapis.com/api/v1/merchants/order/nbu/json/a27147e8-94ba-4ff7-82d2-0afd20c07d37

Positive Response (example):

{
  "id": "3aa202bc-6b20", - Order ID 
  "exp": 1719493881, - Order expiration time
  "amt": 1000, - Order amount
  "cur": "UAH", - Order currency
  "ref": "d4ee06f", - Order ID in the Merchant's system
  "prp": "Payment for goods/services", - Payment purpose
  "uid": "623e460b-9ffd-41df", - Merchant identifier 
  "recn": "Merchant", - Merchant's name
  "recc": "44684355", - Merchant's tax identification number
  "acc": "UA553806343157729535", - Merchant's account number (IBAN)
  "mcc": 5231, - Merchant category code
  "logo_url": "https://public-files-city24.svg", - Link to the Merchant's logo (if available)
  "bic": "380634", - Receiver bank's code (servicing the Merchant)
  "fri": { - Information about the ultimate beneficiary of the funds
    "frn": "Kyivpark LLC", - Name
    "frc": "0987654321", - Tax number
    "fra": "UA55386780956567", -  Account (IBAN)
    "frb": "300335", -  Servicing bank's code
    "frm": "7791" - Merchant category code
  },
  "bpk": { - Receiver bank's public key information (needed for encoding payment notification data)
    "alg": "RS256",
    "e": "AQAB",
    "n": "iwdsLwz7LyT4i9MJVfH...",
    "kid": "9A21DD62-DA56-402D-....",
    "kty": "RSA",
    "use": "sig"
  }
}

Negative Response

{
    "error": "func GetMerchantsOrderNbuJSONHandler() failed. Error: failed to get order by ID: get order by guid err: order not found"
}

QR Code Scanning with the Smartphone Camera or using following a Deep Link

This involves automatically redirecting the Bank's customer to the DCM platform’s payment page in their mobile browser. This page displays a list of participating banks along with corresponding deep links for completing the payment.

The deep link contains a reference to the participating bank's mobile app and payment information about the order in JWT format.

The structure of the payment information in JWT fully mirrors the JSON data from the QR code.

Example Deeplink structure:

https://awesome-bank.com.ua/deeplinks/payment_create?order=$JWT

Before providing the deep link to the DCM platform, the participant bank must ensure that such a deep link is correctly registered as an App Link for Android applications and as a Universal Link for iOS.

JWT format

eyJhbGciOiJSUzI1NiIsImtpZCI6IjljMzdlYjc5LWI2YmYtNDQzNC1hYzNhLTM1NTZjOGI0YjBmNyIsInR5cCI6IkpXVCJ9.eyJhY2MiOiJVQTI0MzA1Mjk5MDAwMDAyNjAwMzAwNjcxODE4MSIsImFtdCI6MTAwLCJiaWMiOiIzMDUyOTkiLCJicGsiOnsiYWxnIjoiUlMyNTYiLCJlIjoiQVFBQiIsIm4iOiJpd2RzTHd6N0x5VDRpOU1KVmZIYnVMRVNGcUZONWV6dVhNd2V1bTI1QVRibEt4U3VwZGM4a2FvZF85VlNDODVuM1lJb2NxQXVHUlhCclhXRS1zMmE0aUM0X3lNWFVfbDJBTnQ2TjBSUXpGb2p3Y0M0Sk9MX0RnUHR6QzNTMEdEU2JKbHhMMjNydk04NEpJWGxvX09NQ1RoTGZ4N1ZHSjBJcmNMX0drbW5ZZUpmZ1pKYWxKV1JXUXZpLVcwN1Q2aF85TVVBZzNQMzN5UUpwWk1XWXdUSFlSc2dZcXFHZ2R6eWhKaVc2M0w2WjJwMnJNaFhUNXJSRTVHeFNSaDk0UHJfTzZiNEhscmVhMS1kNXhCbzY2RjEyMXBhNURiV25UMzMzRlZ1MS1OOHl2YldzampoWXpHRjdxcTQxM215REdsU0NkSFNiU0Jfb0UwZjVKQU9QVHhzTFEiLCJraWQiOiI5QTIxREQ2Mi1EQTU2LTQwMkQtODdBNS00NzE0QjExM0RBRDQiLCJrdHkiOiJSU0EiLCJ1c2UiOiJzaWcifSwiY3VyIjoiVUFIIiwiZXhwIjoxNzM4ODU3MzAwLCJmcmkiOm51bGwsImlkIjoiZWFjZDU0ZDUtOTYyOC00YjcxLTkxNmMtNWNhMmYyNWEzYzIzIiwibG9nb191cmwiOiJodHRwczovL3B1YmxpYy1maWxlcy1kY20tcHJlLXByb2QuczMuZXUtY2VudHJhbC0xLmFtYXpvbmF3cy5jb20vcHJlcHJvZC1hZG1pbi5wbmciLCJtY2MiOjQ3MjIsInBycCI6ItCe0L_Qu9Cw0YLQsCDQt9CwINGC0L7QstCw0YAg0LfQs9GW0LTQvdC-INGW0Lcg0LfQsNC80L7QstC70LXQvdC90Y_QvCAjODE3NDE1OGZiNmIxNDAyMGExYTMiLCJyZWNjIjoiNDA2ODgxNzAiLCJyZWNuIjoi0KLQntCSIOKAnNCe0JvQmyDQotCg0JXQktCV0Jsg0JPQoNCj0J_igJ0iLCJyZWYiOiI4MTc0MTU4ZmI2YjE0MDIwYTFhMyIsInVpZCI6Ijk2YjQ4YzdmLWRlOWMtNGNkNC1iNzNjLTZhY2IzOTYyMGY0ZiJ9.iSeSGbhZhjhctHQ4nJtpu6-WgH1v5D513D1GyhwneZGC6Fzjl6wfOaEp9QiwJqAxsd726Xb4sqUUNukniZenjU9hqEJDNNz5leG8CG6d_3Uk3-xx7W_sEUkzlnvuZN9ti_Ih97wDBRQtxzqK6lMqRT2FnP4bgzIgeYY8f7HgqyXLW-INnWyIsM9SlEIfLtPeW-fcyQn-SOLSTHEHk_H_bFTelU_MpKqkvMBWPC_frkCOIde7WqA8Wb9LOoEvaY9YvimIFpDccA98_yphupgE1X-bQljrqF1oAoUOWhY4EJd3A90dw0ENKdEPGvs2tzViOM50fa4fLOods1Ny1PxjfA

PreviousE-commerce NextPayment message