Pay request initiation

Methods described on this page:

• POST /pay_request

• GET /pay_request_status

After generating the funding order, the recipient shares the link or QR code with the payer. The payer has several options to process the recipient's data:

• Scanning the QR code using the initiating bank's mobile application

• Scanning the QR code using the smartphone camera

• Clicking on the deeplink, which automatically redirects to the payment interface

Scanning the QR code with the initiating bank's mobile application

This method involves the bank receiving the order_guid parameter, which is embedded in the QR code data as a URL.

Example URL:

https://p2p-service:8080/p2p/order.html?order_guid=d1f54a9f-50d3-4a16-b5a8-e79a45160a8b

The order_guid is passed as a query parameter.

The bank must use the received order_guid in the POST /pay_request request to obtain complete information about the recipient, as well as the recipient bank's public key for data encryption.

POST/pay_request

Endpoint: POST/api/v1/p2p/pay-requests

Body: plain text JWT token

Payload:

{
"debtor": {
"account": "UA41003506518366713636167" 
},
"order_guid": "9479bcb7-84a4-4a07-b0b8-d218d8ad2a53",
"jti": "1234567890" 
}

In response, the DCM platform provides either a positive (intermediate) response or an error message.

Response 202: plain text JWT token

{
"debtor": {
"account": "UA41003506518366713636167"
},
"order_guid": "9479bcb7-84a4-4a07-b0b8-d218d8ad2a53",
"guid": "19aec56f-fbc5-4915-abb4-5dff98c94cf6",
"status": "created"
}

Response 4хх ERROR

{ 
"code": "SOME_CODE", 
"message": "some code description" 
}

Error list:

Code 400:

• "INVALID_DEBTOR_ACCOUNT"

• "INVALID_СREDITOR_PHONE"

• "INVALID_TYPE"

• "INVALID_CURRENCY"

• "UNSUPPORTED_CURRENCY"

• "INVALID_EXTERNAL_ID"

• "EXTERNAL_ID_NOT_UNIQUE"

• "EXPIRES_AT_IS_NOT-FUTURE_DATE"

• "INVALID_PURPOSE"

• "INVALID_REQUEST "

Code 401:

• "AUTHORIZATION_FAILED"

Code 500:

• "INTERNAL_ERROR"

Based on the results of the search and retrieval of recipient data, the DCM platform sends the final set of data to the initiating bank in the form of a "Pay request" callback.

Scanning a QR Code with a Phone Camera / Following a Deeplink

If the QR code is scanned using the device’s camera, the bank client is automatically redirected to the DCM platform’s payment page in the mobile browser. This page displays a list of participating banks along with their respective deeplink payment links for further processing.

If the payer receives a deeplink via a messaging app and clicks on it, the process is the same as scanning a QR code with a camera. The client is automatically redirected to the DCM platform’s payment page, where they can select their bank and proceed with the payment using the provided deeplink links.

The deeplink contains a link to the mobile application of the participating bank and includes the order_guid parameter.

The deeplink structure example: https://awesome-bank.com.ua/deeplinks/payment_create?order_guid=d1f54a9f-50d3-4a16-b5a8-e79a45160a8b&tpm_type=p2p

Before providing the deeplink to the DCM platform, the participating bank must verify that the deeplink is properly registered for Android apps (App Link) and iOS apps (Universal Links).

The DCM platform allows retrieving information about the status of a pay_request using the GET /pay_request_status request.

GET/pay_request_status

Endpoint: GET /api/v1/p2p/pay-requests/:pay_request_guid

Response 2хх OK (same as POST/pay_request )

{
"debtor": {
"account": "UA41003506518366713636167" 
},
"order_guid": "9479bcb7-84a4-4a07-b0b8-d218d8ad2a53",-
"guid": "19aec56f-fbc5-4915-abb4-5dff98c94cf6",
"status": "created" 
}

Response 4хх ERROR

{ 
"code": "SOME_CODE", 
"message": "some code description" 
}

Довідник помилок:

Code 400:

• "INVALID_ORDER_GUID"

Code 401:

• "AUTHORIZATION_FAILED"

Code 404:

• "ORDER NOT FOUND"

Code 500:

• "INTERNAL_ERROR"

The following steps are identical for all P2P transfer scenarios, namely:

• Payment message initiation by the initiating bank

• Processing of the "Pay-in" callback by the recipient's bank

• Processing of the "Pay-out" callback by the initiating bank

• Handling and payment of Gross Settlement Register (GSR)