3.31. api/v4/transfer-by-ref

Introduction

Deposit to card transfer (D2C) is a money transfer from Connecting Party bank account (Deposit) and Receiver bank card number (PAN) or tokenized card data (Card Reference ID). Deposit to card is initiated through HTTPS POST request by using URLs and the parameters specified below. Use OAuth RSA-SHA256 for authentication.

API URLs

Integration	Production
https://sandbox.connpay.com/paynet/api/v4/transfer-by-ref/ENDPOINTID	https://gate.connpay.com/paynet/api/v4/transfer-by-ref/ENDPOINTID
https://sandbox.connpay.com/paynet/api/v4/transfer-by-ref/group/ENDPOINTGROUPID	https://gate.connpay.com/paynet/api/v4/transfer-by-ref/group/ENDPOINTGROUPID

Request Parameters

Note

Request must have content-type=application/x-www-form-urlencoded and Authorization headers.

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

Parameter Name	Description	Value
client_orderid	Connecting Party order identifier.	`Necessity`: Required `Type`: String `Lenght`: 128
login	Connecting Party’s login. Must be used as oauth_consumer_key in OAuth Authorization, not included in request as login parameter.	`Necessity`: Required `Type`: String `Lenght`: 20
destination-card-no	Card number of destination card. Mandatory if destination-card-ref-id omitted. For the scenario of payment to a card inside the system, this card will be considered as a destination, and all processing limits, lists and fraud scoring will be applied to it as a destination card.	`Necessity`: Conditional `Type`: String `Lenght`: 16-19
destination-card-ref-id	Card reference id to destination card, obtained at Card Registration step. Mandatory if destination-card-no omitted. For the scenario of payment to a card inside the system, this card will be considered as a destination, and all processing limits, lists and fraud scoring will be applied to it as a destination card.	`Necessity`: Conditional `Type`: Numeric `Lenght`: 20
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.	`Necessity`: Required `Type`: Numeric `Lenght`: 10
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.	`Necessity`: Required `Type`: String `Lenght`: 3
order_desc	Order description.	`Necessity`: Required `Type`: String `Lenght`: 64k
receiver_identity_document_series	Receiver’s identity document series (e.g. 4 digits for domestic passport).	`Necessity`: Optional `Type`: String `Lenght`: 512
receiver_identity_document_number	Receiver’s identity document number (e.g. 6 digits for domestic passport).	`Necessity`: Optional `Type`: String `Lenght`: 512
receiver_identity_document_id	Receiver’s identity document id. Possible values: 21 for domestic passport or 31 for international passport.	`Necessity`: Optional `Type`: String `Lenght`: 512
receiver_address1	Receiver’s address.	`Necessity`: Conditional* `Type`: String `Lenght`: 512
receiver_city	Receiver’s city.	`Necessity`: Conditional* `Type`: String `Lenght`: 512
receiver_first_name	Receiver first name.	`Necessity`: Required `Type`: String `Lenght`: 128
receiver_middle_name	Receiver middle name.	`Necessity`: Optional `Type`: String `Lenght`: 128
receiver_last_name	Receiver last name.	`Necessity`: Required `Type`: String `Lenght`: 128
receiver_phone	Receiver full international cell phone number, including country code.	`Necessity`: Optional `Type`: String `Lenght`: 128
receiver_resident	Is receiver a resident?	`Necessity`: Optional `Type`: Boolean `Lenght`: true/false
ipaddress	Customer’s IP address, included for fraud screening purposes.	`Necessity`: Optional `Type`: String `Lenght`: 45
first_name	Sender first name.	`Necessity`: Optional `Type`: String `Lenght`: 128
middle_name	Sender middle name.	`Necessity`: Optional `Type`: String `Lenght`: 128
last_name	Sender last name.	`Necessity`: Optional `Type`: String `Lenght`: 128
ssn	Last four digits of the Sender’s social security number.	`Necessity`: Optional `Type`: Numeric `Lenght`: 32
birthday	Sender date of birth, in the format MMDDYY.	`Necessity`: Optional `Type`: Numeric `Lenght`: 8
address1	Sender address line 1.	`Necessity`: Optional `Type`: String `Lenght`: 50
city	Sender city.	`Necessity`: Optional `Type`: String `Lenght`: 50
state	Sender’s state. Please see Appendix A for a list of valid state codes. Mandatory for USA, Canada and Australia.	`Necessity`: Optional `Type`: String `Lenght`: 2-3
zip_code	Sender ZIP code.	`Necessity`: Optional `Type`: String `Lenght`: 10
receiver_zip_code	Receiver ZIP code.	`Necessity`: Conditional* `Type`: String `Lenght`: 10
country	Sender country(two-letter country code). Please see Appendix B for a list of valid country codes.	`Necessity`: Optional `Type`: String `Lenght`: 2
receiver_country_code	Receiver country(two-letter country code). Please see Appendix B for a list of valid country codes.	`Necessity`: Optional `Type`: String `Lenght`: 2
phone	Sender full international phone number, including country code.	`Necessity`: Optional `Type`: String `Lenght`: 15
cell_phone	Sender full international cell phone number, including country code.	`Necessity`: Optional `Type`: String `Lenght`: 15
email	Sender email address.	`Necessity`: Optional `Type`: String `Lenght`: 50
purpose	Destination to where the payment goes. It is useful for the Connecting Parties 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.	`Necessity`: Optional `Type`: String `Lenght`: 128
server_callback_url	URL the transaction result will be sent to. Connecting Party may use this URL for custom processing of the transaction completion, e.g. to collect sales data in Connecting Party’s database. See more details at Connecting Party Callbacks.	`Necessity`: Optional `Type`: String `Lenght`: 128
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. See more details at Statuses.	`Necessity`: Optional `Type`: String `Lenght`: 250
redirect_success_url	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.	`Necessity`: Optional `Type`: String `Lenght`: 1024
redirect_fail_url	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.	`Necessity`: Optional `Type`: String `Lenght`: 1024
merchant_data	Any additional information for this transaction which may be useful in Connecting Party’s external systems, e.g. VIP customer, TV promo campaign lead. Will be returned in Status response and Connecting Party Callback.	`Necessity`: Optional `Type`: String `Lenght`: 64k

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.

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	Connecting Party order id.
serial-number	Unique number assigned by ConnPay server to particular request from the Connecting Party.
error-message	If status is error this parameter contains the reason for decline or error details.
error-code	The error code is case of error status.

Request Example

POST /paynet/api/v4/transfer-by-ref/39915 HTTP/1.1
Host: sandbox.connpay.com
User-Agent: curl/7.83.0
Accept: */*
Authorization: OAuth oauth_consumer_key="TestMerchant", oauth_nonce="w1rmMzx2Sq2k5Hi7KAZmdhHHD6BygKcE", oauth_signature="rXn0DwLOlaV%2Ft1q3s%2FJdLybJTdxKKN0XeFtyVNZ0U5bG0Qfcc6iyHqQG66Ohb852CYKjhrxvG3wf33RlIQdO9f23OSg91JkdrUgl8QDrMqntC5myWGR1woums%2BMjpV821fAY8AS%2BBByNUKOuC1mwFgLYwr5YinbhjDa6P8aEdHgbf%2FVw5vg9OqjwKxJhSXPGB5mIg7T9gTNXF4n4YTUJA0l%2BWyeGcIjuTSsiCUnbsrNjBOGYc0PlUSuHirwJ0NiKVdHk3qaZrGaEw8SZEq%2F8x0naoaaOXUq%2FkpqPfTJT%2FjTl%2FbGyX1x%2FwTl6EYgIElavHYj2psIGmFnyUk%2FYnaGZHikE00rSf4IkG5Ye2M4hyl7lKQOCXMZMvvGtfvLm0RsAod8o30KuDD5Tw%2BRmDiQNCqN8GeZawHsZipgwZuy2IdZ3sHiot3U6NEt1OVH9TsWDU%2FstfBJOWBBStTRTTh4hn3Zvf5jLuTfTcepKz4CIgdQGGmMmRSz6dcBnkYJaa7VRTh27dz%2BnEuC0laEYAytVuzQA43MvUXNLmAuh9JlmqQquAZwB%2BRFfLPgOj%2FVVsFsqX35UWBYQtWlWdEVc3jWBVxCjEW0s8cAcowlb4R2g4V48HC2Rz3ggfINzP9%2FWtX1nkNnIlzQAeYbMREguYqFrK%2BYK6Lqyu%2BM1jeo6j9CWhhk%3D", oauth_signature_method="RSA-SHA256", oauth_timestamp="1697442690", oauth_version="1.0"
Content-Length: 805
Content-Type: application/x-www-form-urlencoded
Connection: close

address1=10020Main%20st
&amount=100
&birthday=19820115
&cell_phone=%2B19023384543
&city=Seattle
&client_orderid=34T43R77N
&country=US
&currency=USD
&destination-card-ref-id=1461819
&email=john.smith%40gmail.com
&first_name=John
&ipaddress=65.153.12.232
&last_name=Smith
&merchant_data=VIP%20customer
&middle_name=M
&order_desc=Test%20Order%20Description
&phone=%2B12063582043
&purpose=user_account1
&receiver_address1=Red%20Sq%2C%201a
&receiver_city=Moscow
&receiver_first_name=Jane
&receiver_identity_document_id=21
&receiver_identity_document_number=222222
&receiver_identity_document_series=1111
&receiver_last_name=Doe
&receiver_middle_name=L
&receiver_phone=%2B79031110022
&receiver_resident=true
&redirect_url=http%3A%2F%2Fwww.example.com%2F
&server_callback_url=https%3A%2F%2Fhttpstat.us%2F200
&ssn=1267&state=WA
&zip_code=98102

Success Response Example

HTTP/1.1 200
Server: server
Date: Mon, 16 Oct 2023 13:20: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: 145

type=async-response
&serial-number=00000000-0000-0000-0000-000002ee3a57
&merchant-order-id=34T43R77N
&paynet-order-id=7234671
&end-point-id=39915

Fail Response Example

HTTP/1.1 200
Server: server
Date: Mon, 16 Oct 2023 07:54:11 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: 162

type=validation-error
&serial-number=00000000-0000-0000-0000-000002ee3a4f
&merchant-order-id=34T43R77N
&error-message=Rebill+1461819+was+not+found
&error-code=104

Postman Collection

Request Builder

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

Debug form

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