[УКР](https://hackmd.io/UvXgiPdmRGOs0hwDtc_CEQ) | ENG ![](https://i.imgur.com/ULmPUgP.jpg) :arrow_left: [Guide](https://hackmd.io/QA2NYRliRLGviJl5P4-ZCw) # [1040217] Bulk Card Payment by Token *What is "Token Payment" and how the cards are tokenized, see in the section ["Token Payment"](https://hackmd.io/hELnx1lqQwS9RiactYbLEA).* *What is "Server-Server card payment" and how the sender is authenticated, see in the section "[Server-Server Card Payment](https://hackmd.io/83UDlVHPRf2CxEBCi6ECBg)".* ## Request *See the description of the "Partner", "KeyAES" and "Sign" attributes in the section "[General API Integration Information](https://hackmd.io/ijxPm0xtTpycgTjuU_NHQQ)".* ### Data Structure The Data structure for this operation is formed from the following parameters: :::info <details> <summary>Data structure formation (examples are below)</summary> <br> ~~~ { "Phone": "", "Sum": , "ClientToken": "", "Action": "Prepare"/"Pay", "SuccessCallback": "", "FailedCallback": "", "Service": [ { "Sum": , "Attributes": { "ServiceName": { "uk": "" } }, "ServiceCode": "" } ], "Transaction":{ "TransactionID": "", "TerminalID": "", "DateTime": "" }, "BrowserData": { "device": { "channel": "" }, "browserIP": "", "browserTZ": , "browserLanguage": "", "browserUserAgent": "", "browserColorDepth": , "browserJavaEnabled": , "browserScreenWidth": , "browserScreenHeight": , "fraudhuntFingerprint": "" } } ~~~ </details> ::: |Parameter|Required|Type|Description|Example| |:----:|:----:|:----:|----|:----:| | `Phone` | Yes | String | Client phone number in format: "380xxxxxxxxxxxx". |`380679335544`| | `Sum` | Yes | Integer| Operation sum in kopecks. |1UAH=>`100`| |`ClientToken`|Yes|String|Client card token.|`d1d2a97aac30.. d12c291f4e669`| |`Action`|No|String|Request type: `Prepare` - commission calculation, or `Pay` - payment (default value). |`Prepare` or `Pay`| | `SuccessCallback` | No | String | URL (server) is called for successful operation. See section ["Server-Server Card Payment"](https://hackmd.io/83UDlVHPRf2CxEBCi6ECBg). |`https://partner.host/ cb_success`| | `FailedCallback` | No | String | URL (server) is called for failed operation. See section ["Server-Server Card Payment"](https://hackmd.io/83UDlVHPRf2CxEBCi6ECBg). |`https://partner.host/ cb_fail`| | `Service`^1^ | Yes | Array | Array of structures transmits data for service bulk payment. |See below.| |`BrowserData`|No|Structure|Structure transmits browser data for *3DSecure 2.0*. See section ["BrowserData structure"](https://hackmd.io/83UDlVHPRf2CxEBCi6ECBg#%E2%80%9CBrowserData%E2%80%9D-structure).|See example in section ["BrowserData structure"](https://hackmd.io/83UDlVHPRf2CxEBCi6ECBg#%E2%80%9CBrowserData%E2%80%9D-structure).| |`Transaction`|Yes|Structure|Structure transmits transaction data. See section "[Transaction Structure](https://hackmd.io/ijxPm0xtTpycgTjuU_NHQQ?view#2-Data)".|See example below.| ^1^ **"Service"** Structure Parameters: |Parameter|Required|Type|Description|Example| |:----:|:----:|:----:|----|:----:| | `Sum` | Yes | Integer| Payment sum for the service in kopecks. |1UAH=>`100`| | `Attributes` | Yes | Structure | Structure transmits service data, for example, service name: `ServiceName`.| `{"uk": "Kyiv Teremky; Sports and health services; 001151371"}`| | `ServiceCode` | Yes |String | Alphanumeric service name or its provider. List of these values is individual and formed depending on the Partner's services.|`SL_8`| :::success <details> <summary>Example of "Data" structure</summary> <br> ~~~md { "Phone": "380932799111", "Sum": 14000, "ClientToken": "d1d2a97aac30eefd2d69598425d2bf3b2316a2f84b48e2a1d1b2c291f4e669", "Action": "Pay", "FailedCallback": "https://api.kf.ua/api/paybox/xpay/process_payment/?status=failed&order_id=PAY_xpay_50b21b8b583247f28bd3d4b0a2fb4bec", "SuccessCallback": "https://api.kf.ua/api/paybox/xpay/process_payment/?status=success&order_id=PAY_xpay_50b21b8b583247f28bd3d4b0a2fb4bec", "Service": [ { "Sum": 14000, "Attributes": { "ServiceName": { "uk": "Kyiv Teremky; Sports and health services; 001151371" } }, "ServiceCode": "SL_8" } ], "Transaction": { "TransactionID": "PAY_xpay_50b21b8b583247f28bd3d4b0a2fb4bec", "TerminalID": "1", "DateTime": "20220619 063111" } } ~~~ </details> ::: ## Response *See the general information on the response structure formation in the section "[General API Integration Information](https://hackmd.io/ijxPm0xtTpycgTjuU_NHQQ?view#Response-Structure)"*. ### Parameter "Action":"Prepare" When the request value `"Action":"Prepare"` is sent, the commission calculation data is transmitted in the "Data" response structure: |Parameter|Required|Type|Description|Example| |:----:|:----:|:----:|----|:----:| |`Sum`|Yes|Integer|Sum of the operation in kopecks. |`500`| |`Fee`|Yes|Integer|Sum of commission in kopecks.|`50`| |`TotalSum`|Yes|Integer|Total operation sum in kopecks, including commission.|`550`| :::success <details> <summary>Response example for request value "Action":"Prepare"</summary> <br> ~~~md { "Code": 102, "Message": "done", "Data": { "Sum": 500, "Fee": 50, "TotalSum": 550, "OperationStatus": 7 }, "KeyAES": "", "Sign": "" } ~~~ </details> ::: ### Parameter "Action":"Pay" :::info For payment, you need to repeat the request [104021] with the same data, but specify the value `Pay` in the parameter `Action`. ::: #### Response Examples for Request Value "Action":"Pay" :::success <details> <summary>Request successfully accepted and needs "3DS" verification</summary> <br> ~~~md { "Code": 102, "Message": "need3ds", "Data": { "OperationID": 111, "3dsHtml": "<html page in base64 encoding>", "OperationStatus": 2 }, "KeyAES": "", "Sign": "" } ~~~ </details> ::: :::success <details> <summary>Request successfully accepted and needs "OTP" verification</summary> <br> ~~~md { "Code": 102, "Message": "needOTP", "Data": { "OperationID": 111, "otpJson": "<JSON structure as string>", "OperationStatus": 3 }, "KeyAES": "", "Sign": "" } ~~~ </details> ::: :::success <details> <summary>Operation Successfully Completed</summary> <br> ~~~md { "Code": 200, "Message": "done", "Data": { "OperationID": 555, "OperationStatus": 10 }, "KeyAES": "", "Sign": "" } ~~~ </details> ::: :::success <details> <summary>Operation Failed</summary> <br> ~~~md { "Code": 200, "Message": "done", "Data": { "OperationID": 111, "OperationStatus": 21, "Reason": 3 }, "KeyAES": "", "Sign": "" } ~~~ </details> ::: ## Related Requests [[10101] Card-Card](https://hackmd.io/VYlXRMiWRkimK0sxlTZ2BA) [[10102/101023/101025] Card-Wallet](https://hackmd.io/MUZzd3mTRQeQfBsE-emVVQ) [[10103] Card-IBAN of Individual](https://hackmd.io/9c9kaHeMTH-LiGf_mVWwpg) [[101031] Card-IBAN of Legal Entity](https://hackmd.io/XQDv9qmoRiqFzfzcD0H1uA) [[10150/10051] Card-Phone-Card](https://hackmd.io/ES9hW5BlS6CozQAmULgnRw) **Token Payment** [[104021] Card Payment by Token](https://hackmd.io/I4FJ0d0eStuvfqG2YmS8IQ) [[104121] Auto Debit by Token. MO/TO Operations](https://hackmd.io/X4ImobdtSJ-Hy1qM-p7PWA) **Get Card Data** [[20400/20410] Get Card Data by Phone Number](https://hackmd.io/Xd9OZWXARcSZRTCsu-1jrw) [[20404] Get Card Data by Token](https://hackmd.io/PSdh1ldNSmmJMR4OIhM_-Q) **Get Transaction Data** [[20003] Get Operation Status](https://hackmd.io/_eAjmoG-QPWoWWmsLOGf1g) ## Reference Materials General parameters of the XPAY system are given in the section ["Reference Materials"](https://hackmd.io/16yLv895Qo-FWTvrWWQwbg):  operation types, payment types, response codes, operation status, reasons of operation rejection, etc. ![](https://i.imgur.com/17gAyWb.png) :arrow_left: [Guide](https://hackmd.io/QA2NYRliRLGviJl5P4-ZCw) :arrow_left: [General API Integration Information](https://hackmd.io/ijxPm0xtTpycgTjuU_NHQQ) <details> <summary>XPAY Support</summary> </br> Phone: +38 093 891 92 00 Email: info@xpay.com.ua Telegram: @xpaysupportbot </details>