3.14. /api/v2/sale
Introduction
Sale 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/sale/ENDPOINTID |
https://gate.connpay.com/paynet/api/v2/sale/ENDPOINTID |
https://sandbox.connpay.com/paynet/api/v2/sale/group/ENDPOINTGROUPID |
https://gate.connpay.com/paynet/api/v2/sale/group/ENDPOINTGROUPID |
Request Parameters
Note
Warning
The following characters must be escaped in the parameter values: & + “.
Additional Parameters
For Connecting Party
Note
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 : RequiredType : StringLength : 45 |
customer_browser_accept_header |
Exact content of the HTTP accept headers as sent to the 3DS Requestor from the Cardholder’s browser. |
Necessity : RequiredType : StringLength : 2048 |
customer_browser_javascript_enabled |
Boolean that represents the ability of the cardholder browser to execute JavaScript. |
Necessity : RequiredType : BooleanLength : - |
customer_browser_accept_language |
Value representing the browser language as defined in IETF BCP47. |
Necessity : RequiredType : StringLength : 8 |
customer_browser_user_agent |
Exact content of the HTTP user-agent header. |
Necessity : RequiredType : StringLength : 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 Connecting Party. See details here Upload CRes Result. |
Necessity : OptionalType : StringLength : 256 |
customer_browser_info |
If true, then the fields below must be present. |
Necessity : OptionalType : BooleanLength : - |
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 : OptionalType : StringLength : 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 : OptionalType : BooleanLength : - |
customer_browser_screen_height |
Total height of the Cardholder’s screen in pixels. Becomes required when browser_javaScript_enabled = true. |
Necessity : OptionalType : NumericLength : 6 |
customer_browser_screen_width |
Total width of the cardholder’s screen in pixels. Becomes required when browser_javaScript_enabled = true. |
Necessity : OptionalType : NumericLength : 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 : OptionalType : StringLength : 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 : StringLength : 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 : StringLength : 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 : StringLength : 19-28 |
tds_authentication_result_transaction_id |
xid for 1.0.2 or dsTransID for 2.1.0/2.2.0 |
Type : StringLength : 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 : StringLength : 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 : StringLength : 5 |
Response Parameters
Note
Parameter Name |
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 declined or error this parameter contains the reason for decline or error details. |
error-code |
The error code in case of declined or error status. |
end-point-id |
Endpoint id used for the transaction. |
Request with Cardholder Data Example
POST /paynet/api/v2/sale/39529 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=John
&expire_month=01
&expire_year=2042
&cvv2=123
&client_orderid=34T43R77N
&order_desc=Test Order Description
&first_name=John
&last_name=Smith
&ssn=1267
&birthday=19820115
&address1=100%20Main%20st
&city=Seattle
&state=WA
&zip_code=98102
&country=US
&phone=+12063582043
&cell_phone=+19023384543
&amount=156
&email=john.smith@gmail.com
¤cy=RUB
&ipaddress=65.153.12.232
&site_url=https://doc.connpay.com/
&purpose=user_account1
&redirect_url=http%3A%2F%2Fhttps://doc.connpay.com/%2Fdoc%2Fdummy.htm
&server_callback_url=https%3A%2F%2Fhttpstat.us%2F200
&merchant_data=VIP customer
&dapi_imei=123
&control=c821e33bd22773c05c23725d0b1d2dbd9f191399
POST /paynet/api/v2/sale/39529 HTTP/1.1
User-Agent: curl/7.83.0
Accept: */*
Content-Length: 314
Content-Type: application/x-www-form-urlencoded
Connection: close
&client_orderid=34T43R77N
&order_desc=Test Order Description
&first_name=John
&last_name=Smith
&ssn=1267
&birthday=19820115
&address1=100%20Main%20st
&city=Seattle
&state=WA
&zip_code=98102
&country=US
&phone=+12063582043
&cell_phone=+19023384543
&amount=156
&email=john.smith@gmail.com
¤cy=RUB
&ipaddress=65.153.12.232
&site_url=https://doc.connpay.com/
&purpose=user_account1
&redirect_url=http%3A%2F%2Fhttps://doc.connpay.com/%2Fdoc%2Fdummy.htm
&server_callback_url=https%3A%2F%2Fhttpstat.us%2F200
&merchant_data=VIP customer
&dapi_imei=123
&control=c821e33bd22773c05c23725d0b1d2dbd9f191399
Request with Card Recurring Payment ID Example
POST /paynet/api/v2/sale/39915 HTTP/1.1
Host: sandbox.connpay.com
User-Agent: curl/7.83.0
Accept: */*
Content-Length: 317
Content-Type: application/x-www-form-urlencoded
Connection: close
card_recurring_payment_id=1491954
&cvv2=123
&client_orderid=34T43R77N
&order_desc=Test Order Description
&amount=777
¤cy=USD
&ipaddress=65.153.12.232
&redirect_url=http://doc2.doc2.com/doc/dummy.htm
&server_callback_url=https://httpstat.us/200
&control=80761544c64373d1624240add048d36d42fe528a
Success Response Example
HTTP/1.1 200
Server: server
Date: Wed, 17 Nov 2021 11:03:17 GMT
Content-Type: text/html;charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Keep-Alive: timeout=60
Vary: Accept-Encoding
X-XSS-Protection: 1
Strict-Transport-Security: max-age=31536000
Content-Language: ru-RU
P3P: CP="NOI ADM DEV COM NAV OUR STP"
Content-Encoding: gzip
type=async-response
&serial-number=00000000-0000-0000-0000-000002d9b22a
&merchant-order-id=inv4097763
&paynet-order-id=6768788
&end-point-id=22903
Fail Response Example
HTTP/1.1 200
Server: server
Date: Wed, 17 Nov 2021 13:14:40 GMT
Content-Type: text/html;charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Keep-Alive: timeout=60
Vary: Accept-Encoding
X-XSS-Protection: 1
Strict-Transport-Security: max-age=31536000
Content-Language: ru-RU
P3P: CP="NOI ADM DEV COM NAV OUR STP"
Content-Encoding: gzip
type=validation-error
&serial-number=00000000-0000-0000-0000-000002b36f64
&merchant-order-id=inv4097763
&error-message=End+point+with+id+22903+not+found
&error-code=3
Postman Collection
Request Builder
String to sign |
---|
Signature |
---|
|