Skip to main content

Network Token Postbacks

When a network token's status changes (e.g., from requested to active, or active to suspended), a postback is sent to the configured URL.

The postback URL can be configured at two levels:

  1. Merchant level — set via the dashboard or your account manager. Applies to all tokens for the merchant.
  2. Token level — pass postback_url when creating a token via POST /v2/network_tokens. Overrides the merchant-level URL for that specific token.

If no URL is configured at either level, no postback is sent.

caution

The network token postback URL is separate from your transaction postback URL. It must be a stable, persistent endpoint.

network_token_idString
UUID of the network token
merchant_idString
UUID of the merchant
statusString
Token status: requested, active, suspended, failed, archive_pending, archived
networkString
Card network: visa or mastercard
providerString
Token provider identifier
error_codeString
Error code (only present if status is failed)
error_detailString
Error detail message (only present if status is failed)
created_atString
Token creation timestamp (ISO 8601)
updated_atString
Last update timestamp (ISO 8601)
checksumString
SHA1 hex digest of the payload for verification
Example Postback
POST https://example.com/webhooks/network-tokens
Content-Type: application/x-www-form-urlencoded
Gateway-Webhook-Signature: base64-encoded-hmac-sha256-signature

network_token_id=f47ac10b-58cc-4372-a567-0e02b2c3d479
&merchant_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890
&status=active
&network=visa
&provider=vts
&created_at=2026-03-31T10:15:22Z
&updated_at=2026-03-31T14:31:46Z
&checksum=sha1-hex-digest

Signature Verification​

The Gateway-Webhook-Signature header contains a Base64-encoded HMAC-SHA256 signature of the raw request body, signed with your incoming_key. Verify it the same way as transaction postbacks.

Retry Behavior​

Failed postbacks (non-2xx/3xx responses or timeouts) are retried up to 10 times. A 5-second timeout applies per attempt.

Last updated on