Authentication

API setup

To authenticate with any of the Ping Payments APIs, you must include two specific headers in every request. These headers ensure secure and tenant-specific access to your data and services.

Header	Description
`tenant_id`	Your unique account identifier at Ping Payments. This ID is associated with your organization or personal account.
`x-api-secret`	A secret key used to authorize API access. Keep this key confidential and secure. If you suspect that your secret key has been compromised, contact us immediately to request a new secret key.

Verify credentials

To confirm that your integration and authentication are working correctly, make a request to the Ping endpoint.

IP whitelisting

As an additional layer of security, Ping Payments supports IP whitelisting. This allows you to restrict the usage of your x-api-secret to specific server environments under your control. This is communicated and set up during the onboarding process.

Callback verification

The Ping Payments API relies heavily on callbacks (webhooks) to notify your system of important events in real time — such as when a payment is completed or a transaction status changes.

To help ensure the authenticity and integrity of these callbacks, Ping Payments offers an optional callback signature mechanism.

Why Use Callback Signatures?

Enabling signature verification allows your system to:
• Confirm that a callback was genuinely sent by Ping Payments.
• Detect if the payload has been altered in transit.
• Prevent unauthorized or spoofed requests from triggering logic in your system.

How It Works

When callback signature verification is enabled:
1. Each callback sent by Ping Payments includes a signature header.
2. You use your registered signing key to compute a hash of the received payload.
3. You compare your computed hash to the signature provided by Ping.
4. If they match, the callback is verified and safe to process.

Enabling and Verifying Signatures

To enable callback signing and retrieve your signing key, simply generate new signing keys. See SigningKeys for more information.

Note: Signature verification is optional (even when enabled), but is offered for your benefit and highly recommended.