.. meta::
   :description: /api/v4/payout-form ConnPay API endpoint: initiate a payout via hosted form where the recipient enters card details to receive funds.

.. _/api/v4/payout/form/:

/api/v4/payout-form
####################

.. role:: ex

.. role:: code

Introduction
^^^^^^^^^^^^

To make a payout-form request send an :code:`HTTPS POST` request - by using :ref:`URLs<payout-form/apis>` and the :ref:`parameters<payout_form_parameters>` specified below. Use :ref:`RSA-SHA256` for authentication.

.. _payout-form/apis:

API URLs
^^^^^^^^

.. note::
    | The path in API URL should not be hardcoded, as it may be changed in future.

.. list-table::
  :widths: 50, 50
  :header-rows: 1
  :class: longtable

  * - Integration
    - Production
  * - :ex:`https://sandbox.connpay.com/paynet/api/v4/payout-form/ENDPOINTID`
    - :ex:`https://gate.connpay.com/paynet/api/v4/payout-form/ENDPOINTID`
  * - :ex:`https://sandbox.connpay.com/paynet/api/v4/payout-form/group/ENDPOINTIDGROUPID`
    - :ex:`https://gate.connpay.com/paynet/api/v4/payout-form/group/ENDPOINTGROUPID`

.. _payout_form_parameters:

Request Parameters
^^^^^^^^^^^^^^^^^^

.. note::
  | Request must have content-type=application/x-www-form-urlencoded and :ref:`Authorization headers<RSA-SHA256>`.
  | Ask Support Manager if Conditional fields are Required for integration.

.. list-table::
  :widths: 35, 50, 20
  :header-rows: 1
  :class: longtable

  * - Parameter Name
    - Description
    - Value
  * - :code:`client_orderid`
    - Connecting Party's order identifier.
    - | ``Necessity``: Required
      | ``Type``: String
      | ``Lenght``: 128
  * - :code:`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
  * - :code:`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
  * - :code:`order_desc`
    - Brief order description.
    - | ``Necessity``: Conditional
      | ``Type``: String
      | ``Length``: 64
  * - :code:`ipaddress`
    - Receiver’s IP address (IPv4 or IPv6).
    - | ``Necessity``: Conditional
      | ``Type``: String
      | ``Length``: 7-45
  * - :code:`purpose`
    - Payout purpose.
    - | ``Necessity``: Conditional
      | ``Type``: String
      | ``Length``: 128
  * - :code:`server_callback_url`
    - | URL, where the transaction status is sent to. Connecting Party may use server callback URL for custom processing of the transaction completion, e.g. to collect payment data in the Connecting Party’s information system. For the list of parameters which come along with server callback to :ex:`server_callback_url` refer to :ref:`Connecting Party callback parameters<merchant_callback_parameters>`. This parameter can be sent instead of :ex:`notify_url`. If :ex:`server_callback_url` is sent, Payment Gateway sends callback notification only when original transaction receives final status. If :ex:`notify_url` is sent, Payment Gateway sends callback notification once the original transaction receives final status, and about every future update for this original transaction (reversal, chargeback, etc).
    - | ``Necessity``: Optional
      | ``Type``: String
      | ``Length``: 1024
  * - :code:`notify_url`
    - | URL, where the transaction status is sent to. Connecting Party may use notify URL for custom processing of the transaction completion, e.g. to collect payment data in the Connecting Party’s information system. For the list of parameters which come along with server callback to :ex:`notify_url` refer to :ref:`Connecting Party callback parameters<merchant_callback_parameters>`. This parameter can be sent instead of :ex:`server_callback_url`. If :ex:`notify_url` is sent, Payment Gateway sends callback notification once the original transaction receives final status, and about every future update for this original transaction (reversal, chargeback, etc). If :ex:`server_callback_url` is sent, Payment Gateway sends callback notification only when original transaction receives final status.
    - | ``Necessity``: Optional
      | ``Type``: String
      | ``Length``: 1024
  * - :code:`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 :ex:`approved`, :ex:`declined` in any other final :ref:`status<statuses>`.
      | 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 :ex:`server_callback_url` or :ref:`status API command</api/v2/status/>`.
        Pass :ex:`https://doc.connpay.com` if you have no need to return Receiver anywhere. Use either :ex:`redirect_url` or combination of :ex:`redirect_success_url` and :ex:`redirect_fail_url`, not both.
    - | ``Necessity``: Optional
      | ``Type``: String
      | ``Length``: 1024
  * - :code:`redirect_succes_url`
    - | URL, where the Receiver is redirected to when transaction status is :ex:`approved` (See :ref:`status list<statuses>`).
      | 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 :ex:`server_callback_url` or :ref:`status API command</api/v2/status/>`.
        Otherwise put :ex:`https://doc.connpay.com` if there is no need to redirect Receiver anywhere. Use either combination of :ex:`redirect_success_url` and :ex:`redirect_fail_url` or :ex:`redirect_url`, not both.
    - | ``Necessity``: Optional
      | ``Type``: String
      | ``Lenght``: 1024
  * - :code:`redirect_fail_url`
    - | URL, where the Receiver is redirected to when transaction status is not :ex:`approved` (See :ref:`status list<statuses>`).
      | 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 :ex:`server_callback_url` or :ref:`status API command</api/v2/status/>`.
        Pass :ex:`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 :ex:`redirect_fail_url` and :ex:`redirect_success_url` or :ex:`redirect_url`, not both.
    - | ``Necessity``: Optional
      | ``Type``: String
      | ``Length``: 1024
  * - :code:`account_number`
    - Account number.
    - | ``Necessity``: Conditional
      | ``Type``: String
      | ``Length``: 24
  * - :code:`account_name`
    - Bank account.
    - | ``Necessity``: Conditional
      | ``Type``: String
      | ``Length``: 128
  * - :code:`ewallet_type`
    - Type of e-wallet.
    - | ``Necessity``: Conditional
      | ``Type``: String
      | ``Length``: 64
  * - :code:`ewallet_wallet`
    - E-wallet ID.
    - | ``Necessity``: Conditional
      | ``Type``: String
      | ``Length``: 128
  * - :code:`crypto_wallet_address`
    - Address of crypto wallet.
    - | ``Necessity``: Conditional
      | ``Type``: String
      | ``Length``: 64
  * - :code:`bank_name`
    - Bank Name.
    - | ``Necessity``: Conditional
      | ``Type``: String
      | ``Length``: 255
  * - :code:`bank_branch`
    - Bank Branch Name.
    - | ``Necessity``: Conditional
      | ``Type``: String
      | ``Length``: 255
  * - :code:`bank_code`
    - Bank code.
    - | ``Necessity``: Conditional
      | ``Type``: String
      | ``Length``: 32
  * - :code:`bank_address1`
    - Bank address.
    - | ``Necessity``: Conditional
      | ``Type``: String
      | ``Length``: 255
  * - :code:`bank_zip_code`
    - Bank postal ZIP code.
    - | ``Necessity``: Conditional
      | ``Type``: String
      | ``Length``: 255
  * - :code:`bank_province`
    - Bank province.
    - | ``Necessity``: Conditional
      | ``Type``: String
      | ``Length``: 255
  * - :code:`bank_area`
    - Bank area.
    - | ``Necessity``: Conditional
      | ``Type``: String
      | ``Length``: 255
  * - :code:`routing_number`
    - Routing number used to identify specific bank branches in China.
    - | ``Necessity``: Conditional
      | ``Type``: String
      | ``Length``: 16
  * - :code:`legal_person_name`
    - Name on the legal document.
    - | ``Necessity``: Conditional
      | ``Type``: String
      | ``Length``: 128
  * - :code:`legal_person_document_number`
    - Number of legal document.
    - | ``Necessity``: Conditional
      | ``Type``: String
      | ``Length``: 128
  * - :code:`receiver_first_name`
    - Receiver first name, also can be sent as :code:`first_name`.
    - | ``Necessity``: Conditional
      | ``Type``: String
      | ``Length``: 128
  * - :code:`receiver_last_name`
    - Receiver last name, also can be sent as :code:`last_name`.
    - | ``Necessity``: Conditional
      | ``Type``: String
      | ``Length``: 128
  * - :code:`receiver_birthday`
    - Receiver birthday, also can be sent as :code:`birthday`.
    - | ``Necessity``: Conditional
      | ``Type``: Numeric
      | ``Length``: 30
  * - :code:`receiver_country_code`
    - Receiver country code, also can be sent as :code:`country`.
    - | ``Necessity``: Conditional
      | ``Type``: String
      | ``Length``: 3
  * - :code:`receiver_state`
    - Receiver state, should be provided for countries that have states (USA, Canada, Australia), also can be sent as :code:`state`.
    - | ``Necessity``: Conditional
      | ``Type``: String
      | ``Length``: 4
  * - :code:`receiver_city`
    - Receiver city, also can be sent as :code:`city`.
    - | ``Necessity``: Conditional
      | ``Type``: String
      | ``Length``: 128
  * - :code:`receiver_zip_code`
    - Receiver zip code, also can be sent as :code:`zip_code`.
    - | ``Necessity``: Conditional
      | ``Type``: Numeric
      | ``Length``: 32
  * - :code:`receiver_address1`
    - Receiver address, also can be sent as :code:`address1`.
    - | ``Necessity``: Conditional
      | ``Type``: String
      | ``Length``: 256
  * - :code:`receiver_phone`
    - Receiver phone, also can be sent as :code:`phone`.
    - | ``Necessity``: Conditional
      | ``Type``: Numeric
      | ``Length``: 128
  * - :code:`receiver_email`
    - Receiver E-mail, also can be sent as :code:`email`.
    - | ``Necessity``: Conditional
      | ``Type``: String
      | ``Length``: 128
  * - :code:`receiver_identity_document_id`
    - Receiver identity document identifier, also can be sent as :code:`identity_document_id`.
    - | ``Necessity``: Conditional
      | ``Type``: String
      | ``Length``: 128
  * - :code:`receiver_identity_document_number`
    - Receiver identity document number, also can be sent as :code:`identity_document_number`.
    - | ``Necessity``: Conditional
      | ``Type``: String
      | ``Length``: 128
  * - :code:`merchant_data`
    - Any additional information for this transaction which may be useful in Connecting Party's external systems, e.g. :ex:`VIP customer`, :ex:`TV promo campaign lead`. Will be returned in Status response and Connecting Party's Callback.
    - | ``Necessity``: Optional
      | ``Type``: String
      | ``Length``: 64k
  * - :code:`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: :ex:`testparam%3Dtest1%26mynewparam%3Dtest2` and is parsed into :ex:`$MFD_testparam = test1` and :ex:`$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 :code:`merchant_form_data=theme%3Ddark` in request and :ex:`$MFD_theme` macro placeholder on payment form will be changed to :ex:`dark`.
    - | ``Necessity``: Optional
      | ``Type``: String
      | ``Length``: 128
  * - :code:`preferred_language`
    - Preferred language.
    - | ``Necessity``: Optional
      | ``Type``: String
      | ``Length``: 2
  * - :code:`customer_level`
    - Customer level in CMS system
    - | ``Necessity``: Optional
      | ``Type``: Varchar
      | ``Length``: 32
  * - :code:`customer_id`
    - Customer ID in CMS system. Required if transaction goes via CMS (Payment Gateway mode)
    - | ``Necessity``: Optional
      | ``Type``: Int
      | ``Length``: 10
  * - :code:`merchant_customer_identifier`
    - Merchant Customer ID in CMS system. Required if transaction goes via CMS (CRM mode)
    - | ``Necessity``: Optional
      | ``Type``: Varchar
      | ``Length``: 64
  * - :code:`card_recurring_payment_id`
    - Payer’s tokenized cardholder's data ID, referred as Recurring Payment ID (RPI). Send either :code:`card_recurring_payment_id` or combination of :code:`credit_card_number`, :code:`card_printed_name`, :code:`expire_month` and :code:`expire_year`, not all. To create :code:`card_recurring_payment_id` see :ref:`api-v4-card-ref-id`. **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.

.. list-table::
  :widths: 30, 70
  :header-rows: 1
  :class: longtable

  * - Parameter Name
    - Description
  * - :code:`type`
    - The type of response. May be :ex:`async-response`, :ex:`validation-error`, :ex:`error`. If type equals :ex:`validation-error` or :ex:`error`, :ex:`error-message` and :ex:`error-code` parameters contain error details.
  * - :code:`paynet-order-id`
    - Order id assigned to the order by ConnPay.
  * - :code:`merchant-order-id`
    - Connecting Party order id.
  * - :code:`serial-number`
    - Unique number assigned by ConnPay server to particular request from the Connecting Party.
  * - :code:`error-message`
    - If status is :ex:`error` this parameter contains the reason for decline or error details.
  * - :code:`error-code`
    - The error code is case of :ex:`error` status.
  * - :code:`redirect_url`
    - The URL to the page where the Connecting Party should redirect the client's browser. Connecting Party should send :ex:`HTTP 302` redirect.

Request Example
^^^^^^^^^^^^^^^

.. code-block:: http


    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
^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: http

  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
^^^^^^^^^^^^^^^^^^^^^

.. code-block:: http

  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 :code:`account_number` value passed in Payout request.

Testing :ex:`account_number` values:

    * :ex:`account_number` = 1234567890 to get APPROVED
    * :ex:`account_number` = 0987654321 to get DECLINED
    * :ex:`account_number` = 1987654321 to get PROCESSOR_INTERNAL_ERROR

Postman Collection
^^^^^^^^^^^^^^^^^^

.. raw:: html
    :file: ../_static/Postman/Postman_payout_form.html

Request Builder
^^^^^^^^^^^^^^^

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

.. raw:: html
    :file: ../_static/examples/V4Payout_Form_Debug.html