1.1.5. Deposit to Card Transfer

Direct Integration

Deposit to card 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/v2/create-card-ref/ENDPOINTID – to get card-ref-id
https://gate.connpay.com/paynet/api/v4/transfer-by-ref/ENDPOINTID – to make transfer from account to destination card-ref-id
for integration purposes use staging environment sandbox.connpay.com instead of production gate.connpay.com

Deposit to card multi currency URL

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/create-card-ref/group/ENDPOINTGROUPID – to get card-ref-id
https://gate.connpay.com/paynet/api/v4/transfer-by-ref/group/ENDPOINTGROUPID – to make multi currency transfer from account or source card-ref-id to destination card number or destination card-ref-id

Deposit to card General Flow

Deposit to card is made in three steps:

  1. Initial payment – make initial payment sale or preauth transaction type to verify and authorize the credit card
  2. Card registration – get card’s reference ID card-ref-id and remember it
  3. Money transfer – run transfer-by-ref using card-ref-id

Process Card Registration

Merchant should get card-ref-id that will be used in future payments in order to avoid storing the credit card sensitive data which is required by PCI DSS. Card Registration ID is totally secure and cannot be used by fraudsters to process fraudulent transaction even if they know it. This allows to securely save card-ref-id in Customer’s profile on the Merchant’s side.

Card registration transactions are initiated through HTTPS POST request by using URL in the following format:

https://gate.connpay.com/paynet/api/v2/create-card-ref/ENDPOINTID
for integration purposes use staging environment sandbox.connpay.com instead of production gate.connpay.com

Card registration request parameters

Note

Request must have content-type=application/x-www-form-urlencoded and Authorization headers.
Request parameters Description
login Merchant login name
client_orderid Merchant order identifier of the transaction for which the status is requested
orderid Order id assigned to the order by ConnPay
control Checksum used to ensure that it is ConnPay (and not a fraudster) that initiates the callback for a particular Merchant. This is SHA-1 checksum of the concatenation login + client-order-id + paynet-order-id + merchant-control

As you may see from the parameters list Merchant has to supply orderid and client_orderid associated with the first payment transaction. It emphasizes that the first payment is a mandatory step to process any recurrent payments.

Card Registration 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.
Response parameter Description
type The type of response. May be create-card-ref-response, validation-error, error. If type equals validation-error or error, error-message and error-code parameters contain error details
status The status code of the order. May be approved, error or filtered. It type equals filtered it means the transaction was considered fraudulent by ConnPay Server
card-ref-id Card reference ID to used in deposit to card payments
unq-card-ref-id Unique customer’s tokenized cardholder’s data ID to each PAN. It can be used by Merchant for loyalty programs or fraud control.
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
error-code The error code is case of declined or error status
end-point-id Endpoint id used for the transaction.

Process money transfer

Merchant initiates transfer using given destination-card-no or destination-card-ref-id.
ConnPay returns new Order ID for the this transfer.
Merchant starts polling ConnPay by using Order Status API.
ConnPay returns current status of the order. processing status means the order is still being processed.
ConnPay processes the payment using appropriate bank’s gateway.
Merchant keeps polling ConnPay by using Order Status API.
ConnPay returns current status of the order -approved.
See more details about asynchronous status polling at Order Status API.

Money transfer request parameters

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

Note

Request must have content-type=application/x-www-form-urlencoded and Authorization headers.
Money transfer request parameter Length/Type Comment Necessity
client_orderid 128/String Merchant order identifier Mandatory
login 20/String Merchant’s login. Must be used as oauth_consumer_key in OAuth Authorization, not included in request as login parameter Mandatory
destination-card-no 16-19/String Card number of destination card. Mandatory if destination-card-ref-id omitted Conditional
destination-card-ref-id 20/Numeric Card reference id to destination card, obtained at Card Registration step. Mandatory if destination-card-no omitted Conditional
amount 10/Numeric 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 Mandatory
currency 3/String Currency the transaction is charged in (three-letter currency code). Example ofВ  valid parameter values are: USD for US Dollar EUR for European Euro Mandatory
order_desc 64k/String Order description Mandatory
receiver_identity_document_series 512/String Receiver’s identity document series (e.g. 4 digits for Russian Federation passport) Optional
receiver_identity_document_number 512/String Receiver’s identity document number (e.g. 6 digits for Russian Federation passport) Optional
receiver_identity_document_id 512/String Receiver’s identity document id. Possible values: 21 for Russian Federation passport or 31 for international passport Optional
receiver_address1 512/String Receiver’s address Conditional*
receiver_city 512/String Receiver’s city Conditional*
receiver_first_name 128/String Receiver first name Mandatory
receiver_middle_name 128/String Receiver middle name Optional
receiver_last_name 128/String Receiver last name Mandatory
receiver_phone 128/String Receiver full international cell phone number, including country code Optional
receiver_resident Boolean (true/false) Is receiver a resident? Optional
ipaddress 45/String Customer’s IP address, included for fraud screening purposes Optional
first_name 128/String Sender first name Optional
middle_name 128/String Sender middle name Optional
last_name 128/String Sender last name Optional
ssn 32/Numeric Last four digits of the Sender’s social security number Optional
birthday 8/Numeric Sender date of birth, in the format MMDDYY Optional
address1 50/String Sender address line 1 Optional
city 50/String Sender city Optional
state 2-3/String Sender’s state. Please see Appendix A for a list of valid state codes. Mandatory for USA, Canada and Australia Optional
zip_code 10/String Sender ZIP code Optional
receiver_zip_code 10/String Receiver ZIP code Conditional*
country 2/String Sender country(two-letter country code). Please see Appendix B for a list of valid country codes Optional
receiver_country_code 2/String Receiver country(two-letter country code). Please see Appendix B for a list of valid country codes Optional
phone 15/String Sender full international phone number, including country code Optional
cell_phone 15/String Sender full international cell phone number, including country code Optional
email 50/String Sender email address Optional
purpose 128/String Destination to where the payment goes. It is useful for the merchants who let their clients to transfer money from a credit card to some type of client’s account, e.g. game or mobile phone account. Sample values are: +7123456789; gamer0001@ereality.com etc. This value will be used by fraud monitoring system Optional
server_callback_url 128/String URL the transaction result will be sent to. Merchant may use this URL for custom processing of the transaction completion, e.g. to collect sales data in Merchant’s database. See more details at Merchant Callbacks Optional
redirect_url 250/String 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. See more details at Statuses Optional
redirect_success_url 1024/String URL the cardholder will be redirected to upon completion of the transaction. Please note that the cardholder will be redirected only in case if the transaction is approved Optional
redirect_fail_url 1024/String URL the cardholder will be redirected to upon completion of the transaction. Please note that the cardholder will be redirected only in case if the transaction is declined or filtered Optional
merchant_data 64k/String Any additional information for this transaction which may be useful in Merchant’s external systems, e.g. VIP customer, TV promo campaign lead. Will be returned in Status response and Merchant Callback. Optional

Parameters marked as Conditional* can be mandatory for specific integrations. For more information, please contact your manager in ConnPay.

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
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

Transfer Response Example

type=async-response
&serial-number=00000000-0000-0000-0000-0000000624e8
&merchant-order-id=59e1e3ca-5d44-11e1-b3d6-002522b853b4
&paynet-order-id=94935

Transfer Request Postman Collection

Transfer Request Debug

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

Debug form

Fillup mandatory fields (the red ones) with appropriate values. Empty values will not be included in output.

Use either destination-card-no or destination-card-ref-id

URL input URL
login your login should be used as Consumer Public for OAuth
client_orderid make it or use your internal invoice ID
destination-card-no enter the beginning of the sequence, and then "i".
destination-card-ref-id
order_desc
amount
currency
ipaddress
first_name
middle_name
last_name
ssn
birthday
address1
city
state
zip_code
country
phone
cell_phone
email
purpose
receiver_first_name
receiver_middle_name
receiver_last_name
receiver_phone
receiver_resident
receiver_identity_document_series
receiver_identity_document_number
receiver_identity_document_id
receiver_address1
receiver_city
redirect_url
redirect_success_url
redirect_fail_url
server_callback_url
merchant_data

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.
Recommended status polling time is 5 minutes with 3-5 seconds interval.
See more details at Statuses

Status API URL

Status API calls are initiated through HTTPS POST request by using URL in the following format:
https://gate.connpay.com/paynet/api/v2/status/ENDPOINTID
for integration purposes use staging environment sandbox.connpay.com instead of production gate.connpay.com

Order status call parameters

Note

Request must have content-type=application/x-www-form-urlencoded.
Call status 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
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 Optional
control Checksum used to ensure that it is ConnPay (and not a fraudster) that initiates the callback for a particular Merchant. This is SHA-1 checksum of the concatenation login + client-order-id + paynet-order-id + merchant-control. See Order Status API call authorization through control parameter for more details about generating control checksum Mandatory
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 The status code of the initial transaction. May be approved, declined, processing, error or filtered. It type equals filtered it means the transaction was considered fraudulent by ConnPay Server
amount Actual transaction amount. This value can be changed during the transaction flow
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/
destination-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
purpose Destination to where the payment goes. It is useful for the merchants who let their clients to transfer money from a credit card to some type of client’s account, e.g. game or mobile phone account. Sample values are: +7123456789; gamer0001@ereality.com etc. This value will be used by fraud monitoring system
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
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)
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 assigned to the specific request by ConnPay. If this field exist in status request, status response return for this specific request
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.

Note

* - 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-00000aa68276
&merchant-order-id=pg1sbw
&processor-tx-id=15222817
&paynet-order-id=15222817
&status=approved
&amount=20000.00
&descriptor=no
&transaction-type=transfer
&receipt-id=18042926-d652-331c-b5a0-3e1dbacf69b2
&email=gmail.com
&last-name=Smith
&first-name=John
&processor-rrn=187722741
&approval-code=610669
&order-stage=transfer_approved
&phone=%2B79633014273
&dest-bank-name=SBERBANK
&dest-bin=427655
&dest-last-four-digits=7682
&dest-card-type=VISA
&paynet-processing-date=2015-04-06+22%3A00%3A27+MSK
&by-request-sn=00000000-0000-0000-0000-00000a8d3992
&destination-card-hash-id=1664889
&destination-card-country-alpha-three-code=MYS
&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=20000.00
&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 concatenating of the values of the parameters in the following order:

  • login
  • client_orderid
  • orderid
  • merchant_control

For example assume the following values are corresponds the parameters above:

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 Debug

endpointid
login
client_orderid
orderid
merchant_control
by-request-sn

String to sign
Signature