Authentication

Payd uses API keys with HTTP Basic authentication. Each key belongs to one Payd account, and every request you make with it acts on that account.

Create a key

1. Sign in to the Payd Money App.
2. Open Settings, then API keys.
3. Name the key after where you will use it, such as "Online shop", and create it.
4. Copy the username and password straight away. Payd shows the password once.

The app also shows an API secret. It works in place of the password, so keep it as safe as the password.

Send the key with each request

Join the username and password with a colon, encode the result in Base64, and send it in the Authorization header:

Authorization: Basic base64(username:password)

Most HTTP clients do this for you:

cURL

curl https://api.payd.money/api/v2/payments/discovery/KE \
  -u "$PAYD_API_USERNAME:$PAYD_API_PASSWORD"

Node.js

const auth = Buffer.from(
  `${process.env.PAYD_API_USERNAME}:${process.env.PAYD_API_PASSWORD}`,
).toString('base64')

const res = await fetch('https://api.payd.money/api/v2/payments/discovery/KE', {
  headers: { Authorization: `Basic ${auth}` },
})
console.log(await res.json())

Python

import os
import requests

auth = (os.environ["PAYD_API_USERNAME"], os.environ["PAYD_API_PASSWORD"])
res = requests.get("https://api.payd.money/api/v2/payments/discovery/KE", auth=auth, timeout=30)
print(res.json())

PHP

<?php
$ch = curl_init('https://api.payd.money/api/v2/payments/discovery/KE');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_USERPWD => getenv('PAYD_API_USERNAME') . ':' . getenv('PAYD_API_PASSWORD'),
    CURLOPT_TIMEOUT => 30,
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);

Find your account id

Payins, payouts and balance checks name the account they act on. Look up the account your key belongs to once, and keep it in your configuration:

curl https://api.payd.money/api/v2/api_keys/$PAYD_API_USERNAME \
  -u "$PAYD_API_USERNAME:$PAYD_API_PASSWORD"

{
  "api_key": {
    "id": "0b6c5d0e-3c8f-4a59-9a64-0d5f2e7c1a33",
    "account_id": "4f28836c-2f1e-4d9b-9a51-6f3c2b1d8e70",
    "name": "Online shop",
    "username": "your_key_username",
    "user_id": "9e1d2f4a-6b7c-4d8e-9f01-2a3b4c5d6e7f"
  }
}

Field	Meaning
account_id	The Payd account this key acts on. Send it as vendor_config.account_id on payins and payouts, and in the path of the balances endpoint.
user_id	The Payd user who created the key.

The response also has password and api_secret fields. They are always empty here: Payd never sends your credentials back.

When authentication fails

A missing or wrong key gets a 401 before Payd looks at the rest of the request:

{
  "error_code": "user_unauthorized",
  "error_message": "API key validation failed",
  "status_code": 401,
  "request_id": "c38729b625825cd0"
}

error_message is missing API key credentials when the request has no Authorization header, and API key validation failed when the username or password is wrong.

If you send a key that works but name an account it does not belong to, you get 403 with error_code permission_denied. See errors for the full list.

Keep keys safe

• Call the API only from your server. Never put a key in a web page, a mobile app or a public repository.
• Store keys in environment variables or a secrets manager, not in code.
• Use a separate key for each app or site, so you can replace one without touching the others.
• If a key leaks, create a new key, move your app to it, and email support@paydhq.com to switch the old key off.
• Anyone with the key can move money out of the account, so limit who can read it.