Custom Signature Generation Guide for Check 3DS & Charge APIs (MPI Forward Message Merchants)

This guide details how merchants enrolled in CUSTOM_SIGNATURE_VALIDATION generate the Signature header for the Cards Host-to-host API .

Component

Client-Id:value
Request-Id:value
Request-Timestamp:value
Request-Target:value
Digest:value

Component Explanation

Name
Client-id	Retrieved from the Request Header
Request-id	Retrieved from the Request Header
Request-Timestamp	Retrieved from the Request Header
Request-Target	The path of the endpoint that will be hitted e.g: /credit-card/check-three-d-secure. NOTE: For the HTTP Notification from DOKU to merchant server, this will be the path of merchant Notification URL. As for the Inquiry Request, this will be the path of merchant Inquiry URL
Signature	For merchants enrolled in the Custom Signature Validation feature, the Check 3DS and Charge APIs use a custom digest value when generating the request signature. The Digest is calculated as: SHA256Base64("{order.invoice_number}::{order.amount}::{order.currency}::{Request-Id}::{Client-Id}") Notes: order.invoice_number is optional for Check 3DS. If it is not provided, use an empty string. The HMAC key is the merchant's existing Secret Key. The Signature header format remain

• This custom Signature is only used for Card's /check-three-d-secure/ and /charge/ API, for other API such as Capture, Refund, Check Status, etc please refer to the Legacy Signature Documentation

Step-by-step Example

1. Prepare input Parameters

Parameters	Example
Client-Id	MCH-12345
Request-Id	REQ-98765
Request-Timestamp	2026-03-31T10:00:00Z
Request-Target	/credit-card/check-three-d-secure
Secret Key	my-secret-key-123
order.invoice_number	INV-2026-001
order.amount	150000
order.currency	IDR

The order object in the request payload and the request headers must contain identical values.

2. Construct Digest Raw String

Plaintext

INV-2026-001::150000::IDR::REQ-98765::MCH-12345

2. Generate Base64 SHA-256 Digest

• SHA-256 Hash (hex): 4a8fdb75b7b629e41ca50d4f1311025cf2f4cb664bd96c8cae553a0fce508b9e

• Base64 String: So/bdbebKeQcpQ1PExECXPL0y2ZL2WyMrlU6D85Qi54=

Client-Id:MCH-12345
Request-Id:REQ-98765
Request-Timestamp:2026-03-31T10:00:00Z
Request-Target:/credit-card/check-three-d-secure
Digest:So/bdbebKeQcpQ1PExECXPL0y2ZL2WyMrlU6D85Qi54=

4. Compute HMAC-SHA256 & Output Header

• HMAC-SHA256 Binary Hash over the component string using my-secret-key-123.

• Base64 Encoded Result: 6u073A1I/HptjG5L9Xk/vR1mXUjV6oO3S0KxYv3G8Y8=

Resulting request header value:

Signature: HMACSHA256=6u073A1I/HptjG5L9Xk/vR1mXUjV6oO3S0KxYv3G8Y8=

Signature Validation Errors

If validation fails, the API responds with HTTP 400 Bad Request using the standard error schema:

{
  "status": "FAILED",
  "error": {
    "code": "invalid_signature",
    "message": "Signature verification failed",
    "type": "SECURITY_ERROR"
  }
}

Common Error Codes:

• invalid_header_request: Missing required parameters (e.g., Client-Id, Request-Id).

• request_time_out_of_range: Request-Timestamp falls outside the server tolerance window.

• invalid_signature: Signature hash mismatch.