Authentication

This API use JSON format for receiving request bodies and passing responses.

This API use RSA signatures (passed in x-sign header) to verify the origin of request. Sign is generated on request body, passed in base64 encoding and verified in the same way. Contact support with your RSA public key to obtain access to this API. See Generating signatures chapter for details.

Usage flow

Payments

• Payment session creation. Session lifetime is 30 days
• Manually expire created session if needed
• Adding payment to a session. It can use secure payment mechanism (using hold before package is delivered) or just general payment
• Confirming secure payment by a seller
• Voiding paid / holded payments

Payments via precoded frames

• Init payment

Informational endpoints

• get list of available cities for delivery
• get list of warehouses
• calculate delivery price based on package dimensions and cities

Postbacks

• after payment session changes its status postback is send to a client (server2server). Postback url is passed on session creation. Postback payload is described below

Endpoints

Testing environment: https://api-qecom.novapay.ua/v1

Merchant_id: 1

Merchant private key:

-----BEGIN RSA PRIVATE KEY-----
MIIEowIBAAKCAQEA7YQwYDqNbDIbUXZL2HYvZX6wi59DgsMlYjwpoSgHvn0RTnWl
/uR2sIJ9tquYh5Ya+TtUhzrc0N6mZPTLUuyK4qKq2NJaG2Xdr2M5LhMjF46llWkD
qMW/CcMdVTTE4b1FxOOXURNmZ7nWCchuiVU9nm0K5qYAQpPJFzwg9uDljYgcMp3N
9L1WaiyzIqJqL4R9L39j2t4yOUb4m44xyjujGViHm5lQBNklkOcsxMlb0T3AVNcA
+KckSl32TdvvmSx9BwzK4SDqQAR8MtKA4hbeA3KGCflRlJKv5KcCpPOOzaoUlaTN
OLmJIhl0/VjpsKqLNMQOyRSkpRVCFhgp6sO/ewIDAQABAoIBAEBaqbTZCIqBRQ+c
as56rzrjybf67hLXByEHxgvJSdfeETtd+x0GD/ahVKiS8+AA1swivDNrynq5aQI/
pXuRZcwkYQAgdpOn1Rn5W3vVaZOvbcP+0SQAeFOPzznP82xqmSXQuKYaCIwgORMr
gG+rbeeoCeUWo0lmu3yVKSVbKDdhXQqQB0EiC1rZoEKr9iKOAS5Hvi7pU/bxpH3a
xEGh8ov8E89UtubiIL+LhqsN5dVgowWiaPbA945z497VgjAu+/I2jQ6HhuyPNhK1
SMa0LExXN5xmzF3WJ8ofVMS/hJbLYWgidfUi+MYCgm3W1YtpnNFBKDiDa83cEWqo
r5/GJYECgYEA9w9yXkAsUe3c3Qw1lGSZJNzSlbwCKA4wMaiLhsZWfyLrkzzQnY+t
tu+5Tfa3EU3bLof3juwSBSVwYcb3ZJWGeVURYQwO3ZirZQ3xxEQTI5FTCuJRPMsf
8oiq6NxgZrK3NdtmtecH6+IvrO/J3UPKc8a+iop3zR2tTU4rs2jAbMECgYEA9hxV
yAGXZavNHfrqIn9NCZLySaYrMKSZj36xCcksHK7do77OmsqAp8wQuxYIPoABNO/8
bd2ry33b8Zd3dv5iRI3GMmmrxQ7yDviKeUptKKBZsm9CWEcGnmNOia+ZyJbRl9Fp
jnrtUNOCQxwz144eTAKLV2JUD6Kgfr1ee1EDbzsCgYEA7Q0zLV/hppLWUno+hq2n
i4kdvXHxl8FVWLBhf+WaZM56voGhoSyU/2wwnq/Uo5PSdGkdjVLRT4LGu+qOwUH/
DzgiPr21HcY43fNtQGYY/w2XYmAYln5HnwynAFtDXAaqZ9CmUm7kWN5j5EkHpXhA
LqpJdOC7ZmHNQNl6cOBXkYECgYA7Qi9VbSyrCmblJRljHQvLllpIaX5UxA1Fg9fU
5197uI8dckAE/WVlAbm1kmSByAiCWpaJTaqj4LYowbO+LxoyL4DdepwlYqfd+vI8
qjMGaTWvxSJQZyms0XSDqoh4x/fHemDUMb0ajRL8XboN2OZqnuI2NDLRYPMMEUTC
pIsTKQKBgGqbsr+cn+Ny2cPO8KCx1y6WWrT2X5k286rjAMGxNNG/aNqejpTixAaJ
dA8rov0FcJ03MOhw69XYxkVGpLqWhtMjiWSYuHJBSspvp0QcD9nQykXDLfO7FeeA
p8WexL0FZSkNlkMbcpMI6U0g51cwacZeGA3qXoKWzWfz2Brmom90
-----END RSA PRIVATE KEY-----

Server public key:

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAw1FeLVQlCYMnxVMPwhHA
AYik6KGfYz0GJW0SP4dBs6XQ2Ap2kP0X3K5WtJNnPehiWf7jJz9XH2Xh/17t37kZ
KXGEdWYtPUAWQItLGSIwmPMau+YBFFvLD8OReFhFXc6sjReSPJSFV8KDtOP7By9u
+KxYqZTVqPxCeYXHOzT7vtDJBJDLbe0pJ3B3wRihMEuHP54X4zqEAi/vbqArhHDD
O07FZpQ3PA/Fkgj8jMTUxU3LxmIIkNIuLz+Ze/PxL88qvRkRoHd73agYSs5bVdCg
urGUs2hGFQap4KiyR0TRtaJujM715y1gjVFN7Khkkol/dJaHRqxUaZv3dlL+RMXG
/wIDAQAB
-----END PUBLIC KEY-----

Payments

POST /session

Creates payment session

request body

successful response

example

curl -X POST -H 'Content-type:application/json' -H 'x-sign: JUmrQmn92kwzsZG1zwTDtYW7RGBC/4ftrfl7e9ik6vksq9qK03ifZEXpQl8+uygAWSos5fAGUqSvqtHR/JxRicaaz9+cnKbwddkm1v/0IeyRcYU9oUI46ut2phaP1br40xlofgSvjbs1Z77x6wlNh2QPke/oHT/LfZKtCCjo/AOIVpPD+jQ14DhRSgepd20JYJHBTyAGkIO6oDeAjgtczcTyARJwYQn4vR9cpedfJx+hvwUD8RZgUYvlKU1ojNNjVmwojklfvxOJVD0G29tNh+I8M5K7qdh/+Ewo5zaLlbB5WLVppwBNIqRsE3PS1xAZyWqVt3tkO2iy6T3DZ08+vQ==' -d '{"merchant_id":1,"client_first_name":"Иванов","client_last_name":"Иван","client_patronymic":"Иванович","client_phone":"+380982850654","metadata":{"lol":"kek"},"callback_url":"http://test.com"}' https://api-qecom.novapay.ua/v1/session -v
Note: Unnecessary use of -X or --request, POST is already inferred.
*   Trying 10.18.16.101...
* TCP_NODELAY set
* Connected to api-qecom.novapay.ua (10.18.16.101) port 80 (#0)
> POST /v1/session HTTP/1.1
> Host: api-qecom.novapay.ua
> User-Agent: curl/7.61.0
> Accept: */*
> Content-type:application/json
> x-sign: JUmrQmn92kwzsZG1zwTDtYW7RGBC/4ftrfl7e9ik6vksq9qK03ifZEXpQl8+uygAWSos5fAGUqSvqtHR/JxRicaaz9+cnKbwddkm1v/0IeyRcYU9oUI46ut2phaP1br40xlofgSvjbs1Z77x6wlNh2QPke/oHT/LfZKtCCjo/AOIVpPD+jQ14DhRSgepd20JYJHBTyAGkIO6oDeAjgtczcTyARJwYQn4vR9cpedfJx+hvwUD8RZgUYvlKU1ojNNjVmwojklfvxOJVD0G29tNh+I8M5K7qdh/+Ewo5zaLlbB5WLVppwBNIqRsE3PS1xAZyWqVt3tkO2iy6T3DZ08+vQ==
> Content-Length: 210
>
* upload completely sent off: 210 out of 210 bytes
< HTTP/1.1 200 OK
< Content-Length: 70
< Content-Type: application/json; charset=utf-8
< Date: Fri, 14 Jun 2019 11:01:40 GMT
< Etag: W/"46-HVjkl/f/vngsaRaKqTRHZ4purpY"
< Strict-Transport-Security: max-age=15552000; includeSubDomains
< X-Content-Type-Options: nosniff
< X-Dns-Prefetch-Control: off
< X-Download-Options: noopen
< X-Frame-Options: SAMEORIGIN
< X-Sign: gzD5ICXRWsG/i2ctOIQUVnhYKUNKJiwgKS5IDyQD7X9JqOWwy9qwZPgZNHVSmVL7IibBocfMNvlaw4tNvnZLNHQ3hRSezEBHGb1RWqEsj6d8FlaQqR+NtGmjA02YvMH9MEIlsw6u1v7WrTB9RdIbkr08R9ISRSM5rkpEQOxGZq9AWNI6bxik9OHL2fM8+xUOy5C1xY/8/RvKUO6U6XNK7NVDPu8ZM3lqQCyUmcDxTFG2wjnp8wM9417I+STnsxskSEbQ2xxOl0QX8K2m3kH7pOGSRt6rEdY+ZRdDbER9xqOAQekGHpm0rvVlL16XzKa93i7w9HCbhUtLdHuhelR6fQ==
< X-Xss-Protection: 1; mode=block
<
* Connection #0 to host api-qecom.novapay.ua left intact
{"id":"28c72df1-6bcc-4fda-9119-d89928de74c5","metadata":{"lol":"kek"}}

POST /expire

Manually expire created session

request body

successful response

empty

POST /payment

Add payment to created session and optionaly initialize its processing

request body

successful response

POST /void

Void paid or holded payments (paid ones can be voided only till 23:59)

request body

successful response

empty. Postback with status update will be sent via postbacks (see Postback schema)

POST /complete-hold

Complete holded payments (created with use_hold: true parameter)

request body

successful response

empty. Postback with status update will be sent via postbacks (see Postback schema)

POST /confirm-delivery-hold

Confirm holded secure delivery session by seller, results in express waybill number return

request body

successful response

POST /get-status

Return current session status

request body

successful response

Payments via precoded frames

POST /frames/init

request body

successful response

Informational endpoints

POST /delivery-price

request body

successful response

POST /delivery-info

request body

list cities

Detailed reference: https://devcenter.novaposhta.ua/docs/services/556d7ccaa0fe4f08e8f7ce43/operations/556d885da0fe4f08e8f7ce46

list warehouses

Detailed reference: https://devcenter.novaposhta.ua/docs/services/556d7ccaa0fe4f08e8f7ce43/operations/556d8211a0fe4f08e8f7ce45

example

curl -X POST -H 'Content-type:application/json' -H 'x-sign: IZfzX4zQEniwANKACIeNaBe4eUiXaQBhZCi/eH9sb7IMtnOYn8DqSvIza5muRLHg7ocyncrxXI+ifV0fJP8M5Z6HOC2EEjaunH5LC7/JOLmVfFsFPPStmtDEHcMFjEICOE2ujNhS2g4BUWb4IygygNjn1LRfi6uib7Sj41S3LTI+kUo2MdBdnDhfBHZo7cbjEqfUoWX0d/7HUJg2UrboHNQClC+DW8Qo+sF3WRyiDqb6G2Tbu1iqlFJBXZStfmEncDb0fybIa0DkJG9g2eLM2LfEDolAZs6St7IlJWXDiSyh9ntyLwBaGWHyz1nH1A7LGL+Pj8QEdmRnpzYU6bx8yA==' -d '{"merchant_id":1,"modelName":"Address","calledMethod":"getCities","methodProperties":{"Ref":"ebc0eda9-93ec-11e3-b441-0050568002cf"}}' https://api-qecom.novapay.ua/v1/delivery-info -v
Note: Unnecessary use of -X or --request, POST is already inferred.
*   Trying 10.18.16.101...
* TCP_NODELAY set
* Connected to api-qecom.novapay.ua (10.18.16.101) port 80 (#0)
> POST /v1/delivery-info HTTP/1.1
> Host: api-qecom.novapay.ua
> User-Agent: curl/7.61.0
> Accept: */*
> Content-type:application/json
> x-sign: IZfzX4zQEniwANKACIeNaBe4eUiXaQBhZCi/eH9sb7IMtnOYn8DqSvIza5muRLHg7ocyncrxXI+ifV0fJP8M5Z6HOC2EEjaunH5LC7/JOLmVfFsFPPStmtDEHcMFjEICOE2ujNhS2g4BUWb4IygygNjn1LRfi6uib7Sj41S3LTI+kUo2MdBdnDhfBHZo7cbjEqfUoWX0d/7HUJg2UrboHNQClC+DW8Qo+sF3WRyiDqb6G2Tbu1iqlFJBXZStfmEncDb0fybIa0DkJG9g2eLM2LfEDolAZs6St7IlJWXDiSyh9ntyLwBaGWHyz1nH1A7LGL+Pj8QEdmRnpzYU6bx8yA==
> Content-Length: 132
>
* upload completely sent off: 132 out of 132 bytes
< HTTP/1.1 200 OK
< Content-Length: 671
< Content-Type: application/json; charset=utf-8
< Date: Fri, 14 Jun 2019 11:15:36 GMT
< Etag: W/"29f-HHAXTQJ7Iy5Xvlxpc4wjokmeBrw"
< Strict-Transport-Security: max-age=15552000; includeSubDomains
< X-Content-Type-Options: nosniff
< X-Dns-Prefetch-Control: off
< X-Download-Options: noopen
< X-Frame-Options: SAMEORIGIN
< X-Sign: TUeZJIdAlRvJCZAvxuTPROD1TM0db0c3dzaJhce7cNTPEeXOMoJt3MyaraMRDX4poMthn41UQRznQ1VLwEdFqLY2dyS1Z4OWk0YzHS4H7VTCvTe4HEjzObcYx0Fcmqkc+ouPobeKMlHEq1JYv/7R4DAP6graXEbwLpHDgKeF+/QBJnERVR/jkrwp+abu7Rv6jsTAuCmZIA7CA8ZSPbohfQnj4q2JVZwX0Vr3+hbfyAq2RlkFAarE7kRiyBqq+CXU6NYFS3KafcV/4Kl2Am7zbIDmhKWxyE/9AdC2Jr9uEE+AGOxkBP+c+g9b32+/sjlmZ1ksoPWcVo51PzDQXNddXA==
< X-Xss-Protection: 1; mode=block
<
* Connection #0 to host api-qecom.novapay.ua left intact
{"success":true,"data":[{"Description":"Агрономічне","DescriptionRu":"Агрономичное","Ref":"ebc0eda9-93ec-11e3-b441-0050568002cf","Delivery1":"1","Delivery2":"1","Delivery3":"1","Delivery4":"1","Delivery5":"1","Delivery6":"1","Delivery7":"0","Area":"71508129-9b87-11de-822f-000c2965ae0e","SettlementType":"563ced13-f210-11e3-8c4a-0050568002cf","IsBranch":"0","PreventEntryNewStreetsUser":null,"Conglomerates":null,"CityID":"890","SettlementTypeDescriptionRu":"село","SettlementTypeDescription":"село","SpecialCashCheck":1}],"errors":[],"warnings":[],"info":{"totalCount":1},"messageCodes":[],"errorCodes":[],"warningCodes":[],"infoCodes":[]}

POST /print-express-waybill

Return express waybill pdf for confirmed secure delivery session

request body

Postback schema

{
    id, --session id
    status, -- see Session statuses chapter
    created_at, -- transaction timestamp
    amount,
    metadata, --additional data passed to server on session creation
    client_first_name,
    client_last_name,
    client_patronymic,
    client_phone,
    external_id,
    delivery: { -- used if secure payment used
        recipient_city,
        recipient_warehouse
    },
    products, -- products array, passed to the system on operation adding
    delivery_amount, -- delivery price
    delivery_status_code, -- used if secure payment used. Statuses is taken from https://devcenter.novaposhta.ua/docs/services/556eef34a0fe4f02049c664e/operations/55702cbba0fe4f0cf4fc53ee
    delivery_status_text
}

Session Statuses

Errors

Errors are divided into to sections validation and processing.

Validation Errors

HTTP status - 400

Structure

{
    type: 'validation',
    errors - array of json schema validation errors with dataPath and message properties
}

Processing Errors

HTTP status - 400

Structure

{
    type: 'processing',
    error
}

Available error messages

Available contragent identifiers for testing

38324133
38130410
3281310142
2878207789
39203133
13669756
37193071
31316718
111111
identifier10
identifier9
identifier3

Generating signatures

• signature generating algorithm: SHA-1
• preferred key: encrypted by password 2048 bit length

Key generating example

Sign generating for PHP language example

When converting data to JSON in PHP, pay attention to the use of JSON_UNESCAPED_UNICODE flag.

Openssl signature generating example

echo -n '{"merchant_id":1,"client_first_name":"Иванов","client_last_name":"Иван","client_patronymic":"Иванович","client_phone":"+380982850654","metadata":{"lol":"kek"},"callback_url":"http://test.com"}'  | openssl dgst -sha1 -sign key.pem |  openssl enc -base64

JUmrQmn92kwzsZG1zwTDtYW7RGBC/4ftrfl7e9ik6vksq9qK03ifZEXpQl8+uygA
WSos5fAGUqSvqtHR/JxRicaaz9+cnKbwddkm1v/0IeyRcYU9oUI46ut2phaP1br4
0xlofgSvjbs1Z77x6wlNh2QPke/oHT/LfZKtCCjo/AOIVpPD+jQ14DhRSgepd20J
YJHBTyAGkIO6oDeAjgtczcTyARJwYQn4vR9cpedfJx+hvwUD8RZgUYvlKU1ojNNj
VmwojklfvxOJVD0G29tNh+I8M5K7qdh/+Ewo5zaLlbB5WLVppwBNIqRsE3PS1xAZ
yWqVt3tkO2iy6T3DZ08+vQ==