HiPay Gateway Guide

HiPay fact sheet

Adding a HiPay gateway

To add a HiPay gateway:

curl https://core.spreedly.com/v1/gateways.xml \
  -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/xml' \
  -d '<gateway>
        <gateway_type>hi_pay</gateway_type>
        <username>username</username>
        <password>password</password>
      </gateway>'

<gateway>
  <token>3Z4ASJ64NN8A6BVQ5X6HRHAK3R</token>
  <gateway_type>hi_pay</gateway_type>
  <name>HiPay</name>
  <description nil="true"/>
  <merchant_profile_key nil="true"/>
  <sub_merchant_key nil="true"/>
  <username>username</username>
  <characteristics>
    <supports_purchase type="boolean">true</supports_purchase>
    <supports_authorize type="boolean">true</supports_authorize>
    <supports_capture type="boolean">true</supports_capture>
    <supports_credit type="boolean">true</supports_credit>
    <supports_general_credit type="boolean">false</supports_general_credit>
    <supports_void type="boolean">true</supports_void>
    <supports_adjust type="boolean">false</supports_adjust>
    <supports_verify type="boolean">false</supports_verify>
    <supports_reference_purchase type="boolean">false</supports_reference_purchase>
    <supports_purchase_via_preauthorization type="boolean">false</supports_purchase_via_preauthorization>
    <supports_offsite_purchase type="boolean">false</supports_offsite_purchase>
    <supports_offsite_authorize type="boolean">false</supports_offsite_authorize>
    <supports_offsite_synchronous_purchase type="boolean">false</supports_offsite_synchronous_purchase>
    <supports_offsite_synchronous_authorize type="boolean">false</supports_offsite_synchronous_authorize>
    <supports_3dsecure_purchase type="boolean">false</supports_3dsecure_purchase>
    <supports_3dsecure_authorize type="boolean">false</supports_3dsecure_authorize>
    <supports_3dsecure_2_mpi_purchase type="boolean">false</supports_3dsecure_2_mpi_purchase>
    <supports_3dsecure_2_mpi_authorize type="boolean">false</supports_3dsecure_2_mpi_authorize>
    <supports_store type="boolean">true</supports_store>
    <supports_remove type="boolean">true</supports_remove>
    <supports_fraud_review type="boolean">false</supports_fraud_review>
    <supports_network_tokenization type="boolean">false</supports_network_tokenization>
    <supports_populate_mit_fields type="boolean">false</supports_populate_mit_fields>
    <supports_inquire_by_gateway_transaction_id type="boolean">false</supports_inquire_by_gateway_transaction_id>
    <supports_inquire_by_order_id type="boolean">false</supports_inquire_by_order_id>
    <supports_transaction_retry type="boolean">false</supports_transaction_retry>
    <supports_stored_stored_credentials type="boolean">false</supports_stored_stored_credentials>
    <supports_3dsecure_2_purchase type="boolean">true</supports_3dsecure_2_purchase>
    <supports_3dsecure_2_authorize type="boolean">true</supports_3dsecure_2_authorize>
  </characteristics>
  <credentials>
    <credential>
      <name>username</name>
      <value>username</value>
    </credential>
  </credentials>
  <gateway_settings>
  </gateway_settings>
  <gateway_specific_fields>
  </gateway_specific_fields>
  <payment_methods>
    <payment_method>credit_card</payment_method>
    <payment_method>third_party_token</payment_method>
  </payment_methods>
  <state>retained</state>
  <redacted type="boolean">false</redacted>
  <sandbox type="boolean">false</sandbox>
  <mode>default</mode>
  <created_at type="dateTime">2024-01-30T16:24:54Z</created_at>
  <updated_at type="dateTime">2024-01-30T16:24:54Z</updated_at>
</gateway>

Configure for Gateway-specific 3DS2

If you plan to utilize Gateway-Specific 3DS2, additional configuration steps are necessary.

Firstly, it’s important to note that if this isn’t configured correctly, you aren’t guaranteed to get final/complete status for all transactions, so customers could be charged without your system getting updated with that fact. To verify, you need to do a production 3D-secure transaction and ensure you get a redirect and callback from Spreedly indicating the transaction has completed.

Secondly, make the following configuration changes within the HiPay account under “Menu” > “Old Interface” > “Integration” > “Feedback Parameters”:

Mandatory: Ensure successful transactions by verifying the following fields:
- state
- status
- reference
Optional: You may choose to check an additional optional field for inclusion in your gateway responses.

The defaults for other fields should suffice. To view how the page appears and where the parameters are listed, please refer to the image below:

Learn more about Gateway specific 3DS2.

Authorization and Purchase transactions

HiPay Gateway requires the following parameters for this type of transaction. Some of the parameters are required and some are optional due to Spreedly internal logic.

description (required): The order short description.
currency (required)Base currency for this order. This three-character currency code complies with ISO 4217
amount (required): Total order amount, including purchased items, shipping fees (if present), and tax fees (if present).

NOTE: The required fields should be provided by the merchant.

payment_product (optional): The payment method used to proceed with checkout. Depending on the payment product, parameters specific to the payment method are required. The list of payment products to display on the payment page.
- Spreedly Integration: By default, Spreedly obtains this information from the payment_method.brand parameter.
orderid (optional): Unique order ID. Max lengths of 32 characters.
- Spreedly Integration: Spreedly will utilize the transaction token as the orderId parameter in cases where no order_id was provided in the request.
cardtoken (optional): Token obtained from the HiPay Enterprise Secure Vault API when tokenizing a credit or debit card.
- Token Generation: Refer to the HiPay Enterprise Tokenization API documentation.
- Spreedly Integration: Automatically retrieved it from the response.

Void, Refund, or Capture transactions

HiPay Gateway requires the following parameters for this type of transaction, some of the parameters are required and some are optional due to Spreedly internal logic.

transaction_reference (optional): The unique identifier of the transaction.
- Spreedly Integration: Obtained from the authorization of the transaction in the response.
operation (optional): The operation to perform on the transaction. The operation can be refund, void, or capture.
- Spreedly Integration: Automatically sent by Spreedly based on the transaction type.

Gateway Transaction ID Value

This value is a string separated by a delimiter |, containing 3 values: transaction_ref, card_token, and payment_product. The transaction_ref is the value of the transaction identifier. The card_token is the value of the tokenized payment method with the gateway. The payment_product is the brand of the card that was tokenized.

For merchants, to parse the gateway_transaction_id and retrieve the values individually, utilize your languages version of #string.split('|') to dissect the string into it’s individual contents.