1.1.3. Synchronous account verification

Account verification transaction diagram

The Merchant should use Elecsnet API as described in General Account verification Process Flow.

Account verification request Customer checks out the order and Merchant sends Account verification request to Elecsnet server with specified parameters described in Account verification Request Parameters.

Process Account verification Elecsnet server forwards Account verification request to bank acquirer synchronously.

Processing result The bank responds to Elecsnet server with approve or decline for requested Account verification.

Final status Elecsnet server returns status to Merchant.

Process Account verification transaction

For integration purposes use staging environment sandbox.elecsnet.ru instead of production pay.elecsnet.ru. 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://pay.elecsnet.ru/paynet/api/v2/sync/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

Note

Request must have content-type=application/x-www-form-urlencoded.

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

Account verification Request Parameters	Length/Type	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	45/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 URL callbacks]({% post_url 2015-02-19-merchant-callbacks %})	Optional
merchant_data	64k/String	Any additional information for this transaction which may be useful in Merchant’s external systems, e.g. VIP customer, TV promo campaign lead. Will be returned in Status response and Merchant Callback	Optional

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=user_account1
&server_callback_url=https://httpstat.us/200
&merchant_data=VIP customer
&control=768eb8162fc361a3e14150ec46e9a6dd8fbfa483

Unsuccessful Synchronous Account verification Response

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.

Account verification Response Parameter	Description
type	The type of response. May be validation-error, error
merchant-order-id	Merchant order id
serial-number	Unique number assigned by Elecsnet server to particular request from the Merchant.
error-message	Error details
error-code	The error code

Unsuccessful Account verification Response Example

Successful Synchronous Account verification Response

Status Response Parameter	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 Elecsnet
merchant-order-id	Merchant order id
phone	Customer phone
serial-number	Unique number assigned by Elecsnet 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	Electronic link to receipt https://pay.elecsnet.ru/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 reference ID to used in subsequent recurrent payments
verified-3d-status	See 3-D Secure Status List for details
verified-rsc-status	See Random Sum Check Status List for details
merchantdata	If provided in initial request, merchant_data parameter and its value will be included in status response

Successful Account verification 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

Account verification Request Debug

      account verification (by ENDPOINTID)

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

• CURL
• PHP
• Ruby

Copy to clipboard

Copy to clipboard

Copy to clipboard

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 GET 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