Hivelinq.com API Reference (1.0)

Download OpenAPI specification:Download

Get started

Hivelinq.com provides a collection of APIs that enable you to process and manage payments. Our APIs accept and return JSON in the HTTP body, and return standard HTTP response codes. You can consume the APIs directly using your favorite HTTP/REST library. We have a testing environment called sandbox, which you can sign up for to test API calls without affecting live data.

Authentication

When you sign up for an account, you can authenticate with Secret API key which Hivelinq.com will provide upon account approval. Unless explicitly stated, all endpoints require authentication using Secret API Key. Public keys should only be used in JavaScript or native applications.

  • Server-to-server authentication. Use your secret key for server-to-server communication. Support for API keys depends on the endpoint. Never share your API keys, or access tokens. Keep them guarded and secure.

Changelog

Date Description of change
2022/07/22 Hivelinq.com API Reference generated.
2022/08/02 Hosted payment page extended request "customer_details (object)" added

Payments

Request a payment

Send a payment or payout.

Note: successful payout requests will always return a 202 response.

SecurityApiSecretKey
Request
header Parameters
Fzb-Idempotency-Key
string

An optional idempotency key for safely retrying payment requests

Request Body schema: application/json
One of:

Payment Request

type
string
Default: "card"

The payment source type Note: To make a payment with full card details, you must be SAQ D PCI compliant

Value: "card"
amount
integer

Transaction amount. The decimal separator must be a point “.”

trackingMemberCode
string <= 50 characters

A reference you can later use to identify this payment, such as an order number

currencyId
integer [ 2 .. 3 ]

ISO 4217 Currency code (numeric) that indicates the currency of the transaction.

countryId
integer [ 2 .. 3 ]

ISO 3166 Country code (numeric) that indicates the country where the transaction took place.

cardNumber
string

The card number (without separators)

cardHolder
string <= 50 characters

The name of the cardholder

cardExpiryMonth
integer

The expiry month of the card

cardExpiryYear
integer

The expiry year of the card

cardCvv
integer

The card verification value/code. 3 digits, except for Amex (4 digits)

capture
boolean
Default: true

Whether to capture the payment (if applicable)

3ds
boolean
Default: false

Whether to process this payment as a 3D Secure payment

object (CustomerDetails)
redirectUrl
string <uri> <= 1024 characters

For redirect payment methods, this overrides the default success redirect URL configured on your account

notificationUrl
string <uri> <= 1024 characters

For webhook notification (IPN), this overrides the default success notification URL configured on your account

Responses
202

Payment asynchronous or further action required

401

Unauthorized

422

Invalid data was sent

429

Too many requests or duplicate request detected

502

Bad Gateway

post/payments
Request samples
application/json
{
  • "type": "card",
  • "amount": 1,
  • "trackingMemberCode": "ORD-2022-01-01",
  • "currencyId": 978,
  • "countryId": 826,
  • "cardHolder": "Bruce Wayne",
  • "cardNumber": "4242424242424242",
  • "cardExpiryMonth": 9,
  • "cardExpiryYear": 2022,
  • "cardCvv": 123,
  • "capture": true,
  • "3ds": false,
  • "customer_details": {
    },
  • "notificationUrl": "http://mydomain.com/ipn"
}
Response samples
application/json
{
  • "success": true,
  • "code": 0,
  • "locale": "en",
  • "message": "string",
  • "data": {
    }
}

Refund a payment

Refunds a payment if supported by the payment method.

For card payments, refund requests are processed asynchronously. You can use workflows to be notified if the refund is successful.

SecurityApiSecretKey
Request
header Parameters
Fzb-Idempotency-Key
string

An optional idempotency key for safely retrying payment requests

Request Body schema: application/json
transaction_id
integer

Id obtained with a Payment transaction.

transaction_guid
string

Guid obtained with a Payment transaction.

amount
integer >= 0

The amount to refund. If not specified, the full payment amount will be refunded

trackingMemberCode
string <= 50 characters

A reference you can later use to identify this refund request

Responses
202

Refund accepted

401

Unauthorized

403

Refund not allowed

404

Payment not found

422

Invalid data was sent

502

Bad Gateway

post/refund
Request samples
application/json
{
  • "transaction_id": 0,
  • "transaction_guid": "string",
  • "amount": 0,
  • "trackingMemberCode": "string"
}
Response samples
application/json
{
  • "success": true,
  • "code": 0,
  • "locale": "en",
  • "message": "string",
  • "data": {
    }
}

Capture a payment

Captures a payment if supported by the payment method.

For card payments, capture requests are processed asynchronously. You can use workflows to be notified if the capture is successful.

SecurityApiSecretKey
Request
header Parameters
Fzb-Idempotency-Key
string

An optional idempotency key for safely retrying payment requests

Request Body schema: application/json
transaction_id
integer

Id obtained with a Payment transaction.

transaction_guid
string

Guid obtained with a Payment transaction.

amount
integer >= 0

The amount to refund. If not specified, the full payment amount will be captured

trackingMemberCode
string <= 50 characters

A reference you can later use to identify this capture request

Responses
202

Capture accepted

401

Unauthorized

403

Capture not allowed

404

Payment not found

422

Invalid data was sent

502

Bad Gateway

post/capture
Request samples
application/json
{
  • "transaction_id": 0,
  • "transaction_guid": "string",
  • "amount": 0,
  • "trackingMemberCode": "string"
}
Response samples
application/json
{
  • "success": true,
  • "code": 0,
  • "locale": "en",
  • "message": "string",
  • "data": {
    }
}

Void a payment

Voids a payment if supported by the payment method.

For card payments, void requests are processed asynchronously. You can use workflows to be notified if the void is successful.

SecurityApiSecretKey
Request
header Parameters
Fzb-Idempotency-Key
string

An optional idempotency key for safely retrying payment requests

Request Body schema: application/json
transaction_id
integer

Id obtained with a Payment transaction.

transaction_guid
string

Guid obtained with a Payment transaction.

Responses
202

Void accepted

401

Unauthorized

403

Void not allowed

404

Payment not found

422

Invalid data was sent

502

Bad Gateway

post/void
Request samples
application/json
{
  • "transaction_id": 0,
  • "transaction_guid": "string",
  • "trackingMemberCode": "string"
}
Response samples
application/json
{
  • "success": true,
  • "code": 0,
  • "locale": "en",
  • "message": "string",
  • "data": {
    }
}

Get transaction status

Gets a payment final status.

This method returns final status of payment.

SecurityApiSecretKey
Request
header Parameters
Fzb-Idempotency-Key
string

An optional idempotency key for safely retrying payment requests

Request Body schema: application/json
transaction_id
integer

Id obtained with a Payment transaction.

transaction_guid
string

Guid obtained with a Payment transaction.

Responses
202

Void accepted

401

Unauthorized

404

Payment not found

422

Invalid data was sent

502

Bad Gateway

post/transaction
Request samples
application/json
{
  • "transaction_id": 0,
  • "transaction_guid": "string",
  • "trackingMemberCode": "string"
}
Response samples
application/json
{
  • "Result": true,
  • "Status": "Approved",
  • "ResponseCode": 0,
  • "Message": "string",
  • "TrackingMemberCode": "string",
  • "TransactionId": "string",
  • "TransactionGuid": "string",
  • "TransactionDateTime": "2019-08-24T14:15:22Z",
  • "Cdc": {
    }
}

Hosted Payments Page

Create a Hosted Payments Page session

Send a payment or payout.

Note: successful payout requests will always return a 202 response.

When you use Hosted Payment Page, all transaction will be processed with 3D-Secure

SecurityApiSecretKey
Request
header Parameters
Fzb-Idempotency-Key
string

An optional idempotency key for safely retrying payment requests

Request Body schema: application/json
One of:

Hosted Payment Request

type
string
Default: "card"

The payment source type Note: To make a payment with full card details, you must be SAQ D PCI compliant

Value: "card"
amount
integer

The payment amount. Omit the amount or provide a value of 0 to perform a card verification.

trackingMemberCode
string <= 50 characters

A reference you can later use to identify this payment, such as an order number

currencyId
integer [ 1 .. 3 ]

The three-digits ISO-3 numeric currency code

countryId
integer [ 1 .. 3 ]

The three-digits ISO-3 numeric country code

capture
boolean
Default: true

Whether to capture the payment (if applicable)

object (CustomerDetails)
redirectUrl
string <uri> <= 1024 characters

For redirect payment methods, this overrides the default success redirect URL configured on your account

notificationUrl
string <uri> <= 1024 characters

For webhook notification (IPN), this overrides the default success notification URL configured on your account

Responses
202

Payment asynchronous or further action required

401

Unauthorized

422

Invalid data was sent

429

Too many requests or duplicate request detected

502

Bad Gateway

post/hosted-payments
Request samples
application/json
{}
Response samples
application/json
{
  • "success": true,
  • "code": 0,
  • "locale": "en",
  • "message": "string",
  • "data": {
    }
}