3.20. /api/v2/sale

Introduction

Sale is initiated through HTTPS POST request by using URLs and the parameters specified below. Use SHA-1 for authentication. See Statuses.

API URLs

Integration

Production

https://sandbox.payneteasy.eu/paynet/api/v2/sale/ENDPOINTID

https://gate.payneteasy.eu/paynet/api/v2/sale/ENDPOINTID

https://sandbox.payneteasy.eu/paynet/api/v2/sale/group/ENDPOINTGROUPID

https://gate.payneteasy.eu/paynet/api/v2/sale/group/ENDPOINTGROUPID

Request Parameters

Note

Request must have content-type=application/x-www-form-urlencoded.
Acquirer can redefine the necessity of some fields so they become required instead of optional.
Leading and trailing whitespace in input parameters will be omitted.

Warning

The following characters must be escaped in the parameter values: & + .

Parameter Name

Description

Value

client_orderid

Unique order identifier assigned by Connecting Party.

Necessity: Required
Type: String
Length: 128

order_desc

Brief order description.

Necessity: Required
Type: String
Length: 64k

amount

Amount to be charged. The amount has to be specified in the highest units with . delimiter. For instance, 10.5 for USD means 10 US Dollars and 50 Cents.

Necessity: Required
Type: Numeric
Length: 10

currency

Currency the transaction is charged in (See: Currency codes). Sample values are: USD for US Dollar EUR for European Euro.

Necessity: Required
Type: String
Length: 3

address1

Payer’s address line 1.

Necessity: Required
Type: String
Length: 50

city

Payer’s city.

Necessity: Required
Type: String
Length: 50

zip_code

Payer’s ZIP code.

Necessity: Required
Type: String
Length: 10

country

Payer’s country. Please see Country codes for a list of valid country codes.

Necessity: Required
Type: String
Length: 2

phone

Payer’s full international phone number, including country code.

Necessity: Required
Type: String
Length: 15

email

Payer’s e-mail address.

Necessity: Required
Type: String
Length: 50

ipaddress

Payer’s IP address, included for fraud screening purposes.

Necessity: Required
Type: String
Length: 45

control

Checksum generated by SHA-1. Control string is represented as concatenation of the following parameters:
1. <ENDPOINTID | ENDPOINTGROUPID> (See: Request URL)
2. Request parameter: client_orderid
3. Request parameter: amount (in minor units)
4. Request parameter: email
5. merchant_control (Control key assigned to Connecting Party account in the Payneteasy gateway system).
Necessity: Required
Type: String
Length: 40

cvv2

Payer’s CVV2 code. CVV2 (Card Verification Value) is a three- or four-digit number AFTER the credit card number in the signature area of the card.

Necessity: Required
Type: Numeric
Length: 3-4

credit_card_number

Payer’s credit card number. Send either combination of credit_card_number, card_printed_name, expire_month and expire_year or card_recurring_payment_id, not all.

Necessity: Conditional
Type: Numeric
Length: 20

card_recurring_payment_id

Payer’s tokenized cardholder’s data ID. Send either card_recurring_payment_id or combination of credit_card_number, card_printed_name, expire_month and expire_year, not all. To create card_recurring_payment_id see /api/v4/create-card-ref.

Necessity: Conditional
Type: Long
Length: 20

card_printed_name

Cardholder name, printed on the bank card.

Necessity: Conditional
Type: String
Length: 128

expire_month

Bank card expiration month.

Necessity: Conditional
Type: Numeric
Length: 2

expire_year

Bank card expiration year.

Necessity: Conditional
Type: Numeric
Length: 4

first_name

Payer’s first name. Parameter necessity depends on the Acquiring channel and necessity of it must be clarified with Tech Support.

Necessity: Required
Type: String
Length: 50

last_name

Payer’s last name. Parameter necessity depends on the Acquiring channel and necessity of it must be clarified with Tech Support.

Necessity: Required
Type: String
Length: 50

state

Payer’s state. Please see Mandatory State codes for a list of valid state codes. Required for USA, Canada and Australia.

Necessity: Conditional
Type: String
Length: 2-3

redirect_url

URL, where the Payer is redirected to upon completion of the transaction. Please note that redirection is performed in any case, no matter whether transaction is approved, declined in any other final status.
Connecting Party must not use the parameters come along with the redirect HTTP Request to treat the status of the transaction. Instead Connecting Party can utilize server_callback_url or status API command. Pass http://https://doc.payneteasy.eu if you have no need to return payer anywhere. Use either redirect_url or combination of redirect_success_url and redirect_fail_url, not both.
Necessity: Optional
Type: String
Length: 1024

redirect_success_url

URL, where the Payer is redirected to when transaction status is approved (See status list).
Connecting Party must not use the parameters come along with the redirect HTTP Request to treat the status of the transaction. Instead Connecting Party can utilize server_callback_url or status API command. Otherwise put http://https://doc.payneteasy.eu if there is no need to redirect Payer anywhere. Use either combination of redirect_success_url and redirect_fail_url or redirect_url, not both.
Necessity: Optional
Type: String
Length: 1024

redirect_fail_url

URL, where the Payer is redirected to when transaction status is not approved (See status list).
Connecting Party must not use the parameters come along with the redirect HTTP Request to treat the status of the transaction. Instead Connecting Party can utilize server_callback_url or status API command. Pass http://https://doc.payneteasy.eu if there is no need to redirect Payer anywhere. Use either combination of redirect_fail_url and redirect_success_url or redirect_url, not both.
Necessity: Optional
Type: String
Length: 1024

ssn

Last four digits of the payer’s social security number.

Necessity: Optional
Type: Numeric
Length: 32

birthday

Payer’s date of birth, in the format YYYYMMDD.

Necessity: Optional
Type: Numeric
Length: 8

cell_phone

Payer’s full international cell phone number, including country code.

Necessity: Optional
Type: String
Length: 15

site_url

The URL of the E-commerce entity, where the payment is originated from.

Necessity: Optional
Type: String
Length: 128

purpose

Destination to where the payment goes. It is useful for the Connecting Party’s who let their payers to top up their accounts with bank card (Mobile phone accounts, game accounts etc.). Sample values are: +7123456789; gamer0001@ereality.com etc. This value can be used by the fraud monitoring system.

Necessity: Optional
Type: String
Length: 128

server_callback_url

URL, where the transaction status is sent to.
Connecting Party may use server callback URL for custom processing of the transaction completion, e.g. to collect payment data in the Connecting Party’s information system. For the list of parameters which come along with server callback to server_callback_url refer to Connecting Party callback parameters.
Necessity: Optional
Type: String
Length: 1024

merchant_data

Custom Connecting Party details, which can be attached to the transaction and passed back in the status response, Connecting Party callback parameters or server_callback_url. Additional information of transaction which may be useful in Connecting Party’s external system, e.g. VIP customer, TV promo campaign lead.
Information returns in Status response and Connecting Party Callback.
Necessity: Optional
Type: String
Length: 64k

dapi_imei

Unique device identifier.

Necessity: Optional
Type: String
Length: 32

minimum_transaction_amount

This parameter can be used to limit the minimum transaction amount, if transaction amount is submitted by Payer on the form. Contact support manager to enable this feature. Value format is the same as in the amount parameter.

Necessity: Optional
Type: Numeric
Length: 10

maximum_transaction_amount

This parameter can be used to limit the maximum transaction amount, if transaction amount is submitted by Payer on the form. Contact support manager to enable this feature. Value format is the same as in the amount parameter.

Necessity: Optional
Type: Numeric
Length: 10

customer_level

Customer level in CMS system.

Necessity: Optional
Type: Varchar
Length: 32

customer_id

Customer ID in CMS system. Necessity becomes required if transaction goes via CMS (PNE).

Necessity: Optional
Type: Int
Length: 10

merchant_customer_identifier

Connecting Party Customer ID in CMS system. Necessity becomes required if transaction goes via CMS (CRM).

Necessity: Optional
Type: Varchar
Length: 64

recurring-payment-id

Recurring Payment ID can be sent instead of cardholder data. CVV for native is not needed. Customer Data can be updated via /api/v4/update-recurring-payment/. Recurring Payment ID creation is initiated through HTTPS POST request by using URLs and the parameters specified below. Use OAuth RSA-SHA256 for authentication.

Necessity: Conditional
Type: Long

Additional Parameters

For Connecting Party

Note

Browser data for 3DS 2.X is gathered by Connecting Party system on 3DS authentication stage. For some processing channels, however, the browser data and/or Connecting Party URL for 3DS challenge results must be provided in initial transaction request. Please contact Support manager to clarify if these parameters should be included in request parameters.

The Connecting Party’s site needs to accurately populate the browser information for each transaction. This data can be obtained by Connecting Party’s servers. Ensure that the data is not altered or hard-coded, and that it is unique to each transaction.

Parameter Name

Description

Value

ipaddress

IP address of the browser as returned by the HTTP headers to the 3DS Requestor.

Necessity: Required
Type: String
Length: 45

customer_browser_accept_header

Exact content of the HTTP accept headers as sent to the 3DS Requestor from the Cardholder’s browser.

Necessity: Required
Type: String
Length: 2048

customer_browser_javascript_enabled

Boolean that represents the ability of the cardholder browser to execute JavaScript.

Necessity: Required
Type: Boolean
Length: -

customer_browser_accept_language

Value representing the browser language as defined in IETF BCP47.

Necessity: Required
Type: String
Length: 8

customer_browser_user_agent

Exact content of the HTTP user-agent header.

Necessity: Required
Type: String
Length: 2048

tds_areq_notification_url, alias tds_cres_notification_url

Fully qualified URL of Connecting Party system that will receive the CRes message or Error Message. This CRes message must be sent to Connecting Party. See details here Upload CRes Result.

Necessity: Optional
Type: String
Length: 256

customer_browser_info

If true, then the fields below must be present.

Necessity: Optional
Type: Boolean
Length: -

customer_browser_color_depth

Value representing the bit depth of the colour palette for displaying images, in bits per pixel. Becomes required when browser_javaScript_enabled = true.

Necessity: Optional
Type: String
Length: 2

customer_browser_java_enabled

Boolean that represents the ability of the cardholder browser to execute Java. Becomes required when browser_javaScript_enabled = true.

Necessity: Optional
Type: Boolean
Length: -

customer_browser_screen_height

Total height of the Cardholder’s screen in pixels. Becomes required when browser_javaScript_enabled = true.

Necessity: Optional
Type: Numeric
Length: 6

customer_browser_screen_width

Total width of the cardholder’s screen in pixels. Becomes required when browser_javaScript_enabled = true.

Necessity: Optional
Type: Numeric
Length: 6

customer_browser_time_zone

Time-zone offset in minutes between UTC and the Cardholder browser local time. Note that the offset is positive if the local time zone is behind UTC and negative if it is ahead. Becomes required when browser_javaScript_enabled = true.

Necessity: Optional
Type: String
Length: 5

For Payment Institutions

The PSP or Acquirer can fill the 3DS results for each transaction, if 3DS authentication is performed on their side.

Parameter Name

Description

Value

tds_authentication_result_type

Type of result. Possible values are:
- SIMPLE
Type: String
Length: 6

tds_authentication_result_authentication_type

Authentication Type. Indicates the type of authentication method the Issuer will use to challenge the Cardholder, whether in the ARes message or what was used by the ACS when in the RReq message. Possible values are:
- 01 = Static
- 02 = Dynamic
- 03 = OOB
- 04 = Decoupled
- 05-79 = Reserved for EMVCo future use (values invalid until defined by EMVCo)
- 80-99 = Reserved for DS use
Type: String
Length: 2

tds_authentication_result_authentication_value

Authentication Value. Payment System-specific value provided by the ACS or the DS using an algorithm defined by Payment System. Authentication Value may be used to provide proof of authentication. A 20-byte value that has been Base64 encoded, giving a 28-byte result

Type: String
Length: 19-28

tds_authentication_result_transaction_id

xid for 1.0.2 or dsTransID for 2.1.0/2.2.0

Type: String
Length: 19-36

tds_authentication_result_transaction_status

Transaction Status. Indicates whether a transaction qualifies as an authenticated transaction or account verification. Possible values are:
- Y = Authentication Verification Successful
- N = Not Authenticated/Account Not Verified, Transaction denied
- U = Authentication/Account Verification Could Not Be Performed, Technical or other problem, as indicated in ARes or RReq
- A = Attempts Processing Performed, Not Authenticated/Verified, but a proof of attempted authentication/verification is provided
- C = Challenge Required, Additional authentication is required using the CReq/CRes
- D = Challenge Required, Decoupled Authentication confirmed
- R = Authentication/ Account Verification Rejected, Issuer is rejecting
Type: String
Length: 1

tds_authentication_result_message_version

Message Version Number. Protocol version identifier This shall be the Protocol Version Number of the specification utilised by the system creating this message. The Message Version Number is set by the 3DS Server which originates the protocol with the AReq message. The Message Version Number does not change during a 3DS transaction. Possible values are:
- 1.0.2
- 2.1.0
- 2.2.0
Type: String
Length: 5

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.

Parameter Name

Description

type

The type of response. May be async-response, validation-error, error etc..
If type equals validation-error or error, error-message and error-code parameters contain error details.

paynet-order-id

Order id assigned to the order by Payneteasy.

merchant-order-id

Connecting Party order id.

serial-number

Unique number assigned by Payneteasy server to particular request from the Connecting Party.

error-message

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

error-code

The error code in case of declined or error status.

end-point-id

Endpoint id used for the transaction.

Request with Cardholder Data Example

POST /paynet/api/v2/sale/39529 HTTP/1.1
User-Agent: curl/7.83.0
Accept: */*
Content-Length: 314
Content-Type: application/x-www-form-urlencoded
Connection: close

credit_card_number=4538977399606732
&card_printed_name=John
&expire_month=01
&expire_year=2042
&cvv2=123
&client_orderid=34T43R77N
&order_desc=Test Order Description
&first_name=John
&last_name=Smith
&ssn=1267
&birthday=19820115
&address1=100%20Main%20st
&city=Seattle
&state=WA
&zip_code=98102
&country=US
&phone=+12063582043
&cell_phone=+19023384543
&amount=156
&email=john.smith@gmail.com
&currency=RUB
&ipaddress=65.153.12.232
&site_url=https://doc.payneteasy.eu
&purpose=user_account1
&redirect_url=http%3A%2F%2Fhttps://doc.payneteasy.eu%2Fdoc%2Fdummy.htm
&server_callback_url=https%3A%2F%2Fhttpstat.us%2F200
&merchant_data=VIP customer
&dapi_imei=123
&control=c821e33bd22773c05c23725d0b1d2dbd9f191399
Request for SBP Example
POST /paynet/api/v2/sale/39529 HTTP/1.1
User-Agent: curl/7.83.0
Accept: */*
Content-Length: 314
Content-Type: application/x-www-form-urlencoded
Connection: close

&client_orderid=34T43R77N
&order_desc=Test Order Description
&first_name=John
&last_name=Smith
&ssn=1267
&birthday=19820115
&address1=100%20Main%20st
&city=Seattle
&state=WA
&zip_code=98102
&country=US
&phone=+12063582043
&cell_phone=+19023384543
&amount=156
&email=john.smith@gmail.com
&currency=RUB
&ipaddress=65.153.12.232
&site_url=https://doc.payneteasy.eu
&purpose=user_account1
&redirect_url=http%3A%2F%2Fhttps://doc.payneteasy.eu%2Fdoc%2Fdummy.htm
&server_callback_url=https%3A%2F%2Fhttpstat.us%2F200
&merchant_data=VIP customer
&dapi_imei=123
&control=c821e33bd22773c05c23725d0b1d2dbd9f191399

Request with Card Recurring Payment ID Example

POST /paynet/api/v2/sale/39915 HTTP/1.1
Host: sandbox.payneteasy.eu
User-Agent: curl/7.83.0
Accept: */*
Content-Length: 317
Content-Type: application/x-www-form-urlencoded
Connection: close

card_recurring_payment_id=1491954
&cvv2=123
&client_orderid=34T43R77N
&order_desc=Test Order Description
&amount=777
&currency=USD
&ipaddress=65.153.12.232
&redirect_url=http://doc2.doc2.com/doc/dummy.htm
&server_callback_url=https://httpstat.us/200
&control=80761544c64373d1624240add048d36d42fe528a

Success Response Example

HTTP/1.1 200
Server: server
Date: Wed, 17 Nov 2021 11:03:17 GMT
Content-Type: text/html;charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Keep-Alive: timeout=60
Vary: Accept-Encoding
X-XSS-Protection: 1
Strict-Transport-Security: max-age=31536000
Content-Language: ru-RU
P3P: CP="NOI ADM DEV COM NAV OUR STP"
Content-Encoding: gzip

type=async-response
&serial-number=00000000-0000-0000-0000-000002d9b22a
&merchant-order-id=inv4097763
&paynet-order-id=6768788
&end-point-id=22903

Fail Response Example

HTTP/1.1 200
Server: server
Date: Wed, 17 Nov 2021 13:14:40 GMT
Content-Type: text/html;charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Keep-Alive: timeout=60
Vary: Accept-Encoding
X-XSS-Protection: 1
Strict-Transport-Security: max-age=31536000
Content-Language: ru-RU
P3P: CP="NOI ADM DEV COM NAV OUR STP"
Content-Encoding: gzip

type=validation-error
&serial-number=00000000-0000-0000-0000-000002b36f64
&merchant-order-id=inv4097763
&error-message=End+point+with+id+22903+not+found
&error-code=3

Postman Collection

Request Builder

endpointid or groupid

input ENDPOINTID or ENDPOINTGROUPID

client_orderid

make it or use internal invoice ID

order_desc
first_name
last_name
ssn
birthday
address1
city
state
zip_code
country
phone
cell_phone
amount
email
currency
card_recurring_payment_id

use either RPI or card number, not both

ipaddress
site_url
credit_card_number

card_printed_name
expire_month
expire_year
cvv2
purpose
merchant_control

input Control Key

redirect_url
redirect_success_url
redirect_fail_url
server_callback_url
merchant_data
dapi_imei

String to sign
Signature