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.

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.