1.1.6. Transfer V4

Transfer V4 Integration Data

Transfer V4 URL

The End point ID is an entry point for incoming Merchant’s transactions and is the only ConnPay object which is exposed via API.

Deposit to card transactions are initiated through HTTPS POST request by using URL in the following format:
https://gate.connpay.com/paynet/api/v4/transfer/ENDPOINTID – to use v4 transfer.
https://gate.connpay.com/paynet/api/v4/transfer-form/ENDPOINTID – to use v4 transfer-form.
for integration purposes use staging environment sandbox.connpay.com instead of production gate.connpay.com

3DS redirect

If your gate supports 3-D Secure you need to send status request and process html return parameter to send customer to 3-D Secure Authorisation. The simplified schema looks like:

Customer -> Merchant: Initiate transaction
activate Merchant

Merchant -> "ConnPay": transfer-by-ref
activate "ConnPay"
"ConnPay" --> Merchant: async-response
Merchant -> "ConnPay": status
"ConnPay" --> Merchant: html
deactivate "ConnPay"
Merchant --> Customer: urldecode(html)
deactivate Merchant

Sender card data

Sending either tokenized cardholder’s data card_recurring_payment_id or combination of credit_card_number, card_printed_name, expire_month and expire_year is Mandatory. For more information, please contact your manager in ConnPay.

Note

Request must have content-type=application/x-www-form-urlencoded and Authorization headers.
Money transfer request parameter Length/Type Comment
credit_card_number 19/Numeric Sender`s credit card number. Send either combination of credit_card_number, card_printed_name, expire_month and expire_year or card_recurring_payment_id, not all
card_recurring_payment_id Long Sender’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 Process Card Registration via v4/create-card-ref
card_printed_name 128/String Sender`s card printed name.
expire_month 2/String Sender credit card’s month of expiration.
expire_year 2-4/String Sender credit card’s year of expiration.
cvv2 3-4/String Sender`s CVV2 code. CVV2 (Card Verification Value) is the three of four digit number farthest to the right on the flip side of a credit card
deposit2card True/False Marker of deposit to card transfer. If “true”, no sender cardholder data is needed to process the transaction. If “false”, sender cardholder data is needed.

Receiver card data

Sending either tokenized cardholder’s data destination_card_recurring_payment_id or combination of destination-card-no, destination_card_printed_name, destination_expire_month and destination_expire_year is Mandatory. For more information, please contact your manager in ConnPay.

Money transfer request parameter Length/Type Comment
destination-card-no 19/Numeric Receiver`s card PAN. Send either combination of destination-card-no, destination_card_printed_name, destination_expire_month and destination_expire_year or destination_card_recurring_payment_id, not all
destination_card_recurring_payment_id Long Receiver’s tokenized cardholder’s data ID. Send either destination_card_recurring_payment_id or combination of destination-card-no, destination_card_printed_name, destination_expire_month and destination_expire_year, not all. To create destination_card_recurring_payment_id see Process Card Registration via v4/create-card-ref
destination_card_printed_name 128/String Receiver`s card printed name.
destination_expire_month 2/String Receiver credit card’s month of expiration.
destination_expire_year 2-4/String Receiver credit card’s year of expiration.

Sender customer data

Parameters below can be mandatory for specific integrations. For more information, please contact your manager in ConnPay.

Money transfer request parameter Length/Type Comment
sender_first_name 128/String Sender’s first name. Depends on Acquirer’s side
sender_last_name 128/String Sender’s last name. Depends on Acquirer’s side
sender_middle_name 128/String Sender’s middle name/patronym. Depends on Acquirer’s side
sender_ssn 11/String Last four digits of the Sender’s social security number
sender_birth_place 128/String Sender`s birth place
sender_birthday 30/String Sender’s birthday
sender_address1 256/String Sender’s address
sender_city 128/String Sender’s city
sender_state 4/String Sender’s US states (two letter abbreviation). Not applicable outside the US
sender_zip_code 32/String Sender`s zip code
sender_citizenship 128/String Sender`s citizenship
sender_country_code 3/String Sender’s country (two letter abbreviation)
sender_phone 128/String Sender’s full international phone number, including country suffix
sender_cell_phone 128/String Sender’s full international cell phone number, including country suffix
sender_email 128/String Sender’s email address
sender_resident Boolean Is sender a resident?
sender_identity_document_id 128/String Sender`s identity document name
sender_identity_document_series 12/String Sender`s identity document series
sender_identity_document_number 16/String Sender`s identity document number
sender_identity_document_issuer_name 128/String Sender`s identity document issuer
sender_identity_document_issuer_department_code 32/String Sender`s identity document issuer department code
sender_identity_document_issue_date Date Sender`s identity document issue date

Receiver customer data

Parameters below can be mandatory for specific integrations. For more information, please contact your manager in ConnPay.

Money transfer request parameter Length/Type Comment
receiver_first_name 128/String Receiver’s first name. Depends on Acquirer’s side
receiver_last_name 128/String Receiver’s last name. Depends on Acquirer’s side
receiver_middle_name 128/String Receiver’s middle name/patronym. Depends on Acquirer’s side
receiver_birth_place 128/String Receiver`s birth place
receiver_birthday 128/String Receiver’s birthday
receiver_address1 256/String Receiver’s address
receiver_city 128/String Receiver’s city
receiver_zip_code 32/String Receiver`s zip code
receiver_region 30/String Receiver`s region
receiver_area 50/String Receiver`s area
receiver_citizenship 128/String Receiver`s citizenship
receiver_country_code 3/String Receiver`s country (two letter abbreviation)
receiver_phone 128/String Receiver’s full international phone number, including country suffix
receiver_email 128/String Receiver’s email address
receiver_resident Boolean Is receiver a resident?
receiver_identity_document_id 128/String Receiver`s identity document name
receiver_identity_document_series 12/String Receiver`s identity document series
receiver_identity_document_number 16/String Receiver`s identity document number
receiver_identity_document_issuer_name 128/String Receiver`s identity document issuer
receiver_identity_document_issuer_department_code 32/String Receiver`s identity document issuer department code
receiver_identity_document_issue_date Date Receiver`s identity document issue date

Sender anti-fraud data

Money transfer request parameter Length/Type Comment
customer_user_agent 512/String Customer User Agent Info
customer_localtime 128/String Customer Localtime
customer_screen_size 32/String Customer Screen Size
customer_accept_language 128/String Customer browser accept language
customer_accept 128/String Customer Browser Accept Header
ipaddress 7-45/String The customer’s IP address, include for fraud screening purposes. NB: 45 is for IPv4 tunneling like 0000:0000:0000:0000:0000:0000:192.168.100.10

Mandatory fields

Parameter name Description
ipaddress The customer’s IP address, include for fraud screening purposes. NB: 45 is for IPv4 tunneling like 0000:0000:0000:0000:0000:0000:192.168.100.101
client_orderid Customer order ID
currency Currency the transaction is charged in (three-letter currency code). Example ofВ  valid parameter values are: USD for US Dollar EUR for European Euro
amount Amount to be transferred. 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
redirect_url URL the cardholder will be redirected to upon completion of the transaction. Please note that the cardholder will be redirected in any case, no matter whether the transaction is approved or declined. Optional for direct integration(non-form) deposit2card
order_desc Order description
Parameters, which will define the type of transaction are listed below.

Additional fields for transfer V4 transactions

For merchants - customer browser information and 3DS results notification URL

Note

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 merchant 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 merchant’s site needs to accurately populate the browser information for each transaction. This data can be obtained by merchant’s servers. Ensure that the data is not altered or hard-coded, and that it is unique to each transaction.

Field Name Length/Type Description Conditional Inclusion
tds_areq_notification_url, alias tds_cres_notification_url 256/String Fully qualified URL of merchant system that will receive the CRes message or Error Message. This CRes message must be sent to ConnPay. See details here Upload CRes Result Optional
customer_browser_info Boolean If true, then the fields below must be present Optional
ipaddress 45/String IP address of the browser as returned by the HTTP headers to the 3DS Requestor Required
customer_browser_accept_header 2048/String Exact content of the HTTP accept headers as sent to the 3DS Requestor from the Cardholder’s browser Required
customer_browser_color_depth 2/String Value representing the bit depth of the colour palette for displaying images, in bits per pixel Required when browser_javaScript_enabled = true; otherwise Optional
customer_browser_java_enabled Boolean Boolean that represents the ability of the cardholder browser to execute Java Required when browser_javaScript_enabled = true; otherwise Optional
customer_browser_javascript_enabled Boolean Boolean that represents the ability of the cardholder browser to execute JavaScript Required
customer_browser_accept_language 8/String Value representing the browser language as defined in IETF BCP47 Required
customer_browser_screen_height 6/Numeric Total height of the Cardholder’s screen in pixels Required when browser_javaScript_enabled = true; otherwise Optional
customer_browser_screen_width 6/Numeric Total width of the cardholder’s screen in pixels Required when browser_javaScript_enabled = true; otherwise Optional
customer_browser_time_zone 5/String 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 Required when browser_javaScript_enabled = true; otherwise Optional
customer_browser_user_agent 2048/String Exact content of the HTTP user-agent header Required

For PSPs and Acquirers - 3DS authentication results

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

Field Name Length/Type Description
tds_authentication_result_type 6/String
Type of result. Possible values are:
- SIMPLE
tds_authentication_result_authentication_type 2/String
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
tds_authentication_result_authentication_value 19-28/String 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
tds_authentication_result_transaction_id 19-36/String xid for 1.0.2 or dsTransID for 2.1.0/2.2.0
tds_authentication_result_transaction_status 1/String
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
tds_authentication_result_message_version 5/String
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

Transfer v4 fill rules

Transaction type Parameters to send
PAN —> PAN cvv2,expire_month,expire_year,card_printed_name,credit_card_number,destination-card-no + mandatory fields
PAN —> RPI cvv2,expire_month,expire_year,card_printed_name,credit_card_number,destination_card_recurring_payment_id + mandatory fields
RPI —> PAN card_recurring_payment_id, expire_month,expire_year,card_printed_name, destination-card-no + mandatory fields
RPI —> RPI card_recurring_payment_id, expire_month,expire_year,card_printed_name, destination_card_recurring_payment_id + mandatory fields
0 —> PAN (deposit2card) destination-card-no, deposit2card = true + mandatory fields
0 —> RPI (deposit2card) destination_card_recurring_payment_id, deposit2card = true + mandatory fields

Transfer Response

Note

Response has Content-Type: text/html;charset=utf-8 header. All parameters in response are x-www-form-urlencoded, with (0xA) character at the end of each parameter’s value
Transfer response parameter Description
type The type of response. May be async-response, validation-error, error. 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 Merchant order id
serial-number Unique number assigned by ConnPay server to particular request from the Merchant
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

Transfer Request V4 Postman Collection

Transfer Request V4 debug

Possible transaction flow scenarios can be tested with E-Commerce test cards

Enter your private key in PKCS#1 container to use debug. See OAuth RSA-SHA256 for details.

Debug form
URL input URL(use /v4/transfer-form/ENDPOINTID for transfer-form)
endpointid or endpointgroupid input your ENDPOINTID or ENDPOINTGROUPID
login your login should be used as Consumer Public for OAuth
destination-card-no enter the beginning of the sequence, and then "i".
destination_expire_month
destination_expire_year
destination_card_printed_name
birthday
destination_card_recurring_payment_id use either RPI or card number, not both
credit_card_number enter the beginning of the sequence, and then "i".
card_recurring_payment_id use either RPI or card number, not both
amount
currency
cvv2
card_printed_name
expire_month
expire_year
ipaddress
order_desc
receiver_first_name
receiver_middle_name
receiver_last_name
redirect_url
redirect_success_url
redirect_fail_url
client_orderid
merchant_form_data
deposit2card boolean used only to determine if transaction type is deposit2card

Normalized parameters string to sign, according to OAuth 1.0a rules
POST body parameters to submit
OAuth 1.0a headers to submit.
HEX Encoded Signature
* HEX encoded string is for debug purposes only. You shouldn't send this string to the server neither in HEX nor in Encoded HEX representation.
Base64 Encoded Signature
* Binary RSA-SHA256 signature directly encoded in base64 should be sent to the server.

Order status

Merchant must use Order status API call to get the customer’s order transaction status. After any type of transaction is sent to ConnPay server and order id is returned, Merchant should poll for transaction status. When transaction is processed on ConnPay server side it returns it’s status back to Merchant and at this moment the Merchant is ready to show the customer transaction result, whether it’s approved or declined.

See more details at Statuses

Status API URL

For integration purposes use staging environment sandbox.connpay.com instead of production gate.connpay.com. Status API calls are initiated through HTTPS POST request by using URL in the following format:

The End point ID is an entry point for incoming Merchant’s transactions for single currency integration.
https://gate.connpay.com/paynet/api/v2/status/ENDPOINTID - for v2 status integration.
https://gate.connpay.com/paynet/api/v4/status/ENDPOINTID - for v4 status integration.
The End point group ID is an entry point for incoming Merchant’s transactions for multi currency integration.
https://gate.connpay.com/paynet/api/v2/status/group/ENDPOINTGROUPID - for v2 status integration.
https://gate.connpay.com/paynet/api/v4/status/group/ENDPOINTGROUPID - for v4 status integration.

Order status call parameters

Note

Request must have content-type=application/x-www-form-urlencoded.
Status Call Parameter Description Necessity
login Merchant login name Mandatory
client_orderid Merchant order identifier of the transaction for which the status is requested Mandatory
orderid Order id assigned to the order by ConnPay Conditional
control Checksum used to ensure that status request is initiated from Merchant in Status API v2. This is SHA-1 checksum of the concatenation login + client-order-id + paynet-order-id + merchant-control. For Status API v4 this parameter is not used, request is signed used OAuth. See the Order status V4 Debug and OAuth for details Mandatory
by-request-sn Serial number assigned to the specific request by ConnPay. If this field exist in status request, status response return for this specific request. Include this parameter to get the status response with the particular transaction stage (can be used in specific cases). To get the latest transaction status, don’t include this parameter in status request Optional
In most common cases, the best option is to include both client_orderid and orderid parameters to status request. Order status can be requested with only client_orderid if it’s unique to merchant and orderid is not received. If orderid is not received in response, but this response contains an error, see the received error message to get the information why transaction was not created in the system.

Order Status Response

Note

Response has Content-Type: text/html;charset=utf-8 header. All parameters in response are x-www-form-urlencoded, with (0xA) character at the end of each parameter’s value
* - these parameters are not defined by default. Please contact tech support to include these fields in callback.
Status Response Parameter Description
type The type of response. May be status-response
status See Status List for details
amount Amount of the initial transaction
currency Currency of the initial transaction
paynet-order-id Order id assigned to the order by ConnPay
merchant-order-id Merchant order id
phone Customer phone
serial-number Unique number assigned by ConnPay server to particular request from the Merchant
dest-last-four-digits Last four digits of customer credit card number
dest-bin Bank BIN of customer credit card number
dest-card-type Type of customer credit card (VISA, MASTERCARD, etc)
gate-partial-reversal Processing gate support partial reversal (enabled or disabled)
gate-partial-capture Processing gate support partial capture (enabled or disabled)
transaction-type Transaction type (sale, reversal, capture, preauth)
processor-rrn Bank Receiver Registration Number
processor-tx-id Acquirer transaction identifier
receipt-id Electronic link to receipt https://gate.connpay.com/paynet/view-receipt/ENDPOINTID/receipt-id/
cardholder-name Cardholder name
card-exp-month Card expiration month
card-exp-year Card expiration year
card-type Type of customer credit card
destination-card-hash-id Unique card identifier to use for loyalty programs or fraud checks
destination-card-country-alpha-three-code Three letter country code of destination card issuer. See Country Codes for details
email Customer e-mail
first-name Customer’s first name
last-name Customer’s last name
country * Customer’s country (two-letter country code). Please see Country Codes for a list of valid country codes.
state * Customer’s state . Please see Country Codes for a list of valid state codes. Mandatory for USA, Canada and Australia.
city * Customer’s city
zip_code * Customer’s ZIP code
address1 * Customer’s address line 1
dest-bank-name Bank name by customer card BIN
terminal-id Acquirer terminal identifier to show in receipt
paynet-processing-date Acquirer transaction processing date
approval-code Bank approval code
order-stage The current stage of the transaction processing. See Order Stage for details
loyalty-balance The current bonuses balance of the loyalty program for current operation. if available
loyalty-message The message from the loyalty program. if available
loyalty-bonus The bonus value of the loyalty program for current operation. if available
loyalty-program The name of the loyalty program for current operation. if available
descriptor Bank identifier of the payment recipient
original-gate-descriptor Descriptor, which is set on gate level in the system
error-message If status in declined, error, filtered this parameter contains the reason for decline
error-code The error code is case status in declined, error, filtered
by-request-sn Serial number from status request, if exists in request. Warning parameter amount always shows initial transaction amount, even if status is requested by-request-sn
verified-3d-status See 3-D Secure Status List for details
eci Electronic Commerce Indicator (Visa)
ips-dst-payment-product-code Code for card set by multinational financial service. (Visa/Mastercard)
ips-dst-payment-product-name Decrypted code for card set by multinational financial service. (Visa/Mastercard)
ips-dst-payment-type-code Type of card code set by multinational financial service. (Visa/Mastercard)
ips-dst-payment-type-name Decrypted code for type of card set by multinational financial service. (Visa/Mastercard)
initial-amount Amount, set in initiating transaction, without any fees or commissions. This value can’t change during the transaction flow
seller-commission Total commission for processed transaction. This is optional parameter. Please contact your manager in ConnPay, if you would like to receive it
acquirer-commission Acquirer commission for processed transaction. This is optional parameter. Please contact your manager in ConnPay, if you would like to receive it
motivational-message This is an optional message which contains extended information about the reason for the declined transaction.
transaction-date Date of final status assignment for transaction.

Order Status Response Example

type=status-response
&serial-number=00000000-0000-0000-0000-0000005b5eec
&merchant-order-id=6132tc
&processor-tx-id=9568-47ed-912d-3a1067ae1d22
&paynet-order-id=161944
&status=approved
&amount=7.56
&descriptor=no
&original-gate-descriptor=test 12345678 3Ds Bank
&gate-partial-reversal=enabled
&gate-partial-capture=enabled
&transaction-type=cancel
&receipt-id=2050-3c93-a061-8a19b6c0068f
&name=FirstName
&cardholder-name=FirstName
&card-exp-month=3
&card-exp-year=2028
&email=no
&last-name=Smith
&first-name=John
&processor-rrn=510458047886
&approval-code=380424
&order-stage=cancel_approved
&dest-last-four-digits=1111
&dest-bin=444455
&dest-card-type=VISA
&phone=%2B79685787194
&dest-bank-name=UNKNOWN
&paynet-processing-date=2015-04-14+10%3A23%3A34+MSK
&by-request-sn=00000000-0000-0000-0000-0000005b5ece
&destination-card-hash-id=1569311
&destination-card-country-alpha-three-code=RUS
&verified-3d-status=AUTHENTICATED
&eci=02
&ips-dst-payment-product-code=SAP
&ips-dst-payment-product-name=SAP—Platinum Mastercard® Salary– Immediate Debit
&ips-dst-payment-type-code=Debit
&ips-dst-payment-type-name=MASTERCARD Debit
&initial-amount=7.56
&transaction-date=2023-01-10+12%3A46%3A28+MSK

Status request authorization through control parameter

The checksum is used to ensure that it is Merchant (and not a fraudster) that sends the request to ConnPay. This SHA-1 checksum, the parameter control, is created by concatenation of these parameters values in the following order:

  • login
  • client_orderid
  • orderid
  • merchant_control

For example, assume these parameters have the values as listed below:

Parameter Name Parameter Value
login cool_merchant
client_orderid 5624444333322221111110
orderid 9625
merchant_control r45a019070772d1c4c2b503bbdc0fa22

The complete string example may look as follows:

cool_merchant56244443333222211111109625r45a019070772d1c4c2b503bbdc0fa22

Encrypt the string using SHA-1 algorithm. The resultant string yields the control parameter which is required for authorizing the callback. For the example control above will take the following value:

c52cfb609f20a3677eb280cc4709278ea8f7024c

Order status Postman Collection

Order status V2 Debug

Possible transaction flow scenarios can be tested with E-Commerce test cards

endpointid
login
client_orderid
orderid
merchant_control
by-request-sn

String to sign
Signature
              
            
 


Order status V4 Debug

Possible transaction flow scenarios can be tested with E-Commerce test cards

Enter your private key in PKCS#1 container to use debug. See OAuth RSA-SHA256 for details.

Order status form
URL input URL
endpointid or groupid input your ENDPOINTID or ENDPOINTGROUPID
login
client_orderid input your Invoice Number
orderid
by-request-sn

Normalized parameters string to sign, according to OAuth 1.0a rules
POST body parameters to submit
OAuth 1.0a headers to submit.
HEX Encoded Signature
* HEX encoded string is for debug purposes only. You shouldn't send this string to the server neither in HEX nor in Encoded HEX representation.
Base64 Encoded Signature
* Binary RSA-SHA256 signature directly encoded in base64 should be sent to the server.

Transfer Form Integration

Transfer Form integration is relevant for merchants who are not able to accept customer card details (merchant’s website must complete PCI DSS certification). In case of Transfer Form integration merchant is released of accepting payment details and all this stuff is completely implemented on the ConnPay gateway side. In addition merchant may customize the look and feel of the Transfer Form. Merchant must send the template to his/her Manager for approval before it could be used.

Transfer Form API URL

For integration purposes use staging environment sandbox.connpay.com instead of production gate.connpay.com. Transfer Form transactions are initiated through HTTPS POST request by using URL in the following format:

Form Transaction by ENDPOINTID

The End point ID is an entry point for incoming Merchant’s transactions for single currency integration.

https://gate.connpay.com/paynet/api/v4/transfer-form/ENDPOINTID - for transfer transactions

Form Transaction by ENDPOINTGROUPID

The End point group ID is an entry point for incoming Merchant’s transactions for multi currency integration.

https://gate.connpay.com/paynet/api/v4/transfer-form/group/ENDPOINTGROUPID - for transfer transactions

General Transfer Form Process Flow

    Customer -> Merchant: Checkout
activate Merchant

Merchant -> "ConnPay": transfer-form/ENDPOINTID
activate "ConnPay"

"ConnPay" --> Merchant: status=processing
deactivate "ConnPay"
deactivate Merchant

Customer -> Customer: Input cardholder data
Customer -> "ConnPay": Submit form
activate "ConnPay"
"ConnPay" -> "ConnPay": Processing
"ConnPay" --> Customer: Redirect to **redirect_url**
deactivate "ConnPay"

Customer -> Merchant: Return to the Shop

alt status
  loop
     Merchant -> "ConnPay": status/ENDPOINTID
     activate "ConnPay"
     "ConnPay" --> Merchant: status=processing
     deactivate "ConnPay"
    end
  else callback
   ... transaction processing ...
   "ConnPay" --> Merchant: Callback notification
end

Checkout – Customer proceeds to order checkout.
Merchant initiates a transaction by sending HTTPS POST request to the specified URL. It should be v4/transfer-form/ENDPOINTID.
ConnPay gateway returns response which contains an additional parameter redirect-url. This is the URL where merchant must redirect Customer’s browser to.
See details about response format in Transfer Form Response.
Merchant sends HTTP 302 redirect to Customer’s browser using URL which is obtained from the redirect-url response parameter.
Customer fills in payment details and submits the Transfer Form.
ConnPay gateway processes the transaction according to 3D or Non 3D process.
When transfer authorization is completed ConnPay gateway redirects the Customer’s browser to redirect_url request parameter provided by merchant in the original request accomplished at step 2. See details in Transfer Form final redirect.

Initiating a transaction with Transfer Form

Merchant must supply the following parameters to initiate a transfer transaction using form template.

Note

Request must have content-type=application/x-www-form-urlencoded and Authorization headers.
Response has Content-Type: text/html;charset=utf-8 header. All parameters in response are x-www-form-urlencoded, with (0xA) character at the end of each parameter’s value.
Acquirer can redefine the necessity of some fields, so they become mandatory instead of optional
Leading and trailing whitespace in input parameters will be omitted

Sender card data

Sending either tokenized cardholder’s data card_recurring_payment_id or combination of credit_card_number, card_printed_name, expire_month and expire_year is Mandatory. For more information, please contact your manager in ConnPay.

Request parameter name Length/Type Comment
credit_card_number 19/Numeric Sender`s credit card number. Send either combination of credit_card_number, card_printed_name, expire_month and expire_year or card_recurring_payment_id, not all
card_recurring_payment_id Long Sender’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 Process Card Registration via v4/create-card-ref
card_printed_name 128/String Sender`s card printed name.
expire_month 2/String Sender credit card’s month of expiration.
expire_year 2-4/String Sender credit card’s year of expiration.
cvv2 3-4/String Sender`s CVV2 code. CVV2 (Card Verification Value) is the three of four digit number farthest to the right on the flip side of a credit card

Receiver card data

Sending either tokenized cardholder’s data destination_card_recurring_payment_id or combination of destination-card-no, destination_card_printed_name, destination_expire_month and destination_expire_year is Mandatory. For more information, please contact your manager in ConnPay.

Request parameter name Length/Type Comment
destination-card-no 19/Numeric Receiver`s card PAN. Send either combination of destination-card-no, destination_card_printed_name, destination_expire_month and destination_expire_year or destination_card_recurring_payment_id, not all
destination_card_recurring_payment_id Long Receiver’s tokenized cardholder’s data ID. Send either destination_card_recurring_payment_id or combination of destination-card-no, destination_card_printed_name, destination_expire_month and destination_expire_year, not all. To create destination_card_recurring_payment_id see Process Card Registration via v4/create-card-ref
destination_card_printed_name 128/String Receiver`s card printed name
destination_expire_month 2/String Receiver credit card’s month of expiration
destination_expire_year 2-4/String Receiver credit card’s year of expiration

Transfer-form v4 fill rules

Transaction type Parameters to send
form —> PAN destination-card-no + mandatory fields
form —> RPI destination_card_recurring_payment_id + mandatory fields
PAN —> form credit_card_number, cvv2,expire_month,expire_year,card_printed_name + mandatory fields
RPI —> form card_recurring_payment_id, cvv2,expire_month,expire_year,card_printed_name, + mandatory fields
form —> form mandatory fields
0 —> form(deposit2card) deposit2card = true + mandatory fields
In case of transfer-form transaction, you will receive a response with redirect_url, which contains URL of the form to fill in the remaining parameters.

Transfer Form Response

Response parameter name Description
type The type of response. May be async-form-response, validation-error, error. 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 Merchant order id
serial-number Unique number assigned by ConnPay server to particular request from the Merchant
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 Merchant should redirect the client’s browser. Merchant should send HTTP 302 redirect, see General Transfer Form Process Flow

Transfer Form final redirect

Upon completion of Transfer Form process by the Customer he/she is automatically redirected to redirect_url. The redirection is performed as an HTTPS POST request with the parameters specified in the following table.

Redirect parameter name Description
status See Status List for details
orderid Order id assigned to the order by ConnPay
merchant_order Merchant order id
client_orderid Merchant order id
error_message If status is declined or error this parameter contains the reason for decline or error details
control Checksum used to ensure that it is ConnPay (and not a fraudster) that initiates the request. This is SHA-1 checksum of the concatenation status + orderid + client_orderid + merchant-control
descriptor Gate descriptor
processor-tx-id Acquirer transaction identifier
amount Actual transaction amount.
bin Bank BIN of customer credit card number
type The type of response.
card-type Type of customer credit card
phone Customer phone
last-four-digits Last four digits of customer credit card number
card-holder-name Cardholder name
error_code Error Code

If Merchant has passed server_callback_url in original Transfer Form request ConnPay will call this URL. Merchant may use it for custom processing of the transaction completion, e.g. to collect sales data in Merchant’s database. The parameters sent to this URL are specified in Sale, Return Callback Parameters

Transfer Form Template Sample

<html>
<head>
<script type="text/javascript">
  function isCCValid(r){var n=r.length;if(n>19||13>n)return!1;
    for(i=0,s=0,m=1,l=n;i<l;i++)d=parseInt(r.substring(l-i-1,l-i),10)*m,s+=d>=10?d%10+1:d,1==m?m++:m--;
    return s%10==0?!0:!1}
</script>
</head>
<body>
<h3>Order #$!MERCHANT_ORDER_ID - $!ORDERDESCRIPTION</h3>
<h3>Total amount: $!AMOUNT $!CURRENCY to $!MERCHANT</h3>

<form action="${ACTION}" method="post">
  <div>Cardholder name: <input name="${CARDHOLDER}" type="text" maxlength="64"/></div>
  <div><label for="cc-number">Credit Card Number</label> <input id="cc-number" name="${CARDNO}" type="text" maxlength="19" autocomplete="cc-number"/></div>
  <div>Card verification value: <input name="${CVV2}" type="text" maxlength="4" autocomplete="off"/></div>
  <div>
    Expiration date:
    <select class="expiry-month" name="${EXPMONTH}" size="1" autocomplete="cc-exp-month" >
      <option value="01">January</option><option value="02">February</option><option value="03">March</option>
      <option value="04">April</option><option value="05">May</option><option value="06">June</option>
      <option value="07">July</option><option value="08">August</option><option value="09">September</option>
      <option value="10">October</option><option value="11">November</option><option value="12">December</option>
    </select>
      <select class="expiry-year" id="cc-exp-year" name="${EXPYEAR}" size="1" autocomplete="cc-exp-year">
      ${EXPIRE_YEARS}
    </select>
  </div>
  <div><label for="dest-number">Destination card number:</label> <input id="dest-number" name="${DESTINATIONCARDNO}" type="text" maxlength="19" autocomplete="off"/></div>
  $!{INTERNAL_SECTION}
  #if($!card_error)
  <div style="color: red;">$!card_error</div>
  #end
  <input name="submit" onclick="return isCCValid(document.getElementById('cardnumber').value);" type="submit" value="Pay"/>
</form>
</body>
</html>

Transfer form autofill

If you want to use autofill in your transfer form, certain element attributes <id> <autocomplete> <label for> should be hardcoded in the following manner:

#if ($INPUT_SOURCE_CARD_CARDHOLDER)
<!-- Card printed name field -->
<li class="form-li">
    <label class="form-label" for="cc-name">Card printed name:</label>
    <input class="form-name-field" id="cc-name" name="${CARDHOLDER}" type="text" maxlength="50" autocomplete="cc-name" value="${CARDHOLDER_VALUE}" />
</li>
#end
#if ($INPUT_SOURCE_CARD_CVV2)
<!-- CVV field -->
<li class="form-li">
    <label class="form-label" for="${CVV2}">Card security code (CVV2/CVC2):</label>
    <input class="form-cvv-field" name="${CVV2}" id="${CVV2}" type="password" maxlength="4" autocomplete="off" />
</li>
#end
#end
#if ($INPUT_DESTINATION_CARD)
<!-- Destination Card Number field -->
#if($!DESTINATIONCARDNO)
<li class="form-li">
    <label class="form-label" for="${DESTINATIONCARDNO}">Destination card number:</label>
    <input class="form-number-field" id="${DESTINATIONCARDNO}" name="${DESTINATIONCARDNO}" type="text" maxlength="19" autocomplete="off"  />
</li>
#end
#end

Our default transfer form template supports autocomplete. In case if you want to add additional fields for autocomplete, this specification should be used for naming references.

Wait Page Template Sample

<html>
<head>
<script type="text/javascript">
  function fc(t) {
    document.getElementById("seconds-remaining").innerHTML = t;
    (t > 0) ? setTimeout(function(){fc(--t);}, 1000) : document.checkform.submit();}
</script>
</head>
<body onload="fc($!refresh_interval)">
<h3>Order #$!MERCHANT_ORDER_ID - $!ORDERDESCRIPTION</h3>
<h3>Total amount: $!AMOUNT $!CURRENCY to $!MERCHANT</h3>
Please wait, your payment is being processed, remaining <span id="seconds-remaining">&nbsp;</span> seconds.
<form name="checkform" method="post">
  <input type="hidden" name="tmp" value="$!uuid"/>
      $!{INTERNAL_SECTION}
  <input type="submit" value="Check" />
</form>
</body>
</html>

Wait Page macros

Field Name Macro Field Value Macro Description
${MERCHANT} n/a End point display name
${SKIN_VERSION} n/a CSS skin version
${ORDERDESCRIPTION} n/a Order description
${AMOUNT} n/a Amount
${CURRENCY} n/a Currency
${PAYNET_ORDER_ID} n/a ConnPay order id
${MERCHANT_ORDER_ID} n/a Merchant order id
${refresh_interval} n/a Refresh interval recommended by system
${uuid} n/a Internal
${INTERNAL_SECTION} n/a Internal for iFrame integration
${CUSTOMER_IP_COUNTRY_ISO_CODE} n/a Customer country defined by IP Address
${PREFERRED_LANGUAGE} n/a Customer language send by merchant via input parameters
${BROWSER_LANGUAGE} n/a Customer language defined by browser settings
${CUSTOMER_LANGUAGE} n/a Customer language send by merchant via input parameters or defined by browser settings if first is not set

Finish Page Template Sample

<html>
    <head>
    </head>
    <body>
        <h3>Processing of the payment has finished</h3>
        <h3>Order Invoice: $!{MERCHANT_ORDER_ID}</h3>
            <h3>Order ID: $!{PAYNET_ORDER_ID}</h3>
            <h3>Status: $!{STATUS}</h3>

        #if($ERROR_MESSAGE)
            <h3>Error: $!{ERROR_MESSAGE}</h3>
        #end
    </body>
</html>

Finish Page Macros

Field Name Macro Field Value Macro Description
${STATUS} n/a Order status
${PAYNET_ORDER_ID} n/a System order id
${MERCHANT_ORDER_ID} n/a Merchant order id
${ERROR_MESSAGE} n/a Contains the reason for decline or error details
${SKIN_VERSION} n/a CSS skin version
${CUSTOMER_IP_COUNTRY_ISO_CODE} n/a Customer country defined by IP Address
${PREFERRED_LANGUAGE} n/a Customer language send by merchant via input parameters
${BROWSER_LANGUAGE} n/a Customer language defined by browser settings
${CUSTOMER_LANGUAGE} n/a Customer language send by merchant via input parameters or defined by browser settings if first is not set

Transfer Form Request Postman Collection

Transfer Form Request Debug

Enter your private key in PKCS#1 container to use debug. See OAuth RSA-SHA256 for details.

Debug form
URL input URL(use /v4/transfer-form/ENDPOINTID for transfer-form)
endpointid or endpointgroupid input your ENDPOINTID or ENDPOINTGROUPID
login your login should be used as Consumer Public for OAuth
destination-card-no enter the beginning of the sequence, and then "i".
credit_card_number enter the beginning of the sequence, and then "i".
destination_card_recurring_payment_id use either RPI or card number, not both
card_recurring_payment_id use either RPI or card number, not both
amount
currency
cvv2
card_printed_name
expire_month
expire_year
ipaddress
order_desc
redirect_url
redirect_success_url
redirect_fail_url
client_orderid
merchant_form_data
deposit2card boolean used only to determine if transaction type is deposit2card

Normalized parameters string to sign, according to OAuth 1.0a rules
POST body parameters to submit
OAuth 1.0a headers to submit.
HEX Encoded Signature
* HEX encoded string is for debug purposes only. You shouldn't send this string to the server neither in HEX nor in Encoded HEX representation.
Base64 Encoded Signature
* Binary RSA-SHA256 signature directly encoded in base64 should be sent to the server.

Order status

Merchant must use Order status API call to get the customer’s order transaction status. After any type of transaction is sent to ConnPay server and order id is returned, Merchant should poll for transaction status. When transaction is processed on ConnPay server side it returns it’s status back to Merchant and at this moment the Merchant is ready to show the customer transaction result, whether it’s approved or declined.

See more details at Statuses

Status API URL

For integration purposes use staging environment sandbox.connpay.com instead of production gate.connpay.com. Status API calls are initiated through HTTPS POST request by using URL in the following format:

The End point ID is an entry point for incoming Merchant’s transactions for single currency integration.
https://gate.connpay.com/paynet/api/v2/status/ENDPOINTID - for v2 status integration.
https://gate.connpay.com/paynet/api/v4/status/ENDPOINTID - for v4 status integration.
The End point group ID is an entry point for incoming Merchant’s transactions for multi currency integration.
https://gate.connpay.com/paynet/api/v2/status/group/ENDPOINTGROUPID - for v2 status integration.
https://gate.connpay.com/paynet/api/v4/status/group/ENDPOINTGROUPID - for v4 status integration.

Order status call parameters

Note

Request must have content-type=application/x-www-form-urlencoded.
Status Call Parameter Description Necessity
login Merchant login name Mandatory
client_orderid Merchant order identifier of the transaction for which the status is requested Mandatory
orderid Order id assigned to the order by ConnPay Conditional
control Checksum used to ensure that status request is initiated from Merchant in Status API v2. This is SHA-1 checksum of the concatenation login + client-order-id + paynet-order-id + merchant-control. For Status API v4 this parameter is not used, request is signed used OAuth. See the debug Order status V4 Debug and OAuth for details Mandatory
by-request-sn Serial number assigned to the specific request by ConnPay. If this field exist in status request, status response return for this specific request. Include this parameter to get the status response with the particular transaction stage (can be used in specific cases). To get the latest transaction status, don’t include this parameter in status request Optional
In most common cases, the best option is to include both client_orderid and orderid parameters to status request. Order status can be requested with only client_orderid if it’s unique to merchant and orderid is not received. If orderid is not received in response, but this response contains an error, see the received error message to get the information why transaction was not created in the system.

Order Status Response

Note

Response has Content-Type: text/html;charset=utf-8 header. All parameters in response are x-www-form-urlencoded, with (0xA) character at the end of each parameter’s value.
Status Response Parameter Description
type The type of response. May be status-response
status See Status List for details
amount Amount of the initial transaction
currency Currency of the initial transaction
paynet-order-id Order id assigned to the order by ConnPay
merchant-order-id Merchant order id
phone Customer phone
serial-number Unique number assigned by ConnPay server to particular request from the Merchant
dest-last-four-digits Last four digits of customer credit card number
dest-bin Bank BIN of customer credit card number
dest-card-type Type of customer credit card (VISA, MASTERCARD, etc)
gate-partial-reversal Processing gate support partial reversal (enabled or disabled)
gate-partial-capture Processing gate support partial capture (enabled or disabled)
transaction-type Transaction type (sale, reversal, capture, preauth)
processor-rrn Bank Receiver Registration Number
processor-tx-id Acquirer transaction identifier
receipt-id Electronic link to receipt https://gate.connpay.com/paynet/view-receipt/ENDPOINTID/receipt-id/
cardholder-name Cardholder name
card-exp-month Card expiration month
card-exp-year Card expiration year
destination-card-hash-id Unique card identifier to use for loyalty programs or fraud checks
destination-card-country-alpha-three-code Three letter country code of source card issuer. See Country Codes for details
email Customer e-mail
first-name Customer’s first name
last-name Customer’s last name
country * Customer’s country (two-letter country code). Please see Country Codes for a list of valid country codes
state * Customer’s state . Please see Country Codes for a list of valid state codes. Mandatory for USA, Canada and Australia
city * Customer’s city
zip_code * Customer’s ZIP code
address1 * Customer’s address line 1
dest-bank-name Bank name by customer card BIN
terminal-id Acquirer terminal identifier to show in receipt
paynet-processing-date Acquirer transaction processing date
approval-code Bank approval code
order-stage The current stage of the transaction processing. See Order Stage for details
loyalty-balance The current bonuses balance of the loyalty program for current operation. if available
loyalty-message The message from the loyalty program. if available
loyalty-bonus The bonus value of the loyalty program for current operation. if available
loyalty-program The name of the loyalty program for current operation. if available
descriptor Bank identifier of the payment recipient
original-gate-descriptor Descriptor, which is set on gate level in the system
error-message If status in declined, error, filtered this parameter contains the reason for decline
error-code The error code is case status in declined, error, filtered
by-request-sn Serial number from status request, if exists in request. Warning parameter amount always shows initial transaction amount, even if status is requested by-request-sn
verified-3d-status See 3-D Secure Status List for details
eci Electronic Commerce Indicator (Visa)
ips-src-payment-product-code Code for card set by multinational financial service. (Visa/Mastercard)
ips-src-payment-product-name Decrypted code for card set by multinational financial service. (Visa/Mastercard)
ips-src-payment-type-code Type of card code set by multinational financial service. (Visa/Mastercard)
ips-src-payment-type-name Decrypted code for type of card set by multinational financial service. (Visa/Mastercard)
initial-amount Amount, set in initiating transaction, without any fees or commissions. This value can’t change during the transaction flow
seller-commission Total commission for processed transaction. This is optional parameter. Please contact your manager in ConnPay, if you would like to receive it
acquirer-commission Acquirer commission for processed transaction. This is optional parameter. Please contact your manager in ConnPay, if you would like to receive it
motivational-message This is an optional message which contains extended information about the reason for the declined transaction.
transaction-date Date of final status assignment for transaction.
* - these parameters are not defined by default. Please contact tech support to include these fields in callback.

Order Status Response Example

type=status-response
&serial-number=00000000-0000-0000-0000-0000005b5eec
&merchant-order-id=6132tc
&processor-tx-id=9568-47ed-912d-3a1067ae1d22
&paynet-order-id=161944
&status=approved
&amount=7.56
&descriptor=no
&original-gate-descriptor=test 12345678 3Ds Bank
&gate-partial-reversal=enabled
&gate-partial-capture=enabled
&transaction-type=cancel
&receipt-id=2050-3c93-a061-8a19b6c0068f
&name=FirstName
&cardholder-name=FirstName
&card-exp-month=3
&card-exp-year=2028
&email=no
&last-name=Smith
&first-name=John
&processor-rrn=510458047886
&approval-code=380424
&order-stage=cancel_approved
&dest-last-four-digits=1111
&dest-bin=444455
&dest-card-type=VISA
&phone=%2B79685787194
&dest-bank-name=UNKNOWN
&paynet-processing-date=2015-04-14+10%3A23%3A34+MSK
&by-request-sn=00000000-0000-0000-0000-0000005b5ece
&destination-card-hash-id=1569311
&destination-card-country-alpha-three-code=RUS
&verified-3d-status=AUTHENTICATED
&eci=02
&ips-dst-payment-product-code=SAP
&ips-dst-payment-product-name=SAP—Platinum Mastercard® Salary– Immediate Debit
&ips-dst-payment-type-code=Debit
&ips-dst-payment-type-name=MASTERCARD Debit
&initial-amount=7.56
&motivational-message=Sorry, your payment has been declined.
&transaction-date=2023-01-10+12%3A46%3A28+MSK

Status request authorization through control parameter

The checksum is used to ensure that it is Merchant (and not a fraudster) that sends the request to ConnPay. This SHA-1 checksum, the parameter control, is created by concatenation of these parameters values in the following order:

  • login
  • client_orderid
  • orderid
  • merchant_control

For example, assume these parameters have the values as listed below:

Parameter Name Parameter Value
login cool_merchant
client_orderid 5624444333322221111110
orderid 9625
merchant_control r45a019070772d1c4c2b503bbdc0fa22

The complete string example may look as follows:

cool_merchant56244443333222211111109625r45a019070772d1c4c2b503bbdc0fa22

Encrypt the string using SHA-1 algorithm. The resultant string yields the control parameter which is required for authorizing the callback. For the example control above will take the following value:

c52cfb609f20a3677eb280cc4709278ea8f7024c

Order status Postman Collection

Order status V2 Debug

Possible transaction flow scenarios can be tested with E-Commerce test cards

endpointid
login
client_orderid
orderid
merchant_control
by-request-sn

String to sign
Signature
              
            
 


Order status V4 Debug

Possible transaction flow scenarios can be tested with E-Commerce test cards

Enter your private key in PKCS#1 container to use debug. See OAuth RSA-SHA256 for details.

Order status form
URL input URL
endpointid or groupid input your ENDPOINTID or ENDPOINTGROUPID
login
client_orderid input your Invoice Number
orderid
by-request-sn

Normalized parameters string to sign, according to OAuth 1.0a rules
POST body parameters to submit
OAuth 1.0a headers to submit.
HEX Encoded Signature
* HEX encoded string is for debug purposes only. You shouldn't send this string to the server neither in HEX nor in Encoded HEX representation.
Base64 Encoded Signature
* Binary RSA-SHA256 signature directly encoded in base64 should be sent to the server.