Overview · Authentication & Requests · Test & Live Mode · Start a Payment · Payment Result · Confirm a Payment · Create an Escrow · Escrow Checkout · Create an Invoice · Errors · Security · Currencies

The DroppCash API lets your website or app accept payments, create escrows and send invoices. Everything below is a plain HTTPS request, so you can use any language.

How a payment works

1. Your server calls POST /payment/process with the amount, currency and your own order reference. You get back a url.
2. You send the buyer to that url. The buyer signs in with their DroppCash account and confirms the payment.
3. DroppCash sends the result to your web_hook and redirects the buyer to your success_url.
4. Your server calls GET /payment/check-validity to confirm the payment is real, then delivers the goods.

1. Get your API access key. Sign up or log in, then open the API key page in your user dashboard. Use the key only on your server and never put it in a web page or mobile app.

2. Send it as a Bearer token in the Authorization header of every request:

CopyAuthorization: Bearer YOUR_ACCESS_KEY
Accept: application/json
Content-Type: application/json

3. Send your data as JSON (recommended) or as normal form fields. Both work.

In your user dashboard you can set the API service mode to test or active (live).

• Test mode: no money moves and no wallet balance is needed. The checkout, webhook and redirect all work exactly as in live mode, so you can test your whole integration.
• Active (live) mode: the buyer's wallet is charged and your wallet is credited.

In both modes the buyer signs in with a DroppCash account during checkout, so create a second test account to play the buyer. In live mode that account also needs a wallet in the payment currency with enough balance.

POST https://droppcash.app/payment/process

The access key is not a body parameter. Send it in the Authorization: Bearer header.

cURL

Copycurl -X POST https://droppcash.app/payment/process \
  -H "Authorization: Bearer YOUR_ACCESS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "custom": "ORDER-1001",
  "currency_code": "USD",
  "amount": 280.00,
  "details": "Digital Product",
  "web_hook": "https://yoursite.com/web_hook.php",
  "success_url": "https://yoursite.com/success",
  "cancel_url": "https://yoursite.com/cancel",
  "customer_email": "customer@mail.com"
}'

PHP

Copy<?php
$parameters = [
    'custom'         => 'ORDER-1001',
    'currency_code'  => 'USD',
    'amount'         => 280.00,
    'details'        => 'Digital Product',
    'web_hook'       => 'https://yoursite.com/web_hook.php',
    'success_url'    => 'https://yoursite.com/success',
    'cancel_url'     => 'https://yoursite.com/cancel',
    'customer_email' => 'customer@mail.com',
];

$ch = curl_init('https://droppcash.app/payment/process');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Accept: application/json',
    'Content-Type: application/json',
    'Authorization: Bearer YOUR_ACCESS_KEY',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($parameters));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

if (($response['code'] ?? 0) === 200) {
    header('Location: ' . $response['url']);   // send the buyer to checkout
    exit;
}
echo 'Error: ' . json_encode($response['message'] ?? 'Unknown error');

Node.js

Copy// Node.js 18+ (run this on your server, never in the browser)
const res = await fetch('https://droppcash.app/payment/process', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_KEY',
    'Content-Type': 'application/json',
    'Accept': 'application/json',
  },
  body: JSON.stringify({
    custom: 'ORDER-1001',
    currency_code: 'USD',
    amount: 280.0,
    details: 'Digital Product',
    web_hook: 'https://yoursite.com/web_hook',
    success_url: 'https://yoursite.com/success',
    cancel_url: 'https://yoursite.com/cancel',
    customer_email: 'customer@mail.com',
  }),
});
const data = await res.json();
if (data.code === 200) {
  // redirect the buyer to data.url
} else {
  console.error(data.message);
}

Python

Copyimport requests

r = requests.post(
    "https://droppcash.app/payment/process",
    headers={"Authorization": "Bearer YOUR_ACCESS_KEY"},
    json={
        "custom": "ORDER-1001",
        "currency_code": "USD",
        "amount": 280.00,
        "details": "Digital Product",
        "web_hook": "https://yoursite.com/web_hook",
        "success_url": "https://yoursite.com/success",
        "cancel_url": "https://yoursite.com/cancel",
        "customer_email": "customer@mail.com",
    },
    timeout=30,
)
data = r.json()
if data["code"] == 200:
    checkout_url = data["url"]   # redirect the buyer here
else:
    print(data["message"])

Success response

Copy{
  "code": 200,
  "status": "OK",
  "payment_id": "AIYmQIOAz0GlmsjfhgiOeu304",
  "message": "Your payment has been processed. Please follow the URL to complete the payment.",
  "url": "https://droppcash.app/process-checkout?payment_id=AIYmQIOAz0GlmsjfhgiOeu304"
}

Save the payment_id with your order and redirect the buyer to url.

When the buyer pays, DroppCash does two things with the same data:

• Webhook: a form-encoded POST to your web_hook URL. Respond with any 2xx status. The reply is not read and the call is not retried.
• Redirect: the buyer is sent to your success_url with the same fields added as a query string (?code=200&status=OK&payment_id=...).

PHP webhook example

Copy<?php
// web_hook.php - receives the payment result from DroppCash
$paymentId = $_POST['payment_id'] ?? '';
$custom    = $_POST['custom'] ?? '';

// 1. Never trust this request on its own. Ask DroppCash if the payment is real
//    (see "Confirm a Payment" below).
// 2. Match $custom and the amount with YOUR order record.
// 3. Make sure you only fulfil each order once - the webhook can arrive
//    together with the buyer's redirect.

http_response_code(200);

Node.js webhook example

Copy// Node.js (Express) webhook example
app.use(express.urlencoded({ extended: false }));

app.post('/web_hook', async (req, res) => {
  const { payment_id, custom } = req.body;
  // 1. confirm with check-validity (next section)
  // 2. match custom and amount with your own order
  // 3. fulfil the order once only
  res.sendStatus(200);
});

GET https://droppcash.app/payment/check-validity?payment_id=PAYMENT_ID

Send the payment_id as a query parameter and your access key in the Authorization header. This must be a GET request.

cURL

Copycurl -G https://droppcash.app/payment/check-validity \
  -H "Authorization: Bearer YOUR_ACCESS_KEY" \
  --data-urlencode "payment_id=AIYmQIOAz0GlmsjfhgiOeu304"

PHP

Copy<?php
$paymentId = 'AIYmQIOAz0GlmsjfhgiOeu304';

$ch = curl_init('https://droppcash.app/payment/check-validity?payment_id=' . urlencode($paymentId));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Accept: application/json',
    'Authorization: Bearer YOUR_ACCESS_KEY',
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

if (($response['code'] ?? 0) === 200) {
    // payment is completed - safe to deliver the order
}

Node.js

Copyconst url = new URL('https://droppcash.app/payment/check-validity');
url.searchParams.set('payment_id', 'AIYmQIOAz0GlmsjfhgiOeu304');

const res = await fetch(url, {
  headers: { 'Authorization': 'Bearer YOUR_ACCESS_KEY', 'Accept': 'application/json' },
});
const data = await res.json();
if (data.code === 200) {
  // payment is completed - safe to deliver the order
}

Python

Copyimport requests

r = requests.get(
    "https://droppcash.app/payment/check-validity",
    params={"payment_id": "AIYmQIOAz0GlmsjfhgiOeu304"},
    headers={"Authorization": "Bearer YOUR_ACCESS_KEY"},
    timeout=30,
)
if r.json()["code"] == 200:
    pass  # payment is completed - safe to deliver the order

Responses

Copy// Payment completed
{ "code": 200, "status": "OK", "message": "Transaction is valid" }

// Payment not found or not completed yet
{ "code": 404, "status": "error", "message": "Transaction Not Found." }

// Wrong or missing access key
{ "code": 401, "status": "error", "message": "Invalid API credentials." }

Escrow holds money safely until it is released to the receiver. It suits marketplaces. The money comes from the wallet of the account that owns the access key, in the currency you choose, and is taken immediately.

POST https://droppcash.app/payment/make-escrow

cURL

Copycurl -X POST https://droppcash.app/payment/make-escrow \
  -H "Authorization: Bearer YOUR_ACCESS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "receiver_email": "seller@mail.com",
    "currency_code": "NGN",
    "amount": 20,
    "description": "Digital Product",
    "pay_charge": true
  }'

PHP

Copy<?php
$parameters = [
    'receiver_email' => 'seller@mail.com',
    'currency_code'  => 'NGN',
    'amount'         => 20,
    'description'    => 'Digital Product',
    'pay_charge'     => true,
];

$ch = curl_init('https://droppcash.app/payment/make-escrow');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Accept: application/json',
    'Content-Type: application/json',
    'Authorization: Bearer YOUR_ACCESS_KEY',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($parameters));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

Responses

Copy// Success
{ "code": 200, "status": "OK", "message": "An Escrow Has Been Made to seller@mail.com" }

// Validation problem (message is a list)
{ "code": 422, "status": "error", "message": ["The selected receiver email is invalid."] }

// Not enough money in your wallet
{ "code": 422, "status": "error", "message": "Insufficent Balance In Your Wallet" }

Create an invoice for your customer. DroppCash emails them a payment link and also returns it to you so you can redirect them straight to a clean checkout page.

POST https://droppcash.app/payment/create-invoice

cURL

Copycurl -X POST https://droppcash.app/payment/create-invoice \
  -H "Authorization: Bearer YOUR_ACCESS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "invoice_to": "Test User",
    "email": "customer@mail.com",
    "currency_code": "NGN",
    "item": ["Baby doll", "Toy car", "Gift wrap"],
    "amount": [10, 20, 30],
    "address": "Lagos, Nigeria",
    "allow_escrow": true,
    "pay_charge": true,
    "invoice_status": "publish",
    "success_url": "https://yoursite.com/success",
    "cancel_url": "https://yoursite.com/cancel"
  }'

PHP

Copy<?php
$parameters = [
    'invoice_to'     => 'Test User',
    'email'          => 'customer@mail.com',
    'currency_code'  => 'NGN',
    'item'           => ['Baby doll', 'Toy car', 'Gift wrap'],
    'amount'         => [10, 20, 30],
    'address'        => 'Lagos, Nigeria',
    'allow_escrow'   => true,
    'pay_charge'     => true,
    'invoice_status' => 'publish',
    'success_url'    => 'https://yoursite.com/success',
    'cancel_url'     => 'https://yoursite.com/cancel',
];

$ch = curl_init('https://droppcash.app/payment/create-invoice');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Accept: application/json',
    'Content-Type: application/json',
    'Authorization: Bearer YOUR_ACCESS_KEY',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($parameters));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

if (($response['code'] ?? 0) === 200) {
    header('Location: ' . $response['url']);   // customer pays on the invoice page
    exit;
}

Responses

Copy// Success
{
  "code": 200,
  "status": "OK",
  "message": "Invoice Has Been Made",
  "url": "https://droppcash.app/view-invoice/eyJpdiI6..."
}

// Customer email has no account (a link to register is returned)
{ "code": 500, "status": "OK", "message": "User Not Registerred On Dropppay", "url": "https://droppcash.app/user/register" }

// item and amount lists do not match
{ "code": 500, "status": "error", "message": "An Error In Your API Parameters Caused This." }

With escrow checkout the buyer pays into DroppCash escrow instead of paying you directly. The money is held safely until the buyer releases it to you. You are the seller: the account that owns the API access key is the one that gets paid.

1. Your server calls POST /payment/escrow/process and gets a checkout url.
2. You send the buyer to that URL. The buyer signs in to their DroppCash account and funds the escrow.
3. DroppCash redirects the buyer to your success_url and calls your web_hook with event escrow.funded. You can now ship the goods or deliver the service.
4. When the buyer has received the order, they release the payment from their DroppCash account (My Escrows). You get the event escrow.released and the money is in your wallet.
5. If something goes wrong, you can refund the buyer, or either side can open a dispute that DroppCash support decides.

Start an escrow payment takes the same fields as Start a Payment (currency_code, amount, custom, details, customer_email, web_hook, success_url, cancel_url) plus one optional field:

cURL

Copycurl -X POST https://droppcash.app/payment/escrow/process \
  -H "Authorization: Bearer YOUR_ACCESS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "currency_code": "NGN",
    "amount": 7500.50,
    "custom": "ORDER-1001",
    "details": "Laptop bag",
    "customer_email": "buyer@mail.com",
    "web_hook": "https://yoursite.com/webhook.php",
    "success_url": "https://yoursite.com/success.php",
    "cancel_url": "https://yoursite.com/cancel.php",
    "pay_charge": false
  }'

Copy{
  "code": 200,
  "status": "OK",
  "payment_id": "AIYmQIOAz0GlmsjfhgiOeu304",
  "message": "Your escrow payment has been created. Please send the buyer to the URL to fund the escrow.",
  "url": "https://droppcash.app/payment/process-checkout?payment_id=AIYmQIOAz0GlmsjfhgiOeu304"
}

Check the status with GET /payment/escrow/status?payment_id=... (Bearer key). Always use this call, never the address bar, to confirm what happened.

Copy{
  "code": 200,
  "status": "OK",
  "escrow": {
    "payment_id": "AIYmQIOAz0GlmsjfhgiOeu304",
    "custom": "ORDER-1001",
    "amount": "7500.5",
    "currency": "NGN",
    "test": 0,
    "escrow_id": "42",
    "escrow_status": "held",
    "transaction": "K3JD8SL2QW1X",
    "charge": "75",
    "funded_at": "2026-10-16T10:15:00+00:00"
  }
}

Refund the buyer (only while the status is held): POST /payment/escrow/refund with {"payment_id": "..."}. The buyer gets back everything they paid: the held amount, plus the escrow fee if the buyer paid it (pay_charge true). The response shows the refunded total.

Copy{ "code": 200, "status": "OK", "message": "Escrow refunded to the buyer.", "refunded": "7575.5" }

// not refundable (already released, disputed or refunded)
{ "code": 422, "status": "error", "message": "Escrow can only be refunded while it is held." }

Webhook events. DroppCash sends a form-encoded POST to your web_hook URL every time something happens. Events: escrow.funded, escrow.released, escrow.refunded, escrow.disputed, escrow.closed. Answer with any 2xx status. Calls are not retried, so also use the status call as a safety net.

Every webhook is signed. The header X-DroppCash-Signature holds sha256= followed by the HMAC-SHA256 of the raw request body, using your API access key as the secret. Reject any call whose signature does not match, then also check that amount and currency match your order.

PHP

Copy<?php
$raw       = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_DROPPCASH_SIGNATURE'] ?? '';
$expected  = 'sha256=' . hash_hmac('sha256', $raw, 'YOUR_ACCESS_KEY');

if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit;
}
parse_str($raw, $event);   // $event['event'], $event['payment_id'], ...

Node.js

Copy// Node.js (Express): use express.raw({ type: '*/*' }) so you get the raw body
const crypto = require('crypto');
app.post('/webhook', express.raw({ type: '*/*' }), (req, res) => {
  const expected = 'sha256=' + crypto.createHmac('sha256', 'YOUR_ACCESS_KEY').update(req.body).digest('hex');
  const given = req.get('X-DroppCash-Signature') || '';
  const ok = expected.length === given.length && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(given));
  if (!ok) return res.sendStatus(401);
  const event = Object.fromEntries(new URLSearchParams(req.body.toString()));
  res.sendStatus(200);
});

Python

Copyimport hmac, hashlib
from urllib.parse import parse_qs

def is_genuine(raw_body: bytes, signature_header: str, access_key: str) -> bool:
    expected = "sha256=" + hmac.new(access_key.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature_header or "")

# event = {k: v[0] for k, v in parse_qs(raw_body.decode()).items()}

Test mode. With a test-mode key nothing is charged and no real escrow exists, but the whole flow works: checkout, redirect, webhooks, status and refund. Because no real buyer is there to release the money, use POST /payment/escrow/simulate with {"payment_id": "...", "action": "released"} (or "disputed") to act as the buyer. This call is refused for live payments.

Remember: the HTTP status is always 200. Check the code field in the JSON body.

Example validation error:

Copy{
  "code": 422,
  "status": "error",
  "message": [
    "The amount must be greater than 0.",
    "The success url must be a valid URL."
  ]
}

• Keep your access key on your server only. If it leaks, create a new one from your dashboard.
• Always confirm a payment with check-validity before you deliver, and compare custom and the amount with your own order.
• Fulfil each order once only. Store the payment_id against the order and ignore repeats.
• Use HTTPS for web_hook, success_url and cancel_url.
• Do not turn off SSL certificate checks (such as CURLOPT_SSL_VERIFYHOST or verify=False) in your own code.

Use the currency code exactly as shown. The list updates automatically when new currencies are added.