.. _/api/v2/status/: /api/v2/status ############################## .. contents:: :local: .. role:: ex .. role:: code Introduction ^^^^^^^^^^^^^^^^^^^^^^^^ To make an order status request one have to send an :code:`HTTPS POST` request to the :ref:`URLs` and the :ref:`parameters` specified below. Use :ref:`SHA-1` for authentication. See :ref:`statuses`. .. _status_request_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/v2/status/ENDPOINTID` - :ex:`https://gate.payneteasy.com/paynet/api/v2/status/ENDPOINTID` * - :ex:`https://sandbox.payneteasy.com/paynet/api/v2/status/group/ENDPOINTGROUPID` - :ex:`https://gate.payneteasy.com/paynet/api/v2/status/group/ENDPOINTGROUPID` .. _status_request_parameters: Request Parameters ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. note:: | Request must have content-type=application/x-www-form-urlencoded. .. list-table:: :widths: 30, 45, 25 :header-rows: 1 :class: longtable * - Parameter Name - Description - Necessity * - :code:`login` - Merchant login name. - Mandatory * - :code:`client_orderid` - Unique order identifier assigned by merchant. - Mandatory * - :code:`orderid` - Order id assigned to the order by Payneteasy. - Conditional * - :code:`by-request-sn` - Serial number assigned to the specific request by Payneteasy. If this field exist in status request, status response return for this specific request. Include this parameter to get the status request with the particular transaction stage (can be used in specific cases). To get the latest transaction status, don’t include this parameter in status request. - Optional * - :code:`control` - | Checksum generated by :ref:`SHA-1`. Control string is represented as concatenation of the following parameters: | 1. Request parameter: :ex:`login`. | 2. Request parameter: :ex:`client_orderid`. | 3. Request parameter: :ex:`orderid`. | 4. :ex:`merchant_control` (Control key assigned to Connecting Party account in the Payneteasy gateway system). - Mandatory | | In most common cases, the best option is to include both :code:`client_orderid` and :code:`orderid` parameters to status request. Order status can be requested with only :code:`client_orderid` if it’s unique to merchant and :code:`orderid` is not received. If :code:`orderid` is not received in response, but this response contains an error, see the received error message to get the information why transaction was not created in the system. .. _status_v2_response_parameters: Response Parameters ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | The same API command for status request is used in multiple Use-Cases, therefore some of the mentioned response parameters might not be present for specific case. Below is the full list of possible 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. | * - these parameters are not defined by default. Please contact tech support to include these fields in callback. .. list-table:: :widths: 30, 70 :header-rows: 1 :class: longtable * - Status Response Parameter - Description * - :code:`type` - The type of response. May be :ex:`status-response`. * - :code:`status` - See :ref:`status_list` for details. * - :code:`amount` - Actual transaction amount. This value can be changed during the transaction flow. * - :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. * - :code:`paynet-order-id` - Order id assigned to the order by gate.payneteasy.com. * - :code:`merchant-order-id` - Connecting Party order id. * - :code:`phone` - Payer’s full international phone number, including country code. * - :code:`html` - HTML code of 3DS authorization form, encoded in application/x-www-form-urlencoded MIME format. Merchant must decode this parameter before showing the form to the Payer. gate.payneteasy.com System returns the following response parameters when it gets 3DS authorization form from the Issuer Bank. It contains auth form HTML code which must be passed through without any changes to the client's browser. This parameter exists and has value only when the redirection HTML is already available. For non-3DS this never happens. For 3DS HTML has value after some short time after the processing has been started. * - :code:`redirect-to` - For 3DS authorization the merchant can redirect the Payer to URL provided in this parameter instead of rendering the page provided in :code:`html` parameter. The :code:`redirect-to` parameter is returned only if the :code:`html` parameter is returned. Merchant should use :ex:`GET` HTTP method to redirect. This parameter must be used to work with 3DS 2.0. * - :code:`serial-number` - Unique number assigned by gate.payneteasy.com server to particular request from the Connecting Party. * - :code:`last-four-digits` - Last four digits of Payer bank card number. * - :code:`dest-last-four-digits` - Last four digits of customer credit card number. Relevant only for transfer transactions. * - :code:`bin` - Bank BIN of Payer bank card number. * - :code:`card-type` - Type of Payer bank card (:ex:`VISA`, :ex:`MASTERCARD`, etc). * - :code:`gate-partial-reversal` - Processing gate support partial reversal (enabled or disabled). * - :code:`gate-partial-capture` - Processing gate support partial capture (enabled or disabled). * - :code:`transaction-type` - Transaction type (:ex:`sale`, :ex:`reversal`, :ex:`capture`, :ex:`preauth`). * - :code:`processor-rrn` - Bank Receiver Registration Number. * - :code:`processor-tx-id` - Acquirer transaction identifier. * - :code:`receipt-id` - Electronic link to receipt :code:`https://gate.payneteasy.com/paynet/view-receipt/ENDPOINTID/receipt-id/`. * - :code:`name` - Payer's name. * - :code:`card-ref-id` - Card reference ID used in subsequent recurrent payments. Relevant only if card-ref-id was created for initial transaction. * - :code:`cardholder-name` - Cardholder's name. * - :code:`card-exp-month` - Bank card expiration month. * - :code:`card-exp-year` - Bank card expiration year. * - :code:`card-hash-id` - Unique card identifier to use for loyalty programs or fraud checks. * - :code:`card-country-alpha-three-code` - Three letter country code of source card issuer. See :ref:`country-state-codes` for details. * - :code:`destination-card-country-alpha-three-code` - Three letter country code of destination card issuer. See :ref:`country-state-codes` for details. * - :code:`dest-bin` - Bank BIN of customer credit card number. * - :code:`dest-card-type` - Type of customer credit card (:ex:`VISA`, :ex:`MASTERCARD`, etc). * - :code:`dest-bank-name` - Bank name by customer card BIN. * - :code:`destination-hash-id` - Unique card identifier to use for loyalty programs or fraud checks. Relevant only for transfer transactions. * - :code:`destination-card-hash-id` - Unique card identifier to use for loyalty programs or fraud checks. * - :code:`first-name` - Payer’s first name. * - :code:`last-name` - Payer’s last name. * - :code:`email` - Payer's e-mail. * - :code:`country` * - Payer’s country (two-letter country code). Please see :ref:`country-state-codes` for a list of valid country codes. * - :code:`state` * - Payer’s state . Please see :ref:`country-state-codes` for a list of valid state codes. Mandatory for USA, Canada and Australia. * - :code:`city` * - Payer’s city. * - :code:`zip_code` * - Payer’s ZIP code. * - :code:`address1` * - Payer’s address line 1. * - :code:`purpose` - Destination to where the payment goes. It is useful for the merchants who let their payers to top up their accounts with bank card (Mobile phone accounts, game accounts etc.). Sample values are: :ex:`+9999999999`; :ex:`mail@example.com` etc. This value can be used by the fraud monitoring system. * - :code:`bank-name` - Bank name by Payer card BIN. * - :code:`terminal-id` - Acquirer terminal identifier to show in receipt. * - :code:`paynet-processing-date` - Acquirer transaction processing date. * - :code:`approval-code` - Bank approval code. * - :code:`order-stage` - The current stage of the transaction processing. See :ref:`order_stage` for details. * - :code:`total-reversal-amount` - Total amount of processed reversals. Relevant only for reversal transactions. * - :code:`reversal-amount` - The amount of the last processed reversal. Relevant only for reversal transactions. * - :code:`auth-response-code` - Response code used in Iso8583 protocol. Only returned in specific cases. * - :code:`acquirer-processing-date` - Acquirer transaction processing date. * - :code:`processor-auth-credit-code` - Approval credit code. Only returned in specific cases. * - :code:`processor-credit-rrn` - Retrieval Reference Number for credit transaction. * - :code:`processor-credit-arn` - Acquirer card reference number for credit transaction. * - :code:`processor-debit-arn` - Acquirer card reference number for debit transaction. * - :code:`loyalty-balance` - The current bonuses balance of the loyalty program for current operation. :ex:`if available`. * - :code:`loyalty-message` - The message from the loyalty program. :ex:`if available`. * - :code:`loyalty-bonus` - The bonus value of the loyalty program for current operation :ex:`if available`. * - :code:`loyalty-program` - The name of the loyalty program for current operation :ex:`if available`. * - :code:`descriptor` - Bank identifier of the payment recipient. * - :code:`original-gate-descriptor` - Descriptor, which is set on gate level in the system. * - :code:`error-message` - If status in :ex:`declined`, :ex:`error`, :ex:`filtered` this parameter contains the reason for decline. * - :code:`error-code` - The error code is case status in :ex:`declined`, :ex:`error`, :ex:`filtered`. * - :code:`by-request-sn` - Serial number assigned to the specific request by gate.payneteasy.com. If this field exist in status request, status response return for this specific request. * - :code:`verified-3d-status` - See :ref:`3d_secure_status_list` for details. * - :code:`verified-rsc-status` - Returned if Random Sum Check was performed. See :ref:`alternative_cardholder_authentication` * - :code:`eci` - Electronic Commerce Indicator (Visa). * - :code:`ips-src-payment-product-code` - Code for card set by multinational financial service (Visa/Mastercard). * - :code:`ips-src-payment-product-name` - Decrypted code for card set by multinational financial service (Visa/Mastercard). * - :code:`ips-src-payment-type-code` - Type of card code set by multinational financial service (Visa/Mastercard). * - :code:`ips-src-payment-type-name` - Decrypted code for type of card set by multinational financial service (Visa/Mastercard). * - :code:`merchantdata` - If provided in initial request, merchant_data parameter and its value will be included in status response. * - :code:`initial-amount` - Amount, set in initiating transaction, without any fees or commissions. This value can't change during the transaction flow. * - :code:`seller-commission` - Total commission for processed transaction. This is optional parameter. Please contact your manager in Payneteasy, if you would like to receive it. * - :code:`acquirer-commission` - Acquirer commission for processed transaction. This is optional parameter. Please contact your manager in Payneteasy, if you would like to receive it. * - :code:`motivational-message` - This is an optional message which contains extended information about the reason for the declined transaction. * - :code:`transaction-date` - Date of final status assignment for transaction. * - :code:`orig-amount` - Contains the original request amount if it was converted on auxiliary endpoint in Parallel form integration. Relevant only for Payment Cashier transactions. * - :code:`orig-currency` - Contains the original request currency if it was converted on auxiliary endpoint in Parallel form integration. Relevant only for Payment Cashier transactions. .. only:: sbp_parameters_enabled | QR Code Status Response Parameters: .. list-table:: :widths: 30, 70 :header-rows: 1 :class: longtable * - Status Response Parameter - Description * - :code:`qr-code` - QR code in base 64 format. * - :code:`qr-code-payload-type` - QR Code type = SBP. * - :code:`qr-code-payload-value` - Link to the QR code =https://qr.nspk.ru/BS***** (only for H2H integration). PaReqForm Status Response Parameters ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. list-table:: :widths: 40, 60 :header-rows: 1 :class: longtable * - Name - Description * - :code:`tds-pareq-form-pareq` - ACS 3DS PaReq data, which received by the Connecting Party. * - :code:`tds-pareq-form-acs-url` - ACS URL to redirect the Payer to 3DS 1.0.2 Authentication Flow. CReqForm Status Response Parameters ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. list-table:: :widths: 30, 70 :header-rows: 1 :class: longtable * - Name - Description * - :code:`tds-creq-form-creq` - A CReq message initiates Cardholder interaction in a Challenge Flow and is used to carry authentication data from the Cardholder. It is formed by the 3DS Server and is posted through the Cardholder's browser by the merchant to the ACS URL. * - :code:`tds-creq-form-acs-url` - ACS URL to redirect the Payer for Challenge Flow. MethodUrlFrame Status Response Parameters ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. list-table:: :widths: 35, 65 :header-rows: 1 :class: longtable * - Name - Description * - :code:`tds-method-url-frame-3ds-server-trans-id` - Universally unique transaction identifier assigned by the 3DS Server to identify a single transaction. * - :code:`tds-method-url-frame-3ds-method-url` - 3DS Method URL used in iframe form which is provided to Payer browser by the merchant. Rules to form the HTML form. | :code:`threeDSMethodData` (:code:`threeDSMethodNotificationURL` + :code:`threeDSServerTransID`). Request Example ^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none POST /paynet/api/v2/status/37211 HTTP/1.1 Host: sandbox.payneteasy.com User-Agent: curl/7.77.0 Accept: */* Content-Length: 99 Content-Type: application/x-www-form-urlencoded Connection: close login=TestYujik &client_orderid=123 &orderid=6863082 &control=647f0581bbceb804a73e98d9ea7e78640a75bf1c Success Response Example ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. only:: sbp_parameters_enabled .. code-block:: none type=status-response &serial-number=00000000-0000-0000-0000-0000037704d3 &merchant-order-id=902B4FF5 &paynet-order-id=6863082 &status=processing &amount=10.42 ¤cy=RUB &original-gate-descriptor=PAYMENT-RUB &transaction-type=sale &receipt-id=7d59a029-2316-36e5-b29b-96139fc7af38 &card-exp-month=0 &card-exp-year=0 &email=john.smith@gmail.com &order-stage=sale_3d_validating &merchantdata=VIP customer &card-type=SBP &phone=12063582043 &paynet-processing-date=2023-03-29 13:47:40 MSK &first-name=John &last-name=Smith &initial-amount=10.42 &qr-code=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAQAAAAEACAIAAADTED8xAAAFIklEQVR42u3dSXLjQAwEQP7/0/IbHFI... &qr-code-payload-type=SBP &qr-code-payload-value=https://qr.nspk.ru/BS100069IM4ESCN090DP55N859KG1AAD .. only:: sbp_parameters_disabled .. code-block:: none HTTP/1.1 200 OK Server: server Date: Mon, 12 Sep 2022 09:02:42 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 X-Cached: EXPIRED Content-Length: 1275 type=status-response &serial-number=00000000-0000-0000-0000-000002ddb056 &merchant-order-id=123 &processor-tx-id=PNTEST-6863082 &paynet-order-id=6863082 &status=approved &amount=555.00 ¤cy=USD &descriptor=XXXX &original-gate-descriptor=XXXX &gate-partial-reversal=enabled &gate-partial-capture=enabled &transaction-type=sale &receipt-id=081c0c0b-0dd1-3083-b251-e624ac8e57b4 &name=CARD+HOLDER &cardholder-name=CARD+HOLDER &card-exp-month=12 &card-exp-year=2099 &email=john.smith%40gmail.com &last-name=Smith &first-name=John &processor-rrn=0225083062885 &approval-code=979249 &order-stage=sale_approved &merchantdata=VIP+customer &last-four-digits=2063 &bin=410002 &card-type=VISA &phone=12063582043 &bank-name=BANCO+ITAUCARD+S.A. &auth-response-code=00 &terminal-id=12345678 &paynet-processing-date=2022-09-07+13%3A22%3A39+MSK &acquirer-processing-date=2022-09-07+13%3A22%3A39+MSK &processor-auth-credit-code=206551 &card-hash-id=2639503 &card-country-alpha-three-code=BRA &verified-3d-status=NOT_AUTHENTICATED &processor-credit-rrn=0225060914211 &processor-credit-arn=809124106 &processor-debit-arn=601904020 &purpose=user_account1 &ips-src-payment-product-code=F &ips-src-payment-product-name=Visa+Classic &ips-src-payment-type-code=Credit &ips-src-payment-type-name=VISA+Credit &initial-amount=555.00 Fail Response Example ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none HTTP/1.1 200 OK Server: server Date: Mon, 12 Sep 2022 09:08:02 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 X-Cached: MISS Content-Length: 137 type=validation-error &serial-number=00000000-0000-0000-0000-000002ddb057 &error-message=End+point+with+id+372118+not+found &error-code=3 Postman Collection ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. raw:: html :file: ../_static/Postman/Postman_status.html Request Builder ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. raw:: html :file: ../_static/examples/sale_transaction_Order_Status_Debug.html