API Reference

Payyus API provides following functions:

  • PART I
    • Authorization
    • 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

Errors

Errors are divided on 2 types:

  • Part I errors
  • Part II errors

Part I errors have only one JSON field - "error". Part II errors have 3 JSON fields - "message-type", "error-code" and "details".

Example Part I error

{
    "error":"operation required"
}

Example Part II error

{
    "message-type":"error",
    "error-code":"message-type required.",
    "details":""
}

Authorization

request field description

  • op required

    The type of operation.
    Must be: loginMerchant

  • merchant_username required

    Username for authorization.
    For example: TestUsername

  • merchant_password required

    Merchant password for authorization.
    For example: mainPassword

  • client_username required

    Developer's identificator.
    For example: clover

  • client_secret required

    Developer's secret key.
    For example: payyus-clover

  • terminal_id required

    Terminal id that you got when registered
    For example: 65

response field description

  • available_transactions

    Amount of transactions for current merchant.
    For example 900

  • terminal

    Terminal status.
    May be : valid or invalid

  • init

    Merchant object for customization.

  • tipActive

    Indicates whether the account maintains a tips.

  • brandingBackColor

    Branding background color
    For example: #00007d

  • brandingForeColor

    Branding foreground color
    For example: #ffffff

  • brandingImage

    URL for merchant image. URL prefix is https://app.payyus.com/phone/

  • token

    Access token object.

  • access_token

    Token for getting access to next requests.

  • expiry_date

    lifetime of access_token
    For example: 2017-11-18 

https://app.payyus.com/terminal-api/terminal-api.php?op=loginMerchant&merchant_username=TestUsername&merchant_password=mainPassword&client_username=clover&client_secret=payyus-clover&terminal_id=65
{
    "available_transactions":"0",
    "terminal":"valid",
    "init":{
        "tipActive":"0",
        "brandingBackColor":"#00007d",
        "brandingForeColor":"#ffffff",
        "brandingImage":"images/app-logo.svg"
    },
    "token":{
        "access_token":"7734c563e068c4
aa6adbacec82c2941436bfdf7b199f928651ff928ac724da56",
        "expiry_date":"2017-11-15"
    }
}
Error Messages Description
merchant username is not registered if merchant_username is not registered.
invalid password if client_secret or client_username is invalid.
client credentials are incorrect if client_secret or client_username is invalid.
invalid terminal id if terminal_id is invalid.

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 example 900 

https://app.payyus.com/terminal-api/terminal-api.php?op=getAvailableTransactions&access_token=7ef547255db89c7560a1a9289654e3e4e427036918f2dd1b6791a11fa812a412&client_username=clover&client_secret=payyus-clover
{
    "available_transactions":"0"
}
Error Messages Description
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 example payyus9

  • serverUrl

    Server url for Web Socket
    For example wss://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"
}
Error Messages Description
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 or error

  • 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"
}
Error Messages Description
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 be payment_result_sentto_terminal or payment_result_sentto_terminal or error

  • shopper-cnum

    Shopper's cnum. See above
    For example: 15c0be999e69385e5786b4959a5b9639

  • payment-result

    Status of payment, success or not.
    Can be: ok or cancelled

  • 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":""
}
Error Messages Description
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.