Authentication
All platform requests are identified by an API Key sent in Authorization header of every request. Keys can be managed under Settings > Developer > API Keys.
$ curl \
--url https://api.synaptopay.com/v1/example \
--header 'Authorization: Api-Key sk_live_JEKJKiXQX43bI1OETEGeuS'
# ^ Note: API-Key header.Webhooks
Webhooks for relevant events can be enabled under Settings > Developer > Webhook Endpoints.
Signatures
Requests are sent with a Synapto-Signature header which can be validated using HMAC-SHA256 using the signing secret of the endpoint to guarantee message authenticity.
// Example request.
var SIGNING_SECRET = "whsec_lFlsnLxC3X4yW7dByaMMkGasgatGyI";
var HEADERS = Map.of("Synapto-Signature", "t=1759581623,v1=f0c3e10b74a338ef0fa494da0613853a7ca6062be6c885f797256df31125737b");
var REQUEST_BODY = "example-webhook-body";
// Decode signature header.
var header = HEADERS.get("Synapto-Signature");
var decoded = new HashMap<String, String>();
for (var pair : header.split(",")) {
var key = pair.split("=")[0];
var value = pair.split("=")[1];
decoded.put(key, value);
}
// Calculate correct signature. Requests are encoded using UTF8.
var signaturePayload = decoded.get("t") + "." + REQUEST_BODY;
var expectedSignature = Hashing
.hmacSha256(SIGNING_SECRET.getBytes(UTF_8))
.hashBytes(signaturePayload.getBytes(UTF_8))
.toString(); // Returns hex-encoded digest.
// Assert signature is valid.
if (!expectedSignature.equals(decoded.get("v1"))) {
System.out.println("❌ Invalid signature.");
} else {
System.out.println("✅ Valid signature.");
}The Java example uses Guava for hashing, the valid signature in the example can be used to verify your implementation.
Retries
Acknowledge webhook requests with a 200 status within 10 seconds. Unacknowledged deliveries are automatically retried over 3 days using exponential backoff and jitter.
Support
If you need any help, reach out to [email protected], mention you are an engineer and someone technical will get back to you.
Before go-live, escalation paths (e-mail, phone, etc.) are shared.