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.

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.

The following is an example of how to verify of the signature of the callback:

# 1. Encode the request body
content = JSON_ENCODE(request_body)

# 2. Read and decode the signature from the header
signature_header = GET_HEADER("signature")
signature = BASE64_DECODE(signature_header)

# 3. Decode your public key (if stored as Base64)
pubkey_b64 = CONFIG["CALLBACK_PUBLIC_KEY"]
public_key = BASE64_DECODE(pubkey_b64)

# 4. Verify with Ed25519 (EdDSA)
is_valid = CRYPTO_VERIFY(
    algorithm  = "EdDSA",
    message    = content,
    signature  = signature,
    public_key = public_key,
    curve      = "ed25519"
)

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.