2.6. eCheck integration

2.6.1. eCheck API URL

eCheck transactions are initiated through HTTPS POST request by using URL in the following format:

https://gate.payneteasy.eu/paynet/api/v2/sale-echeck/ENDPOINTID
for integration purposes use staging environment sandbox.payneteasy.eu instead of production gate.payneteasy.eu

The End point ID is an entry point for incoming Merchant’s transactions and is actually the only Payneteasy object which is exposed via API.

2.6.2. eCheck Integration Overview

Payneteasy allows merchants to accept electronic check payments for goods and services purchased via e-commerce websites. An electronic check works much like a regular check, only instead of using a paper check to provide their bank account, routing number and payment authorization, the customer provides the merchant with the necessary payment information through other methods, allowing the merchant to process the information electronically.

eCheck Transaction Flow

Merchant initiates a transaction by sending HTTPS POST request to the eCheck API URL and specifies the parameters according to eCheck Request Parameters Payneteasy Server returns response described in eCheck Response eCheck Request Parameters

eCheck Request Parameter Length/Type Comment Necessity*
client_orderid 128/String Merchant order identifier. Mandatory
order_desc 64k/String Brief order description Mandatory
first_name 50/String Customer’s first name Mandatory
last_name 50/String Customer’s last name Mandatory
ssn 32/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/String Customer’s state . Please see Reference for a list of valid state codes. Mandatory for USA, Canada and Australia Mandatory
zip_code 10/String Customer’s ZIP code Mandatory
country 2/String Customer’s country(two-letter country code). Valid country only US. Mandatory
phone 15/String Customer’s full international phone number, including country code. Optional
email 50/String Customer’s email address. Mandatory
amount 10/Numeric 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 Mandatory
currency 3/String USD for US Dollar Mandatory
routing_number 9/String This element should contain the customer’s 9 digit bank routing number. Mandatory
account_number 20/String This element should contain the customer’s bank account number. Mandatory
check_number 22/String This element should contain the customer’s check number. Optional
check_date 12/String This element should contain the customer’s check date. Format is MM/DD/YYYY Optional
bank_name 128/String This element should contain the customer’s bank name. Optional
ipaddress 45/String Customer’s IP address, included for fraud screening purposes. Mandatory
control 40/String Checksum generated by SHA-1. See Request authorization through control parameter for more details. Mandatory

* leading and trailing whitespace in input parameters will be omitted

eCheck Response

All parameters in response are encoded in application/x-www-form-urlencoded MIME format

eCheck 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.
status See Status List for 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

eCheck Response Example

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

2.6.3. eCheck 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
  • minimal monetary units amount (i.e. cent, penny etc. For amount 0.94 USD value in signing string will be 94, for 10.15 USD value in signing string will be 1015)
  • email
  • merchant_control

A complete string example may look as follows:

59I6email@client.com3E8E45B5-2-42D8-6ECC-FBF6B11B1

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

5b1da0a20a1b9ff4d66caaba15a3e7ee13