1.2.2. Account Verification

Account verification transaction diagram

The Merchant should use PaynetEasy API as described in General Account verification Process Flow.
Account verification is not supportd for 3D gates.

Merchant -> "PaynetEasy": Account verification request
activate "PaynetEasy"
"PaynetEasy" --> Merchant: Order ID
"PaynetEasy" -> Acquirer: Process Account verification
activate Acquirer
Merchant -> "PaynetEasy": Get status by Order ID
Acquirer --> "PaynetEasy": Processing result
deactivate Acquirer
"PaynetEasy" --> Merchant: Final status
deactivate "PaynetEasy"

Account verification request Customer checks out the order and Merchant sends Account verification request to PaynetEasy server with specified parameters described in Account verification Request Parameters.
Order Id PaynetEasy server sends back the response with orderid. Merchant shows the customer a message like Your order is being processed. Please, wait... and starts polling for status with given orderid as described in Order status asynchronous call.
Process Account verification PaynetEasy server forwards Account verification request to bank acquirer asynchronously. The bank starts processing the transaction.
Get status by Order Id Merchant is polling for status with given orderid as described in Order status asynchronous call.
Processing result The bank responds to PaynetEasy server with approve or decline for requested Account verification.
Final status PaynetEasy server returns status to Merchant through Order status asynchronous call.

Process Account verification transaction

For integration purposes use staging environment sandbox.payneteasy.com instead of production gate.payneteasy.com. Account verification transactions are initiated through HTTPS POST request by using URL in the following format:

Account verification transaction by ENDPOINTID

The End point ID is an entry point for incoming Merchant`s transactions for single currency integration.

https://gate.payneteasy.com/paynet/api/v2/account-verification/ENDPOINTID for account verification transaction

Account verification Request Parameters

In order to initiate a Account verification transaction Merchant sends an HTTPS POST request with the parameters specified in Account verification Request Parameters Table below

Sale Request Parameters Length/Type Comment Necessity*
Account verification Request Parameters 128/String Comment Necessity*
client_orderid 128/String Merchant order identifier. Mandatory
order_desc 64k/String Brief order description Mandatory
card_printed_name 128/String Card printed name Mandatory
first_name 50/String Customer’s first name Optional
last_name 50/String Customer’s last name Optional
ssn 4/Numeric Last four digits of the customer’s social security number. Optional
birthday 8/Numeric Customer’s date of birth, in the format YYYYMMDD. Optional
address1 50/String Customer’s address line 1. Mandatory
city 50/String Customer’s city. Mandatory
state 2-3/String Customer’s state . Please see Reference for a list of valid state codes. Conditional
zip_code 10/String Customer’s ZIP code Mandatory
country 2/String Customer’s country(two-letter country code). Please see Reference for a list of valid country codes. Mandatory
phone 15/String Customer’s full international phone number, including country code. Optional
cell_phone 15/String Customer’s full international cell phone number, including country code. Optional
email 50/String Customer’s email address. Mandatory
credit_card_number 20/Numeric Customer’s credit card number. Mandatory
expire_month 2/Numeric Credit card expiration month Mandatory
expire_year 4/Numeric Credit card expiration year Mandatory
cvv2 3-4/Numeric Customer’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. Mandatory
ipaddress 20/String Customer’s IP address, included for fraud screening purposes. Mandatory
site_url 128/String URL the original Account verification is made from. Optional
purpose 128/String Destination to where the payment goes. It is useful for the merchants who let their clients to transfer money from a credit card to some type of client’s account, e.g. game or mobile phone account. Sample values are: +7123456789; gamer0001@ereality.com etc. This value will be used by fraud monitoring system. Optional
control 40/String Checksum generated by SHA-1. See Request authorization through control parameter for more details. Mandatory
server_callback_url 128/String URL the transaction result will be sent to. Merchant may use this URL for custom processing of the transaction completion, e.g. to collect Account verifications data in Merchant’s database. See more details at Merchant Callbacks Optional
* acquirer can redefine the necessity of some fields so they become mandatory instead of optional
** leading and trailing whitespace in input parameters will be omitted

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

Account verification Request Example

client_orderid=902B4FF5
&order_desc=Test Order Description
&first_name=John
&last_name=Smith
&ssn=1267
&birthday=19820115
&address1=100 Main st
&city=Seattle
&state=WA
&zip_code=98102
&country=US
&phone=%2B12063582043
&cell_phone=%2B19023384543
&email=john.smith@gmail.com
&ipaddress=65.153.12.232
&site_url=www.google.com
&credit_card_number=4538977399606732
&card_printed_name=CARD HOLDER
&expire_month=12
&expire_year=2099
&cvv2=123
&purpose=www.twitch.tv/dreadztv
&server_callback_url=http://doc.payneteasy.com/doc/dummy.htm
&merchant_data=VIP customer
&control=768eb8162fc361a3e14150ec46e9a6dd8fbfa483

Account verification Response

Account verification Response Parameter Description
type The type of response. May be async-response, validation-error, error. 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 Merchant order id
serial-number Unique number assigned by PaynetEasy server to particular request from the Merchant.
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

Account verification Response Example

type=async-response
&serial-number=00000000-0000-0000-0000-0000000624e8
&merchant-order-id=59e1e3ca-5d44-11e1-b3d6-002522b853b4
&paynet-order-id=94935

Account verification Request Debug

endpointid input your ENDPOINTID
client_orderid make it or use your internal invoice ID
order_desc
first_name
last_name
ssn
birthday
address1
city
state
zip_code
country
phone
cell_phone
email
ipaddress
site_url
credit_card_number enter the beginning of the sequence, and then "i"
card_printed_name
expire_month
expire_year
cvv2
purpose
merchant_control input your Control Key
server_callback_url
merchant_data

String to sign
Signature
					
				
			
		
			
		

Server callback result

Upon completion by the System it returns the result on the specified server_callback_url with the following parameters described in Account verification, Return Callback Parameters
The checksum is used to ensure that the callback is initiated for a particular Merchant, and not for anybody else claiming to be such Merchant. This SHA-1 checksum, the control parameter, is created by concatenation of the parameters values in the following order:
  • status
  • orderid
  • client_orderid
  • merchant_control

A complete string example may look as follows:

approvedS279G323P4T1209294c258d6536ababe653E8E45B5-7682-42D8-6ECC-FB794F6B11B1

Encrypt the string using SHA-1 algorithm. The resultant string yields the control parameter. For the above-mentioned example the control will take the following value:

e04bd50531f45f9fc76917ac78a82f3efaf0049c

All parameters are sent via POST method.

Server callback result example

status=declined
&error-message=Decline, refer to card issuer
&error-code=107
&paynet-order-id=S279G323P4T1209294
&merchant-order-id=c258d6536ababe65

Account verification request authorization through control parameter

The checksum is used to ensure that it is a particular Merchant (and not a fraudster) that initiates the transaction. This SHA-1 checksum, the parameter control, is created by concatenation of the parameters values in the following order:

  • ENDPOINTID
  • client_orderid
  • email
  • merchant_control

A complete string example may look as follows:

1902B4FF5john.smith@gmail.comB17F59B4-A7DC-41B4-8FF9-37D986B43D20

Encrypt the string using SHA-1 algorithm. The resultant string yields the control parameter (see Account verification Request Parameters) which is required for request authorization. For the above-mentioned example the control will take the following value:

45dec98f9d69000a9f41bdb4ace47a7755fd47cd

Order status

Merchant must use Order status API call to get the customer’s order transaction status. After any type of transaction is sent to PaynetEasy server and order id is returned, Merchant should poll for transaction status. When transaction is processed on PaynetEasy server side it returns it’s status back to Merchant and at this moment the Merchant is ready to show the customer transaction result, whether it’s approved or declined.

Status API URL

For integration purposes use staging environment sandbox.payneteasy.com instead of production gate.payneteasy.com. Status API calls are initiated through HTTPS POST request by using URL in the following format:

Order status call parameters

Status call parameters Description
login Merchant login name
client_orderid Merchant order identifier of the transaction for which the status is requested
orderid Order id assigned to the order by PaynetEasy
by-request-sn Serial number assigned to the specific request by PaynetEasy. If this field exist in status request, status response return for this specific request.
control Checksum used to ensure that it is PaynetEasy (and not a fraudster) that initiates the callback for a particular Merchant. This is SHA-1 checksum of the concatenation login + client-order-id + paynet-order-id + merchant-control. See Order status API call authorization through control parameter for more details about generating control checksum.

Order Status Response

Status Response Paramete Description
type The type of response. May be status-response
status See Status List for details.
paynet-order-id Order id assigned to the order by PaynetEasy
merchant-order-id Merchant order id
phone Customer phone.
serial-number Unique number assigned by PaynetEasy server to particular request from the Merchant.
last-four-digits Last four digits of customer credit card number.
bin Bank BIN of customer credit card number.
card-type Type of customer credit card (VISA, MASTERCARD, etc).
gate-partial-reversal Processing gate support partial reversal (enabled or disabled).
gate-partial-capture Processing gate support partial capture (enabled or disabled).
transaction-type Transaction type (sale, reversal, capture, preauth).
processor-rrn Bank Receiver Registration Number.
processor-tx-id Acquirer transaction identifier.
receipt-id Electronical link to receipt https://gate.payneteasy.com/paynet/view-receipt/ENDPOINTID/receipt-id/
name Cardholder name.
cardholder-name Cardholder name.
card-exp-month Card expiration month.
card-exp-year Card expiration year.
card-hash-id Unique card identifier to use for loyalty programs or fraud checks.
email Customer e-mail.
bank-name Bank name by customer card BIN.
terminal-id Acquirer terminal identifier to show in receipt.
paynet-processing-date Acquirer transaction processing date.
approval-code Bank approval code.
order-stage The current stage of the transaction processing. See Order Stage for details
loyalty-balance The current bonuses balance of the loyalty program for current operation. if available
loyalty-message The message from the loyalty program. if available
loyalty-bonus The bonus value of the loyalty program for current operation. if available
loyalty-program The name of the loyalty program for current operation. if available
descriptor Bank identifier of the payment recipient.
error-message If status in declined, error, filtered this parameter contains the reason for decline
error-code The error code is case status in declined, error, filtered.
by-request-sn Serial number from status request, if exists in request. Warning parameter amount always shows initial transaction amount, even if status is requested by-request-sn.
card-ref-id Card referense ID to used in subsequent recurrent payments
verified-3d-status See 3d Secure Status List for details
verified-rsc-status See Random Sum Check Status List for details

Order Status Response Example

type=status-response
&serial-number=00000000-0000-0000-0000-00000456fa77
&merchant-order-id=avaw23wefd
&processor-tx-id=PNTEST-3622351
&paynet-order-id=3622351
&status=approved
&amount=0.00
&currency=GBP
&descriptor=Minatory
&transaction-type=account_verification
&receipt-id=54d9a433-5199-38d6-b531-61f383298121
&name=CARD+HOLDER
&cardholder-name=CARD+HOLDER
&card-exp-month=12
&card-exp-year=2099
&email=john.smith%40gmail.com
&processor-rrn=514174311400
&approval-code=473741
&order-stage=av_approved
&merchantdata=VIP+customer
&last-four-digits=6732
&bin=453897
&card-type=VISA
&phone=12063582043
&bank-name=MITSUBISHI+UFJ+NICOS+CO.+LTD.
&auth-response-code=00
&terminal-id=12345678
&paynet-processing-date=2015-05-21+16%3A08%3A30+MSK
&acquirer-processing-date=2015-05-21+16%3A08%3A30+MSK
&by-request-sn=00000000-0000-0000-0000-00000456fa76
&card-hash-id=212643
&card-ref-id=50705
&verified-3d-status=AUTHENTICATED
&verified-rsc-status=AUTHENTICATED

Status request authorization through control parameter

The checksum is used to ensure that it is Merchant (and not a fraudster) that sends the request to PaynetEasy. This SHA-1 checksum, the parameter control, is created by concatenating of the values of the parameters in the following order:

  • login
  • client_orderid
  • orderid
  • merchant_control

For example assume the following values are corresponds the parameters above:

Parameter Name Parameter Value
login cool_merchant
client_orderid 5624444333322221111110
orderid 9625
merchant_control r45a019070772d1c4c2b503bbdc0fa22

The complete string example may look as follows:

cool_merchant56244443333222211111109625r45a019070772d1c4c2b503bbdc0fa22

Encrypt the string using SHA-1 algorithm. The resultant string yields the control parameter which is required for authorizing the callback. For the example control above will take the following value:

c52cfb609f20a3677eb280cc4709278ea8f7024c

Order status Debug

endpointid input your ENDPOINTID
login
client_orderid input your Invoice Number
orderid
merchant_control input your Control Key
by-request-sn

String to sign
Signature