Card deposits

The flow

 Customer           Your server                Payee Global API          Secure payment page
    |                    |                            |                            |
    | 1. deposit 50 USD  |                            |                            |
    |------------------->| 2. POST /v2/upi/payin      |                            |
    |                    |--------------------------->|                            |
    |                    | 3. "authenticate"          |                            |
    |                    |    + authenticate_url      |                            |
    |                    |<---------------------------|                            |
    | 4. redirect to authenticate_url                 |                            |
    |<-------------------|                            |                            |
    | 5. card details and 3-D Secure                                               |
    |----------------------------------------------------------------------------->|
    | 6. may come back to your response_url (not proof of payment)                 |
    |------------------->|                            |                            |
    |                    | 7. signed webhook          |                            |
    |                    |<---------------------------|                            |
    |                    | 8. POST /v2/upi/status, any time                        |
    |                    |--------------------------->|                            |

Onboarding

Credentials are issued after onboarding: we review your business, agree the terms in writing and set up your account. When your account is ready you receive a sign-in for the merchant console at https://app2.payeeglobal.com.

Where things are in the console

Keys

The console asks for your password before it shows a key. It also lists a test key; the calls on this page do not use it.

Keep every key on your servers: never in a web page, a mobile app, a support ticket or a chat message.

Rotating keys

You can rotate each key in the console. The old API key and the old encryption key keep working for an overlap window, 24 hours by default, and the console shows until when, so you can switch your servers over. If a key may have leaked, tick Stop the old key now when you rotate: the old key then stops at once.

Rotating the encryption key changes your webhook signing key straight away, with no overlap. Deploy the new signing key to your webhook server as soon as you rotate.

IP allow-list

Send us the public IP addresses of the servers that will call the API. With the allow-list on, a call to create a deposit, check a deposit or create a pay-out from any other address is refused with HTTP 401:

{"status": "unauthorized", "message": "IP address (203.0.113.10) not whitelisted."}

You manage the addresses in the console under IP whitelist.

Domains

Every domain that sends customers to a deposit must be approved before it takes traffic. Send your account manager the list: your checkout domain, each mirror, and the hosts of your response_url and webhook_url. Send new ones ahead of time. We confirm each approval in writing; do not send deposits from a domain we have not confirmed.

Check your key

The balance call needs only your API key, so it is the quickest check of your set-up.

curl -sS -X POST 'https://api2.payeeglobal.com/v2/transaction/balance' \
  -H "Authorization: Bearer $PG_API_KEY" \
  -H 'Content-Type: application/json'

// Node 18 or later, as an ES module (.mjs). No dependencies.
const API_BASE = 'https://api2.payeeglobal.com';

const res = await fetch(`${API_BASE}/v2/transaction/balance`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.PG_API_KEY}`, 'Content-Type': 'application/json' },
});
console.log(res.status, await res.text());

<?php
// PHP 7.4 or later with the curl extension.
const PG_API_BASE = 'https://api2.payeeglobal.com';

$ch = curl_init(PG_API_BASE . '/v2/transaction/balance');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => '',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('PG_API_KEY'), 'Content-Type: application/json'],
]);
$body = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_RESPONSE_CODE), ' ', $body, PHP_EOL;

The samples read your keys from environment variables: PG_API_KEY, PG_ENCRYPTION_KEY and, on your webhook server, PG_WEBHOOK_SIGNING_KEY. A working key answers "status": "success" with your balances; a wrong one answers HTTP 401 with "status": "unauthorized".

Create a card deposit

POST https://api2.payeeglobal.com/v2/upi/payin, with the fields below encrypted as described in the authentication guide.

Leave out membership_duration, upi and pg_id: they do not apply to card deposits. Fields not listed here are ignored, including order_id and customer_user_id: the reference field is merchant_order_id.

Each program below encrypts the deposit, sends it with an Idempotency-Key, and prints the HTTP status and the answer.

// Node 18 or later, as an ES module (.mjs). No dependencies.
import crypto from 'node:crypto';

const API_BASE = 'https://api2.payeeglobal.com';
const IV = Buffer.from('1878eadd223d030ad338a354c29203c3', 'hex'); // fixed 16-byte IV

function encrypt(plainJson, encryptionKeyBase64) {
  const key = Buffer.from(encryptionKeyBase64, 'base64');
  if (key.length !== 32) throw new Error('The encryption key must decode to 32 bytes');
  const cipher = crypto.createCipheriv('aes-256-cbc', key, IV); // PKCS#7 padding is the default
  return Buffer.concat([cipher.update(plainJson, 'utf8'), cipher.final()]).toString('base64');
}

const deposit = {
  payment_method: 'card',
  currency: 'USD',
  amount: '50.00',
  merchant_order_id: 'ORDER-10045',
  first_name: 'Alex',
  last_name: 'Morgan',
  email: 'alex.morgan@example.com',
  country: 'CA',
  response_url: 'https://shop.example.com/checkout/return',
  webhook_url: 'https://shop.example.com/webhooks/payee-global',
};

const res = await fetch(`${API_BASE}/v2/upi/payin`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.PG_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': deposit.merchant_order_id, // reuse it when you retry this deposit
  },
  body: JSON.stringify({ encrypted_data: encrypt(JSON.stringify(deposit), process.env.PG_ENCRYPTION_KEY) }),
  signal: AbortSignal.timeout(60000),
});
const text = await res.text(); // a 429 or 5xx page from the edge is not JSON
console.log(res.status, text);
// HTTP 200 with "status": "authenticate": store transaction_id, then redirect the customer to authenticate_url.

<?php
// PHP 7.4 or later with the openssl and curl extensions.
const PG_API_BASE = 'https://api2.payeeglobal.com';
const PG_IV_HEX = '1878eadd223d030ad338a354c29203c3'; // fixed 16-byte IV

function pg_encrypt(string $plainJson, string $encryptionKeyBase64): string
{
    $key = base64_decode($encryptionKeyBase64, true);
    if ($key === false || strlen($key) !== 32) {
        throw new RuntimeException('The encryption key must decode to 32 bytes');
    }
    $ciphertext = openssl_encrypt($plainJson, 'aes-256-cbc', $key, OPENSSL_RAW_DATA, hex2bin(PG_IV_HEX)); // PKCS#7
    if ($ciphertext === false) {
        throw new RuntimeException('Encryption failed');
    }
    return base64_encode($ciphertext);
}

$deposit = [
    'payment_method' => 'card',
    'currency' => 'USD',
    'amount' => '50.00',
    'merchant_order_id' => 'ORDER-10045',
    'first_name' => 'Alex',
    'last_name' => 'Morgan',
    'email' => 'alex.morgan@example.com',
    'country' => 'CA',
    'response_url' => 'https://shop.example.com/checkout/return',
    'webhook_url' => 'https://shop.example.com/webhooks/payee-global',
];

$body = json_encode([
    'encrypted_data' => pg_encrypt(json_encode($deposit, JSON_UNESCAPED_SLASHES), (string) getenv('PG_ENCRYPTION_KEY')),
]);
$ch = curl_init(PG_API_BASE . '/v2/upi/payin');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $body,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 60,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('PG_API_KEY'),
        'Content-Type: application/json',
        'Idempotency-Key: ' . $deposit['merchant_order_id'], // reuse it when you retry this deposit
    ],
]);
$answer = curl_exec($ch); // a 429 or 5xx page from the edge is not JSON
echo curl_getinfo($ch, CURLINFO_RESPONSE_CODE), ' ', $answer, PHP_EOL;
// HTTP 200 with "status": "authenticate": store transaction_id, then redirect the customer to authenticate_url.

The answer

A normal answer is HTTP 200 with "status": "authenticate":

{
  "status": "authenticate",
  "authenticate_url": "https://api2.payeeglobal.com/app2/checkout/<token>",
  "merchant_order_id": "ORDER-10045",
  "transaction_id": "TK3V9QX2M1791021600123",
  "amount": "50.00",
  "message": "Enter card details.",
  "currency": "USD",
  "payment_method": "card"
}

Outcomes of the create call

Expect authenticate: a card deposit is paid on the secure page, after the create call. If you see a status not listed here, treat the deposit as not paid and check it with the status call.

Send the customer to pay

Redirect the customer to authenticate_url with a full-page redirect: an HTTP 302 from your server, or window.location in the browser. Use the URL exactly as we return it: do not change, rebuild or shorten it, and do not load it in an iframe. It belongs to one deposit.

Card details and 3-D Secure

On the card provider's secure payment page the customer enters the card number, expiry date and security code, and completes 3-D Secure when their bank asks for it: a one-time code, or an approval in the banking app. A bank may also approve without a challenge. There is nothing to send or receive on your side for 3-D Secure.

Your systems never receive card details. You send us the amount, the customer's name and email and your reference; the card is entered only on the card provider's secure payment page. Card data stays out of your pages, your servers and your logs, and out of ours.

The result

The result does not depend on what the customer does next. It reaches you as a signed webhook when the deposit is final. The status call shows the deposit as we have recorded it: a card deposit becomes final there once the card provider has confirmed the outcome to us, which normally happens within minutes of the customer finishing on the payment page. A deposit the customer leaves unfinished stays authenticate until it ends. Reconcile deposits still authenticate 45 minutes after you created them with the status call, and tell us about any you believe were paid: we check them with the card provider.

Return to your site

When the payment ends, the customer can come back to your response_url. The return can carry query parameters such as status, message, order_id and transaction_id, appended with & when your URL already has a query string.

• They are not signed, and they can be missing. Anyone can type them. Use them only to choose what to show, never to credit a deposit.
• The customer may come back before the webhook arrives, or not come back at all. Show "We are confirming your payment" until your server has a verified webhook or a status answer, then show the result.

Check a deposit

POST https://api2.payeeglobal.com/v2/upi/status with a plain JSON body: your merchant_order_id, or our transaction_id. The status call has the code in cURL, Node and PHP.

{
  "status": "success",
  "merchant_order_id": "ORDER-10045",
  "transaction_id": "TK3V9QX2M1791021600123",
  "amount": "50.00",
  "message": "Transaction processed successfully.",
  "upi": null,
  "utr": null,
  "currency": "USD",
  "payment_method": "card"
}

Deposit statuses

Refunds

Refunds are made by us, on your request, for the full amount of a successful deposit only: a deposit cannot be partly refunded. Write to support@payeeglobal.com or your account manager with the transaction_id, your merchant_order_id and the reason.

Once the refund is recorded, the status call shows "refund_status": true and refund_date for the deposit, and the refunded amount comes out of your available balance. Your webhook endpoint may also receive a signed notice with "event": "refund". How long the refund takes to reach the customer's card depends on the customer's bank. Refund fees are as set out in your agreement.

Chargebacks

A chargeback happens when the customer disputes a deposit with their bank. We contact you about each one and tell you which documents to send, and by when. The deposit is listed in the console under Payin, then Chargebacks; the status call shows "chargebacks_status": true and chargeback_date; and your webhook endpoint may receive a signed notice with "event": "chargeback". Chargeback fees and thresholds are as set out in your agreement.

Currencies and limits

Cards work in the currencies switched on for your account, each with your own minimum and maximum per deposit. The console shows them under Payments, then Payment methods. Send the amount in the deposit's own currency, as a string with two decimals: "1700.00", not 1700 or "1,700.00".

Field errors

Each comes with "status": "validation_error", and nothing is created:

The errors guide has the HTTP codes, strict mode and the authentication answers.

Bearer key

Every call carries your API key:

Authorization: Bearer <API key>

Which bodies are encrypted

How to encrypt

1. Build the request fields as a JSON object and serialise it as UTF-8 text.
2. Encrypt that text with AES-256-CBC and PKCS#7 padding. The key is your encryption key, base64-decoded to 32 bytes. The IV is the fixed hex value 1878eadd223d030ad338a354c29203c3, 16 bytes, unless your account manager gave you another one.
3. Base64-encode the ciphertext, standard alphabet with padding.
4. Send {"encrypted_data": "<base64 ciphertext>"} as the body, with Content-Type: application/json.

If we cannot decrypt the body the answer is {"status": "validation_error", "message": "Invalid data encryption."}; a body without encrypted_data is answered Encrypted data must be a non-empty string. During the overlap after you rotate the encryption key, bodies encrypted with the old key are still accepted.

// Node 18 or later. No dependencies.
import crypto from 'node:crypto';

const IV = Buffer.from('1878eadd223d030ad338a354c29203c3', 'hex'); // fixed 16-byte IV

export function encrypt(plainJson, encryptionKeyBase64) {
  const key = Buffer.from(encryptionKeyBase64, 'base64');
  if (key.length !== 32) throw new Error('The encryption key must decode to 32 bytes');
  const cipher = crypto.createCipheriv('aes-256-cbc', key, IV); // PKCS#7 padding is the default
  return Buffer.concat([cipher.update(plainJson, 'utf8'), cipher.final()]).toString('base64');
}

// body = JSON.stringify({ encrypted_data: encrypt(JSON.stringify(fields), process.env.PG_ENCRYPTION_KEY) })

<?php
// PHP 7.4 or later with the openssl extension.
const PG_IV_HEX = '1878eadd223d030ad338a354c29203c3'; // fixed 16-byte IV

function pg_encrypt(string $plainJson, string $encryptionKeyBase64): string
{
    $key = base64_decode($encryptionKeyBase64, true);
    if ($key === false || strlen($key) !== 32) {
        throw new RuntimeException('The encryption key must decode to 32 bytes');
    }
    $ciphertext = openssl_encrypt($plainJson, 'aes-256-cbc', $key, OPENSSL_RAW_DATA, hex2bin(PG_IV_HEX)); // PKCS#7
    if ($ciphertext === false) {
        throw new RuntimeException('Encryption failed');
    }
    return base64_encode($ciphertext);
}

// $body = json_encode(['encrypted_data' => pg_encrypt(json_encode($fields, JSON_UNESCAPED_SLASHES), getenv('PG_ENCRYPTION_KEY'))]);

Check your code with this test vector

The key below is a published example made of the bytes 0 to 31. Never use it for real traffic.

Your code must produce exactly this encrypted_data from exactly this JSON text, byte for byte. Field order and spacing change the ciphertext, not the meaning: we accept any valid JSON.

When we send one

We POST a signed JSON message to the webhook_url of the payment when it reaches one of these statuses:

No webhook is sent while a payment waits for the customer (authenticate) or is being confirmed (pending), and none for a deposit that ends as canceled or expired: the status call shows those. An on_hold payment is later followed by success or failed.

Your endpoint may also receive notices, which carry an event field: the console's test event ("event": "test"), and a notice when a refund or a chargeback is recorded on one of your deposits ("event": "refund" or "event": "chargeback"). Notices move no money; answer them with HTTP 200 and check the deposit with the status call.

The card deposit payload is under Webhook.

The request

POST /webhooks/payee-global HTTP/1.1
Host: shop.example.com
Content-Type: application/json
X-Webhook-Timestamp: 1791021645
X-Webhook-Signature: v1=<64 hex characters>

{"status":"success","merchant_order_id":"ORDER-10045","transaction_id":"TK3V9QX2M1791021600123","amount":"50.00",...}

Verify the signature

1. Read the raw request body before any JSON parsing. Re-serialised JSON will not match.
2. Reject the delivery if X-Webhook-Timestamp is more than 300 seconds away from your clock.
3. Compute HMAC-SHA256 with the signing key over the timestamp, a dot and the raw body, as lowercase hex.
4. Compare it, in constant time, with each v1= value in X-Webhook-Signature. Accept if any one matches.
5. Only then parse the JSON and act on it. Answer HTTP 401 when the signature fails.

Your signing key is under Developers, then Webhooks: choose Reveal next to Webhook signing key. It is 64 hex characters, and it is derived from your encryption key, so you can also compute it once yourself:

signing_key = HMAC-SHA256(key     = <encryption key, the base64 text as UTF-8 bytes>,
                          message = "payee-global/merchant-webhook-signing/v1")   as hex

The label payee-global/merchant-webhook-signing/v1 is a fixed protocol constant; use it exactly as written.

A receiver

Each receiver verifies the signature on the raw body, answers 401 when it fails, and answers 200 once the message is stored. Replace the log line with your own handling: apply each (transaction_id, status) once.

// Node 18 or later, as an ES module (.mjs). No dependencies.
import crypto from 'node:crypto';
import http from 'node:http';

const SIGNING_KEY = Buffer.from(process.env.PG_WEBHOOK_SIGNING_KEY || '', 'hex'); // Developers > Webhooks > Reveal

export function verifyWebhook(rawBody, timestamp, signatureHeader, toleranceSeconds = 300) {
  if (!/^\d+$/.test(String(timestamp || ''))) return false;
  if (Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp)) > toleranceSeconds) return false;
  const expected = Buffer.from(crypto.createHmac('sha256', SIGNING_KEY).update(`${timestamp}.`).update(rawBody).digest('hex'));
  return String(signatureHeader || '').split(',').map((part) => part.trim())
    .filter((part) => part.startsWith('v1='))
    .some((part) => {
      const given = Buffer.from(part.slice(3));
      return given.length === expected.length && crypto.timingSafeEqual(given, expected);
    });
}

http.createServer((req, res) => {
  const chunks = [];
  req.on('data', (chunk) => chunks.push(chunk));
  req.on('end', () => {
    const raw = Buffer.concat(chunks); // the exact bytes we signed: verify before parsing
    if (!verifyWebhook(raw, req.headers['x-webhook-timestamp'], req.headers['x-webhook-signature'])) {
      res.writeHead(401).end();
      return;
    }
    const message = JSON.parse(raw.toString('utf8'));
    if (message.event) {
      // A notice (test, refund, chargeback): no money moved by this message.
      console.log('notice', message.event);
    } else {
      // A payment result. Your code: apply each (transaction_id, status) once.
      console.log('result', message.transaction_id, message.status, message.amount);
    }
    res.writeHead(200).end();
  });
}).listen(Number(process.env.PORT || 8080));

<?php
// PHP 7.4 or later. Serve it at your webhook_url.
function pg_verify_webhook(string $rawBody, string $timestamp, string $signatureHeader, string $signingKeyHex, int $tolerance = 300): bool
{
    if (!ctype_digit($timestamp) || abs(time() - (int) $timestamp) > $tolerance) {
        return false;
    }
    $expected = hash_hmac('sha256', $timestamp . '.' . $rawBody, (string) hex2bin($signingKeyHex));
    foreach (explode(',', $signatureHeader) as $part) {
        $part = trim($part);
        if (strpos($part, 'v1=') === 0 && hash_equals($expected, substr($part, 3))) {
            return true;
        }
    }
    return false;
}

$raw = file_get_contents('php://input'); // the exact bytes we signed: verify before parsing
$ok = pg_verify_webhook(
    $raw,
    $_SERVER['HTTP_X_WEBHOOK_TIMESTAMP'] ?? '',
    $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '',
    (string) getenv('PG_WEBHOOK_SIGNING_KEY') // Developers > Webhooks > Reveal
);
if (!$ok) {
    http_response_code(401);
    exit;
}
$message = json_decode($raw, true);
if (isset($message['event'])) {
    // A notice (test, refund, chargeback): no money moved by this message.
    error_log('notice ' . $message['event']);
} else {
    // A payment result. Your code: apply each (transaction_id, status) once.
    error_log('result ' . $message['transaction_id'] . ' ' . $message['status'] . ' ' . $message['amount']);
}
http_response_code(200);

Signature test vector

Using the example encryption key from the test vector above:

The timestamp check in step 2 rejects this old timestamp; test the HMAC step on its own.

Answer with HTTP 200

• Only HTTP 200 counts as delivered. Any other answer, 201 and 204 included, a redirect, or no answer before we time out, is a failed delivery. Answer within 30 seconds.
• Answer as soon as the message is verified and stored. Do slow work, such as crediting a wallet or sending email, after you answer or in a queue.
• Answer 200 to a message you have already processed. Answer 401 only when the signature fails.

Retries

When a payment result is not answered with HTTP 200 we send it again, about once a minute, up to three more times. For a deposit the first retry comes no sooner than 5 minutes after the deposit was created; for a pay-out, no sooner than 15 minutes. Then we stop. Notices are sent once.

To recover anything you missed, use the status call. You can also resend a payment's webhook from the console: open the payment under Payin or Payout and choose Send Webhook.

Duplicates and order

The same result can reach you more than once: after a retry, after a resend from the console, or after a timeout on your side. Record each (transaction_id, status) once and answer 200 to repeats without acting again. Do not assume an order between the webhook and the customer's return to your site.

Trust the signature, not the sending IP address. If your firewall must allow-list our sending address, ask your account manager for it.

The console test event

Developers, then Webhooks, then Send test event posts a signed test message to the webhook address saved in the console.

Fields in the answer

Ignore fields you do not know: we may add fields.

Safe retries with Idempotency-Key

Send an Idempotency-Key header on every create-deposit call, and reuse it when you retry the same deposit after a timeout or a network error. Use 1 to 200 printable ASCII characters, unique per deposit; your merchant_order_id is a good choice.

The key compares the decrypted deposit, so re-encrypting the same fields for a retry is fine.

References are single-use

Independently of the key, a merchant_order_id can be used once per account: a repeat is refused with Duplicate order_id, field must be unique. A new attempt after a failed deposit therefore needs a new merchant_order_id. Pay-outs work the same way with order_id, which is their guard against paying twice.

After a timeout

A timeout does not tell you whether the request ran. Retry a deposit with the same Idempotency-Key: you get the original answer if the first call completed, and nothing is created twice. For a pay-out, check it by order_id with the pay-out status call before anything else, and never resend it with a new order_id.

HTTP status codes

Strict mode

Send X-Api-Status-Codes: strict (or X-Api-Version: 2) to get real HTTP codes on error answers: 400 for a validation_error, 404 for not found, 500 for a fault on our side. The body is the same in both modes, so code that branches on status keeps working.

Status words

authenticate, pending, to_be_confirm, success, failed, blocked, on_hold, canceled, expired, settled.

A code the API has no name for is shown as UNKNOWN. Deposit statuses says which are final.

Testing with small real amounts

There is no separate test environment. You test on the production API, on your own account, with real cards and small real amounts within your limits. Agree the test window with your account manager first: we watch the first deposits with you. Test deposits are real payments; ask us to refund them.

Launch checklist

• The API key and encryption key are on your servers only; nothing in the browser or apps.
• Your encryption reproduces the test vector.
• Your server addresses are on the IP allow-list, and every domain that sends customers to deposits is approved in writing.
• merchant_order_id is unique per deposit, and every create call sends an Idempotency-Key.
• The customer is sent to authenticate_url unchanged, full page, never in an iframe.
• Your webhook endpoint is on HTTPS, verifies the signature on the raw body, answers 200 quickly and is idempotent.
• Deposits are credited only on a verified webhook or a status answer of success, never on the return to response_url.
• A reconciliation job checks deposits still authenticate after 45 minutes.
• Your code handles HTTP 429, timeouts and Idempotent-Replayed.
• transaction_id is stored with every order and appears in your logs.
• Your team knows how to request refunds and where chargeback notices arrive.
• Tests 1 to 13 passed, and the first real deposits are watched together with us.

Support

Write to support@payeeglobal.com. About a deposit, include the transaction_id and your merchant_order_id, the amount, the currency and the time in UTC, and the answer you received. Never send keys, encrypted bodies or card numbers to support.