API Reference
Payyus API provides following functions:
-
PART I
- Transactions
- Init websocket
-
PART II
- Preparation for payment
- Processing payment
It’s divided on 2 parts: http based protocol and websocket based protocol for taking payment. Part I is http based. It's parameters you can send via http query parameters or with x-www-form-urlencoded header and put it's parameters into request body. Part II is websocet based. All queries must be in JSON format.
https://app.payyus.com/terminal-api/terminal-api.php
Example Part I error
{
"error":"operation required"
}
Example Part II error
{
"message-type":"error",
"error-code":"message-type required.",
"details":""
}
Transactions
request field description
-
op required
The type of operation.
Must be:getAvailableTransactions
-
access_token required
Token which we got after authorization.
-
client_username required
Developer's identificator.
For example:clover
-
client_secret required
Developer's secret key.
For example:payyus-clover
response field description
-
available_transactions
Amount of available transactions for current merchant.
For example900
https://app.payyus.com/terminal-api/terminal-api.php?op=getAvailableTransactions&access_token=7ef547255db89c7560a1a9289654e3e4e427036918f2dd1b6791a11fa812a412&client_username=clover&client_secret=payyus-clover
{
"available_transactions":"0"
}
client credentials are incorrect | if client_secret or client_username is invalid. |
---|---|
Invalid token. Login again | if access_token is invalid. |
Init Websocket
request field description
-
op required
The type of operation.
Must be:initiateWebSocketConnection
-
access_token required
Token which we got after authorize.
-
srv required
Server name which we recieved from first part of customer QR code.
For example:payyus9
-
client_username required
Developer's identificator.
For example:clover
-
client_secret required
Developer's secret key.
For example:payyus-clover
response field description
-
serverId
Server name for Web Socket
For examplepayyus9
-
serverUrl
Server url for Web Socket
For examplewss://app.payyus.com:8443
http://app.payyus.com/terminal-api/terminal-api.php?op=initiateWebSocketConnection&access_token=7ef547255db89c7560a1a9289654e3e4e427036918f2dd1b6791a11fa812a412&srv=payyus9&client_username=clover&client_secret=payyus-clover
{
"serverId":"payyus9",
"serverUrl":"wss://app.payyus.com:8443"
}
client credentials are incorrect | if client_secret or client_username is invalid. |
---|---|
Invalid token. Login again | if access_token is invalid. |
unknown serverId 'payyus9asd' | if srv is invalid. |
Payment preparation
request field description
-
message-type required
Operation type for preparation for payment.
Must be:any_cnum
-
shopper-cnum required
Second part of customer QR code. See above.
For example:524d82b0cf269ee767cb9533f1c2a19b
response field description
-
message-type
Response type for payment preparation.
any_cnum_resp
orerror
-
cnum
Merchant's cnum
For example:953ae8a23097d926a64a0953f314b9de
-
shopper-username
Shopper's email.
For example:watchingyou1984@gmail.com
{
"message-type":"any_cnum",
"shopper-cnum":"524d82b0cf269ee767cb9533f1c2a19b"
}
{
"message-type":"any_cnum_resp",
"cnum":"953ae8a23097d926a64a0953f314b9de",
"shopper-username":"watchingyou1984@gmail.com"
}
message-type required | if message-type is missing. |
---|---|
shopper-cnum required | if shopper-cnum is missing. |
message-invalid-json | if JSON format incorrect. |
Payment processing
request field description
-
message-type required
Operation type for payment processing.
Must be:terminal_ask_shopper_pay
-
merchant-username required
Our merchant username. See Registration.
For example:TestUsername
-
terminal-cnum required
Merchant cnum. See Preparing for payment.
For example:953ae8a23097d926a64a0953f314b9de
-
shopper-cnum required
Second part of customer's QR code. See above.
For example:524d82b0cf269ee767cb9533f1c2a19b
-
amount required
Payment amount.
For example:99.9
response field description
-
message-type
Response type for payment processing.
Can bepayment_result_sentto_terminal
orpayment_result_sentto_terminal
orerror
-
shopper-cnum
Shopper's cnum. See above
For example:15c0be999e69385e5786b4959a5b9639
-
payment-result
Status of payment, success or not.
Can be:ok
orcancelled
-
tip-amount
If the customer left tips.
For example:0
-
pay-amount
Amount of payment.
For example:99.9
-
rewardMessage
First time reward messages.
For example:
{
"message-type":"terminal_ask_shopper_pay",
"merchant-username":"TestUsername",
"terminal-cnum":"953ae8a23097d926a64a0953f
314b9de",
"shopper-cnum":"524d82b0cf269ee767cb9533f
1c2a19b",
"amount":"100"
}
{
"message-type":"payment_result_sentto_terminal",
"shopper-cnum":"15c0be999e69385e5786b4959
a5b9639",
"payment-result":"ok",
"result-reason":"",
"tip-amount":"0",
"pay-amount":100,
"rewardMessage":""
}
amount-invalid | if amount field is incorrect. |
---|---|
message-type required | if message-type is missing. |
message-invalid-json | if JSON format incorrect. |
shopper-cnum required | if shopper-cnum is missing. |