.. _d2c: /api/v4/transfer-by-ref ####################### .. toctree:: :maxdepth: 1 .. contents:: :local: .. role:: ex .. role:: code 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 :code:`HTTPS POST` request by using :ref:`URLs` and the :ref:`parameters` specified below. Use :ref:`OAuth RSA-SHA256` for authentication. .. _api_v4_transfer-by-ref_url: 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.payneteasy.com/paynet/api/v4/transfer-by-ref/ENDPOINTID` - :ex:`https://gate.payneteasy.com/paynet/api/v4/transfer-by-ref/ENDPOINTID` * - :ex:`https://sandbox.payneteasy.com/paynet/api/v4/transfer-by-ref/group/ENDPOINTGROUPID` - :ex:`https://gate.payneteasy.com/paynet/api/v4/transfer-by-ref/group/ENDPOINTGROUPID` .. _api_v4_transfer-by-ref_request: Request Parameters ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. note:: | Request must have content-type=application/x-www-form-urlencoded and :ref:`Authorization headers`. | Parameters marked as :ex:`Conditional*` can be mandatory for specific integrations. For more information, please contact your manager in Payneteasy. .. list-table:: :widths: 26, 50, 24 :header-rows: 1 :class: longtable * - Parameter Name - Description - Value * - :code:`client_orderid` - Connecting Party order identifier. - | ``Necessity``: Required | ``Type``: String | ``Lenght``: 128 * - :code:`login` - Connecting Party's login. Must be used as oauth_consumer_key in OAuth Authorization, not included in request as :ex:`login` parameter. - | ``Necessity``: Required | ``Type``: String | ``Lenght``: 20 * - :code:`destination-card-no` - Card number of destination card. Mandatory if :ex:`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 * - :code:`destination-card-ref-id` - Card reference id to destination card, obtained at Card Registration step. Mandatory if :ex:`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 * - :code:`destination_expire_month` - Expire month of destination card. - | ``Necessity``: Conditional | ``Type``: String | ``Lenght``: 1-2 * - :code:`destination_expire_year` - Expire year of destination card. - | ``Necessity``: Conditional | ``Type``: String | ``Lenght``: 2-4 * - :code:`amount` - Amount to be transferred. The amount has to be specified in the highest units with :ex:`.` delimiter. For instance, :ex:`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). Example of valid parameter values are: :ex:`USD` for US Dollar :ex:`EUR` for European Euro. - | ``Necessity``: Required | ``Type``: String | ``Lenght``: 3 * - :code:`order_desc` - Order description. - | ``Necessity``: Required | ``Type``: String | ``Lenght``: 64k * - :code:`receiver_identity_document_series` - Receiver's identity document series (e.g. 4 digits for domestic passport). - | ``Necessity``: Optional | ``Type``: String | ``Lenght``: 512 * - :code:`receiver_identity_document_number` - Receiver's identity document number (e.g. 6 digits for domestic passport). - | ``Necessity``: Optional | ``Type``: String | ``Lenght``: 512 * - :code:`receiver_identity_document_id` - Receiver's identity document id. Possible values: :ex:`21` for domestic passport or :ex:`31` for international passport. - | ``Necessity``: Optional | ``Type``: String | ``Lenght``: 512 * - :code:`receiver_address1` - Receiver's address. - | ``Necessity``: Conditional\* | ``Type``: String | ``Lenght``: 512 * - :code:`receiver_city` - Receiver's city. - | ``Necessity``: Conditional\* | ``Type``: String | ``Lenght``: 512 * - :code:`receiver_first_name` - Receiver first name. - | ``Necessity``: Required | ``Type``: String | ``Lenght``: 128 * - :code:`receiver_middle_name` - Receiver middle name. - | ``Necessity``: Optional | ``Type``: String | ``Lenght``: 128 * - :code:`receiver_last_name` - Receiver last name. - | ``Necessity``: Required | ``Type``: String | ``Lenght``: 128 * - :code:`receiver_phone` - Receiver full international cell phone number, including country code. - | ``Necessity``: Optional | ``Type``: String | ``Lenght``: 128 * - :code:`receiver_resident` - Is receiver a resident? - | ``Necessity``: Optional | ``Type``: Boolean | ``Lenght``: true/false * - :code:`ipaddress` - Customer's IP address, included for fraud screening purposes. - | ``Necessity``: Optional | ``Type``: String | ``Lenght``: 45 * - :code:`first_name` - Sender first name. - | ``Necessity``: Optional | ``Type``: String | ``Lenght``: 128 * - :code:`middle_name` - Sender middle name. - | ``Necessity``: Optional | ``Type``: String | ``Lenght``: 128 * - :code:`last_name` - Sender last name. - | ``Necessity``: Optional | ``Type``: String | ``Lenght``: 128 * - :code:`ssn` - Last four digits of the Sender's social security number. - | ``Necessity``: Optional | ``Type``: Numeric | ``Lenght``: 32 * - :code:`birthday` - Sender date of birth, in the format :ex:`MMDDYY`. - | ``Necessity``: Optional | ``Type``: Numeric | ``Lenght``: 8 * - :code:`address1` - Sender address line 1. (Please note that in some cases it is not possible to send address length more than 50 characters. Please contact your manager for more details.) - | ``Necessity``: Optional | ``Type``: String | ``Lenght``: 256 * - :code:`city` - Sender city. - | ``Necessity``: Optional | ``Type``: String | ``Lenght``: 50 * - :code:`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 * - :code:`zip_code` - Sender ZIP code. - | ``Necessity``: Optional | ``Type``: String | ``Lenght``: 10 * - :code:`receiver_zip_code` - Receiver ZIP code. - | ``Necessity``: Conditional\* | ``Type``: String | ``Lenght``: 10 * - :code:`country` - Sender country(two-letter country code). Please see Appendix B for a list of valid country codes. - | ``Necessity``: Optional | ``Type``: String | ``Lenght``: 2 * - :code:`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 * - :code:`phone` - Sender full international phone number, including country code. - | ``Necessity``: Optional | ``Type``: String | ``Lenght``: 15 * - :code:`cell_phone` - Sender full international cell phone number, including country code. - | ``Necessity``: Optional | ``Type``: String | ``Lenght``: 15 * - :code:`email` - Sender email address. - | ``Necessity``: Optional | ``Type``: String | ``Lenght``: 50 * - :code:`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: :ex:`+9999999999`; :ex:`mail@example.com` etc. This value will be used by fraud monitoring system. - | ``Necessity``: Optional | ``Type``: String | ``Lenght``: 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`. 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``: 128 * - :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`. 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``: 128 * - :code:`redirect_url` - :ex:`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 :ref:`statuses`. - | ``Necessity``: Optional | ``Type``: String | ``Lenght``: 250 * - :code:`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 :ex:`approved`. - | ``Necessity``: Optional | ``Type``: String | ``Lenght``: 1024 * - :code:`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 :ex:`declined` or :ex:`filtered`. - | ``Necessity``: Optional | ``Type``: String | ``Lenght``: 1024 * - :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 Callback. - | ``Necessity``: Optional | ``Type``: String | ``Lenght``: 64k .. include:: empty.txt 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: 20, 80 :header-rows: 1 :class: longtable * - Response parameter - 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 Payneteasy. * - :code:`merchant-order-id` - Connecting Party order id. * - :code:`serial-number` - Unique number assigned by Payneteasy 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. Request Example ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: guess POST /paynet/api/v4/transfer-by-ref/39915 HTTP/1.1 Host: sandbox.payneteasy.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 ¤cy=USD &destination-card-ref-id=1461819 &card-exp-month=07 &card-exp-year=2028 &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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: text 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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: text 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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. raw:: html :file: ../_static/Postman/Postman_deposit2card.html Request Builder ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Enter your private key in PKCS#1 container to use debug. See :ref:`RSA-SHA256` for details. .. only:: insurance_enabled .. raw:: html :file: ../_static/examples/d2_insurance_Request_Debug_transfer_new.html .. only:: insurance_disabled .. raw:: html :file: ../_static/examples/deposit_to_card_Request_Debug_new.html