3.1. /api/v2/account-verification

Introduction

Account Verification 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.com/paynet/api/v2/account-verification/ENDPOINTID	https://gate.payneteasy.com/paynet/api/v2/account-verification/ENDPOINTID
https://sandbox.payneteasy.com/paynet/api/v2/account-verification/group/ENDPOINTGROUPID	https://gate.payneteasy.com/paynet/api/v2/account-verification/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
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
email	Payer’s e-mail address.	`Necessity`: Required `Type`: String `Length`: 50
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
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: email 4. merchant_control (Control key assigned to Connecting Party account in the Payneteasy gateway system).	`Necessity`: Required `Type`: String `Length`: 128
first_name	Payer’s first name.	`Necessity`: Optional `Type`: String `Length`: 50
last_name	Payer’s last name.	`Necessity`: Optional `Type`: String `Length`: 50
cardrefid	Card reference ID obtained at Card Registration Stage.	`Necessity`: Optional `Type`: String `Length`: 50
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
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
phone	Payer’s full international phone number, including country code.	`Necessity`: Optional `Type`: String `Length`: 15
cell_phone	Payer’s full international cell phone number, including country code.	`Necessity`: Optional `Type`: String `Length`: 15
credit_card_number	Payer’s credit card number. Send either combination of credit_card_number, card_printed_name, expire_month and expire_year or cardrefid, not all.	`Necessity`: Conditional `Type`: Numeric `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
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 Partys 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`: 128

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
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 error this parameter contains the reason for decline or error details.
error-code	The error code is case of error status.

Request Example

POST /paynet/api/v2/account-verification/39915 HTTP/1.1
User-Agent: curl/7.83.0
Accept: */*
Content-Length: 527
Content-Type: application/x-www-form-urlencoded
Connection: close

client_orderid=34T43R77N
&order_desc=Test Order Description
&first_name=John
&last_name=Smith
&birthday=19820115
&address1=100 Main st
&city=Seattle
&state=WA
&zip_code=98102
&country=US
&phone=+12063582043
&cell_phone=+19023384543
&email=john.smith@gmail.com
&ipaddress=65.153.12.232
&site_url=www.google.com
&credit_card_number=4666034752545240
&card_printed_name=CARD HOLDER
&expire_month=12
&expire_year=2099
&cvv2=123
&purpose=user_account1
&server_callback_url=https://httpstat.us/200
&merchant_data=VIP customer
&control=5112b51084be33fa331d995d17b9d82af3bfbbc9

Success Response Example

HTTP/1.1 200
Server: server
Date: Thu, 27 Apr 2023 14:03:58 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 145

type=async-response
&serial-number=00000000-0000-0000-0000-000002e34518
&merchant-order-id=34T43R77N
&paynet-order-id=6994016
&end-point-id=39915

Fail Response Example

HTTP/1.1 200
Server: server
Date: Mon, 22 May 2023 11:14:25 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 152

type=validation-error
&serial-number=00000000-0000-0000-0000-000002e5c583
&merchant-order-id=34T43R77N
&error-message=INVALID_CONTROL_CODE
&error-code=2

Postman Collection

Request Builder

endpointid or groupid	input the ENDPOINTID or ENDPOINTGROUP
client_orderid	make it or use the internal invoice ID
order_desc
cardrefid
first_name
last_name
ssn
birthday
address1
city
state
zip_code
country
phone
cell_phone
email
ipaddress
site_url
credit_card_number
card_printed_name
expire_month
expire_year
cvv2
purpose
merchant_control	input the Control Key
server_callback_url
merchant_data

String to sign

Signature