3.4. /api/v2/documents/add-document

Introduction

Add document is initiated through HTTPS POST request by using URL and the parameters specified below. OAuth HMAC-SHA1 is used for authentication (two-legged mode).

API URLs

Integration Base URL

Production Base URL

https://sandbox.payneteasy.com/paynet/api/v2/documents/add-document/ENDPOINTID/ORDERID

https://gate.payneteasy.com/paynet/api/v2/documents/add-document/ENDPOINTID/ORDERID

Request Headers

Content-Type

The request must contain this header with the following value: binary/octet-stream.

Content-Length

This header specifies correct file size in bytes.

Authorization

OAuth HMAC-SHA1 is used for authentication (two-legged mode).

Request Parameters

Note

Request must have content-type=binary/octet-stream and Authorization headers.

Request parameters

Description

Value

endpoint id

Endpoint of the order. This parameter is passed in request URL.
Necessity: Required
Type: Numeric
Length: 10

order id

Transaction order identifier assigned by Payment Gateway. This parameter is passed in request URL.
Necessity: Required
Type: String
Length: 128

consumer key

Connecting Party’s login name. This parameter is used to calculate signature and is passed in Authorization request header as oauth_consumer_key.
Necessity: Required
Type: String
Length: 20

consumer secret

Connecting Party’s control key. This parameter is used to calculate signature as a part of Encryption key for OAuth HMAC-SHA1.
Necessity: Required
Type: String
Length: 40

file name

Name of the file to upload, e.g. filename.txt. This parameter is passed in the request body as file and in a query part of request URL as fileName.
Necessity: Required
Type: String
Length: 255

comment.

Adds a comment to attached file, accessible via pointing cursor on file in order details page. This parameter is passed in a query part of request URL.
Necessity: Optional
Type: String
Length: 255

file content

Field for the contents of the file. Used to calculate only txt files via bytes per symbol. Use either file content or a combination of file sha1 and file size, not both. Mandatory, if file sha1 and file size fields are empty. This parameter is passed in the request body as a string.
Necessity: Conditional
Type: String
Length: 255

file sha1

Calculate sha1 of the file and insert here. Use either file content or a combination of file sha1 and file size, not both. Mandatory, if file content field is empty. This parameter is passed in base part of request URL, after order id parameter.
Necessity: Conditional
Type: String
Length: 255

file size

Field for file size in bytes. Use either file content or a combination of file sha1 and file size, not both. Mandatory, if file content field is empty. This parameter is passed in Content-Length request header.
Necessity: Conditional
Type: String
Length: 255

Response Parameters

Note

Response has Content-Type: text/html;charset=utf-8 header. All fields are x-www-form-urlencoded, with (0xA) character at the end of each parameter’s value.

Response Parameters

Description

status

May have values such as: success or error. Success means that document attached to order successfully. Error provides error-message.

error-message

If status is error this parameter contains the reason for decline or error details.

Request Example

POST /paynet/api/v2/documents/add-document/6655/1852755/561d839dde5ae8deeced73c14902e04dc746bfc2?fileName=test5.txt&comment=no%20comments HTTP/1.1
Host: sandbox.payneteasy.com
User-Agent: curl/7.83.0
Accept: */*
Content-Type: binary/octet-stream
Content-Length: 7
Authorization: OAuth realm="",oauth_signature_method="HMAC-SHA1",oauth_signature="ItDxdBQtPRqLiKTAOdy%2BAtDB5cI%3D"
Connection: close

Success Response Example

HTTP/1.1 200
Server: server
Date: Tue, 18 Jul 2023 06:10:27 GMT
Content-Type: text/plain;charset=utf-8
Content-Length: 14
Connection: close
X-XSS-Protection: 1
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000

status=success

Fail Response Example

HTTP/1.1 200
Server: server
Date: Tue, 18 Jul 2023 07:37:34 GMT
Content-Type: text/plain;charset=utf-8
Content-Length: 46
Connection: close
X-XSS-Protection: 1
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000

status=error
&error-message=File+hash+mismatch

Request Builder

The file can be uploaded in 2 different ways:

1. Upload file attached to request - to perform this operation the curl request should be executed in the folder with the target file that must be attached. file sha1 and file size parameters must be filled.

2. Upload file with one-line content - to perform this operation file content parameter must be filled.

HTTP method
URL
endpoint ID

input ENDPOINTID

order ID
file size
file content
file sha1
file name
comment
version
consumer key

Input login

consumer secret

Input Control Key

timestamp

nonce

signature method

signature base string
signature
authorization header