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.gitpay.tech/paynet/api/v2/preauth/ENDPOINTID |
https://gate.gitpay.tech/paynet/api/v2/preauth/ENDPOINTID |
https://sandbox.gitpay.tech/paynet/api/v2/preauth/group/ENDPOINTGROUPID |
https://gate.gitpay.tech/paynet/api/v2/preauth/group/ENDPOINTGROUPID |
Request Parameters
Note
Parameter Name |
Description |
Value |
---|---|---|
client_orderid |
Unique order identifier assigned by Connecting Party. |
Necessity : RequiredType : StringLength : 128 |
order_desc |
Brief order description. |
Necessity : RequiredType : StringLength : 125 |
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 : RequiredType : NumericLength : 10 |
currency |
Currency the transaction is charged in (See: Currency codes). Sample values are: USD for US Dollar EUR for European Euro. |
Necessity : RequiredType : StringLength : 3 |
address1 |
Payer’s address line 1. |
Necessity : RequiredType : StringLength : 50 |
city |
Payer’s city. |
Necessity : RequiredType : StringLength : 50 |
zip_code |
Payer’s ZIP code. |
Necessity : RequiredType : StringLength : 10 |
country |
Payer’s country. Please see Country codes for a list of valid country codes. |
Necessity : RequiredType : StringLength : 2 |
phone |
Payer’s full international phone number, including country code. |
Necessity : RequiredType : StringLength : 15 |
Payer’s e-mail address. |
Necessity : RequiredType : StringLength : 50 |
|
ipaddress |
Payer’s IP address, included for fraud screening purposes. |
Necessity : RequiredType : StringLength : 45 |
control |
Checksum generated by SHA-1. Control string is represented as concatenation of the following parameters:
1. <ENDPOINTID | ENDPOINTGROUPID> (See: Request URL).
2. Request parameter: client_orderid.
3. Request parameter: amount in minor units (if sent).
4. Request parameter: email.
5. merchant_control (Control key assigned to Connecting Party account in the GitPay gateway system).
|
Necessity : RequiredType : StringLength : 40 |
cvv2 |
Payer’s CVV2 code. CVV2 (Card Verification Value) is a three- or four-digit number printed on the back of the card in the signature area. |
Necessity : RequiredType : NumericLength : 3-4 |
credit_card_number |
Payer’s bank card number (also known as PAN - Primary Account Number). |
Necessity : RequiredType : NumericLength : 20 |
card_recurring_payment_id |
Payer’s tokenized cardholder’s data ID. Send either card_recurring_payment_id or combination of credit_card_number, card_printed_name, expire_month and expire_year, not all. To create card_recurring_payment_id see /api/v2/create-card-ref. |
Necessity : RequiredType : LongLength : 20 |
card_printed_name |
Cardholder name, printed on the bank card. |
Necessity : RequiredType : StringLength : 64k |
expire_month |
Bank card expiration month. |
Necessity : RequiredType : NumericLength : 2 |
expire_year |
Bank card expiration year. |
Necessity : RequiredType : NumericLength : 4 |
first_name |
Payer’s first name. |
Necessity : RequiredType : StringLength : 50 |
last_name |
Payer’s last name. |
Necessity : RequiredType : StringLength : 50 |
state |
Payer’s state. Please see Mandatory State codes for a list of valid state codes. Required for USA, Canada and Australia. |
Necessity : ConditionalType : StringLength : 2-3 |
redirect_url |
URL, where the Payer is redirected to upon completion of the transaction.
Please note that redirection is performed in any case, no matter whether transaction is approved, declined in any other final status.
Connecting Party must not use the parameters come along with the redirect HTTP Request to treat the status of the transaction.
Instead Connecting Party can utilize server_callback_url or status API command.
Pass https://doc.gitpay.tech/ if you have no need to return payer anywhere. Use either redirect_url or combination of redirect_success_url and redirect_fail_url, not both.
|
Necessity : OptionalType : StringLength : 1024 |
redirect_success_url |
URL, where the Payer is redirected to when transaction status is approved (See status list).
Connecting Party must not use the parameters come along with the redirect HTTP Request to treat the status of the transaction.
Instead Connecting Party can utilize server_callback_url or status API command.
Otherwise put https://doc.gitpay.tech/ if there is no need to redirect Payer anywhere. Use either combination of redirect_success_url and redirect_fail_url or redirect_url, not both.
|
Necessity : OptionalType : StringLength : 1024 |
redirect_fail_url |
URL, where the Payer is redirected to when transaction status is not approved (See status list).
Connecting Party must not use the parameters come along with the redirect HTTP Request to treat the status of the transaction.
Instead Connecting Party can utilize server_callback_url or status API command.
Pass https://doc.gitpay.tech/ if there is no need to redirect Payer anywhere. Use either combination of redirect_fail_url and redirect_success_url or redirect_url, not both.
|
Necessity : OptionalType : StringLength : 1024 |
ssn |
Last four digits of the payer’s social security number. |
Necessity : OptionalType : NumericLength : 32 |
birthday |
Payer’s date of birth, in the format YYYYMMDD. |
Necessity : OptionalType : NumericLength : 8 |
cell_phone |
Payer’s full international cell phone number, including country code. |
Necessity : OptionalType : StringLength : 15 |
site_url |
The URL of the E-commerce entity, where the payment is originated from. |
Necessity : OptionalType : StringLength : 128 |
purpose |
Destination to where the payment goes. It is useful for the Connecting Partys who let their payers to top up their accounts with bank card (Mobile phone accounts, game accounts etc.). Sample values are: +7123456789; gamer0001@ereality.com etc. This value can be used by the fraud monitoring system. |
Necessity : OptionalType : StringLength : 128 |
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 : OptionalType : StringLength : 1024 |
merchant_data |
Custom Connecting Party details, which can be attached to the transaction and passed back in the status response, Connecting Party callback parameters or server_callback_url. Additional information of transaction which may be useful in Connecting Party’s external system, e.g. VIP customer, TV promo campaign lead.
Information returns in Status response and Connecting Party Callback.
|
Necessity : OptionalType : StringLength : 64k |
minimum_transaction_amount |
This parameter can be used to limit the minimum transaction amount, if transaction amount is submitted by Payer on the form. Contact support manager to enable this feature. Value format is the same as in the amount parameter. |
Necessity : OptionalType : NumericLength : 10 |
maximum_transaction_amount |
This parameter can be used to limit the maximum transaction amount, if transaction amount is submitted by Payer on the form. Contact support manager to enable this feature. Value format is the same as in the amount parameter. |
Necessity : OptionalType : NumericLength : 10 |
customer_level |
Customer level in CMS system |
Necessity : OptionalType : VarcharLength : 32 |
customer_id |
Customer ID in CMS system. Necessity becomes required if transaction goes via CMS (PNE) |
Necessity : OptionalType : IntLength : 10 |
merchant_customer_identifier |
Merchant Customer ID in CMS system. Necessity becomes required if transaction goes via CMS (CRM) |
Necessity : OptionalType : VarcharLength : 64 |
recurring-payment-id |
Recurring Payment ID can be sent instead of cardholder data. CVV for native is not needed. Customer Data can be updated via /api/v4/update-recurring-payment/. Recurring Payment ID creation is initiated through HTTPS POST request by using URLs and the parameters specified below. Use OAuth RSA-SHA256 for authentication. |
Necessity : ConditionalType : Long |
Additional Fields for Preauth Transactions
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 GitPay. 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
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 GitPay. |
merchant-order-id |
Connecting Party order id. |
serial-number |
Unique number assigned by GitPay 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=[email protected]
¤cy=USD
&amount=10.42
&ipaddress=65.153.12.232
&site_url=https://doc.gitpay.tech/
&purpose=user_account1
&redirect_url=https://doc.gitpay.tech//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
¤cy=USD
&ipaddress=65.153.12.232
&redirect_url=https://doc.gitpay.tech//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
String to sign |
---|
Signature |
---|
|