API docs by Redocly

Defihub Payment Gateway API (1.1.0)

Download OpenAPI specification:Download

Defihub Payment Gateway API

Changelog

  • 2024-06-17: Added externalUserId and groupId fields in create order request.
  • 2024-05-25: Added payWallet field in webhook payload.
  • 2024-05-20: Added config option when creating order for customization of payment UI and behavior.

HTTP status codes

The table below describes the possible HTTP response codes you can receive when sending an API request.

Code Description
200 OK
400 Invalid request
401 Invalid API key
404 Not found
429 Request limit reached
500 Unexpected error

Webhook Webhook

To ensure the authenticity and integrity of webhooks from Defihub Payment Gateway, verify the signature in your webhook handler:

  • Compute the HMAC SHA256 hash of the payload using your API secret key.
  • Compare the computed signature with the 'x-defihub-signature' header value.
  • Respond to Defihub's webhook requests with a 200 HTTP status code. Other response codes, timeouts, or network errors will cause Defihub to retry the webhook with exponential backoff.

For longer async processing, respond with 200 first, then process the request in the background.

Ensure your webhook handler is idempotent and can handle duplicates. Log the event ID to avoid multiple processing.

See the code examples or the Merchant Backend Demo for more details on handling webhook requests.

Request Body schema: application/json
required
eventId
required
string

Unique identifier for the webhook event, used for idempotency to prevent duplicate processing

type
required
string
Value: "order.paid"

Type of webhook message

required
object

The payload of the webhook message

Request samples

Content type
application/json
{
  • "eventId": "123e4567-e89b-12d3-a456-426614174000",
  • "type": "order.paid",
  • "payload": {
    }
}

Order

Create a new order

header Parameters
merchant-api-key
required
string

Merchant API key

Request Body schema: application/json
required
externalId
required
string

Unique identifier for the order in the merchant's system, used to avoid duplicate orders caused by retried requests

payAmount
required
string [ 0.01 .. 1000000 ]

The amount as a string representation of a big decimal. The maximum precision (number of decimal places) is determined by the currency code. For example, TON allows up to 9 decimal places (10^-9).

currencyCode
required
string
Value: "TON"

The currency code for the order amount

timeout
required
number >= 300

The time-to-live in seconds for the order, specifying the duration within which the order must be paid. Timeout must be greater than 5 minutes.

description
required
string

A brief summary or explanation of the order

groupId
string

An optional identifier for grouping related orders together, useful for batch processing or categorization.

externalUserId
string

An optional identifier for the user in the merchant system, useful for filtering orders by a specific user.

returnUrl
string

The URL to which the user will be redirected upon successful payment of the order. The redirect URL will be appended with necessary query parameters in the following format {returnUrl}?startapp={orderId}_{externalId}... e.g. https://t.me/merchant_defihubdemo_bot/success?startapp=qbnRVuJSstRfsbRxsHQtnN_1795710507605299200. Note that the sequence of these parameters will be preserved, refer to code sample in this section for details on how to parse these parameters.

failReturnUrl
string

The URL to which the user will be redirected if the order completion is unsuccessful. The redirect URL will be appended with necessary query parameters in the following format {failReturnUrl}?startapp={orderId}_{externalId}... e.g. https://t.me/merchant_defihubdemo_bot/error?startapp=qbnRVuJSstRfsbRxsHQtnN_1795710507605299200. Note that the sequence of these parameters will be preserved, refer to code sample in this section for details on how to parse these parameters.

customData
string

An optional custom string that will be included in webhook notifications and can be retrieved when polling the order status

object

Additional configuration settings for customizing the payment UI display and behavior for the user.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "statusCode": 200,
  • "message": "",
  • "data": {
    }
}

Order list

query Parameters
offset
required
number
Example: offset=0

Offset from where to start fetching records

limit
required
number [ 1 .. 200 ]
Example: limit=100

Number of records to fetch

status
string
Enum: "ACTIVE" "EXPIRED" "PAID" "CANCELLED"
Example: status=PAID

Filter by order status. Default is all if not specified

groupId
string
Example: groupId=DAILY_PACKAGE

Filter by group id

externalUserId
string
Example: externalUserId=190222311

Filter by external user id

sort
string
Default: "desc"
Enum: "asc" "desc"
Example: sort=asc

Sort order by created time

header Parameters
merchant-api-key
required
string

Merchant API key

Responses

Response samples

Content type
application/json
{
  • "statusCode": 200,
  • "message": "",
  • "data": [
    ],
  • "meta": {
    }
}

Order info

path Parameters
orderId
required
string
Example: mhvXdrZT4jP5T8vBxuvm75

Order Id

header Parameters
merchant-api-key
required
string

Merchant API key

Responses

Response samples

Content type
application/json
{
  • "statusCode": 200,
  • "message": "",
  • "data": {
    }
}