Basalt DynamicsAPI Docs
Developer documentation

Accept payments with the Basalt Dynamics API

The Basalt Dynamics API is simple to integrate into your company's software. Our API takes cURL requests, has well-formatted URLs, and produces JSON responses.

01Get credentialsGenerate your API keys
02Create a requestSend payment details
03Handle the resultRead JSON and validate IPN

The API can be used in test mode without affecting your real data. Use the test endpoint while integrating, then switch to the live endpoint when you are ready.

01

Reference

Supported Currencies

The supported currencies by Basalt Dynamics are given below.

CurrencyCurrency Symbol
No supported currencies are currently available.
02

Authentication

Get the API key

To access your Basalt Dynamics merchant account, please log in. In case you don't have an account, you can create one here.

1

Open the merchant panel and go to Account > Settings > API Key.

2

Rotate the environment-specific key. The secret is displayed once and stored encrypted.

3

Register each HTTPS webhook hostname before using it, and sign every initiation request with the matching environment secret.

Keep credentials private

Do not share your API keys with anyone. Generate new keys from the merchant panel whenever needed.

Merchant Login
03

Payments

Initiate Payment

Send the exact JSON bytes you sign. Requests require a five-minute timestamp, a unique nonce, an idempotency key, and an HMAC made with the matching environment secret. Never reuse live credentials for test mode.

POSTEndpoint
https://payments.basaltdynamics.com/test/payment/initiate

Test mode does not affect your real data.

Request parameters

ParameterTypeRequirementDescription
public_keystring (255)RequiredYour Public API key
identifierstring (20)RequiredIdentifier is basically for identify payment at your end
currencystring (20)RequiredCurrency Code, Must be in Upper Case. e.g. USD,EUR
amountdecimalRequiredPayment amount
gateway_methodsarrayOptionalThe gateway methods you want to make available
detailsstring (100)RequiredDetails of your payment or transaction
ipn_urlstring / URLRequiredThe url of instant payment notification
success_urlstring / URLRequiredPayment success redirect url
cancel_urlstring / URLRequiredPayment cancel redirect url
site_namestring (255)RequiredYour business site name
site_logostring / URLOptionalYour business site logo
checkout_themestringOptionalCheckout form theme dark/light. Default theme is light
Customer
customer[]arrayRequiredcustomer must be an array
customer.first_namestringRequiredCustomer's first name
customer.last_namestringRequiredCustomer's last name
customer.emailstringRequiredCustomer's valid email
customer.mobilestringRequiredCustomer's valid mobile
Shipping info
shipping_info[]arrayOptionalshipping_info must be an array
shipping_info.address_onestringOptionalCustomer's address one
shipping_info.address_twostringOptionalCustomer's address two
shipping_info.areastringOptionalShipping area of customer
shipping_info.citystringOptionalShipping city of customer
shipping_info.sub_citystringOptionalShipping sub city of customer
shipping_info.statestringOptionalShipping state
shipping_info.postcodestringOptionalShipping postcode
shipping_info.countrystringOptionalShipping country
shipping_info.othersstringOptionalOthers info
Billing info
billing_info[]arrayOptionalbilling_info must be an array
billing_info.address_onestringOptionalCustomer's address one
billing_info.address_twostringOptionalCustomer's address two
billing_info.areastringOptionalBilling area of customer
billing_info.citystringOptionalBilling city of customer
billing_info.sub_citystringOptionalBilling sub city of customer
billing_info.statestringOptionalBilling state
billing_info.postcodestringOptionalBilling postcode
billing_info.countrystringOptionalBilling country
billing_info.othersstringOptionalOthers info
PHP / cURL request
<?php
$parameters = [
    'identifier' => 'YOUR_IDENTIFIER',
    'currency' => 'USD',
    'amount' => 11.00,
    'gateway_methods' => [],
    'details' => 'Purchase T-shirt',
    'ipn_url' => 'https://example.com/ipn',
    'cancel_url' => 'https://example.com/cancel',
    'success_url' => 'https://example.com/success',
    'public_key' => 'YOUR_PUBLIC_KEY',
    'site_name' => 'Your site name',
    'site_logo' => 'https://example.com/logo.png',
    'checkout_theme' => 'light',
    'customer' => ['first_name' => 'John', 'last_name' => 'Doe', 'email' => 'john@example.com', 'mobile' => '12345789'],
    'shipping_info' => [],
    'billing_info' => [],
];
$url = 'https://payments.basaltdynamics.com/test/payment/initiate';
$secret = 'YOUR_TEST_SECRET_KEY';
$body = json_encode($parameters, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR);
$timestamp = (string) time();
$nonce = bin2hex(random_bytes(16));
$signature = hash_hmac('sha256', $timestamp."\n".$nonce."\n".$body, $secret);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Idempotency-Key: '.bin2hex(random_bytes(16)),
    'X-Basalt-Timestamp: '.$timestamp,
    'X-Basalt-Nonce: '.$nonce,
    'X-Basalt-Signature: v1='.$signature,
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 2);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, false);
curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 5);
curl_setopt($ch, CURLOPT_TIMEOUT, 15);
$result = curl_exec($ch);
curl_close($ch);

Example responses

Error
{
  "status": "error",
  "message": ["Invalid api key"]
}
Success
{
  "status": "success",
  "message": ["Payment initiated"],
  "redirect_url": "https://example.com/payment/checkout?payment_trx=..."
}
04

Payments

Validate the Payment and IPN

Basalt Dynamics sends canonical JSON to your registered HTTPS endpoint. Verify the raw request body before decoding it, reject timestamps older than five minutes, and store every event ID with a unique constraint before fulfilling an order.

POST
End pointYour business application IPN URL

IPN parameters

Header / fieldDescription
X-Basalt-TimestampUnix timestamp included in the signed message.
X-Basalt-Signaturev1=HMAC_SHA256(timestamp + "." + raw_body)
X-Basalt-EventStable event identifier. Store it uniquely to reject replay.
environmentExplicit live or test environment marker.
identifierYour original order identifier.
dataPayment transaction, amount, currency and timestamp.
PHP signature validation
<?php
$rawBody = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_BASALT_TIMESTAMP'] ?? '';
$eventId = $_SERVER['HTTP_X_BASALT_EVENT'] ?? '';
$provided = preg_replace('/^v1=/', '', $_SERVER['HTTP_X_BASALT_SIGNATURE'] ?? '');
$secret = 'YOUR_ENVIRONMENT_SECRET_KEY';

if (!ctype_digit($timestamp) || abs(time() - (int) $timestamp) > 300) {
    http_response_code(401); exit;
}
$expected = hash_hmac('sha256', $timestamp.'.'.$rawBody, $secret);
if (!preg_match('/^[a-f0-9]{64}$/', $provided) || !hash_equals($expected, $provided)) {
    http_response_code(401); exit;
}
$event = json_decode($rawBody, true, 32, JSON_THROW_ON_ERROR);
// In one DB transaction: insert $eventId into a UNIQUE column, verify the
// environment/identifier/amount/currency, then fulfill the order exactly once.
http_response_code(204);
Authenticate before processing

Use the raw body and constant-time comparison. Never fulfill from a browser redirect, and never acknowledge a duplicate event as new work.