3.15. /api/v2/sale-form
Introduction
Sale-form 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/sale-form/ENDPOINTID |
https://gate.gitpay.tech/paynet/api/v2/sale-form/ENDPOINTID |
https://sandbox.gitpay.tech/paynet/api/v2/sale-form/group/ENDPOINTGROUPID |
https://gate.gitpay.tech/paynet/api/v2/sale-form/group/ENDPOINTGROUPID |
Request Parameters
Note
Warning
The following characters must be escaped in the parameter values: & + “.
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 : 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 : RequiredType : StringLength : 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 : RequiredType : StringLength : 50 |
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 |
address1 |
Payer’s address line 1. |
Necessity : RequiredType : StringLength : 50 |
city |
Payer’s city. |
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 |
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 |
cell_phone |
Payer’s full international cell phone number, including country code. |
Necessity : OptionalType : StringLength : 15 |
Payer’s e-mail address. |
Necessity : RequiredType : StringLength : 50 |
|
purpose |
Destination to where the payment goes. It is useful for the Connecting Party’s 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 |
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 |
ipaddress |
Payer’s IP address, included for fraud screening purposes. |
Necessity : RequiredType : StringLength : 20 |
site_url |
The URL of the E-commerce entity, where the payment is originated from. |
Necessity : OptionalType : StringLength : 128 |
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 |
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 http://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 http://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 http://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 |
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 |
preferred_language |
Payer’s two-letter language code for multi-language payment-forms. |
Necessity : OptionalType : StringLength : 2 |
merchant_form_data |
Parameters sent in MERCHANT_FORM_DATA API parameter are parsed into macros with the same name, the parameter is url-encoded, example: testparam%3Dtest1%26mynewparam%3Dtest2 and is parsed into $MFD_testparam = test1 and $MFD_mynewparam = test2 macros in the form. Parameter name characters[a-zA-Z0-9], parameter value characters[a-zA-Z0-9], control characters [=&], 2MB max size. For example, this parameter can be used to display payment form in light/dark mode depending on the value passed by Connecting Party (e.g. pass merchant_form_data=theme%3Ddark in request and $MFD_theme macro placeholder on payment form will be changed to dark. |
Necessity : OptionalType : StringLength : 128 |
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 |
Payer’s tokenized cardholder’s data ID, referred as Recurring Payment ID (RPI). 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 |
card-ref-id |
Card reference ID used in subsequent recurring payments. Card reference 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 |
Response Parameters
Note
Parameter name |
Description |
---|---|
type |
The type of response. May be async-form-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 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. |
redirect-url |
The URL to the page where the Connecting Party should redirect the client’s browser. Connecting Party should send HTTP 302 redirect, see General Payment-form Process Flow. |
Request Example
POST /paynet/api/v2/sale-form/39519 HTTP/1.1
User-Agent: curl/7.83.0
Accept: */*
Content-Length: 314
Content-Type: application/x-www-form-urlencoded
Connection: close
client_orderid=inv1409911
&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
&cell_phone=+19023384543
&amount=156
&email=[email protected]
¤cy=USD
&ipaddress=65.153.12.232
&site_url=https://doc.gitpay.tech/
&purpose=user_account1
&redirect_url=http://connectingparty.com/result
&server_callback_url=https://httpstat.us/200
&merchant_data=VIP customer
&merchant_form_data=testparam%3Dtest1%26mynewparam%3Dtest2
&control=185aea68b751221b78fa9138e9d44a6aa4c2c446
Success Response Example
HTTP/1.1 200 OK
Server: server
Date: Tue, 11 Oct 2022 14:25:25 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: 280
type=async-form-response
&serial-number=00000000-0000-0000-0000-000002ddb0b9
&merchant-order-id=Test
&paynet-order-id=6863099
&redirect-url=https%3A%2F%2Fsandbox.gitpay.tech%2Fpaynet%2Fform%2Finit%2FBB587546567A31587163597A68633370432F786752582F6154674965594A696F4D41306C50596E334F5453553D
Fail Response Example
HTTP/1.1 200 OK
Server: server
Date: Tue, 11 Oct 2022 14:16:06 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: 170
type=validation-error
&serial-number=00000000-0000-0000-0000-000002ddb0b7
&error-message=Project+with+currency+RUB+does+not+apply+request+with+currency+USD
&error-code=16
Postman Collection
Request Builder
String to sign |
---|
Signature |
---|
|