NAV Navbar
Logo
shell php

Introduction

The HIPS API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. We support cross-origin resource sharing, allowing you to interact securely with our API from a client-side web application (though you should never expose your secret API key in any public website’s client-side code). JSON is returned by all API responses, including errors, although our API libraries convert responses to appropriate language-specific objects.

To make the API as explorable as possible, accounts have test mode and live mode API keys. There is no “switch” for changing between modes, just use the appropriate key to perform a live or test transaction. Requests made with test-mode credentials never hit the banking networks and incur no cost.

Authentication

Authenticate your account when using the API by including your secret API key in the request. You can manage your API keys in the Hips Dashboard. Your API keys carry many privileges, so be sure to keep them secret! Do not share your secret API keys in publicly accessible areas such GitHub, client-side code, and so forth.

Choose one of the following authentication methods. For in-house direct one-to-one merchants we recommend authenticating using basic access authentication (HTTP Basic Auth).

For multitenancy software such as e-commerce providers we recommend using OAuth 2.0 for API key exchange for a better customer experience.

HTTP Basic Access Auth

To authenticate via basic http auth, use this code:

$ curl "https://api.hips.com/v1/orders" \
   -u "private_BQokikJOvBiI2HlWgH4olfQ2:"
<?
$curl = curl_init('https://api.hips.com/v1/orders');
curl_setopt($process, CURLOPT_USERPWD, 'private_BQokikJOvBiI2HlWgH4olfQ2' . ": ");  
$return = curl_exec($curl);
curl_close($curl);
?>

curl uses the -u flag to pass basic auth credentials (adding a colon after your API key prevents cURL from asking for a password).

or use

$ curl "https://api.hips.com/v1/orders" \
   -H "Authorization: Basic cHJpdmF0ZV9CUW9raWtKT3ZCaUkySGxXZ0g0b2xmUTI"
<?
$curl = curl_init('https://api.hips.com/v1/orders');
curl_setopt($process, CURLOPT_HTTPHEADER, array('Authorization: Basic cHJpdmF0ZV9CUW9raWtKT3ZCaUkySGxXZ0g0b2xmUTI6', $additionalHeaders));
curl_setopt($process, CURLOPT_HEADER, 1);
$return = curl_exec($curl);
curl_close($curl);
?>

Authentication to the API is performed via HTTP Basic Access Authentication. Provide your API key as the basic auth username value. You do not need to provide a password. If you need to authenticate via bearer auth (e.g., for a cross-origin request) see Token Authentication

If you don’t use a client which can handle the HTTP Basic Access Authentication request for you, make sure you send the request as a header with the following format:

Authorization: Basic cHJpdmF0ZV9CUW9raWtKT3ZCaUkySGxXZ0g0b2xmUTI6

Example:

base64encode(‘username:password’) = base64 value to pass in the header

base64encode('private_BQokikJOvBiI2HlWgH4olfQ2:’) = cHJpdmF0ZV9CUW9raWtKT3ZCaUkySGxXZ0g0b2xmUTI6

In the above example the username and empty password are base64 encoded. Note the : sign after your private key in the above example.

Token Authentication

To authenticate via token, use this code:

$ curl "https://api.hips.com/v1/orders" \
   -H "Authorization: private_BQokikJOvBiI2HlWgH4olfQ2"
<?
$curl = curl_init('https://api.hips.com/v1/orders');
curl_setopt($process, CURLOPT_HTTPHEADER, array('Authorization: private_BQokikJOvBiI2HlWgH4olfQ2', $additionalHeaders));
curl_setopt($process, CURLOPT_HEADER, 1);
$return = curl_exec($curl);
curl_close($curl);
?>

If you need to authenticate via bearer auth (e.g., for a cross-origin request), use header "Authorization: private_BQokikJOvBiI2HlWgH4olfQ2" for your API calls.

OAuth 2.0

For multitenancy developer ninjas only!

You can use OAuth to retrieve an access token for use with your Hips API calls. This will enable users to grant your application access to the Hips API on their behalf without the need to manually set up or exchange any keys.“

Implement HIPS OAuth 2.0 to your software

Click here to read more about HIPS OAuth 2.0 Implementation.

HIPS OAuth 2.0 Authorization endpoint:

Live:
https://hips.com/oauth/authorize

Location Headers

All HIPS API actions that create a new resource will return a Location header with the precise URL at which the newly created resource can be found. This URL should be used in all interaction with the API regarding this resource. We recommend you to use this URL instead of constructing one yourself.

Metadata

You can store additional metadata with HIPS that will be returned whenever an order is read from HIPS. The data take two forms: two reference fields to be used to store your internal order reference, and general metadata fields on the order and on each order line that can be used to store arbitrary data.

The reference fields are meta_data_1 and meta_data_2 used to store the interal reference to the order and/or any order item.

Webhooks

Webhook data is sent as JSON in the POST request body.

{
  "event": "payment.successful",
  "resource": {
    "id": "MKFbh5LVpnFWipQNX9Qt3jLE",
    "type": "payment",
    "links": [
      {
        "rel": "self",
        "href": "https://api.hips.com/v1/payments/MKFbh5LVpnFWipQNX9Qt3jLE",
        "method": "GET"
      }
    ],
    "order_id": "oAZmBsFiq6r7ULK3jXRRh4Yo",
    "status": "successful",
    "currency": "USD",
    "amount": 1000,
    "order_status": "successful",
    "merchant_order_id": null,
    "meta_data_1": null,
    "meta_data_2": null
  },
  "jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJkYXRhIjp7ImV2ZW50IjoicGF5bWVudC5zdWNjZXNzZnVsIiwidHlwZSI6InBheW1lbnQiLCJyZXNvdXJjZSI6eyJpZCI6Ik1LRmJoNUxWcG5GV2lwUU5YOVF0M2pMRSIsImxpbmtzIjpbeyJyZWwiOiJzZWxmIiwiaHJlZiI6Imh0dHA6Ly9sb2NhbGhvc3Q6MzAwMC9hcGkvdjEvcGF5bWVudHMvTUtGYmg1TFZwbkZXaXBRTlg5UXQzakxFIiwibWV0aG9kIjoiR0VUIn1dLCJvcmRlcl9pZCI6Im9BWm1Cc0ZpcTZyN1VMSzNqWFJSaDRZbyIsInN0YXR1cyI6InN1Y2Nlc3NmdWwiLCJjdXJyZW5jeSI6IlVTRCIsImFtb3VudCI6MTAwMDAsIm9yZGVyX3N0YXR1cyI6InN1Y2Nlc3NmdWwiLCJtZXJjaGFudF9vcmRlcl9pZCI6bnVsbCwibWV0YV9kYXRhXzEiOm51bGwsIm1ldGFfZGF0YV8yIjpudWxsfX0sImlzcyI6ImhpcHMuY29tIn0.Lblr505ocNse5QyN9KLRU7tx-7iA5ShLKPjK9uBTO2bZGgXAnX6YqH1chxFLpXR3i5TCLm1a3D5bXHX6aRd5bj6zhgywEuaiJCA-b2aggbpxFAadaOgn_G5BqtMaOotf8vGep6d_zQJ7-Mp3Mp-uXDbYaj7rP4RE4QfMc32ng01ZGiGi1KJ4OlMQ3YHPcATlNAxyFv1hl_3QtoXzPYPfzRSqWtxcRnIy7mbrPUzK7WrJOMhPRy9zw7-vdRSqrpbl6bKHZS5SwnnMyXaU1ojbjAVf5Eq6hzUjkrdTUhTx17I3t4YS3gixh5YNj34bqkSujL3ZtQ0i9j0RBEkZnBiAaA"
}

Use webhooks to be notified about events that happen in a Hips account.

Interacting with a third-party API like Hips’s can introduce two problems:

  1. Services not directly responsible for making an API request may still need to know the response of that request
  2. Some events, like disputed charges and many recurring billing events, are not the result of a direct API request

Webhooks solve these problems by letting you register a URL that we will notify anytime an event happens in your account. When the event occurs—for example, when a successful charge is made on a customer’s subscription, Hips execute an webhook.

Configuring your webhook settings

Creating a webhoook endpoint on your server is no different from creating any page on your website. With PHP, you might create a new .php file on your server; with a framework like Sinatra, you would add a new route with the desired URL.

You can add webhook subcription on your HIPS Dashboard or specify a specific webhook url for each request (for multitenancy).

Validating Webhooks

HIPS Public RSA key:

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAu269xcyVkOZLP93D82g8
vsLgLMDIfc853syoQ6gu0K3kwMcSru9iNhj4CWEWp4t7ozDd3o+t6Y6scZtLnSrM
ZhoUkdiOIK7hqF6e9tS+vT8vFOkrmsGysQJbY2IBaX4WknOsQEjARw04S37g6XUB
ERXlC0VwUXrUZVsNCYrE0sa0OvZ/IxHLJrt+fpTOUFrcYowe6Ha7sZEz2ju1x8nq
foEnsfVLRMsgVE+Af2uhANqSONCly0WWJID+q0gIqnDYQ/ETclGDeDcMU7J9/fUG
euPoQtNRJKRWG/J0sqEWFjPtahDyq9slO5qn55rcYdOR2ZGHTkqvLVFwSOSivCmT
1QIDAQAB
-----END PUBLIC KEY-----

HIPS Public RSA key url:

https://static.hips.com/hips_key.pub

HIPS Public RSA (DNS TXT) DomainKey key record:

hips._domainkey.hips.com

HIPS are signing webhooks with JWT (JSON Web Token) with method RS256. Read more about JWT and download JWY libraries at jwt.io.

The JWT Payload is posted in each webhook in the body json under the key jwt. Decode the jwt with a JWT library and make sure you specify algorithm RS256 when you validate the jwt.

Use HIPS Public RSA key to validate the JWT.

If you are validating Hips webhooks with JWT you should only trust the data within the JWT, and only if the JWT signature is verified.

If the signature of the JWT is valid then you know that the webhook is not alterd and that Hips is the sender of the webhook.

Order API / Checkout

The Order API is used to create and update an order with HIPS. The id that is generated and returned for you is used to integrate the HIPS Checkout.

As soon as the purchase is completed the order should be read and handled using HIPS API View an order.

Create a new order

HTTP Request

https://api.hips.com/v1/orders

You must replace private_BQokikJOvBiI2HlWgH4olfQ2 with your private API key.

<?
$json = '{  
   "order_id": "123",
   "purchase_currency": "USD",
   "user_session_id": "3246568465743",
   "user_identifier": "SmartShopper17",
   "meta_data_1": "any_custom_reference",
   "ecommerce_platform": "Magento 1.9.x.x",
   "ecommerce_module": "Hips Magento Module 0.1.0",
   "cart": {  
      "items": [  
         {  
            "type": "physical",
            "sku": "3123123",
            "name": "Hips cup",
            "quantity": 1,
            "unit_price": 1000,
            "discount_rate":0,
            "vat_amount": 250,
            "meta_data_1": "Special color"
         },
         {  
            "type": "physical",
            "sku": "456778",
            "name": "Hips T-shirt",
            "quantity": 1,
            "unit_price": 1000,
            "discount_rate":0,
            "vat_amount": 250
         },
         {  
            "type": "shipping_fee",
            "sku": "1",
            "name": "UPS Express",
            "quantity": 1,
            "unit_price": 1000,
            "discount_rate":0,
            "vat_amount": 250
         }
      ]
   },
   "checkout_settings": {
      "extended_cart": true
   },
   "require_shipping": true,
   "express_shipping": true,
   "hooks": {
    "user_return_url_on_success": "https://mystore.com/thank_you",
    "user_return_url_on_fail": "https://mystore.com/sorry",
    "terms_url": "https://mystore.com/terms",
    "webhook_url": "https://api.mystore.com/confirmations"
   }
}';
$ch = curl_init('https://api.hips.com/v1/orders');
curl_setopt($ch, CURLOPT_USERPWD, 'private_BQokikJOvBiI2HlWgH4olfQ2' . ": ");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");  
curl_setopt($ch, CURLOPT_POSTFIELDS, $json);        
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);              
curl_setopt($ch, CURLOPT_HTTPHEADER, array(                                    
    'Content-Type: application/json',
    'Content-Length: ' . strlen($data_string))
    );
$result = curl_exec($ch);
?>
$ curl --request POST \
  --url https://api.hips.com/v1/orders \
  --header 'Accept: application/json' \
  --header 'Authorization: private_BQokikJOvBiI2HlWgH4olfQ2' \
  --header 'Content-Type: application/json' \
  --data '{  
   "order_id": "123",
   "purchase_currency": "USD",
   "user_session_id": "3246568465743",
   "user_identifier": "SmartShopper17",
   "meta_data_1": "any_custom_reference",
   "ecommerce_platform": "Magento 1.9.x.x",
   "ecommerce_module": "Hips Magento Module 0.1.0",
   "cart": {
      "items": [  
         {  
            "type": "physical",
            "sku": "3123123",
            "name": "Hips cup",
            "quantity": 1,
            "unit_price": 1000,
            "discount_rate":0,
            "vat_amount": 250,
            "meta_data_1": "Special color",
            "weight_unit": "gram",
            "weight": 350
         },
         {  
            "type": "physical",
            "sku": "456778",
            "name": "Hips T-shirt",
            "quantity": 1,
            "unit_price": 1000,
            "discount_rate":0,
            "vat_amount": 250,
            "weight_unit": "gram",
            "weight": 200
         },
         {  
            "type": "shipping_fee",
            "sku": "1",
            "name": "UPS Express",
            "quantity": 1,
            "unit_price": 1000,
            "discount_rate":0,
            "vat_amount": 250
         }
      ]
   },
   "checkout_settings": {
      "extended_cart": true
   },
   "require_shipping": true,
   "express_shipping": true,
   "hooks": {
    "user_return_url_on_success": "https://mystore.com/thank_you",
    "user_return_url_on_fail": "https://mystore.com/sorry",
    "terms_url": "https://mystore.com/terms",
    "webhook_url": "https://api.mystore.com/confirmations"
   }
}'

The above command returns JSON structured like this:

{  
   "id": "UVWofp7AjHiRKNLjhUjMnhc3",
   "object": "order",
   "checkout_uri": "https://checkout.hips.com/UVWofp7AjHiRKNLjhUjMnhc3",
   "merchant_reference": {  
      "meta_data_1": "any_custom_reference",
      "order_id": "123"
   },
   "purchase_currency": "USD",
   "status": "pending",
   "created_at": "2017-01-26T10:10:23.859Z",
   "last_modified_at": "2017-01-26T10:10:23.859Z",
   "expires_at":null,
   "require_shipping": true,
   "billing_address": null,
   "shipping_address": null,
   "cart": {  
      "total_vat_amount": 750,
      "total_vat_amount_formatted": "$7.50",
      "total_amount": 3000,
      "total_amount_formatted": "$30.00",
      "amount_due": 3000,
      "amount_due_formatted": "$30.00",
      "items": [  
         {  
            "id": "HnY8erVezohaLvg4ka3zEL9W",
            "object": "order_item",
            "sku": "3123123",
            "name": "Hips cup",
            "quantity": 1,
            "ean":null,
            "uri":null,
            "image_uri":null,
            "discount_rate":0,
            "vat_amount": 250,
            "unit_price": 1000,
            "meta_data_1": "Special color"
         },
         {  
            "id": "eqqR1MDXDxPP78NkHpznfmRf",
            "object": "order_item",
            "sku": "456778",
            "name": "Hips T-shirt",
            "quantity": 1,
            "ean":null,
            "uri":null,
            "image_uri":null,
            "discount_rate":0,
            "vat_amount": 250,
            "unit_price": 1000
         },
         {  
            "id": "QcMey3dGvbvjUQyf8oiJg2tz",
            "object": "order_item",
            "sku": "1",
            "name": "UPS Express",
            "quantity": 1,
            "ean":null,
            "uri":null,
            "image_uri":null,
            "discount_rate":0,
            "vat_amount": 250,
            "unit_price": 1000
         }
      ]
   },
   "coupons": []
}

Request Parameters

Name Type Description
order_id String Required Your unique order id of this order.
purchase_currency String Required We use the ISO 4217 standard for defining currencies. Examples are EUR, GBP, SEK, etc.
meta_data_1 String Can be used to store arbitrary merchant data on the order
meta_data_2 String Can be used to store arbitrary merchant data on the order
user_session_id String Recommended Used for anti-fraud. Provide the session id on your end.
user_identifier String Recommended Used for anti-fraud. User identifier on your end (can be username, user_id, etc.)
ecommerce_platform String Optional description of merchant’s e-commerce system if applicable
ecommerce_module String Optional description of the module used in merchant’s e-commerce system if applicable
cart Object Required JSON Object containing array of Items.
cart ➔ items Array Required JSON Array containing products ordered by the customer.
cart ➔ items ➔ type String Required Order line type. Possible values: physical, digital,service, shipping_fee, discount or fee.
cart ➔ items ➔ sku String Recommended Article number, SKU or similar.
cart ➔ items ➔ name String Required Descriptive item name.
cart ➔ items ➔ quantity Integer Required Non-negative. The item quantity.
cart ➔ items ➔ ean String EAN code of the product (used for anti-fraud)
cart ➔ items ➔ uri String URL to the product page that can be later embedded in communications between HIPS and the customer. (max 1024 characters)
cart ➔ items ➔ image_uri String URL to an image that can be later embedded in communications between HIPS and the customer. (max 1024 characters)
cart ➔ items ➔ discount_rate Integer Non-negative. In percent. i.e 25 = 25%.
cart ➔ items ➔ unit_price Integer Required Non-negative. Including tax/vat, excludes discount. Minor units. i.e 10000 = 100.00 (max value: 100000000).
cart ➔ items ➔ vat_amount Integer Tax/VAT amount. Non-negative. In minor units i.e 10000 = 10.00.
cart ➔ items ➔ meta_data_1 String Can be used to store arbitrary data on the item
cart ➔ items ➔ meta_data_2 String Can be used to store arbitrary data on the item
cart ➔ items ➔ weight_unit Integer The unit for the provided weight. Can be any of gram, kg, stone, lb. Default gram.
cart ➔ items ➔ weight Integer The weight of the order item in the provided weight unit. Must be provided if you plan to use weight-based Hips Shipping
checkout_settings Object JSON object holding optional checkout settings for Hips Checkout
checkout_settings ➔ extended_cart Boolean Enable the extended cart in order to support handling of shipping
require_shipping Boolean Recommended Specify if the product requires shipping.
express_shipping Boolean Recommended Specify if the product requires shipping and the customer has explicitly asked for express shipping.
shipping_address Object
shipping_address ➔ given_name String Customer’s first name
shipping_address ➔ family_name String Customer’s last name
shipping_address ➔ street_address String Customer’s address
shipping_address ➔ postal_code String Customer’s postal code
shipping_address ➔ state String Customer’s state (2 letters)
shipping_address ➔ city String Customer’s city
shipping_address ➔ country String Customer’s country code. ISO 3166-1 Alpha-2 i.e: US,GB,DE,SE, etc
shipping_address ➔ email String Customer’s e-mail address
shipping_address ➔ phone String Customer’s phone number (mobile)
hooks Object
hooks ➔ user_return_url_on_success String If using HIPS checkout. This is the URL which Hips will send the customer after a successful purchase. If left blank Hips will display a thank you page for the user.
hooks ➔ user_return_url_on_fail String If using HIPS checkout. This is the URL which Hips will send the customer after a declined or aborted purchase. If left blank Hips will display a decline page for the user.
hooks ➔ terms_url String This is the URL for your store’s terms and conditions. This will be embedded in communications between HIPS and the customer.
hooks ➔ webhook_url String If you provide a webhook URL here, this webhook will be called for this specific order, as well as any of any pre-defined webhooks.

Read-Only Response Parameters

Name Type Description
id String HIPS unique ID for this order, also known as Order Token
object String Type of JSON structure
checkout_uri String Full path to HIPS checkout. If you want the user to pay using HIPS checkout, redirect the customer to this URL.
merchant_reference Object Reference object
merchant_reference ➔ order_id String Your order id (sent to Hips on creation of the order.)
status String Order status. Possible values: pending, awaiting_payments,expired, successful. After creation of an order, the status is always pending until a user is assigned to the order. A user gets assigned to an order by executing the checkout url, then order status will change to `awaiting_payments.
expires_at DateTime DateTime when this order, if still not paid, will expire.
billing_address Object If a user is assigned via HIPS checkout, information about the user will be visible here.
cart ➔ total_vat_amount Integer Sum of total tax
cart ➔ total_vat_amount_formatted String Formatted, human readable string of tax for currency
cart ➔ total_amount Integer Total sum of order (to be paid), including tax
cart ➔ total_amount_formatted String Formatted, human readable string of total_amount for currency
cart ➔ amount_due Integer Total sum of order including tax with existing payments deducted.
cart ➔ amount_due String Formatted, human readable string of amount_due for currency
coupons Array Array of discount coupons attached to this order.

View an order

HTTP Request

https://api.hips.com/v1/orders/(:id)

You must replace private_BQokikJOvBiI2HlWgH4olfQ2 with your private API key.

You must replace UVWofp7AjHiRKNLjhUjMnhc3 with your order token (:id).

$ curl --request GET \
  --url https://api.hips.com/v1/orders/UVWofp7AjHiRKNLjhUjMnhc3 \
  --header 'Accept: application/json' \
  --header 'Authorization: private_BQokikJOvBiI2HlWgH4olfQ2' \
  --header 'Content-Type: application/json' 

The above command returns JSON structured like this:

{  
   "id": "UVWofp7AjHiRKNLjhUjMnhc3",
   "object": "order",
   "checkout_uri": "https://checkout.hips.com/UVWofp7AjHiRKNLjhUjMnhc3",
   "merchant_reference": {  
      "order_id": "12344553"
   },
   "purchase_currency": "USD",
   "status": "awaiting_payments",
   "created_at": "2017-01-26T10:10:23.859Z",
   "last_modified_at": "2017-01-26T12:01:43.410Z",
   "expires_at":null,
   "require_shipping": true,
   "billing_address":null,
   "shipping_address":null,
   "cart": {  
      "total_vat_amount": 750,
      "total_vat_amount_formatted": "$7.50",
      "total_amount": 3000,
      "total_amount_formatted": "$30.00",
      "amount_due": 3000,
      "amount_due_formatted": "$30.00",
      "items": [  
         {  
            "id": "HnY8erVezohaLvg4ka3zEL9W",
            "object": "order_item",
            "sku": "3123123",
            "name": "Hips cup",
            "quantity": 1,
            "ean":null,
            "uri":null,
            "image_uri":null,
            "discount_rate":0,
            "vat_amount": 250,
            "unit_price": 1000
         },
         {  
            "id": "eqqR1MDXDxPP78NkHpznfmRf",
            "object": "order_item",
            "sku": "456778",
            "name": "Hips T-shirt",
            "quantity": 1,
            "ean":null,
            "uri":null,
            "image_uri":null,
            "discount_rate":0,
            "vat_amount": 250,
            "unit_price": 1000
         },
         {  
            "id": "QcMey3dGvbvjUQyf8oiJg2tz",
            "object": "order_item",
            "sku": "1",
            "name": "UPS Express",
            "quantity": 1,
            "ean":null,
            "uri":null,
            "image_uri":null,
            "discount_rate":0,
            "vat_amount": 250,
            "unit_price": 1000
         }
      ]
   },
   "coupons": [  

   ]
}

Read-Only Response Parameters

Name Type Description
id String HIPS unique ID for this order, also known as Order Token
object String Type of JSON structure
checkout_uri String Full path to HIPS checkout. If you want the user to pay on HIPS checkout, simply redirect the customer to this URL.
merchant_reference Object Reference object
merchant_reference ➔ order_id String Your order id (sent to Hips on creation of the order.)
status String Order status. Possible values: pending, awaiting_payments,expired, successful. After creation of an order the status is always pending until a user is assigned to the order. A user gets assigned to an order by executing the checkout url, then order status will change to `awaiting_payments.
expires_at DateTime DateTime when this order, if still not paid are expiring.
billing_address Object If a user is assigned via Hips checkout, information about the user will be visible here.
cart ➔ total_vat_amount Integer Sum of total tax
cart ➔ total_vat_amount_formatted String Formatted, human readable string of tax for currency
cart ➔ total_amount Integer Total sum of order (to be paid), including tax
cart ➔ total_amount_formatted String Formatted, human readable string of total_amount for currency
cart ➔ amount_due Integer Total sum of order including tax with existing payments deducted.
cart ➔ amount_due String Formatted, human readable string of amount_due for currency
coupons Array Array of discount coupons attached to this order.
order_id String Your unique order id of this order.
purchase_currency String We use the ISO 4217 standard for defining currencies. Examples are EUR, GBP, SEK, etc.
user_session_id String Used for anti-fraud. User session id on your end.
user_identifier String Used for anti-fraud. User identifier on your end (can be username, user_id, etc.)
cart Object JSON Object containing array of Items.
cart ➔ items Array JSON Array containing products ordered by the customer.
cart ➔ items ➔ type String Order line type. Possible values: physical, digital,service, shipping_fee, discount or fee.
cart ➔ items ➔ sku String Article number, SKU or similar.
cart ➔ items ➔ name String Descriptive item name.
cart ➔ items ➔ quantity Integer Non-negative. The item quantity.
cart ➔ items ➔ ean String EAN code of the product (used for anti-fraud)
cart ➔ items ➔ uri String URL to the product page that can be later embedded in communications between HIPS and the customer. (max 1024 characters)
cart ➔ items ➔ image_uri String URL to an image that can be later embedded in communications between HIPS and the customer. (max 1024 characters)
cart ➔ items ➔ discount_rate Integer Non-negative. In percent. i.e 25 = 25%.
cart ➔ items ➔ unit_price Integer Non-negative. Including tax/vat, excludes discount. Minor units. i.e 10000 = 100.00 (max value: 100000000).
cart ➔ items ➔ vat_amount Integer Tax/VAT amount. Non-negative. In minor units i.e 10000 = 10.00.
require_shipping Boolean Specify if the product requires shipping.
express_shipping Boolean Specify if the product requires shipping and the customer has explicitly asked for express shipping.
shipping_address Object
shipping_address ➔ given_name String Customer’s first name
shipping_address ➔ family_name String Customer’s last name
shipping_address ➔ street_address String Customer’s address
shipping_address ➔ postal_code String Customer’s postal code
shipping_address ➔ state String Customer’s state (2 letters)
shipping_address ➔ city String Customer’s city
shipping_address ➔ country String Customers country code. ISO 3166-1 Alpha-2 i.e: US,GB,DE,SE, etc
shipping_address ➔ email String Customer’s e-mail address
shipping_address ➔ phone String Customer’s phone number (mobile)
hooks Object
hooks ➔ user_return_url_on_success String If using HIPS checkout. This is the URL which Hips will send the customer after a successful purchase. If left blank Hips will display a thank you page for the user.
hooks ➔ user_return_url_on_fail String If using HIPS checkout. This is the URL which Hips will send the customer after a declined or aborted purchase. If left blank Hips will display a decline page for the user.
hooks ➔ terms_url String This is the URL for your stores terms and conditions. This will be embedded in communications between HIPS and the customer.
hooks ➔ webhook_url String If you provide an webhook URL here, this webhook will be used on this order instead of any pre-defined webhooks.

Update an order

HTTP Request

https://api.hips.com/v1/orders/(:id)

You must replace private_BQokikJOvBiI2HlWgH4olfQ2 with your private API key.

$ curl --request PATCH \
  --url https://api.hips.com/v1/orders/UVWofp7AjHiRKNLjhUjMnhc3 \
  --header 'Accept: application/json' \
  --header 'Authorization: private_9xxJrsc1u2TF6cPCm6JzG2ry' \
  --header 'Content-Type: application/json' \
  --data '{  
   "order_id": "123",
   "purchase_currency": "USD",
   "user_session_id": "3246568465743",
   "user_identifier": "SmartShopper17",
   "cart": {  
      "items": [  
         {  
            "type": "physical",
            "sku": "3123123",
            "name": "Hips cup",
            "quantity": 1,
            "unit_price": 1000,
            "discount_rate":0,
            "vat_amount": 250
         },
         {  
            "type": "shipping_fee",
            "sku": "1",
            "name": "UPS Express",
            "quantity": 1,
            "unit_price": 1000,
            "discount_rate":0,
            "vat_amount": 250
         }
      ]
   },
   "require_shipping": true,
   "express_shipping": true,
   "hooks": {
    "user_return_url_on_success": "https://mystore.com/thank_you",
    "user_return_url_on_fail": "https://mystore.com/sorry",
    "terms_url": "https://mystore.com/terms",
    "webhook_url": "https://api.mystore.com/confirmations"
   }
}'

The above command returns JSON structured like this:

{  
   "id": "UVWofp7AjHiRKNLjhUjMnhc3",
   "object": "order",
   "checkout_uri": "https://checkout.hips.com/UVWofp7AjHiRKNLjhUjMnhc3",
   "merchant_reference": {  
      "order_id": "123"
   },
   "purchase_currency": "USD",
   "status": "pending",
   "created_at": "2017-01-26T10:10:23.859Z",
   "last_modified_at": "2017-01-26T10:10:23.859Z",
   "expires_at":null,
   "require_shipping": true,
   "billing_address":null,
   "shipping_address":null,
   "cart": {  
      "total_vat_amount": 500,
      "total_vat_amount_formatted": "$5.00",
      "total_amount": 2000,
      "total_amount_formatted": "$20.00",
      "amount_due": 2000,
      "amount_due_formatted": "$20.00",
      "items": [  
         {  
            "id": "HnY8erVezohaLvg4ka3zEL9W",
            "object": "order_item",
            "sku": "3123123",
            "name": "Hips cup",
            "quantity": 1,
            "ean":null,
            "uri":null,
            "image_uri":null,
            "discount_rate":0,
            "vat_amount": 250,
            "unit_price": 1000,
            "weight_unit": "gram",
            "weight": 350
         },
         {  
            "id": "eqqR1MDXDxPP78NkHpznfmRf",
            "object": "order_item",
            "sku": "456778",
            "name": "Hips T-shirt",
            "quantity": 1,
            "ean":null,
            "uri":null,
            "image_uri":null,
            "discount_rate":0,
            "vat_amount": 250,
            "unit_price": 1000,
            "weight_unit": "gram",
            "weight": 200
         }
      ]
   },
   "coupons": []
}

Request Parameters

Name Type Description
order_id String Required Your unique order id of this order.
purchase_currency String Required We use the ISO 4217 standard for defining currencies. Examples are EUR, GBP, SEK, etc.
user_session_id String Recommended Used for anti-fraud. User session id on your end.
user_identifier String Recommended Used for anti-fraud. User identifier on your end (can be username, user_id, etc.)
cart Object Required JSON Object containing array of Items.
cart ➔ items Array Required JSON Array containing products ordered by the customer.
cart ➔ items ➔ type String Required Order line type. Possible values: physical, digital,service, shipping_fee, discount or fee.
cart ➔ items ➔ sku String Recommended Article number, SKU or similar.
cart ➔ items ➔ name String Required Descriptive item name.
cart ➔ items ➔ quantity Integer Required Non-negative. The item quantity.
cart ➔ items ➔ ean String EAN code of the product (used for anti-fraud)
cart ➔ items ➔ uri String URL to the product page that can be later embedded in communications between HIPS and the customer. (max 1024 characters)
cart ➔ items ➔ image_uri String URL to an image that can be later embedded in communications between HIPS and the customer. (max 1024 characters)
cart ➔ items ➔ discount_rate Integer Non-negative. In percent. i.e 25 = 25%.
cart ➔ items ➔ unit_price Integer Required Non-negative. Including tax/vat, excludes discount. Minor units. i.e 10000 = 100.00 (max value: 100000000).
cart ➔ items ➔ vat_amount Integer Tax/VAT amount. Non-negative. In minor units i.e 10000 = 10.00.
cart ➔ items ➔ weight_unit Integer The unit for the provided weight. Can be any of gram, kg, stone, lb. Default gram.
cart ➔ items ➔ weight Integer The weight of the order item in the provided weight unit. Must be provided if you plan to use weight-based Hips Shipping
require_shipping Boolean Recommended Specify if the product requires shipping.
express_shipping Boolean Recommended Specify if the product requires shipping and the customer has explicitly asked for express shipping.
shipping_address Object
shipping_address ➔ given_name String Customer’s first name
shipping_address ➔ family_name String Customer’s last name
shipping_address ➔ street_address String Customer’s address
shipping_address ➔ postal_code String Customer’s postal code
shipping_address ➔ state String Customer’s state (2 letters)
shipping_address ➔ city String Customer’s city
shipping_address ➔ country String Customer’s country code. ISO 3166-1 Alpha-2 i.e: US,GB,DE,SE, etc
shipping_address ➔ email String Customer’s e-mail address
shipping_address ➔ phone String Customer’s phone number (mobile)
hooks Object
hooks ➔ user_return_url_on_success String If using HIPS checkout. This is the URL which Hips will send the customer after a successful purchase. If left blank Hips will display a thank you page for the user.
hooks ➔ user_return_url_on_fail String If using HIPS checkout. This is the URL which Hips will send the customer after a declined or aborted purchase. If left blank Hips will display a decline page for the user.
hooks ➔ terms_url String This is the URL for your store’s terms and conditions. This will be embedded in communications between HIPS and the customer.
hooks ➔ webhook_url String If you provide an webhook URL here, this webhook will be used on this order instead of any pre-defined webhooks.

Read-Only Response Parameters

Name Type Description
id String HIPS unique ID for this order, also known as Order Token
object String Type of JSON structure
checkout_uri String Full path to HIPS checkout. If you want the user to pay on HIPS checkout, redirect the customer to this URL.
merchant_reference Object Reference object
merchant_reference ➔ order_id String Your order id (sent to Hips on creation of the order.)
status String Order status. Possible values: pending, awaiting_payments,expired, successful. After creation of an order the status is always pending until a user is assigned to the order. A user gets assigned to an order by executing the checkout url, then order status will change to `awaiting_payments.
expires_at DateTime DateTime when this order, if still not paid are expiring.
billing_address Object If a user is assigned via Hips checkout, information about the user will be visible here.
cart ➔ total_vat_amount Integer Sum of total tax
cart ➔ total_vat_amount_formatted String Formatted, human readable string of tax for currency
cart ➔ total_amount Integer Total sum of order (to be paid), including tax
cart ➔ total_amount_formatted String Formatted, human readable string of total_amount for currency
cart ➔ amount_due Integer Total sum of order including tax with existing payments deducted.
cart ➔ amount_due String Formatted, human readable string of amount_due for currency
coupons Array Array of discount coupons attached to this order.

Fulfill an order

Run this API call when you have fulfilled your obligations towards the customer. i.e: When your order are shipped or ready for shipment. If the order is digital or if it is a service then you can run the fulfill command once you know that you are able to fulfill your obligations.

A fulfillment call must be made within 7 days from creation of the order to be guaranteed that the authorization is still approved from any credit card network. Funds will be collected from the user/cardholder and settled to the merchant after the fulfill API call is executed. For automated fulfillments, set the JSON parameter fulfill = true when you create a new order.

What happends when the fulfill API is called?

When HIPS receive a fulfillment call on a order we will continue to collect the funds from the funding source of the customer into the merchants account.

Does digital downloads or services need fulfillment call?

No, if you know that you can deliver a digital product or service you can set the JSON parameter fulfill = true when you create a new order.

HTTP Request

https://api.hips.com/v1/orders/(:id)/fulfill

You must replace private_BQokikJOvBiI2HlWgH4olfQ2 with your private API key.

$ curl --request POST \
  --url https://api.hips.com/v1/orders/UVWofp7AjHiRKNLjhUjMnhc3/fulfill \
  --header 'Accept: application/json' \
  --header 'Authorization: private_9xxJrsc1u2TF6cPCm6JzG2ry' \
  --header 'Content-Type: application/json' 

The above command returns JSON structured like this:

{  
   "id": "UVWofp7AjHiRKNLjhUjMnhc3",
   "object": "fulfill",
   "merchant_reference": {  
      "order_id": "12344553"
   },
   "success": true,
   "message": "Fulfillment request successful"
}

Request Parameters

Name Type Description
id String Required Order id (Order Token)

Read-Only Response Parameters

Name Type Description
id String HIPS unique ID for this order, also known as Order Token
object String Type of JSON structure
merchant_reference Object Reference object
merchant_reference ➔ order_id String Your order id (sent to Hips on creation of the order.)
success Boolean Returns true if fulfillment request is successful.
message String Human readable response from fulfillment request.

Revoke and refund an order

Run this API call when you want to void or refund an order. The revoke can be for the whole order or just a part of the order. If you want to revoke a part of the order you have to specify amount.

The revoke call can be made regardless of order status. Refunds will only be sent should there be any payments on the order.

HTTP Request

https://api.hips.com/v1/orders/(:id)/revoke

You must replace private_BQokikJOvBiI2HlWgH4olfQ2 with your private API key.

$ curl --request POST \
  --url https://api.hips.com/v1/orders/UVWofp7AjHiRKNLjhUjMnhc3/revoke \
  --header 'Accept: application/json' \
  --header 'Authorization: private_9xxJrsc1u2TF6cPCm6JzG2ry' \
  --header 'Content-Type: application/json' \
  --data '{  
   "amount": 1000,
   "items": [
       {  
          "name": "T-shirt out of stock, sorry.",
          "quantity": 1,
          "vat_amount": -250,
          "unit_price": -1000
       } 
   ]

 }'

The above command returns JSON structured like this:

{  
   "id": "UVWofp7AjHiRKNLjhUjMnhc3",
   "object": "revoke",
   "merchant_reference": {  
      "order_id": "12344553"
   },
   "amount": 1000,
   "currency": "USD",
   "success": true,
   "message": "Revoked"
}

Request Parameters

Name Type Description
id String Required Order id (Order Token)
description String Human readable reason for revokation (will be sent to the cardholder statement or credit invoice). Ignored if items are provided.
amount Integer Non-negative. Minor units. i.e 10000 = 100,00 (max value: original order value). Amount that should be returned / refunded back to the customer. If blank the entire amount of the order will be refunded.
items Array JSON Array containing products that will be added to adjust the order.
items ➔ sku String Recommended Article number, SKU or similar.
items ➔ name String Required Descriptive item name.
items ➔ quantity Integer Required Non-negative. The item quantity.
items ➔ ean String EAN code of the product (used for anti-fraud)
items ➔ uri String URL to the product page that can be later embedded in communications between HIPS and the customer. (max 1024 characters)
items ➔ image_uri String URL to an image that can be later embedded in communications between HIPS and the customer. (max 1024 characters)
items ➔ unit_price Integer Required Negative for refunds. Including tax/vat, excludes discount. Minor units. i.e 10000 = 100.00 (max value: 100000000).
items ➔ vat_amount Integer Tax/VAT amount. Negative for refunds. In minor units i.e 10000 = 10.00.
items ➔ meta_data_1 String Can be used to store arbitrary data on the item
items ➔ meta_data_2 String Can be used to store arbitrary data on the item

Read-Only Response Parameters

Name Type Description
id String HIPS unique ID for this order, also known as Order Token
object String Type of JSON structure
merchant_reference Object Reference object
merchant_reference ➔ order_id String Your order id (sent to Hips on creation of the order.)
success Boolean Returns true if fulfillment request is successful.
message String Human readable response from fulfillment request.

Checkout API Integration Guide

HIPS Checkout is the best payment flow, on web and mobile. Checkout builds on hips.js to provide your users with a streamlined, mobile-ready payment experience that is constantly improving flow and payment options.

Integration

Use this javascript code to integrate HIPS checkout on web and mobile pages for a streamlined, mobile-ready payment experience that is constantly improving flow and payment option.

  <script src="https://cdn.hips.com/js/v1/hips.js"></script>
  <script>
       Hips.checkout({
        token: 'UVWofp7AjHiRKNLjhUjMnhc3'
       });
  </script>

If you want to customize the inline checkout with own colors and fonts you can do that by providing some extra parameters.

  <script src="https://cdn.hips.com/js/v1/hips.js"></script>
  <script>
       Hips.checkout({
        token: 'UVWofp7AjHiRKNLjhUjMnhc3',
        style: {
          'mainColor': 'BA68D1',
          'secondColor': 'C29ACE',
          'font': 'Comic Sans MS'
        }
       });
  </script>

You must replace UVWofp7AjHiRKNLjhUjMnhc3 with the order token received from HIPS for each new order.

You can integrate Checkout in as little as a single line of client-side code. As we release new HIPS features, we’ll automatically roll them out to your existing Checkout integration, so that you will always be using our latest technology and payment methods without needing to change a thing.

Checkout supports two different integrations:

The following is a typical transaction flow for HIPS checkout.

  1. Customer adds product to the cart and and proceeds to checkout.
  2. Your system calls HIPS API Create New Order with all items in the card and other costumer information.
  3. You receive an order token from HIPS, example: UVWofp7AjHiRKNLjhUjMnhc3
  4. You use the order token in hips.js for inline checkout (see below) or redirect the customer to HIPS hosted checkout page with the order token, example: https://checkout.hips.com/UVWofp7AjHiRKNLjhUjMnhc3.
  5. When the customer has completed payment, the customer will be sent back to your store’s "thank you” page or if the inline iframe solution is used the store’s thank you page will just show after completed payment.
  6. HIPS will now make a webhook callback to you, based on your webhooks settings in Hips Dashboard. If you want to provide additional specic webhooks, or prefer handling them centally, then you also can pass the hooks ➔ webhook_url when you create the order. Once you receive the webhook you should run the HIPS API View an order and check the status parameter to verify it to be successful.
  7. When you fulfill the order (ship the order or deliver a service) you run the HIPS API Fulfill an order to collect the authorized funds. This is not necessary if you set fulfilled to true when you created the order.
  8. Should you need to refund whole or part of an order, you run the HIPS API Revoke or refund

Hips.checkout() configuration

Name Type Description
token String Required HIPS unique ID for this order, also known as Order Token retrieved from HIPS API Create a new order
style Object JSON object providing optional styling preferences
style ➔ mainColor string A CSS color
style ➔ secondColor string A CSS color
style ➔ font string Overriding the default font

Change or update an order

The normal and recommended integration is to use hips.js on your checkout page below the cart. Should the user choose to change anything in the order that in this stage is already created, you should do the following:

  <script>  
    function change_something(){
      Hips.checkout.suspend();
      example_ajax('/change', function(){
        Hips.checkout.resume();
      });
    }
  </script>
  1. User changes quantity of a product in your cart on the checkout page.
  2. Call Hips.checkout.suspend(); to avoid that the customer checkout and pay without the new quantity is calculated in the total amount.
  3. Run your code to call your own server and update the order in your system and then call the HIPS API Update an order.
  4. When finished, call Hips.checkout.resume(); to reload and resume the checkout with the new data.

Tokenization API

Generate token

HTTP Request

https://api.hips.com/v1/tokens

You must replace public_BQokikJOgvBiI2Hl4456456 with your public API key.

$ curl --request POST \
  --url https://api.hips.com/v1/tokens \
  --header 'Accept: application/json' \
  --header 'Authorization: public_BQokikJOgvBiI2Hl4456456' \
  --header 'Content-Type: application/json' \
  --data '{ 
  "source": "card",
  "card": {
    "number": "4111111111111111",
    "exp_month": "12",
    "exp_year": "21",
    "cvc": "123"
  }
  }'

The above command returns JSON sstructured like this:

{
  "token": "mbDfB8vDXtnydX9kUvUFeZr5",
  "objectType": "token",
  "card": {
    "fingerprint": "9eb9596ade38cd431a44edf4d650d0de68501c9a27be7a6359dc1c502bfac137",
    "brand": "VISA",
    "first6": "411111",
    "last4": "1111",
    "mask": "41XX XXXX XXXX 1111",
    "expires": "2021-12-31"
  },
  "created": "2017-02-02T15:20:23.510Z",
  "type": "card"
}

Request Parameters

Name Type Description
source String Required Payment source, allowed values are card.
card Object Required Required if source is card
card ➔ number String Required Card number, only digits 0-9 allowed.
card ➔ exp_month String Required Card expiration month, 2 digits. Example 01 for January
card ➔ exp_year String Required Card expiration year, 2 digits. Example 25 for year 2025
card ➔ cvc String Required Card cvc, cvv, cvv2 value, 3-4 digits.

Read-Only Response Parameters

Name Type Description
token String Token, this value is your future reference with HIPS to debit, refund etc of this specific payment source.
objectType String Always token.
card Object Required if source is card
card ➔ fingerprint String Unique fingerprint of the card
card ➔ brand String Card brand, example: VISA,MASTERCARD,CHJONES FUEL CARD,UK FUEL CARD,STAR REWARDS,DINERS CLUB INTERNATIONAL,LASER,MAESTRO,DISCOVER,LOYALTY CARD,RBS GIFT CARD,AMERICAN EXPRESS,JCB,BANKCARD(INACTIVE),PHH FUEL CARD,RED LIQUID FUEL CARD,SOLO,RED FUEL CARD,BP FUEL CARD,LUKOIL FUEL CARD,CHINA UNION PAY,EUROSHELL FUEL CARD,ATOS PRIVATE LABEL,GE CAPITAL,PRIVATE LABEL CARD,SWITCH/MAESTRO,UNKNOWN
card ➔ first6 String First 6 digits of card number (for internal storage), also known as card BIN.
card ➔ last4 String Last 4 digits of card number for internal storage and display for cardholder.
card ➔ mask String PCI compliant mask of card number.
card ➔ expires String Expiration date of the card / token
created String Token creation timestamp
type String Type of token, values are card

Javascript for client side tokenization.

Tokenizing payment objects such as credit cards can be easily implemented using hips.js. You can build your own form anyway you like and ask for credit card details yourself, and by utilizing this functionality you can still avoid the PCI DSS certification requirement.

Example form:

  <form action="/pay" method="POST" id="hips-form">
    <div>
      <label for="ccno">Credit card number</label>
      <input type="text" name="name" />
    </div>

    <div>
      <label for="ccno">Credit card number</label>
      <input type="text" name="ccno" id="ccno" data-hips-tokenizer="number" />
    </div>

    <div>
      <label for="expM">Expiration MM/YY</label>
      <select id="expM" data-hips-tokenizer="exp_month">
        <option>01</option>
        <option>02</option>
        <option>03</option>
        <option>04</option>
        <option>05</option>
        <option>06</option>
        <option>07</option>
        <option>08</option>
        <option>09</option>
        <option>10</option>
        <option>11</option>
        <option>12</option>
      </select>

      <select data-hips-tokenizer="exp_year">
        <option>2016</option>
        <option>2017</option>
        <option>2018</option>
      </select>
    </div>

    <div>
      <label for="ccno">CVC</label>
      <input type="text" size="5" id="cvc" data-hips-tokenizer="cvc" />
    </div>

    <div>
      <button type="submit">OK</button>
    </div>
  </form>

Client-side Tokenization Methods

If you were to just use this form as is, the card numbers would be submitted to you as is, which would require PCI DSS certification.

By attaching these data attributes to your inputs we can use hips.js to automatically exchange all sensitive credit card information with unique tokens.

Attribute value Type Description
number String Required Credit card number
exp_month String Required Credit card expiration month, e.g. “02” for february
exp_year String Required Credit card number expiration year, e.g “2020”
cvc String Required Credit card CVC

Methods

There are two different methods that you can use to retrieve the credit card token when you have a compatible form in place. To use either of these, you must first include hips.js Then, you need to make sure that you have set the Hips.public_key property to your own public key in order to enable the script to use the underlying tokenization API

Hips.tokenizeCard

When using Hips.tokenizeCard we automatically replace all credit card related fields with a hidden field containing a token retrieved from Hips.

<script src="https://cdn.hips.com/js/v1/hips.js"></script>
<script>
  Hips.public_key='public_n5NsQzono3d4Se3xQ34E7mPB';
  Hips.tokenizeCard('#hips-form', function(response){
    if(response.error) alert(response.error.message);
    //On success, token is available in response.payload.token
    //Return false to stop form submission even on success.
  });
</script>

In this example we enable tokenization on the form with ID hips-form. You can provide any form element or CSS selector. With the seconds argument we assign a callback function that can be used for error handling as well as bypassing the form submission (for custom ajax request for example)

The first argument of the callback function provides an object representing the response from the API. If something went wrong then the error attribute of that object will be populated and non-false. If not, you can access the token from the object in the payload property. i.e. response.payload.token If your callback function explicitly returns false then the submission will be stopped, which for example could be used for proceeding using ajax.

Using the token

When the tokenizer has been properly implemented, none of the sensitive card information will reach your server. Those fields will simply be stripped from the request resulting from the form’s submission. You will find that in place of the card details, one single card_token value will be available like any other POST field.

Hips.card.getToken

If a form submission is not desirable for your implementation, for example because of a multi-step checkout, you can retrieve the token manually in order to use it as you see fit.

<script src="https://cdn.hips.com/js/v1/hips.js"></script>
<script>
  Hips.public_key='public_n5NsQzono3d4Se3xQ34E7mPB';

  function tokenize(){
    Hips.card.getToken('#hips-form', function(token, error){
      if(response.error){
        alert('Error: '+error.message);
      } else {
        alert('Success, token: '+token);
      }
     });
  }
  </script>
  <button type="button" onclick="tokenize()">Tokenize</button>

In this example we tokenize the form with ID hips-form. You can provide any form element or CSS selector. With the seconds argument we assign a callback function where the first argument will contain the token retrieved from Hips. If something went wrong then the second argument of your callback function will be a object describing the error.

Payment API

Create a new payment

HTTP Request

https://api.hips.com/v1/payments

You must replace private_BQokikJOvBiI2HlWgH4olfQ2 with your private API key.

Example request with card_token

$ curl --request POST \
  --url https://api.hips.com/v1/payments \
  --header 'Accept: application/json' \
  --header 'Authorization: private_BQokikJOvBiI2HlWgH4olfQ2' \
  --header 'Content-Type: application/json' \
  --data '{
"source": "card_token",
"card_token": "73jWmRr6iGmiDN14UH6cut6g",
"purchase_currency": "USD",
"amount": 995,
"customer": {
      "name": "John Doe",
      "email": "john@doe.com",
      "ip_address": "37.123.187.251"
    }
}'

Example request with card

$ curl --request POST \
  --url https://api.hips.com/v1/payments \
  --header 'Accept: application/json' \
  --header 'Authorization: private_BQokikJOvBiI2HlWgH4olfQ2' \
  --header 'Content-Type: application/json' \
  --data '{  
   "source": "card",
   "card": {  
      "number": "4111111111111111",
      "exp_month": "01",
      "exp_year": "21",
      "cvc": "123"
   },
   "purchase_currency": "USD",
   "amount": 995,
   "customer": {
      "name": "John Doe",
      "email": "john@doe.com",
      "ip_address": "37.123.187.251"
    }
}'

The above command returns JSON structured like this:

Example of a payment request where preflight redirect is NOT required:

{
  "id": "z68uoH7QZ1fizWZ3iPR6vbYE",
  "object": "payment",
  "source": "card",
  "status": "successful",
  "preflight": {
    "requires_redirect": false,
    "redirect_user_to_url": null,
    "status": "successful"
  },
  "order": {
    "id": "VqqG2QAiNHA7VwuVGw5GZXtj",
    "merchant_reference": {
      "order_id": null
    }
  },
  "amount": 3000,
  "amount_currency": "USD",
  "settlement_amount": 3000,
  "settlement_amount_currency": "USD",
  "settlement_exchange_rate": 1,
  "authorization_code": "624412",
  "decline_reason": "not_declined"
}

Example of a payment request where preflight redirect IS required (in the example below the preflight indicates that 3D Secure is required and that the cardholder should be redirected to his/her bank for authentication):

{
  "id": "ViCbUHPnMJyTM4YrXbDuDkHc",
  "object": "payment",
  "source": "card",
  "status": "pending",
  "preflight": {
    "requires_redirect": true,
    "redirect_user_to_url": "https://landings.hips.com/redirector/?preflight_id=9vrLvaEms4UCjd1R7nKpKpd9",
    "status": "require_3ds"
  },
  "order": {
    "id": "ifdkHpKK6YW3BovXFn3WVsoP",
    "merchant_reference": {
      "order_id": null
    }
  },
  "amount": 3000,
  "amount_currency": "USD",
  "settlement_amount": 3000,
  "settlement_amount_currency": "USD",
  "settlement_exchange_rate": 1,
  "authorization_code": null,
  "decline_reason": "not_declined"
}

Request Parameters

Name Type Description
meta_data_1 String Can be used to store arbitrary merchant data on the order
meta_data_2 String Can be used to store arbitrary merchant data on the order
source String Required Payment source, allowed values are card, card_token. If card is used the card object must be set, if card_token is used the card_token string must be set with a token from the Tokenization API or Tokenization JavaScript.
order_id String Your unique ID of this payment / order. (for later search reference)
order_token String Order token to connect this payment to if a previous Create new order request was performed.
purchase_currency String Required We use the ISO 4217 standard for defining currencies. Examples are EUR, GBP, SEK, etc.
amount Integer Required Non-negative. Minor units. i.e 10000 = 100,00 (max value: 100000000).
vat_amount Integer Tax/VAT amount. Non-negative. In minor units i.e 10000 = 10.00.
card Object Dependency Required if source is card
card ➔ number String Card number, only digits 0-9 allowed.
card ➔ exp_month String Card expiration month, 2 digits. Example 01 for January
card ➔ exp_year String Card expiration year, 2 digits. Example 25 for year 2025
card ➔ cvc String Card cvc, cvv, cvv2 value, 3-4 digits.
card_token String Dependency Card token from Tokenization API or Tokenization JavaScript. Required if source is card_token.
capture Boolean Dafault false. Indicate if the payment shall be marked as fulfilled and the payment should be settled direct. If this param is set to true there are no need to run the Capture API
customer Object Required
customer ➔ email String Required Email of the customer being charged. Important for anti-fraud use.
customer ➔ name String Required Full name of the customer, as printed on the card.
customer ➔ street_address String Recommended Full address including house number of customer. (used for anti-fraud).
customer ➔ postal_code String Recommended Postal code of customer. (used for anti-fraud).
customer ➔ country String Recommended Customers country code. ISO 3166-1 Alpha-2 i.e: US,GB,DE,SE, etc. (Used for anti-fraud).
customer ➔ ip_address String Required IP address of the customer being charged. IPv4 or IPv6 allowed. Important for anti-fraud use. Examples: 37.123.187.251 or 0:0:0:0:0:ffff:257b:bbfb
preflight Boolean Default is true. Describes if a preflight redirect should be performed before the authorization. Read more about payment preflight in the section below. If preflight is set to false 3D Secure will be skipped (not recommended). To skip preflight, a prior approval from HIPS support must be granted on your merchant account.
recurring Object Required for recurring payments
recurring ➔ frequency String Dependency How often should the recurring charge be executed. Allowed values are day, week, bimonth, month, quarter, biannual and annual
recurring ➔ start Date Date when first recurring payment should be executed. Must be a date in the future. Date format is YYYY-MM-DD.
recurring ➔ amount Integer Dependency Non-negative. Amount beeing charge each occurance. Todays charge will be the amount specified in amount. Minor units. i.e 10000 = 100,00 (max value: 100000000).
recurring ➔ expires Date Date when the recurring payment job should be terminated. Must be a date in the future. Date format is YYYY-MM-DD.
recurring ➔ max_amount Integer Non-negative. Total amount that will be charged in this recurring job before the job is terminated. Minor units. i.e 10000 = 100,00 (max value: 100000000).
recurring ➔ max_retry_attpmpts Integer Default 4. How many retries of retry_attempt_frequency should be performed to charge the customer before this job is terminated and reported as fail.
recurring ➔ retry_attempt_frequency String Default week. How often should the max_retry_attpmpts be executed. Allowed values areday,week,bimonth,month,quarter,biannualandannual`
hooks Object
hooks ➔ user_return_url_on_success String URL where HIPS will send back the customer if a preflight redirection is required (i.e: for 3D Secure authentication). If left blank Hips will display a thank you page for the user.
hooks ➔ user_return_url_on_fail String URL where HIPS will send back the customer if a preflight redirection is required (i.e: for 3D Secure authentication). If left blank Hips will display a decline page for the user.
hooks ➔ webhook_url String If you provide an webhook URL here, this webhook will be used on this payment in addition to any pre-defined webhooks.

Read-Only Response Parameters

Name Type Description
id String Payment ID (store this for later referral to this payment. i.e for capture or `refund
object String Always payment
source String Funding source used. Can be card, invoice,part_payment,swift,bitcoin,swish orpaypal`.
status String Payment Status (see below reference)
preflight Object
preflight ➔ requires_redirect Boolean Indicates if you need to redirect the customer to an external page to complete the payment. (i.e: when a card issuer requires cardholder to authenticate 3D Secure)
preflight ➔ redirect_user_to_url String URL that you redirect the customer to if requires_redirect is true.
preflight ➔ status String Preflight Status (see below reference)
order Object
order ➔ id String Order ID of the created or mapped underlying order.
order ➔ merchant_reference Object
order ➔ merchant_reference ➔ order_id String Your unique order id for this payment/order.
amount Integer Non-negative. Total amount that will/has been charged for this payment request. Minor units. i.e 10000 = 100,00 (max value: 100000000).
amount_currency String Currrency charged, i.e USD
settlement_amount String Non-negative. Total amount that will/has been settled to your HIPS account for this payment request. Minor units. i.e 10000 = 100,00 (max value: 100000000).
settlement_amount_currency String Settlement currrency for this payment request, i.e USD
settlement_exchange_rate Integer Exchange rate for this payment if amount_currency and settlement_amount_currency differs.
authorization_code String Authorization code for this transaction (store this for future reference)
decline_reason String If status is failed then the decline reason will show here. See error and decline codes for details.

Payment Statuses

Name Description
pending The payment request is waiting for a preflight to be successful before it can continue with an authorization.
authorized The payment is authorized (approved by bank or financial institution). The funds are reserved with the customers bank, but is not captured. You must call the Capture API when you want to capture the funds and finalize the payment request. This is normally done when the products ordered are shipped to the customer.
pending_capture The payment is marked as fulfilled or a capture request has been sent, but it has not yet been captured by the system.
failed Payment is declined
successful Payment is authorized, and captured. And will be paid to you.

Preflight Statuses

Name Description
successful No preflight is required.
require_3ds The card used is enrolled in 3D Secure and the cardholder needs to be redirected to his/her bank to finalize the authentication process. If you get this preflight status, you should redirect the customer to the URL in preflight ➔ redirect_user_to_url. The customer will return back to your platform via the URL you specilied in “

View a payment

This command is used you wish to view a payment to check the payment status. This comman shall be executed on a webhook vall to verify the data and the the return of a 3D Secure / Preflight session to see the payment status of the payment request.

HTTP Request

https://api.hips.com/v1/payments/(:id)

You must replace private_BQokikJOvBiI2HlWgH4olfQ2 with your private API key.

$ curl --request GET \
  --url https://api.hips.com/v1/payments/z68uoH7QZ1fizWZ3iPR6vbYE \
  --header 'Accept: application/json' \
  --header 'Authorization: private_BQokikJOvBiI2HlWgH4olfQ2' \
  --header 'Content-Type: application/json' 

The above command returns JSON structured like this: Note that this is a technically a separate payment with a negative amount

{
  "id": "z68uoH7QZ1fizWZ3iPR6vbYE",
  "object": "payment",
  "source": "card",
  "status": "successful",
  "preflight": {
    "requires_redirect": false,
    "redirect_user_to_url": null,
    "status": "successful"
  },
  "order": {
    "id": "VqqG2QAiNHA7VwuVGw5GZXtj",
    "merchant_reference": {
      "order_id": null
    }
  },
  "amount": 3000,
  "amount_currency": "USD",
  "settlement_amount": 3000,
  "settlement_amount_currency": "USD",
  "settlement_exchange_rate": 1,
  "authorization_code": "624412",
  "decline_reason": "not_declined"
}

Request Parameters

Name Type Description
id String Required Payment ID)

Read-Only Response Parameters

Name Type Description
id String Payment ID (store this for later referral to this payment. i.e for capture or `refund
object String Always payment
source String Funding source used. Can be card, invoice,part_payment,swift,bitcoin,swish orpaypal`.
status String Payment Status (see below reference)
preflight Object
preflight ➔ requires_redirect Boolean Indicates if you need to redirect the customer to an external page to complete the payment. (i.e: when a card issuer requires cardholder to authenticate 3D Secure)
preflight ➔ redirect_user_to_url String URL that you redirect the customer to if requires_redirect is true.
preflight ➔ status String Preflight Status (see below reference)
order Object
order ➔ id String Order ID of the created or mapped underlying order.
order ➔ merchant_reference Object
order ➔ merchant_reference ➔ order_id String Your unique order id for this payment/order.
amount Integer Non-negative. Total amount that will/has been charged for this payment request. Minor units. i.e 10000 = 100,00 (max value: 100000000).
amount_currency String Currrency charged, i.e USD
settlement_amount String Non-negative. Total amount that will/has been settled to your HIPS account for this payment request. Minor units. i.e 10000 = 100,00 (max value: 100000000).
settlement_amount_currency String Settlement currrency for this payment request, i.e USD
settlement_exchange_rate Integer Exchange rate for this payment if amount_currency and settlement_amount_currency differs.
authorization_code String Authorization code for this transaction (store this for future reference)
decline_reason String If status is failed then the decline reason will show here. See error and decline codes for details.

Payment Statuses

Name Description
pending The payment request is waiting for a preflight to be successful before it can continue with an authorization.
authorized The payment is authorized (approved by bank or financial institution). The funds are reserved with the customers bank, but is not captured. You must call the Capture API when you want to capture the funds and finalize the payment request. This is normally done when the products ordered are shipped to the customer.
pending_capture The payment is marked as fulfilled or a capture request has been sent, but it has not yet been captured by the system.
failed Payment is declined
successful Payment is authorized, and captured. And will be paid to you.

Preflight Statuses

Name Description
successful No preflight is required.
require_3ds The card used is enrolled in 3D Secure and the cardholder needs to be redirected to his/her bank to finalize the authentication process. If you get this preflight status, you should redirect the customer to the URL in preflight ➔ redirect_user_to_url. The customer will return back to your platform via the URL you specilied in ”

Capture a payment

When an order has been fulfilled and you are ready to deliver, you need to capture the payment in order to finalize the transaction. This step is only necessary if you didn’t provide capture=true when you created the payment.

HTTP Request

https://api.hips.com/v1/payments/(:id)/capture

You must replace private_BQokikJOvBiI2HlWgH4olfQ2 with your private API key.

$ curl --request POST \
  --url https://api.hips.com/v1/payments/z68uoH7QZ1fizWZ3iPR6vbYE/capture \
  --header 'Accept: application/json' \
  --header 'Authorization: private_BQokikJOvBiI2HlWgH4olfQ2' \
  --header 'Content-Type: application/json' 

The above command returns JSON structured like this:

{
  "id": "z68uoH7QZ1fizWZ3iPR6vbYE",
  "object": "payment",
  "status": "successful",
  "order_status": "successful",
  "order_id": "WNzyWdQmXKaiw5zHiiXKoVVt",
  "amount": 3000,
  "amount_currency": "USD"
}

Refund a payment

This command is used you wish to refund a payment made using the payment command. A payment can be fully or partially refunded and the refund currency will always be the same as on the initial payment.

HTTP Request

https://api.hips.com/v1/payments/(:id)/refund

You must replace private_BQokikJOvBiI2HlWgH4olfQ2 with your private API key.

$ curl --request POST \
  --url https://api.hips.com/v1/payments/z68uoH7QZ1fizWZ3iPR6vbYE/refund \
  --header 'Accept: application/json' \
  --header 'Authorization: private_BQokikJOvBiI2HlWgH4olfQ2' \
  --header 'Content-Type: application/json \
  --data '{
    "amount": 1000,
    "items": [
       {  
          "name": "T-shirt out of stock, sorry.",
          "quantity": 1,
          "vat_amount": -250,
          "unit_price": -1000
       } 
   ]
  }' 

The above command returns JSON structured like this: Refunds on payments that are not yet captured will result in the adjustment or voiding of the original payment. If the payment has already been captured then a separate refund payment will be returned instead.

{
  "id": "xTEBzXDY8A6HEJJoZhV1cqBU",
  "object": "payment",
  "status": "successful",
  "order_status": "successful",
  "order_id": "WNzyWdQmXKaiw5zHiiXKoVVt",
  "amount": -1000,
  "amount_currency": "USD"
}

Request Parameters

Name Type Description
id String Required Order id (Order Token)
description String Human readable reason for revokation (will be sent to the cardholder statement or credit invoice). Ignored if items are provided.
amount Integer Non-negative. Minor units. i.e 10000 = 100,00 (max value: original order value). If blank the entire amount of the order will be refunded.
items Array JSON Array containing products that will be added to adjust the order.
items ➔ sku String Recommended Article number, SKU or similar.
items ➔ name String Required Descriptive item name.
items ➔ quantity Integer Required Non-negative. The item quantity.
items ➔ ean String EAN code of the product (used for anti-fraud)
items ➔ uri String URL to the product page that can be later embedded in communications between HIPS and the customer. (max 1024 characters)
items ➔ image_uri String URL to an image that can be later embedded in communications between HIPS and the customer. (max 1024 characters)
items ➔ unit_price Integer Required Negative for refunds. Minor units. Including tax/vat, excludes discount. i.e 10000 = 100.00 (max value: 100000000).
items ➔ vat_amount Integer Tax/VAT amount. Non-negative. In minor units i.e 10000 = 10.00.
items ➔ meta_data_1 String Can be used to store arbitrary data on the item
items ➔ meta_data_2 String Can be used to store arbitrary data on the item

What is a Preflight?

A preflight is a request that are beeing performed on HIPS side before the payment is executed to see if the card beeing charged is enrolled in 3D Secure.

Should the card used for the transaction be enrolled in 3D Secure, the cardholder must be redirected to the card issuer for authentication. You will see this by looking in the preflight object of the JSON response from the Payment API. Look if preflight ➔ requires_redirect is true, in that case redirect the user to preflight ➔ redirect_user_to_url for authentication.

Once the authentication process is completed, the cardholder will return to your specified hooks ➔ user_return_url_on_success or hooks ➔ user_return_url_on_fail depending of the result from the authentication.

When the user gets back to you, you should call View a payment API to get the result of the payment request.

Should the card not be enrolled in 3D secure, the JSON result will include the result of the payment request. The parameter status will be successful if the card was charged or failed if the card charge failed.

** Preflight exemption** 3D Secure is a mandatory authentication mechanism for Visa, MasterCard and American Express card. However, should your environment be unable to redirect a user you can apply for an exemption from HIPS support. If approved you shall pass the parameter preflight=false in the payment request.

What is 3D Secure?

The 3D Secure authentication is an additional fraud prevention scheme that is available to all companies using the HIPS systems to process transactions.

Its a way for the card-issuer to authenticate the cardholder before an internet transaction occurs. A PIN code or equal for any online purchases.

Typical 3D Secure transaction flow:

  1. The cardholder enters card detail in the shop
  2. The shop run the Payment API and create a payment request.
  3. HIPS check if the card is enrolled in 3D Secure
  4. The Payment API returns a preflight status that is require_3ds.
  5. The merchant redirect the cardholder to redirect_user_to_url
  6. The user comes back to the hooks ➔ user_return_url_on_success after a successful 3d secure authentication.
  7. The merchant run View Payment API to see if payment status is authorized, successful or failed.
  8. Based on the result from the payment view the order is dispatched from the merchant.

What are the benefits of using 3D Secure?

Liability Shift : The main benefit to companies using the 3D Secure scheme is the availability of a liability shift for a successfully verified transaction. This offers protection by the card issuers against chargebacks as the liability is assumed.

No extra cost : There are no extra costs to add 3D Secure onto your HIPS account.

Easy to set up and control : For HIPS checkout, 3D secure is controlled and handled automatically by HIPS. For the Payment API, Hips uses a preflight to check if a card is enrolled before the actual authentication occurs. It’s very easy to setup, just follow this documentation.

Are there any limitations of using this?

Cardholder must be redirected outside the shop : The cardholder must be redirected to the issuing bank for authentication. However he/she will come back to your store to a predefined url once the authentication is complete.

Chargebacks can still occur : Fully authenticated 3D Secure transactions do not guarantee a liability shift, this is decided at the discretion of your merchant bank. The majority of frauds, however, will be blocked using 3D secure.

Response and Error Codes

HTTP status code summary (not limited to):

HIPS uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.), and codes in the 5xx range indicate an error with HIPS’s servers (these are rare).

Not all errors map cleanly onto HTTP response codes, however. When a request is valid but does not complete successfully (e.g., a card is declined), we return a 402 error code. To understand why a card is declined, refer to the list of codes in the documentation.

HTTP Code Successful Meaning
200 Yes OK - Your request was sucessful
201 Yes Created - Your request was created
202 Yes Accepted - Your request was accepted
400 No Bad Request – Your request has invalid data. Check your parameters.
401 No Unauthorized – Your API key is wrong, see Authentication
402 No Payment Required - Card declined or no payments are made to an order
403 No Forbidden – The requested data is restricted for your api key.
404 No Not Found – The requested data is not found.
406 No Not Acceptable – You requested a format that isn’t json
429 No Too Many Requests – Your code is pounding our servers, to protect us from evil loops we have a request limit. Should you discover that you need to raise your limit, please contact support.
5XX No Something went wrong on HIPS’s end. (These are rare.)
7XX ¯\(ツ) Sometimes, when you do something really unexpectedly silly, you might end up with a 7XX error. In that case we refer to 7XX-rfc :)

Error types

Error Type Meaning
api_connection_error Failure to connect to HIPS’s API.
api_error API errors cover any other type of problem (e.g., a temporary problem with HIPS’s servers) and are extremely uncommon.
authentication_error Failure to properly authenticate yourself in the request.
card_error Card errors are the most common type of error you should expect to handle. They result when the user enters a card that can’t be charged for some reason.
invalid_request Invalid request errors arise when your request has invalid parameters.
rate_limit Too many requests hit the API too quickly.
restricted Your api key or account is restricted, contact support.

Misc error codes

Error Type Meaning
card_not_supported The payment source does not support this type of purchase
currency_not_supported The payment source does not support the specified currency.
do_not_honor The payment has been declined for an unknown reason
fraudulent The payment has been declined as it suspects to be fraudulent
insufficient_funds The payment source has insufficient funds to complete the purchase
customer_not_accepted HIPS rejects the customer
customer_blacklisted HIPS rejects the customer
unpaid_bills HIPS rejects the customer
customer_not_18 Customer is not 18 (required by law)
no_such_person Rejected - No such person found