3.23. /api/v2/sale-echeck

Introduction

Sale-eCheck 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/sale-echeck/ENDPOINTID

https://gate.payneteasy.com/paynet/api/v2/sale-echeck/ENDPOINTID

Request Parameters

Note

Request must have content-type=application/x-www-form-urlencoded.
Leading and trailing whitespace in input parameters will be omitted.

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

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

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

address1

Payer’s address line 1.
Necessity: Required
Type: String
Length: 50

city

Payer’s city.
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

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

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

routing_number

This element should contain the Payer’s 9 digit bank routing number.
Necessity: Required
Type: String
Length: 9

account_number

This element should contain the Payer’s bank account number.
Necessity: Required
Type: String
Length: 20

check_number

This element should contain the Payer’s check number.
Necessity: Optional
Type: String
Length: 22

check_date

This element should contain the Payer’s check date. Format is MM/DD/YYYY.
Necessity: Optional
Type: String
Length: 12

bank_name

This element should contain the Payer’s bank name.
Necessity: Optional
Type: String
Length: 12

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

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

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.

status

See Status List for 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/sale-echeck/39790 HTTP/1.1
User-Agent: curl/7.83.0
Accept: */*
Content-Length: 314
Content-Type: application/x-www-form-urlencoded
Connection: close

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=+12063582043
&amount=10.55
&email=john.smith@gmail.com
&currency=USD
&ipaddress=65.153.12.232
&routing_number=113024588
&account_number=1234567890
&check_number=77778888
&check_date=02/22/2025
&bank_name=testbank
&server_callback_url=https%3A%2F%2Fhttpstat.us%2F200
&control=5ce2641b344bf35930ba9536055d24f038a1065b

Success Response Example

HTTP/1.1 200
Server: server
Date: Wed, 26 Apr 2023 13:51:16 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: 144

type=async-response
&serial-number=00000000-0000-0000-0000-000002e3450d
&merchant-order-id=902B4FF5
&paynet-order-id=6994012
&end-point-id=39790

Fail Response Example

HTTP/1.1 200
Server: server
Date: Wed, 26 Apr 2023 13:51:16 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: 144

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

Postman Collection

Request Builder

endpointid
client_orderid

make it or use internal invoice ID

order_desc
first_name
last_name
ssn
birthday
address1
city
state
zip_code
country
phone
amount
email
currency
ipaddress
routing_number
account_number
check_number
check_date
bank_name
server_callback_url
merchant_control

String to sign
Signature