3.28. /api/v4/payout-by-ref/

Introduction

Payout By Reference 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/payout-by-ref/ENDPOINTID	https://gate.connpay.com/paynet/api/v4/payout-by-ref/ENDPOINTID
https://sandbox.connpay.com/paynet/api/v4/payout-by-ref/group/ENDPOINTGROUPID	https://gate.connpay.com/paynet/api/v4/payout-by-ref/group/ENDPOINTGROUPID

Request Parameters

Note

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

Parameter Name	Description	Value
client_orderid	Connecting Party’s order identifier.	Necessity: Required Type: String Length: 128
amount	Amount to be charged. The amount has to be specified in the highest units with . delimiter. For instance, 10.5 for USD means 10 US Dollars and 50 Cents.	Necessity: Required Type: Numeric Length: 10
currency	Currency the transaction is charged in (three-letter currency code). Sample values are: USD for US Dollar EUR for European Euro.	Necessity: Required Type: String Length: 3
destination-card-ref-id	Card reference id to destination card, obtained at Card Registration step. 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: Required Type: Numeric Length: 20
order_desc	Brief order description.	Necessity: Optional Type: String Length: 64
ipaddress	Receiver’s IP address (IPv4 or IPv6).	Necessity: Conditional Type: String Length: 7-45
purpose	Payout purpose.	Necessity: Conditional Type: String Length: 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 Length: 128
redirect_url	URL, where the Receiver is redirected to upon completion of the transaction. Please note that redirection is performed in any case, no matter whether transaction is approved, declined in any other final status. Connecting Party must not use the parameters come along with the redirect HTTP Request to treat the status of the transaction. Instead Connecting Party can utilize server_callback_url or status API command. Pass https://doc.connpay.com/ if you have no need to return Receiver anywhere. Use either redirect_url or combination of redirect_success_url and redirect_fail_url, not both.	Necessity: Optional Type: String Length: 128
redirect_success_url	URL, where the Receiver is redirected to when transaction status is approved (See status list). Connecting Party must not use the parameters come along with the redirect HTTP Request to treat the status of the transaction. Instead Connecting Party can utilize server_callback_url or status API command. Otherwise put https://doc.connpay.com/ if there is no need to redirect Receiver anywhere. Use either combination of redirect_success_url and redirect_fail_url or redirect_url, not both.	Necessity: Optional Type: String Length: 1024
redirect_fail_url	URL, where the Receiver is redirected to when transaction status is not approved (See status list). Connecting Party must not use the parameters come along with the redirect HTTP Request to treat the status of the transaction. Instead Connecting Party can utilize server_callback_url or status API command. Pass https://doc.connpay.com/ if there is no need to redirect Receiver anywhere. Use either combination of redirect_fail_url and redirect_success_url or redirect_url, not both.	Necessity: Optional Type: String Length: 1024
account_number	Account Number.	Necessity: Conditional Type: String Length: 24
account_name	Bank account.	Necessity: Optional Type: String Length: 128
ewallet_type	Type of e-wallet.	Necessity: Conditional Type: String Length: 64
ewallet_wallet	E-wallet ID.	Necessity: Conditional Type: String Length: 128
crypto_wallet_address	Address of crypto wallet.	Necessity: Conditional Type: String Length: 64
bank_name	Bank Name.	Necessity: Conditional Type: String Length: 255
bank_branch	Bank Branch Name.	Necessity: Conditional Type: String Length: 255
bank_code	Bank code.	Necessity: Conditional Type: String Length: 32
bank_city	Bank city.	Necessity: Conditional Type: String Length: 128
bank_address1	Bank address.	Necessity: Conditional Type: String Length: 255
bank_zip_code	Bank postal ZIP code.	Necessity: Conditional Type: String Length: 255
bank_province	Bank province.	Necessity: Conditional Type: String Length: 255
bank_area	Bank area.	Necessity: Conditional Type: String Length: 255
routing_number	Routing number used to identify specific bank branches in China.	Necessity: Conditional Type: String Length: 16
legal_person_name	Name on the legal document.	Necessity: Conditional Type: String Length: 128
legal_person_document_number	Number of legal document.	Necessity: Conditional Type: String Length: 128
receiver_first_name	Receiver first name, also can be sent as first_name.	Necessity: Conditional Type: String Length: 128
receiver_last_name	Receiver last name, also can be sent as last_name.	Necessity: Conditional Type: String Length: 128
receiver_birthday	Receiver birthday, also can be sent as birthday.	Necessity: Conditional Type: Numeric Length: 30
receiver_country_code	Receiver country code, also can be sent as country.	Necessity: Conditional Type: String Length: 3
receiver_state	Receiver state, should be provided for countries that have states (USA, Canada, Australia), also can be sent as state.	Necessity: Conditional Type: String Length: 4
receiver_city	Receiver city, also can be sent as city.	Necessity: Conditional Type: String Length: 128
receiver_zip_code	Receiver zip code, also can be sent as zip_code.	Necessity: Conditional Type: Numeric Length: 32
receiver_address1	Receiver address, also can be sent as address1.	Necessity: Conditional Type: String Length: 256
receiver_phone	Receiver phone, also can be sent as phone.	Necessity: Conditional Type: Numeric Length: 128
receiver_email	Receiver E-mail, also can be sent as email.	Necessity: Conditional Type: String Length: 128
receiver_identity_document_id	Receiver identity document identifier, also can be sent as identity_document_id.	Necessity: Conditional Type: String Length: 128
receiver_identity_document_number	Receiver identity document number, also can be sent as identity_document_number.	Necessity: Conditional Type: String Length: 128
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 Length: 64k
bank_bic	BIC of the receiver’s bank.	Necessity: Optional Type: String Length: 128
receiver_inn	Receiver’s INN.	Necessity: Optional Type: String Length: 128
customer_level	Customer level in CMS system	Necessity: Optional Type: Varchar Length: 32
customer_id	Customer ID in CMS system. Necessity becomes required if transaction goes via CMS (PNE)	Necessity: Optional Type: Int Length: 10
merchant_customer_identifier	Merchant Customer ID in CMS system. Necessity becomes required if transaction goes via CMS (CRM)	Necessity: Optional Type: Varchar Length: 64
card-ref-id	Card reference ID used in subsequent recurring payments. Card reference ID creation is initiated through HTTPS POST request by using URLs and the parameters specified below. Use OAuth RSA-SHA256 for authentication.	Necessity: Conditional Type: Long

* Ask Support Manager if Conditional fields are Required for integration.

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.

Payout Request Parameters	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/payout-by-ref/121799 HTTP/1.1
Host: sandbox.connpay.com
User-Agent: curl/8.4.0
Accept: */*
Authorization: OAuth oauth_consumer_key="ErwinTestMerchant", oauth_nonce="8qsDrhiDelGHlxY01aDjCh44u7isXJjL", oauth_signature="WpbNcRxNSDW%2BdJgftRc%2BAN0oe8KAP4CNpUkxjxStFYZEU9Vo%2F7uk9dSKEG%2B76C%2FdlzemILaRmikQqZg93ZK1cibT8zy97uYVDdWVmY2obDSOVb8UipGjt2KFUyKr4awHW9xH%2BTzbR%2FMXwm3y%2Fx2RotElZWxumsL37P5Q%2BCquoAGcO6jjkvkkSH9P4lBYKSmwhfqD4O%2Br8FB3exzNzl2FFBTwLp4ch2G9Cis5a0CkVrpjDB%2FbbbrOutbNPZYhtH45rNz91QAbpvNJ91XjVwxiCm4lCldIO66gF73GQNSFKVG1mstc%2B941Dj1bVhXWQQW%2F9TyPiXfWGP8szg18rwsTHbj1zKCRIaw%2FqVbrOBPhbo%2BJjGMZp2hB1ei0%2FUPIkjeIZkWD2NgJRQEniJfjU7AlILs91augm50fPwWR5JiOuE5uSvwM6VWgXMpYe4USb819ZAK%2BFYTRI%2BenrycFZHmY%2BafOlaOHFtpnbn8FsrzzNbOvGXmXCt2xXAQTaORqMeLRRtkD3DY4rJa8qeO0zYnmT4ZhKsFZjImDdonA3WTG8G7awP9W0RKhHlUGwGaugRWbdPjSbGMhAzs58Y9ptvExr6GwAHhJU1RbzfWL4wCzVbH8%2BAC6I0OrkB13tw2eXP4yIPtEC7iGu%2FkElGz4OrwFEU6cUcEDpeEOmA2%2Fe%2BZFK0w%3D", oauth_signature_method="RSA-SHA256", oauth_timestamp="1721975900", oauth_version="1.0"
Content-Length: 74
Content-Type: application/x-www-form-urlencoded
Connection: keep-alive

amount=10.42
&client_orderid=1
&currency=USD
&destination-card-ref-id=1461897

Success Response Example

HTTP/1.1 200
Server: server
Date: Fri, 26 Jul 2024 06:39:23 GMT
Content-Type: text/html;charset=utf-8
Connection: keep-alive
Keep-Alive: timeout=60
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: 138

type=async-response
&serial-number=00000000-0000-0000-0000-000002f36e41
&merchant-order-id=1
&paynet-order-id=7363634
&end-point-id=121799

Fail Response Example

HTTP/1.1 200
Server: server
Date: Fri, 26 Jul 2024 06:42:43 GMT
Content-Type: text/html;charset=utf-8
Connection: keep-alive
Keep-Alive: timeout=60
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 170

type=validation-error
&serial-number=00000000-0000-0000-0000-000002f36e42
&error-message=Project+with+currency+USD+does+not+apply+request+with+currency+AZN
&error-code=16

Postman Collection

Request Builder

Insert PKCS#1 PEM private key for sandbox environment in the field below. Request builder supports up to 4096 key length.

-----BEGIN RSA PRIVATE KEY----- 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 -----END RSA PRIVATE KEY-----

Debug form

URL
parameters
login	login should be used as Consumer Public for OAuth

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

• CURL
• PHP
• Ruby
• Java

Copy to clipboard

Copy to clipboard

Copy to clipboard

Copy to clipboard