NAV Navbar

Payop REST-like API Reference

The Payop API is organized around REST.

Payop API has predictable resource-oriented URLs, accepts JSON request bodies, returns JSON responses, and uses standard HTTP response codes.

Each request to Payop API should have Content-Type HTTP header with application/json value.

Authentication

The Payop API uses digital signature to sign requests and public key to authenticate requests.

Digital signature is necessary in order to check the immutability/correctness of the data in the process of transferring them over the network between the participants.

You have to create a project and get project keys to sing and authenticate requests.

Each request to Payop API should have public key to allow us identify merchant, who is made request.

You can view and manage your API keys in the Payop Dashboard.

Checkout Payment

Create payment

The Payop software interface is designed to automate electronic payments. The buyer's bank card data is entered not on the seller’s web page, but on the secure gateway page. Thus, when using Payop, the seller is free from the need to independently ensure the security of the payment information of the buyer.

In order to use the Checkout Payment API, the client must perform the following steps:

After completing these steps, you can start creating payments using the API.

URL for requests

Content-Type: application/json

POST https://payop.com/api/v1.1/payments/payment

Parameters

Request Example

{
    "publicKey": "application-117",
    "order": {
        "id": "345",
        "amount": "100.0000",
        "currency": "USD",
        "description": "Order #10",
        "items": [
            {
                "id": "487",
                "name": "Item 1",
                "price": "42"
            },
            {
                "id": "358",
                "name": "Item 2",
                "price": "58"
            }
        ]
    },
    "signature": "11503f3d4583ef6fd8d762685f965d05a3e6f9d62c09be4e5310cef3eb26c4be",
    "paymentMethod": "120c2c30-05da-11e9-841d-bb3884c6e843",
    "paymentGroup": "cash",
    "language": "en",
    "resultUrl": "https://{merchant_site}/payment-result.html",
    "failUrl": "https://{merchant_site}/payment-failed.html",
    "customer": {
        "email": "any@email.com",
        "phone": "+374841842151",
        "name": "Ivanov Ivan"
    }
}
Parameter Type Description Required
publicKey string Public key issued in the project. *
signature string Signature of payment *
order json object *
order.id string Payment ID *
order.amount number Amount of payment. 4 decimal places *
order.currency string The character code of the payment currency, which is supported by the selected payment method. *
order.description string Description of payment
order.items json array Products or services included in the order. An array containing arbitrary data.
customer json object *
customer.email string Customer email. *
customer.phone string Customer phone. [Required] depending on the selected payment method.
customer.name string The name of the buyer. [Required] depending on the selected payment method.
paymentMethod string Selected payment method code. If not selected, the standard %project% payment page will be displayed.
paymentGroup string Payment group: cards_local, cards_international, ewallet, bank_transfer, prepayment, cash, mobile_operator, internet_banking, crypto.
language string Language payment page (en, ru).
resultUrl string Link to the page of successful payment. If not installed, the %project% platform page will be displayed.
failUrl string Link to unsuccessful payment page. If not installed, the %project% platform page will be displayed.

Successful response

Successful response

{
    "data": {
        "message": "Payment created",
        "redirectUrl": "http://%domain%.com/en/payments/v1.1/payment/pay/81"
    },
    "errors": []
}
Parameter Description
message Information about the result of a payment
redirectUrl URL to redirect the user to the payment platform gateway

Failed response

Failed response

{
    "data": [],
    "errors": [{
        "message": "Selected payment method is not valid or disabled by merchant.",
        "code": "MERCHANT_PAYMENT_METHOD_INVALID"
    }]
}
Parameter Description
message Error text
code Error code

Error codes

Code Description
PARAMETER_MISSING Required parameter were not provided or empty. Make sure requests include all required parameters
AMOUNT_TOO_SMALL The specified amount is less than the minimum amount allowed. Use a higher amount and try again
AMOUNT_DECIMAL_PLACES Amount should have {n} decimal places
CURRENCY_UNSUPPORTED Currency you selected is not supported by the platform
CURRENCY_UNSUPPORTED_BY_PAYMENT_METHOD Currency you selected is not supported by the payment method
LANGUAGE_UNSUPPORTED Language you selected is not supported by the platform
EMAIL_INVALID The email address is invalid (e.g., not properly formatted)
PHONE_INVALID The customer phone is invalid (e.g., not properly formatted)
MERCHANT_PAYMENT_METHOD_INVALID Selected payment method is not valid or disabled by merchant
MERCHANT_DOES_NOT_EXISTS Could not find merchant on the platform
MERCHANT_BLOCKED The merchant is blocked
MERCHANT_NOT_VERIFIED The merchant is not verified
MERCHANT_TURNOVER_LIMIT_EXCEEDED The merchant has exceeded his turnover limit
PAYMENT_GROUP_INVALID Selected invalid payment group
PUBLIC_KEY_DOES_NOT_EXISTS Could not find public key on platform
PROJECT_NOT_VERIFIED Project for public key is not verified
SIGNATURE_INVALID The signature is invalid

Payment signature

Signature generation example

PHP

<?php
    // $order = ['id' => 'FF01', 'amount' => '100.0000', 'currency' => 'USD'];
    \ksort($order, SORT_STRING);
    $dataSet = \array_values($order);
    if ($status) {
        \array_push($dataSet, $status);
    }
    \array_push($dataSet, $secretKey);
    \hash('sha256', \implode(':', $dataSet));

Python

import hashlib

# Create Payment
source = bytes("{}:{}:{}:{}".format(amount, currency, order_id, secret_key), "utf-8")
hashlib.sha256(source).hexdigest()

# Callback
source = bytes("{}:{}:{}:{}:{}".format(amount, currency, order_id, status, secret_key), "utf-8")
hashlib.sha256(source).hexdigest()

Examples of signatures generated from real data

Payment

Amount: "1.2000"
Currency: "USD"
Order ID: "Test-Order-354"
Secret key: "supersecretkey"
Result: 3445000c1f55f447b853fe068529c23fc4188e36aa4984e37836538d95f8e015

Amount: "0.4500"
Currency: "EUR"
Order ID: "FK-288-SDC"
Secret key: "fantastic_supersecretkey"
Result: 15c4c6ee83285dd82e1d7d29984a718cc527f218b8a0bb7e9b951b08ea1f30cd

Callback

Amount: "1.2000"
Currency: "USD"
Order ID: "Test-Order-354"
Secret key: "supersecretkey"
Status: "success"
Result: 9f3a1f0d6b82e641c18a5b34734540257c86dccab81656c871045f01267f50b5

Digital signature of the payment is necessary in order to check the immutability/correctness of the data in the process of transferring them over the network between the participants of the payment.

Signature encryption method - sha256

The parameters that make up the digital signature (the order of the parameters does matter)

Create Payment

Parameter Description Type Example
order[id] Payment ID string FF01; 354
order[amount] Amount of payment. 4 decimal places string 100.0000
order[currency] Character code of payment currency, which is supported by the selected payment method string USD; EUR
secretKey Application secret key string rekrj1f8bc4werwer2343kl23dfasf

Callback

Parameter Description Type Example
order[id] Payment ID string FF01; 354
order[amount] Amount of payment. 4 decimal places string 100.0000
order[currency] Character code of payment currency, which is supported by the selected payment method string USD; EUR
status Internal status of the payment transaction. Used only for IPN request string error; success
secretKey Application secret key string rekrj1f8bc4werwer2343kl23dfasf

URL to generate signature

Request example

curl -X POST \
    https://%project%.com/api/v1.1/payments/signature \
    -H 'Content-Type: application/json' \
    -H 'cache-control: no-cache' \
    -d '{"id":"FK-288-SDC", "amount":"0.4500", "currency":"EUR", "secretKey":"rekrj1f8bc4werwer2343kl23dfasf"}'

Using below url you can test the signature generation.

Content-Type: application/json

POST https://payop.com/api/v1.1/payments/signature

Parameter Description Type Example
id Order ID string FK-288-SDC
amount Amount of payment. 4 decimal places string 0.4500
currency Character code of payment currency string EUR
secretKey Application secret key string rekrj1f8bc4werwer2343kl23dfasf

The payment handler (IPN)

After making a payment and assigning a transaction to one of the final statuses (see the status parameter), the payment gateway sends to the Merchant's server a Instant Payment Notification (IPN).

In order to receive notifications about payments, you have to go to the Projects section, select the current Project for the site that should receive notifications and enter the URL of the page where notifications should be sent. Notifications are sent using an HTTP request, GET or POST method (configured in the Project).

It's very important to check the notification parameters. To verify the integrity of the request and authenticate the source of the sender is used digital signature

IPN parameters

GET request example

https://merchantsite.com//payop/ipn?amount=11.9600&amp;currency=USD&orderId=1439725&email=payer@email
&payopId=4878641864&txid=d9b0180ff658516b168a4ac5f458f6d4e447a20393d561627592a612f15e0814
&status=wait&publicKey=application-1864135468
&type=app&language=en&date=2019-02-12T16:06:25+00:00
&signature=0c7cfbacda97dde092b119eecebd91aaaaaaaaaaa0aca497400

POST request example

curl -X POST \
https://merchantsite.com/payop/ipn \
-H 'Content-Type: application/json' \
-d '{
    "amount": "2.0000",
    "currency": "RUB",
    "orderId": "TEST_JLR_567",
    "email": "payer@email",
    "payopId": 46841564681,
    "txid": "120b29b06cdc8ffffffffffff2ecd3dc78c151cb3b3ed728e1720f6",
    "status": "error",
    "publicKey": "application-23423",
    "type": "app",
    "language": "en",
    "date": "2019-02-12T14:43:55+00:00",
    "signature": "0c7cfbacda97dde092b119eecebd91aaaaaaaaaaa0aca497400",
    "error": {
        "message": "Minimal order amount 1 USD.",
        "code": "INVALID_CONNECTOR_REQUEST"
    }
}'
ParameterSend methodDescription
txid GET | POST Unique string transaction identifier in the system Payop
status GET | POST Transaction status in Payop system
  • wait — pending transaction payment
  • success — transaction is paid
  • error — improper processing of transaction
publicKeyGET | POSTPayment application ID for Payop merchant
typeGET | POSTPayment interface type (button, app)
amountGET | POSTPayment amount. 4 decimal places
currencyGET | POSTPayment currency
signatureGET | POSTDigital signature
languageGET | POSTLanguage of payment countries (en, ru)
dateGET | POSTTransaction creation date
orderIdGET | POSTTransaction ID in the merchant system
emailGET | POSTCustomer email
payopId GET | POST Transaction ID in Payop system
errorPOSTjson object
error.messageDescription of the error
error.codeError technical code

Merchant payment methods

Response example

{
    "data": {
        "total_count": 2,
        "items": [
            {
                "title": "Cards International",
                "img": "https://payop.com/public/front/image/payment_methods/visa_mastercard.jpg",
                "pm_id": "33f4b550-f496-11e8-b956-1374829bc209",
                "type": "cards_international",
                "config": {
                    "fields": [
                        {
                            "name": "email",
                            "type": "email",
                            "required": true
                        }
                    ]
                },
                "currencies": [
                    "EUR",
                    "GBP",
                    "USD"
                ]
            },
            {
                "title": "Latvian Banks",
                "img": "https://payop.com/public/front/image/payment_methods/lietuvos_bankas_eurosistema.jpg",
                "pm_id": "a22f2620-f8ac-11e8-952e-47abdf9a6688",
                "type": "bank_transfer",
                "config": {
                    "fields": [
                        {
                            "name": "email",
                            "type": "email",
                            "required": true
                        },
                        {
                            "name": "name",
                            "type": "text",
                            "required": true
                        }
                    ]
                },
                "currencies": [
                  "USD"
                ]
            }                    
        ]
    },
    "errors": []
}

Get payment methods list available for merchant.

To get access to this resource the request should be signed using keys from verified project.

URL for requests

Content-Type: application/json

POST https://payop.com/api/v1.1/merchant/payment-method

Parameters

Parameter Type Description Example Required
publicKey string Public key, specified in the application application-1 *
signature string Request signature a4c6042f9f5bde59ffbbd68bc6f5c78e7a52 *

Transaction Info

Get transaction Info.

By ID

URL for requests

Content-Type: application/json

POST https://payop.com/api/v1.1/transaction/{id}

{id} - Transaction ID

Parameters

Parameter Type Description Example Required
publicKey string Public key, specified in the application application-1 *
signature string Request signature a4c6042f9f5bde59ffbbd68bc6f5c78e7a52 *

By TXID

URL for requests

Content-Type: application/json

POST https://payop.com/api/v1.1/transaction/{txid}

{txid} - Transaction TXID

Parameters

Parameter Type Description Example Required
publicKey string Public key, specified in the application application-1 *
signature string Request signature a4c6042f9f5bde59ffbbd68bc6f5c78e7a52 *

Request signature

Example of generating a signature

PHP

<?php
    \ksort($requestParams, SORT_STRING);
    $dataSet = \array_values($requestParams);
    \array_push($dataSet, $secretKey);
    \hash('sha256', \implode(':', $dataSet));

Request signature allows to check that requested parameters are not modified and allow to identify requestor.

Request signature has all requested parameters, sorted by keys, excluding signature.

Signature encryption method - sha256