Hellopay
API docs by Redocly

Gateway API Reference (1.0.0)

E-mail: [email protected] URL: https://hellopay.co.za/contact-us/ Terms of Service

Hellopay Gateway is an online solution that allows a merchant to quickly perfom integration with their favourite shopping carts and start accepting payments online.

Getting Started

Hellopay Gateway allows merchants to process card payments online. This document describes how a merchant can get started with the Payment Gateway.

HelloPay Image

Merchant Signup

New merchant can either sign up using our sign up form at https://signup.hellopay.co.za/sign-up or be in touch with our agents using our contact us page https://hellopay.co.za/contact-us/

API Key

On passing compliance checks and getting approved, the system will generate and enail an API Key and Terminal ID (TID) pair in your provided email address during signup.

Environments

Two environments are available to be used during development/integration cycle and go live.

  • Sandbox environment which is used for testing your integration
  • Live environment which is used for processing payments in your live system.
Environment Hosted Payment Page URL Payment API URL
Live https://payments.hellopay.co.za/ https://gateway.hellopay.co.za
Sandbox https://sandbox-payments.hellopay.co.za/ https://sandbox-gateway.hellopay.co.za/

Test Cards

The following cards can be used when performing tests in the sandbox environment.

The different card numbers simulates different 3D Secure Authentication Flows. Namely,

  • Frictionless Authentication
  • Fully Challenged Authentication
  • Failed Authentication
Authentication Flow Visa Mastercard
Frictionless Authentication 4069425217889137 5163426869252246
Fully Challenged Authentication(password: test123) 4895749143709709 5192602720584796
Failed Authentication 4069421358347845 5178872338408971

Handling Payments

Hellopay allows payments to be accepted on behalf of merchants from a hosted payment page. The payment page can only be opened with a payment token and an access token.

Payment Token

A payment token captures billing address, shipping address and cardholder's details.

Learn more on Payment Token API

Access Token

An access token has got a limited lifetime of twenty minutes. It is used for authentication purposes in the hosted payment page.

Learn more on Access Token API

Opening Payment Page

The following steps needs to be executed in order to be able to open an instance of the payment page.

  1. Create a payment token using the create payment token api.
  2. Create an access token using the create access token api
  3. Use payment page url from create payment token response and append access token from create access token response
    https://payments.hellopay.co.za/?token=payment-token&accessToken=access-token
  4. Open payment page url to start accepting payment

Merchant Portal

Registered merchants can login using their credentials in the merchant portal to view transactions history.

Transactions Notification

A payment notification is sent on each payment transaction that has occured in our system. A json webhook is sent to registered endpoint when creating a payment token.

bin
string

Card bin number

card_expiry
integer

Card expiry date in mmYY format

card_scheme
string

The card scheme

issuer
string

The card issuer

legal_name
string

The legal name of the entity for which payment has been processed

trading_name
string

The trading name of the entity for which the payment has been processed

mid
string

Hellopay assigned merchant id

tid
string

Hellopay assigned terminal Id

payment_reference
string

Payment reference number to track each payments that occured in the system

transaction_currency
string (CurrencyCode)
Value: "ZAR"

Currency code of currency used during payment processing

transaction_datetime
string <date-time>

Date tine at which transaction occured

transaction_reference
string

Transaction reference of each transactions that occurred for a particular payment

transaction_status
string (PaymentStatus)
Enum: "Approved" "Declined"

The status of individual transactions within a payment group

transaction_type
string (TransactionType)
Enum: "Authorisation" "Refund"

The type of transaction

{
  • "bin": 4069,
  • "card_expiry": 425,
  • "card_scheme": "VISA",
  • "issuer": "SBSA",
  • "legal_name": "One stop pool and hardware pty Ltd",
  • "trading_name": "One stop pool and hardware",
  • "mid": 901000000115566,
  • "tid": 91000005,
  • "payment_reference": "28e44532-fb55-4a4f-a867-b1c58a6ac86f",
  • "transaction_currency": "ZAR",
  • "transaction_datetime": "2019-08-24T14:15:22Z",
  • "transaction_reference": "966433b3-da0b-4540-9839-b3f3b306de18",
  • "transaction_status": "Approved",
  • "transaction_type": "Authorisation"
}

Plugins and SDKs

The following plugins and SDKs have been made available to facilitate integration with the payment gateway. They allow relatively faster go to market and are proven to work.

WooCommerce

The lasest version of our WooCommerce plugin can be downloaded from below:

Hellopay WooCommerce Plugin

Shopify

Our Shopify plugin is currently under development

Error Responses

All api errors are described using problem details as defined in RFC 7807.

type
string

Link to description of error message type

title
string

Description of the http status code

status
integer

Http status code

detail
string

Error Details

instance
string

The resource path

{}

Access Tokens

Create access token

Endpoint for creating access token that enables a merchant to initiate a payment page and accept card payment_description

Authorizations:
API KEY
Request Body schema: application/json
required
terminal_id
required
string

Merchant Terminal Id

Responses

Request samples

Content type
application/json
{
  • "terminal_id": "string"
}

Response samples

Content type
application/json
{
  • "token": "string"
}

Payment Tokens

Create payment token

Endpoint for creating a new payment token that will enable a merchant to send in cardholder's information, billing address, shipping address and order information.

Authorizations:
API KEY
Request Body schema: application/json
required
amount
required
number <long> >= 0

Payment amount in cents.

currency_code
required
string (CurrencyCode)

The currency code of the transaction. Only ZAR is accepted at the moment.

reference_number
string

Merchant's reference number that can be used to easily identifiy transactions on the gateway.

payment_description
string

A verbose description that an order to have a meaningful description.

success_callback_url
string

The success url onto which the card holder will be directed to after they have successfully performed.

failure_callback_url
string

The failure url onto which the card holder will be redirected to after they have not successfully completed a payment.

transaction_notification_url
string

An endpoint at merchant's end where webhook notifications will be sent.

terminal_id
required
string

Unique terminal id assigned to mercahnt to help identify merchant's transactions

object
object

Responses

Request samples

Content type
application/json
{
  • "amount": 0,
  • "currency_code": "ZAR",
  • "reference_number": "string",
  • "payment_description": "string",
  • "success_callback_url": "string",
  • "failure_callback_url": "string",
  • "transaction_notification_url": "string",
  • "terminal_id": "string",
  • "billing_address": {
    },
  • "shipping_address": {
    }
}

Response samples

Content type
application/json
{
  • "token": "string",
  • "reference": "string",
  • "payment_description": "string",
  • "expiry": "2019-08-24T14:15:22Z",
  • "created": "2019-08-24T14:15:22Z",
  • "modified": "2019-08-24T14:15:22Z",
  • "_links": {
    }
}

Get payment token details

Get details related to a specific payment tokens

Authorizations:
Bearer Token
path Parameters
token
string

Unique payment token reference

Responses

Response samples

Content type
application/json
{
  • "token": "string",
  • "amount": 0,
  • "display_amount": "string",
  • "expires": "2019-08-24T14:15:22Z",
  • "created": "2019-08-24T14:15:22Z",
  • "modified": "2019-08-24T14:15:22Z",
  • "currency_code": "string",
  • "success_callback_url": "string",
  • "failure_callback_url": "string",
  • "transaction_notification_url": "string",
  • "reference_number": "string",
  • "payment_description": "string",
  • "billing_address": {
    },
  • "shipping_address": {
    },
  • "terminal_id": "string",
  • "trading_name": "string",
  • "legal_name": "string"
}

Payments

Get payment details

Get payment details by payment reference

Authorizations:
API KEY
path Parameters
payment_reference
string

Unique reference number for a payment

Responses

Response samples

Content type
application/json
{
  • "created": "2019-08-24T14:15:22Z",
  • "modified": "2019-08-24T14:15:22Z",
  • "payment_status": "Approved",
  • "payment_reference": "string",
  • "merchant_reference_id": "string",
  • "currency_code": "ZAR",
  • "authorised_amount": 0,
  • "authorised_amount_for_display": "string",
  • "captured_amount": 0,
  • "captured_amount_for_display": "string",
  • "refunded_amount": "string",
  • "refunded_amount_for_display": "string",
  • "payment_description": "string",
  • "billing_address": {
    },
  • "shipping_address": {
    }
}