Skip to main content
  • All API calls use an HMAC authentication strategy with pre-shared API and secret keys.
  • Sandbox and production environments have different API credentials. Do not reuse across environments.
  • All requests must use HTTPS (TLS 1.2 or higher).
  • You must allow outbound connections to the Payout Origination API base URLs.
  • IP whitelisting may be required for production access depending on your program configuration. Meridian provides details if applicable.
Every request must include the following headers:
HeaderDescription
X-Meridian-Api-KeyIssued by Meridian
X-Meridian-Program-IdIdentifies your Meridian program
X-Meridian-TimestampCurrent time in milliseconds (must be within 60 seconds of the request)
X-Meridian-SignatureHMAC SHA-256 signature
Meridian issues your API Key and Secret during Sandbox and production provisioning.
When Meridian receives the request, it validates the signature. If the signature does not match, the API immediately returns a 401 Unauthorized response.

​
Constructing the signature

1

Build the canonical string

Compute the signature as an HMAC SHA-256 hash over a canonical string that concatenates the following values in order:
Signature componentNotes
API-KeySame value as X-Meridian-Api-Key
TimestampSame value as X-Meridian-Timestamp
Request methodExample: GET, POST, PATCH
Request pathIncluding any parameters. For example:
/v1/payout-origination/{format}, /v1/transactions, or /v1/transactions/txn_01JVY8Y4N9X2M6S5Q7T1
Body contentsThe exact request body sent on the wire. For Payout Origination POST requests, this is the encoded payload. If there is no body, this can be an empty string.
X-Meridian-Program-Id is required on every request but is not included in the canonical signing string.
2

Compute the HMAC

Compute the HMAC using the language-appropriate crypto library with the secret key.
Make sure you compute the HMAC with the API Secret that Meridian issued to you.
3

Compute the SHA-256 hash

Hash the final value using the SHA-256 algorithm and set it as the X-Meridian-Signature header.
import javax.crypto.Mac
import javax.crypto.spec.SecretKeySpec

fun buildMeridianSignature(apiKey: String, apiSecret: String, programId: String, method: String, path: String, body: String = ""): Map<String, String> {
    val timestamp = System.currentTimeMillis().toString()
    val canonical = apiKey + timestamp + method + path + body
    val mac = Mac.getInstance("HmacSHA256").apply {
        init(SecretKeySpec(apiSecret.toByteArray(), "HmacSHA256"))
    }
    val signature = mac.doFinal(canonical.toByteArray())
        .joinToString("") { "%02x".format(it) }

    return mapOf(
        "X-Meridian-Api-Key" to apiKey,
        "X-Meridian-Program-Id" to programId,
        "X-Meridian-Timestamp" to timestamp,
        "X-Meridian-Signature" to signature,
        "Content-Type" to "text/plain"
    )
}

​
Common errors

Meridian returns 401 Unauthorized for requests with missing or invalid signatures.
The most common causes are:
  • Canonical string fields concatenated in the wrong order.
  • Timestamp too far from the server’s current time.
  • Forgetting to compute the HMAC with your unique Secret Key.
  • Signing a different Base64 string than the one actually sent.
  • Forgetting to SHA-256 hash the final string.
  • Including X-Meridian-Program-Id in the canonical string.