Build commerce into your app with PING.

1. Quick start for beginners

If you are new to APIs, follow these steps:

1. Become a PING developer and complete the annual access process. The current admin-controlled fee is $50.00 per year.
2. Ask PING admin to enable your developer account after payment confirmation.
3. Generate an API key. Treat it like a password.
4. Call the API from your server, not from browser JavaScript or a mobile app binary.
5. Start with GET /api/v4/actions/definitions to see the actions your account can use.
6. Execute an action with POST /api/v4/actions.

2. Authentication

Every developer request needs an active API key and an active annual developer subscription.

Preferred header:

X-API-Key: sdm_your_secret_key

Bearer authentication is also accepted:

Authorization: Bearer sdm_your_secret_key

Never put an API key in:

• browser JavaScript
• HTML source
• React/Vue/Flutter public builds
• Git repositories
• screenshots or support tickets

For a mobile app, call your own backend, and let your backend call PING.

3. The Action API

The Action API is the easiest way to integrate PING because it uses the same deterministic business action layer used by the conversational engine.

Basic request

curl -X POST https://YOUR_DOMAIN/api/v4/actions \
  -H 'X-API-Key: sdm_your_key' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-2026-00001' \
  -d '{
    "action": "find_anything",
    "args": {
      "query": "phone under 500000"
    }
  }'

Typical response

{
  "success": true,
  "action": "find_anything",
  "data": {
    "items": []
  }
}

Exact response fields depend on the action. Always read the action definition before building a production integration.

Public action catalogue

4. Conversational commerce

You can build a chat experience where your own UI interprets the customer message and then calls PING actions, or you can connect a business channel to PING's conversational engine.

Business AI sales agent

A business can connect PING to its customer channel so the engine can answer product questions, show prices, create orders, collect payment, send invoices, track orders, handle FAQs and escalate to staff.

5. Utilities and bills

Bills are a utility inside PING rather than the identity of the platform. Your application should use SENDAM/PING-level bill actions and never depend on a private provider implementation.

6. Wallet and payments

Financial operations are protected by idempotency, ownership checks, transaction state validation and server-side payment verification.

7. Protected transactions / escrow

Use escrow when the buyer needs payment protection around a marketplace or service transaction. Do not mark an order paid merely because a client says payment succeeded; use the server-verified payment result.

8. Crypto receiving and crypto → NGN

PING keeps received crypto as crypto until the user explicitly asks to convert and withdraw it in NGN.

Example quote

curl -X POST https://YOUR_DOMAIN/api/v4/crypto/quote \
  -H 'X-API-Key: sdm_your_key' \
  -H 'Content-Type: application/json' \
  -d '{"asset":"USDT","amount":100,"currency":"NGN"}'

The quote records the rate, gross NGN, fee, net NGN and expiry. On withdrawal, the crypto amount is locked so it cannot be spent twice. If the withdrawal is rejected, the reserved crypto is released.

9. Errors and how to handle them

10. Security rules

• Keep API keys on your server.
• Use HTTPS only.
• Use a unique idempotency key for every money-moving request.
• Never trust browser payment success messages as proof of payment.
• Never store PING provider secrets in your frontend.
• Do not expose internal provider names, private URLs or credentials to customers.
• Log request IDs and PING references, not secrets.
• Give each integration the smallest set of scopes it needs.

// Browser code — DON'T
fetch('https://YOUR_DOMAIN/api/v4/actions', {
  headers: { 'X-API-Key': 'sdm_REAL_SECRET' }
});

// Browser → your server → PING
// Your server stores the PING API key privately.

11. Building an AI sales agent

The recommended architecture is:

Do not duplicate PING's payment, wallet, escrow or transaction state logic inside your bot. Let PING remain the deterministic action layer while your business owns its customer-facing experience and inventory rules.

12. More code examples

Python

import requests

url = 'https://YOUR_DOMAIN/api/v4/actions'
headers = {
    'X-API-Key': 'sdm_your_key',
    'Content-Type': 'application/json',
    'Idempotency-Key': 'demo-order-001'
}
payload = {
    'action': 'find_anything',
    'args': {'query': 'coffee near me'}
}
response = requests.post(url, headers=headers, json=payload, timeout=30)
print(response.json())

PHP

<?php
$ch = curl_init('https://YOUR_DOMAIN/api/v4/actions');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: sdm_your_key',
        'Content-Type: application/json',
        'Idempotency-Key: demo-order-001',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'action' => 'find_anything',
        'args' => ['query' => 'coffee near me'],
    ]),
]);
$result = curl_exec($ch);
curl_close($ch);
echo $result;

Node.js

const response = await fetch('https://YOUR_DOMAIN/api/v4/actions', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.PING_API_KEY,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'demo-order-001'
  },
  body: JSON.stringify({
    action: 'find_anything',
    args: { query: 'coffee near me' }
  })
});
console.log(await response.json());

13. Developer onboarding

1. Create or identify the PING developer account.
2. Pay the annual developer access fee shown by Admin.
3. Admin enables the account for one year.
4. Receive/generate an API key.
5. Store the key in your backend secret manager or server configuration.
6. Call /api/v4/actions/definitions.
7. Build one non-financial action first.
8. Add financial actions only after you have implemented idempotency and transaction-state handling.

For integration help, start with the definitions endpoint and build from the smallest action needed for your use case.