3.11. /api/v2/preauth

Introduction

Preauth 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.connpay.com/paynet/api/v2/preauth/ENDPOINTID	https://gate.connpay.com/paynet/api/v2/preauth/ENDPOINTID
https://sandbox.connpay.com/paynet/api/v2/preauth/group/ENDPOINTGROUPID	https://gate.connpay.com/paynet/api/v2/preauth/group/ENDPOINTGROUPID

Request Parameters

Note

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

Additional Fields for Preauth Transactions

Browser data for 3DS 2.X is gathered by ConnPay system on 3DS authentication stage. For some processing channels, however, the browser data and/or Connecting Party URL for 3DS challenge results must be provided in initial transaction request. Please contact Support manager to clarify if these parameters should be included in request parameters.

The Connecting Party’s site needs to accurately populate the browser information for each transaction. This data can be obtained by Connecting Party’s servers. Ensure that the data is not altered or hard-coded, and that it is unique to each transaction.

Parameter Name	Description	Value
ipaddress	IP address of the browser as returned by the HTTP headers to the 3DS Requestor.	`Necessity`: Required `Type`: String `Length`: 45
customer_browser_accept_header	Exact content of the HTTP accept headers as sent to the 3DS Requestor from the Cardholder’s browser.	`Necessity`: Required `Type`: String `Length`: 2048
customer_browser_javascript_enabled	Boolean that represents the ability of the cardholder browser to execute JavaScript.	`Necessity`: Required `Type`: Boolean `Length`: -
customer_browser_accept_language	Value representing the browser language as defined in IETF BCP47.	`Necessity`: Required `Type`: String `Length`: 8
customer_browser_user_agent	Exact content of the HTTP user-agent header.	`Necessity`: Required `Type`: String `Length`: 2048
tds_areq_notification_url, alias tds_cres_notification_url	Fully qualified URL of Connecting Party system that will receive the CRes message or Error Message. This CRes message must be sent to ConnPay. See details here Upload CRes Result.	`Necessity`: Optional `Type`: String `Length`: 256
customer_browser_info	If true, then the fields below must be present.	`Necessity`: Optional `Type`: Boolean `Length`: -
customer_browser_color_depth	Value representing the bit depth of the colour palette for displaying images, in bits per pixel. Becomes required when browser_javaScript_enabled = true.	`Necessity`: Optional `Type`: String `Length`: 2
customer_browser_java_enabled	Boolean that represents the ability of the cardholder browser to execute Java. Becomes required when browser_javaScript_enabled = true.	`Necessity`: Optional `Type`: Boolean `Length`: -
customer_browser_screen_height	Total height of the Cardholder’s screen in pixels. Becomes required when browser_javaScript_enabled = true.	`Necessity`: Optional `Type`: Numeric `Length`: 6
customer_browser_screen_width	Total width of the cardholder’s screen in pixels. Becomes required when browser_javaScript_enabled = true.	`Necessity`: Optional `Type`: Numeric `Length`: 6
customer_browser_time_zone	Time-zone offset in minutes between UTC and the Cardholder browser local time. Note that the offset is positive if the local time zone is behind UTC and negative if it is ahead. Becomes required when browser_javaScript_enabled = true.	`Necessity`: Optional `Type`: String `Length`: 5

For Payment Institutions

The PSP or Acquirer can fill the 3DS results for each transaction, if 3DS authentication is performed on their side.

Parameter Name	Description	Value
tds_authentication_result_type	Type of result. Possible values are: - SIMPLE	`Type`: String `Length`: 6
tds_authentication_result_authentication_type	Authentication Type. Indicates the type of authentication method the Issuer will use to challenge the Cardholder, whether in the ARes message or what was used by the ACS when in the RReq message. Possible values are: - 01 = Static - 02 = Dynamic - 03 = OOB - 04 = Decoupled - 05-79 = Reserved for EMVCo future use (values invalid until defined by EMVCo) - 80-99 = Reserved for DS use	`Type`: String `Length`: 2
tds_authentication_result_authentication_value	Authentication Value. Payment System-specific value provided by the ACS or the DS using an algorithm defined by Payment System. Authentication Value may be used to provide proof of authentication. A 20-byte value that has been Base64 encoded, giving a 28-byte result	`Type`: String `Length`: 19-28
tds_authentication_result_transaction_id	xid for 1.0.2 or dsTransID for 2.1.0/2.2.0	`Type`: String `Length`: 19-36
tds_authentication_result_transaction_status	Transaction Status. Indicates whether a transaction qualifies as an authenticated transaction or account verification. Possible values are: - Y = Authentication Verification Successful - N = Not Authenticated/Account Not Verified, Transaction denied - U = Authentication/Account Verification Could Not Be Performed, Technical or other problem, as indicated in ARes or RReq - A = Attempts Processing Performed, Not Authenticated/Verified, but a proof of attempted authentication/verification is provided - C = Challenge Required, Additional authentication is required using the CReq/CRes - D = Challenge Required, Decoupled Authentication confirmed - R = Authentication/ Account Verification Rejected, Issuer is rejecting	`Type`: String `Length`: 1
tds_authentication_result_message_version	Message Version Number. Protocol version identifier This shall be the Protocol Version Number of the specification utilised by the system creating this message. The Message Version Number is set by the 3DS Server which originates the protocol with the AReq message. The Message Version Number does not change during a 3DS transaction. Possible values are: - 1.0.2 - 2.1.0 - 2.2.0	`Type`: String `Length`: 5

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 ConnPay.
merchant-order-id	Connecting Party order id.
serial-number	Unique number assigned by ConnPay 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.
end-point-id	Endpoint id used for the transaction.

Request with Cardholder Data Example

POST /paynet/api/v2/preauth/39549 HTTP/1.1
User-Agent: curl/7.83.0
Accept: */*
Content-Length: 314
Content-Type: application/x-www-form-urlencoded
Connection: close

credit_card_number=4538977399606732
&card_printed_name=CARD HOLDER
&expire_month=12
&expire_year=2099
&cvv2=123
&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
&currency=USD
&amount=10.42
&ipaddress=65.153.12.232
&site_url=https://doc.connpay.com/
&purpose=user_account1
&redirect_url=https://doc.connpay.com//doc/dummy.htm
&server_callback_url=https://httpstat.us/200
&merchant_data=VIP customer
&control=768eb8162fc361a3e14150ec46e9a6dd8fbfa483

Request with Card Recurring Payment ID Example

POST /paynet/api/v2/preauth/39549 HTTP/1.1
User-Agent: curl/7.83.0
Accept: */*
Content-Length: 314
Content-Type: application/x-www-form-urlencoded
Connection: close

card_recurring_payment_id=1491927
&cvv2=123
&client_orderid=34T43R77N
&order_desc=Test Order Description
&amount=777
&currency=USD
&ipaddress=65.153.12.232
&redirect_url=https://doc.connpay.com//doc/dummy.htm
&server_callback_url=https://httpstat.us/200
&control=218d377897ce25c2ac69d99de42bc6902eb5bcd8

Success Response Example

HTTP/1.1 200 OK
Server: server
Date: Mon, 05 Sep 2022 10:43:57 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: 139

type=async-response
&serial-number=00000000-0000-0000-0000-000002ddb018
&merchant-order-id=123
&paynet-order-id=6863073
&end-point-id=39914

Fail Response Example

HTTP/1.1 200 OK
Server: server
Date: Mon, 05 Sep 2022 10:51:14 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: 208

type=validation-error
&serial-number=00000000-0000-0000-0000-000002ddb019
&merchant-order-id=123
&error-message=Validate+card+number+failed.+Card+Number+length+must+be+between+16+and+19+digits..
&error-code=8

Postman Collection

Request Builder

endpointid or groupid	input ENDPOINTID or ENDPOINTGROUPID
client_orderid	make it or use internal invoice ID
order_desc
first_name
last_name
ssn
birthday
address1
city
state
zip_code
country
phone
cell_phone
amount
email
currency
ipaddress
site_url
credit_card_number
card_printed_name
expire_month
expire_year
cvv2
purpose
merchant_control	input Control Key
redirect_url
redirect_success_url
redirect_fail_url
server_callback_url
merchant_data
merchant_form_data

String to sign

Signature