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.