GET Order Details

For Credify to create a payment flow for your orders, we will need basic info about the order, this guide will provide the details on how to get this API setup from your side.

caution

This is only required for custom e-commerce stores, if you are using WooCommerce or Shopify follow the instructions in merchant dashboard.

API Specifications

Endpoint:

GET <Your order details API URL>?orderID={orderID}&timestamp={timestamp}&hmac={hashString}

Parameter	Description
Base URL	You can pick any base URL on your website and inform Credify with the URL during the setup process
orderID	A unique order identifier that was initially sent by iframe/your website
timestamp	A timestamp that was taken upon receiving the request. Can be used by your side for better security controls
hashString	HMAC hash of the URL without hmac parameter ('<Your order details API URL>?orderID={orderID}&timestamp={timestamp}' for example: 'https://my-store.com/api/order?orderID=12333&timestamp=1732742969'), this hash can be used to validate the authenticity of the request.

Expected Response

{
    "lineItems": ["2 X Large White T-Shirt", "Black Hat"],
    "shippingAddress": "Giza \nEgypt",
    "total": 500.5,
    "customer": {
        "name": "John Doe",
        "phone": "+201009993343"
    },
    "orderSerial": "#11"
}

Field	Description
lineItems	An array of items included in the order, with quantity and description.
shippingAddress	The address where the order will be shipped.
total	The total cost of the order.
customer	An object containing customer name and phone number.
orderSerial	A unique serial number for the order.

Validating the HMAC

To ensure the integrity and authenticity of the URL with HMAC, you can validate the HMAC provided with the URL. Here is a step-by-step guide on how to validate the HMAC:

1. Extract Parameters: Extract the orderID, timestamp, and hmac from the URL.
2. Recreate the URL with Parameters: Recreate the URL using the extracted orderID and timestamp.
3. Generate HMAC: Use the same HMAC secret to generate a hash from the recreated URL.
4. Compare HMACs: Compare the generated HMAC with the provided hmac. If they match, the URL is valid.

Node JS

const crypto = require('crypto')

function validateHMAC(baseURL, HMACSecret, orderID, timestamp, providedHMAC) {
    const urlWithParams = `${baseURL}?orderID=${orderID}&timestamp=${timestamp}`
    const hmac = crypto.createHmac('sha256', HMACSecret)
    const hash = hmac.update(urlWithParams).digest('hex')
    return hash === providedHMAC
}

// Example usage
const baseURL = 'https://example.com/api/order'
const HMACSecret = 'your_hmac_secret'
const orderID = '12345'
const timestamp = '1617181723'
const providedHMAC = 'your_provided_hmac_string_here'

const isValid = validateHMAC(
    baseURL,
    HMACSecret,
    orderID,
    timestamp,
    providedHMAC,
)
console.log(`Is the URL valid? ${isValid}`)

C# DotNetCore

using System;
using System.Security.Cryptography;
using System.Text;

public class HMACValidator
{
    public static bool ValidateHMAC(string baseURL, string HMACSecret, string orderID, string timestamp, string providedHMAC)
    {
        string urlWithParams = $"{baseURL}?orderID={orderID}&timestamp={timestamp}";
        using (var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(HMACSecret)))
        {
            var hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(urlWithParams));
            var hashString = BitConverter.ToString(hash).Replace("-", "").ToLower();
            return hashString == providedHMAC;
        }
    }
}

// Example usage
string baseURL = "https://example.com/api/order";
string HMACSecret = "your_hmac_secret";
string orderID = "12345";
string timestamp = "1617181723";
string providedHMAC = "your_provided_hmac_string_here";

bool isValid = HMACValidator.ValidateHMAC(baseURL, HMACSecret, orderID, timestamp, providedHMAC);
Console.WriteLine($"Is the URL valid? {isValid}");

Java

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;

public class HMACValidator {

    public static boolean validateHMAC(String baseURL, String HMACSecret, String orderID, String timestamp, String providedHMAC) throws Exception {
        String urlWithParams = baseURL + "?orderID=" + orderID + "&timestamp=" + timestamp;
        Mac hmac = Mac.getInstance("HmacSHA256");
        SecretKeySpec secretKeySpec = new SecretKeySpec(HMACSecret.getBytes(StandardCharsets.UTF_8), "HmacSHA256");
        hmac.init(secretKeySpec);
        byte[] hash = hmac.doFinal(urlWithParams.getBytes(StandardCharsets.UTF_8));
        StringBuilder hashString = new StringBuilder();
        for (byte b : hash) {
            hashString.append(String.format("%02x", b));
        }
        return hashString.toString().equals(providedHMAC);
    }

    public static void main(String[] args) throws Exception {
        String baseURL = "https://example.com/api/order";
        String HMACSecret = "your_hmac_secret";
        String orderID = "12345";
        String timestamp = "1617181723";
        String providedHMAC = "your_provided_hmac_string_here";

        boolean isValid = validateHMAC(baseURL, HMACSecret, orderID, timestamp, providedHMAC);
        System.out.println("Is the URL valid? " + isValid);
    }
}

PHP

function validateHMAC($baseURL, $HMACSecret, $orderID, $timestamp, $providedHMAC) {
    $urlWithParams = "{$baseURL}?orderID={$orderID}&timestamp={$timestamp}";
    $hash = hash_hmac('sha256', $urlWithParams, $HMACSecret);
    return $hash === $providedHMAC;
}

// Example usage
$baseURL = 'https://example.com/api/order';
$HMACSecret = 'your_hmac_secret';
$orderID = '12345';
$timestamp = '1617181723';
$providedHMAC = 'your_provided_hmac_string_here';

$isValid = validateHMAC($baseURL, $HMACSecret, $orderID, $timestamp, $providedHMAC);
echo "Is the URL valid? " . ($isValid ? 'true' : 'false');