Authentication

Secure requests

Every request carries your credentials and a hash that proves it hasn’t been changed. How you send your credentials depends on which API you’re calling.

Which method does my API use?

Most APIs use HTTP Basic. Only the Business API, on mypaga.com, uses credential headers. Both use the same keys from Get your API keys, both need a request hash, and every API only accepts requests from whitelisted IP addresses.

All APIs except the Business API

HTTP Basic

Combine your public key and secret key into one Authorization header, plus the hash header.

Used by Collect, Direct Debit and every other API not on mypaga.com.

Business API only

Credential headers

Send your public key and secret key as the principal and credentials headers, plus the hash header.

Recognise it by its base URL: mypaga.com.

Example requests

Both examples call Sandbox. Swap in the Live base URL when you go live.

curl -X POST https://beta-collect.paga.com/paymentRequest \
  -H "Content-Type: application/json" \
  -u "YOUR_PUBLIC_KEY:YOUR_SECRET_KEY" \
  -H "hash: YOUR_REQUEST_HASH" \
  -d '{"referenceNumber": "REF-0001", "amount": "5000"}'

curl -X POST https://beta.mypaga.com/paga-webservices/business-rest/secured/accountBalance \
  -H "Content-Type: application/json" \
  -H "principal: YOUR_PUBLIC_KEY" \
  -H "credentials: YOUR_SECRET_KEY" \
  -H "hash: YOUR_REQUEST_HASH" \
  -d '{"referenceNumber": "REF-0001"}'

In the HTTP Basic example, -u sends Authorization: Basic base64(publicKey:secretKey) for you.

Generate the request hash

Every request needs a hash header: a SHA-512 hash of specific request values, in a set order, followed by your hash key. Your hash key itself is never sent.

Find the hash values for the operation

Each API page lists them, and the table below covers the common ones.

Join the values in order, then add your hash key

Use the exact order listed, with no spaces or separators, and put your hash key last.

Hash with SHA-512

Convert the result to a hexadecimal string.

Send it in the hash header

Generate a new hash for every request.

Example: Check status, where the values are referenceNumber + hashKey:

const crypto = require("crypto");

const hashKey = process.env.PAGA_HASH_KEY;
const referenceNumber = "REF-0001";

const hash = crypto
  .createHash("sha512")
  .update(referenceNumber + hashKey)
  .digest("hex");

import hashlib, os

hash_key = os.environ["PAGA_HASH_KEY"]
reference_number = "REF-0001"

hash_value = hashlib.sha512(
    (reference_number + hash_key).encode("utf-8")
).hexdigest()

$hashKey = getenv("PAGA_HASH_KEY");
$referenceNumber = "REF-0001";

$hash = hash("sha512", $referenceNumber . $hashKey);

import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.util.HexFormat;

String hashKey = System.getenv("PAGA_HASH_KEY");
String referenceNumber = "REF-0001";

MessageDigest md = MessageDigest.getInstance("SHA-512");
byte[] digest = md.digest((referenceNumber + hashKey).getBytes(StandardCharsets.UTF_8));
String hash = HexFormat.of().formatHex(digest); // Java 17+

Hash values for common operations

Operation	API	Values, in order
Payment request	Collect	`referenceNumber + amount + currency + payer.phoneNumber + payer.email + hashKey`
Check status	Collect	`referenceNumber + hashKey`
Charge debit mandate	Direct Debit	`referenceNumber + amount + accountReference + hashKey`
Account balance	Business	`referenceNumber + hashKey`
Deposit to bank	Business	`referenceNumber + amount + destinationBankUUID + destinationBankAccountNumber + hashKey`

Every other operation lists its hash values on its own API page.

Base URLs

API	Method	Sandbox	Live
Collect and Direct Debit	HTTP Basic	`beta-collect.paga.com`	`collect.paga.com`
Business API	Credential headers	`beta.mypaga.com`	`www.mypaga.com`

If a request is rejected

Keys and URL don’t match

Sandbox keys only work with Sandbox URLs, and Live keys with Live URLs.

Hash values out of order

Use exactly the values and order listed for that operation, with no separators.

IP address not whitelisted

API calls only work from addresses you’ve added in IP whitelisting.

Account not approved yet

Keys work once your account is approved. See Get started.

Need help? We’re here 24/7

Talk to our support team any time, or ask questions in the developer community.

Email support Join us on Slack