HydroPay Gateway

Introduction

HydroPay is an online payment gateway that provides merchants a various payment options allowing consumers to pay using their favourite payment method.

The purpose of this manual is to guide you with the integration of the HydroPay system into your website. We advise you to read this document completely before you start integrating HydroPay into your e-commerce website.

Before you start

Before you start with the integration of the HydroPay system, please make sure you have an account. Without an account, you can't establish a connection for testing.

Please send an email to HydroPay (info@hydropay.com) if you wish to test the service and you don't have an agreement with HydroPay yet. If you already have an agreement, please contact your account manager.

Connection to HydroPay Gateway

The HydroPay system expects you to send a set of variables via a GET request. The system automatically recognize if you are making a test or live transaction depending on your authentication.

The URL for the Gateway is: https://gateway.hydropay.com/payment

Overview of GET variables

Name

Type

Required

Description

key

string

required

Your PUBLIC KEY for given channel.

currency

string

required

The ISO-4217 code of the transaction currency. This value is exactly three characters, for example 'eur' is for Euros.

amount

integer

required

The total amount of your payment without a decimal divider. For example, a value of 10.95 will be written as 1095.

description

string

required

The payment description which will be displayed during checkout to a customer.

return_url

string

required

The URL where a user will return to after a transaction. You can add GET variables, if needed.

checksum

string

required

The checksum hash to ensure a secured connection between your and the HydroPay system.

method

string

optional

Which payment method will be used. Default is method=card.

capture

boolean

optional

Indicates if a transaction should be captured immediately or authorized for later capture. Default is capture=true.

statement_descriptor

string

optional

A dynamic statement descriptor shows in a customer's bank statement. If not set a default descriptor will be used.

metadata[]

array

optional

Metadata is useful for storing additional, structured information on an object.

customer[]

array

optional

Store a customer for later charges. Leave it blank if you want to make one-time payment.

Example usage

curl -v "https://gateway.hydropay.com/payment" \
"?key=pkey_test_AHM396xOsEGuKGzw9a7Wi2Wb3" \
"&amount=1099" \
"&currency=eur" \
"&description=Test payment" \
"&checksum=740572329d01e4d796706042a5528d75b1c3bc02d443f1d6447527f14616af17" \
"&return_url=http://example.com" \
"&metadata[order_id]=123456"

Example response

HTTP/1.1 302 FOUND
Connection: keep-alive
Content-Length: 248
Content-Type: text/html; charset=utf-8
Date: Tue, 20 Nov 2018 08:53:43 GMT
Location: https://gateway.hydropay.com/checkout?trx=6d0f1dfb-87db-4a6c-b041-ff8c17c5b537&livemode=false
Server: nginx
Strict-Transport-Security: max-age=63072000
X-Content-Type-Options: nosniff
X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
‚Äč
<!DOCTYPE html>
<html>
<head>
<title>Moved</title>
</head>
<body>
<p>This items has been moved <a href="https://gateway.hydropay.com/checkout?trx=6d0f1dfb-87db-4a6c-b041-ff8c17c5b537&amp;livemode=false">here</a>.</p>
</body>
</html>

Simply redirect user to a new location obtained from the initial request to finish their transaction.

https://gateway.hydropay.com/checkout?trx=6d0f1dfb-87db-4a6c-b041-ff8c17c5b537&livemode=false

The redirect link is available only for 10 minutes, after which it automatically expires.

Checksum calculation

The checksum is an important variable. It is a calculation of various other variables combined with a value known only to the HydroPay system and you. This required checksum calculation adds security to the connection. It is calculated using the SHA256 or SHA384 or SHA512 algorithms.

The calculation is simply concatenating your private key, &currency=eur, &amount=1099 and &description=Test payment.

Example hash calculationsha256(skey_test_YOUR_PRIVATE_KEY&currency=eur&amount=1099&description=Test payment)Resulting into 570c5845b5c05744b99c38431b38420314fdd951dc145d020a204606944ad81c hash value.

Return URL parameters

When a customer is redirected back from the Gateway one or two additional GET parameters are added by HydroPay. The first parameter is status with three possible values: success, failed or canceled. The second parameter is charge containing a new charge ID for further reference.

  • Example of a successful transaction: /?status=success&charge=ch_MGAWN8VXQK2dkDJ9pl

  • Example of a failed transaction: /?status=failed&charge=ch_MGAWN8VXQK2dkDJ9pl

  • Example of a transaction canceled by user: /?status=canceled

Charging customers

HydroPay allows to store customer's payment information for later charges. To store a customer add customer[] parameters to your payment form. After a successful charge you will obtain a webhook callback containing event details.

Example of a webhook callback:

{
"object": {
"id": "ch_NQWROVjXPxXm3o1P89",
"object": "charge",
"amount": 3097,
"amount_refunded": 0,
"captured": true,
"created": "2018-01-25T09:42:24+00:00",
"currency": "eur",
"customer": "cus_MGAWN8VXQK2dkDJ9pl",
"channel": "chnl_OdJ0Bq7XgDJnWx4mMp",
"description": "Order 20180125.1298",
"failure_code": null,
"failure_message": null,
"livemode": false,
"metadata": {},
"paid": true,
"refunded": false,
"refunds": [],
"source": {
"id": "card_NQWROVjXPxXm3o1P89",
"object": "card",
"address_city": null,
"address_country": null,
"address_line1": null,
"address_line2": null,
"address_state": null,
"address_zip": null,
"brand": "Visa",
"country": "US",
"customer": null,
"cvc_check": "unavailable",
"exp_month": 1,
"exp_year": 2022,
"last4": "0002",
"fingerprint": "kAOAwII41BZ6SuRoYYyHjfJ5sxMx3YC83iukfPdLYPY=",
"metadata": {},
"name": "John Doe"
},
"statement_descriptor": null,
"status": "succeeded"
},
"type": "charge.succeeded",
"created": "2018-01-25T09:42:27"
}

Save the customer ID obtained from a webhook and other info in your database for later use. When it's time to charge the customer again, retrieve the customer ID.

curl https://api.hydropay.com/charges \
-u YOUR_PRIVATE_KEY: \
-d amount=1500 \
-d currency=eur \
-d customer=cus_MGAWN8VXQK2dkDJ9pl