3.27. /api/v4/payout-form

Introduction

To make a payout-form request send an 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-form/ENDPOINTID	https://gate.connpay.com/paynet/api/v4/payout-form/ENDPOINTID
https://sandbox.connpay.com/paynet/api/v4/payout-form/group/ENDPOINTIDGROUPID	https://gate.connpay.com/paynet/api/v4/payout-form/group/ENDPOINTGROUPID

Request Parameters

Note

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

Ask Support Manager if Conditional fields are Required for integration.

Parameter Name	Description	Value
client_orderid	Connecting Party’s order identifier.	Necessity: Required Type: String Lenght: 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 Lenght: 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
order_desc	Brief order description.	Necessity: Conditional 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: 1024
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: 1024
redirect_succes_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 Lenght: 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 you use non-3DS schema for transactions processing and you have no need to return 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: Conditional 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_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’s Callback.	Necessity: Optional Type: String Length: 64k
merchant_form_data	Parameters sent in merchant_form_data API parameter are parsed into macros with the same name, the parameter is url-encoded, example: testparam%3Dtest1%26mynewparam%3Dtest2 and is parsed into $MFD_testparam = test1 and $MFD_mynewparam = test2 macros in the form. Parameter name characters[a-zA-Z0-9], parameter value characters[a-zA-Z0-9], control characters [=&], 2MB max size. For example, this parameter can be used to display payment form in light/dark mode depending on the value passed by Connecting Party (e.g. pass merchant_form_data=theme%3Ddark in request and $MFD_theme macro placeholder on payment form will be changed to dark.	Necessity: Optional Type: String Length: 128
preferred_language	Preferred language.	Necessity: Optional Type: String Length: 2
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_recurring_payment_id	Payer’s tokenized cardholder’s data ID, referred as Recurring Payment ID (RPI). 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 /api/v4/create-card-ref. Note: For the scenario of payment to a card inside the system, this card will be considered as a source, and all processing limits, lists and fraud scoring will be applied to it as a source card.	Necessity: Conditional Type: Long

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.

Parameter Name	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.
redirect_url	The URL to the page where the Connecting Party should redirect the client’s browser. Connecting Party should send HTTP 302 redirect.

Request Example

POST /paynet/api/v4/payout-form/39915 HTTP/1.1
Host: sandbox.connpay.com
User-Agent: curl/7.83.0
Accept: */*
Authorization: OAuth oauth_consumer_key="TestMerchant", oauth_nonce="GtAAIvMXjF6QLjWDaFk8L9C4glV9rwQ0", oauth_signature="RpPfm4BDtjrDikqy3hvQIUiLdWOM4Gao0VzSkFIbvEI1RSK969crOUmNHXFNXgoNKV7yvI98jlTar3IZPin%2B8JwXRN0EgS8SUQHd1xPQaKD6RdLXazrwNUaxl0yeg9IwRLBJz5TzF7DphCQVwTvKZkSYfFnLayQyheExhzSJPCFUm%2Bh33PtxJAAsCscYgTGlNkaVRYARZ5b2Pe%2FSygITeg2xevn0yjoqd1Rl0wbB3d1EvqGB7AFJMxpMG1lMe33w6FKvU%2B6rJgIGEipkoTZ8HITwZybZvhrFDWst1ODTzJxfuxd8JBE0Pn1dwDBAbLkPKqD5%2F%2BLOsszUnDJ%2FJSAItNWMmEQ7QBumvYG2qgUSKJi%2FsG7VM%2FJY1esr5CELW%2FeMXfWEwNMNx0w%2BUQ8t%2F7YOWQpZAmtfykRyM%2BNwGbHaFWt%2F6honcfXtwbYIOu5XtWyiOn37CxdY5CB9sZyo%2FAFP7isByhs3kRpcc%2BioFlpsyXWi1K3LvevqheGC8jDsf6XTqh%2Fn%2B1njjopUmkuKFB1qzxu0I%2FO4AIIPzm%2BvSfJmTzO5iYV11%2FtFzLEr9BCVRXShbjACwRFEDEQv9C73csGpWop9XGB7CKLaPD3KlLswVNMuOhZyU4FxLP%2BglEpJ7xJB45arMHShBHUl1GnedAHh7Nq46Si1mEOBpm0rdEUgRJfZbGKu12VO2U9B5q8Nack3QNHD9yJ3hyEEaURGg2yzSaCiTJd2wuOmqJ4KJ9aZTQ0F6T6wHj9lf0dzE47KK3ldbqryGUNwTBvQRPJqPgEfIQy6Ou3hbimi1feWQoA9Q9vx7SNPiKaZMYG8tNLo6qMT00iZ12b3qgbiVNbFYrqWckQrEoOj16Lp9A%2FeaMkF%2FFL%2B6DxicGPQaPTMezTRnHTvkI4rZcRZoxlOcEeI3a%2FWTiBXxcUVwfnpOaWeOi4DWdSY%2BJuiIIGRjBjh5owtR87lexWAxUPH8a5bmrS9TcHNF1amggunLjzk5hDAiMgJRyhL7btB2B3rkHbNvbfZ6QnNAjvgBWdoB7djjbRe4Pob4T3wC%2Bg5aTFxhyQSEIlhKiQ9WpPUlUR3stXyP31zgs4BgCbi3t1OYyV2XCl0W%2BrXa5x%2FqFbfN3AJB7ttfq4TNi5G0CeabcZ0T%2FhlHn2sopQPkX1ZnokmO3Tof7TANmZ9nM0avlTjFJjOpqunPoc7Uq4VbT7QyTayfO9d38IizWEncc77f6ZiDxnUQW0jJhrt0e4GN2iJ7WwcZ82NSq5kQAPGUaqiUsr5YchSZke7KUXuJjKVqLpVI7VyR%2B82LcA2oqVeu6ifgjGuCJBQiC%2F9nsEetosRz8Z2vp1jiZ%2F3u61n0dwkowGftGcnIT73JFr7hg%3D%3D", oauth_signature_method="RSA-SHA256", oauth_timestamp="1678178824", oauth_version="1.0"
Content-Length: 381
Content-Type: application/x-www-form-urlencoded
Connection: close


account_number=1234567890
&amount=100
&bank_branch=test_branch
&bank_name=test_bank
&client_orderid=12345
&currency=USD
&order_desc=TEST
&redirect_url=http%3A%2F%2Fhttps://doc.connpay.com/%2Fdoc%2Fdummy.htm%09
&server_callback_url=https%3A%2F%2Fhttpstat.us%2F200

Success Response Example

HTTP/1.1 200
Server: server
Date: Tue, 07 Mar 2023 08:47:54 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: 281

type=async-form-response
&serial-number=00000000-0000-0000-0000-000002e33afd
&merchant-order-id=12345
&paynet-order-id=6993513
&redirect-url=https%3A%2F%2Fsandbox.connpay.com%2Fpaynet%2Fform%2Finit%2FBB587546567A31587163597A684535634A775969614A5A6367507733385468565A54514E48467135715A74773D

Fail Response Example

HTTP/1.1 403 Forbidden
Server: server
Date: Thu, 25 Aug 2022 06:50:16 GMT
Content-Type: text/html
Content-Length: 735
Connection: close
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000

<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
<title>403</title>

<style type="text/css">
body {
font-family: Arial, sans-serif;
font-size: 130%;
background-color: #eee;
}

p {
margin: 10em auto 0;
width: 500px;
border: 1px solid gray;
text-align: center;
vertical-align: middle;
padding: 40px 20px;
background-color: #fff;
-webkit-border-radius: 20px;
-moz-border-radius: 20px;
border-radius: 20px;
}
</style>
</head>

<body>
<p>Access is denied</p>
</body>
</html>

Test Scenario

Different Payout transaction statuses can be received on sandbox depending on the account_number value passed in Payout request.

Testing account_number values:

• account_number = 1234567890 to get APPROVED

• account_number = 0987654321 to get DECLINED

• account_number = 1987654321 to get PROCESSOR_INTERNAL_ERROR

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