3.20. /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.sbctech.ru/paynet/api/v2/sale-form/ENDPOINTID	https://gate.sbctech.ru/paynet/api/v2/sale-form/ENDPOINTID
https://sandbox.sbctech.ru/paynet/api/v2/sale-form/group/ENDPOINTGROUPID	https://gate.sbctech.ru/paynet/api/v2/sale-form/group/ENDPOINTGROUPID

Request Parameters

Note

Request must have content-type=application/x-www-form-urlencoded.
Acquirer can redefine the necessity of some fields so they become required instead of optional.
Leading and trailing whitespace in input parameters will be omitted.

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`: 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
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
cell_phone	Payer’s full international cell phone number, including country code.	`Necessity`: Optional `Type`: String `Length`: 15
email	Payer’s e-mail address.	`Necessity`: Required `Type`: String `Length`: 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`: Optional `Type`: String `Length`: 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`: 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
ipaddress	Payer’s IP address, included for fraud screening purposes.	`Necessity`: Required `Type`: String `Length`: 20
site_url	The URL of the E-commerce entity, where the payment is originated from.	`Necessity`: Optional `Type`: String `Length`: 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 SBC gateway system).	`Necessity`: Required `Type`: String `Length`: 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.sbctech.ru/ 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`: Optional `Type`: String `Length`: 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.sbctech.ru/ 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`: Optional `Type`: String `Length`: 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.sbctech.ru/ 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`: Optional `Type`: String `Length`: 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. This parameter can be sent instead of notify_url. If server_callback_url is sent, Payment Gateway sends callback notification only when original transaction receives final status. If notify_url is sent, Payment Gateway sends callback notification once the original transaction receives final status, and about every future update for this original transaction (reversal, chargeback, etc).	`Necessity`: Optional `Type`: String `Length`: 1024
notify_url	URL, where the transaction status is sent to. Connecting Party may use notify 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 notify_url refer to Connecting Party callback parameters. This parameter can be sent instead of server_callback_url. If notify_url is sent, Payment Gateway sends callback notification once the original transaction receives final status, and about every future update for this original transaction (reversal, chargeback, etc). If server_callback_url is sent, Payment Gateway sends callback notification only when original transaction receives final status.	`Necessity`: Optional `Type`: String `Length`: 1024
preferred_language	Payer’s two-letter language code for multi-language payment-forms.	`Necessity`: Optional `Type`: String `Length`: 2
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`: Optional `Type`: String `Length`: 64k
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`: Optional `Type`: String `Length`: 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`: Optional `Type`: Numeric `Length`: 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`: Optional `Type`: Numeric `Length`: 10
customer_level	Customer level in CMS system	`Necessity`: Optional `Type`: Varchar `Length`: 32
customer_id	Customer ID in CMS system. Required if transaction goes via CMS (Payment Gateway mode)	`Necessity`: Optional `Type`: Int `Length`: 10
merchant_customer_identifier	Merchant Customer ID in CMS system. Required if transaction goes via CMS (CRM mode)	`Necessity`: Optional `Type`: Varchar `Length`: 64
card_recurring_payment_id	Payer’s tokenized cardholder’s data ID, referred as Recurring Payment ID (RPI). Recurring Payment ID can be created with v4 tokenization request.	`Necessity`: Conditional `Type`: Long
cardrefid	Card reference ID used in subsequent recurring payments. Card reference ID can be created with v4 tokenization request or v2 tokenization request.	`Necessity`: Conditional `Type`: Long

For Faster Payments System (СБП) integration use purpose field for fpsRequestId parameter.

Request Parameters for Insurance

Parameter Name	Description	Value
insurance_amount	The insurance amount. The amount must be specified in minimum units with a . delimiter. For example, 100.5 in USD means 100 US dollars and 50 cents.	`Type`: Numeric `Length`: 10
insured_person_first_name	Insured person’s first name.	`Type`: String `Length`: 256
insured_person_last_name	Insured person’s last name.	`Type`: String `Length`: 256
insured_person_middle_name	Insured person’s middle name.	`Type`: String `Length`: 256
insured_person_birthday	Insured person’s date of birth.	`Type`: String `Length`: 256
insured_person_document_series	Insured person’s document series.	`Type`: String `Length`: 256
insured_person_document_number	Insured person’s document number.	`Type`: String `Length`: 256
insured_person_document_issue_date	Date the insured person’s document was issued.	`Type`: String `Length`: 256
insured_person_document_issuer_name	Name of the authority that issued the insured person’s document.	`Type`: String `Length`: 256
insured_person_document_issuer_code	Code of the authority that issued the insured person’s document.	`Type`: String `Length`: 256
insured_person_registration_address	Insured person’s registration address.	`Type`: String `Length`: 256
insured_person_phone	Full international phone number of the insured person.	`Type`: String `Length`: 256
insured_person_email	Insured person’s email address.	`Type`: String `Length`: 256
card_insurance_agreement_number	Agreement number.	`Type`: String `Length`: 256
card_insurance_agreement_sell_date	Sale date of the agreement.	`Type`: String `Length`: 256
card_insurance_agreement_start_date	Agreement start date.	`Type`: String `Length`: 256
card_insurance_agreement_end_date	Agreement end date.	`Type`: String `Length`: 256
card_insurance_agreement_amount	Insurance amount.	`Type`: String `Length`: 256
card_insurance_agreement_bonus	Insurance premium.	`Type`: String `Length`: 256

Note

The acquirer can override the mandatory nature of some fields to make them mandatory instead of optional.

Leading and trailing whitespace in input parameters will be trimmed.

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.

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 SBC.
merchant-order-id	Connecting Party order id.
serial-number	Unique number assigned by SBC 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=john.smith@gmail.com
&currency=USD
&ipaddress=65.153.12.232
&site_url=https://doc.sbctech.ru/
&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

Request Example for Insurance

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
&cell_phone=+19023384543
&amount=10.42
&insurance_amount=10
&email=john.smith@gmail.com
&currency=AED
&ipaddress=65.153.12.232
&site_url=www.google.com
&purpose=user_account1
&redirect_url=https://doc.sbctech.ru//doc/dummy.htm
&server_callback_url=https://httpstat.us/200
&merchant_data=VIP customer
&merchant_form_data=testparam%3Dtest1%26mynewparam%3Dtest2
&insured_person_first_name=John
&insured_person_last_name=Doe
&insured_person_middle_name=J
&insured_person_birthday=19820115
&insured_person_document_series=4111
&insured_person_document_number=562297
&insured_person_document_issue_date=19970117
&insured_person_document_issuer_name=First document department
&insured_person_registration_address=Seattle 100 Main st
&insured_person_phone=+12063582043
&insured_person_email=john.smith@gmail.com
&card_insurance_agreement_number=210H3FIM2426726391
&card_insurance_agreement_sell_date=20210115
&card_insurance_agreement_start_date=20210116
&card_insurance_agreement_end_date=20250115
&card_insurance_agreement_amount=20000
&card_insurance_agreement_bonus=4000
&control=c1ac1d532c96ddde35ad87be8b80a3d5aa0f2f48

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.sbctech.ru%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

Insurance

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
purpose
merchant_control	input Control Key
redirect_url
redirect_success_url
redirect_fail_url
server_callback_url
merchant_data
cardrefid
maximum-transaction-amount
minimum-transaction-amount
merchant_form_data
insurance_amount
insured_person_first_name
insured_person_last_name
insured_person_middle_name
insured_person_birthday
insured_person_document_series
insured_person_document_number
insured_person_document_issue_date
insured_person_document_issuer_name
insured_person_registration_address
insured_person_phone
insured_person_email
card_insurance_agreement_number
card_insurance_agreement_sell_date
card_insurance_agreement_start_date
card_insurance_agreement_end_date
card_insurance_agreement_amount
card_insurance_agreement_bonus

String to sign

Signature