Push Push Payments Gateway API

• Base URL: https://pushpushpayments.app — the same host for both environments.
• The environment is selected by the key you use: pk_sandbox_… / sk_sandbox_… for testing, pk_live_… / sk_live_… for real money. There is no separate sandbox hostname.
• All requests and responses are JSON. Send Content-Type: application/json.
• Amounts are always integers in minor units (4990 = 49.90). Supported currencies: USD EUR GBP UAH KZT PLN TRY.
• Server-side only. The secret key signs requests and must never be shipped to a browser or a mobile app. If you cannot keep it on a server, use Hosted Checkout.

// Node.js 18+ — create a payment
import crypto from "node:crypto";

const BASE = "https://pushpushpayments.app";
const PATH = "/api/public/v1/payments";
const KEY_ID = process.env.PPP_KEY_ID;   // pk_live_...
const SECRET = process.env.PPP_SECRET;   // sk_live_...

const body = JSON.stringify({
  order_id: "A-1001",
  amount: 4990,
  currency: "EUR",
  description: "Order A-1001",
  return_url: "https://shop.example/thanks",
  callback_url: "https://shop.example/hooks/pushpush",
  customer: {
    name: "Jane Doe",
    email: "jane@buyer-mail.com",
    phone: "+447700900123",
    address: "12 King Street",
    city: "Manchester",
    postal_code: "M2 6DW",
    country: "GB",
  },
  card: { number: "4012888888881881", exp_month: 12, exp_year: 2030, cvv: "123", holder: "JANE DOE" },
});

const ts = Math.floor(Date.now() / 1000).toString();
const signature = crypto
  .createHmac("sha256", SECRET)
  .update(`${ts}.POST.${PATH}.${body}`)
  .digest("hex");

const res = await fetch(BASE + PATH, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Api-Key": KEY_ID,
    "X-Timestamp": ts,
    "X-Signature": signature,
    "Idempotency-Key": "A-1001",
  },
  body,
});

const payment = await res.json();
// payment.status === "pending" && payment.payment_url -> redirect the shopper now

# cURL — the signature must be computed over the exact same raw body
BODY='{"order_id":"A-1001","amount":4990,"currency":"EUR"}'
TS=$(date +%s)
SIG=$(printf '%s' "$TS.POST./api/public/v1/payments.$BODY" \
  | openssl dgst -sha256 -hmac "$PPP_SECRET" -hex | awk '{print $2}')

curl -X POST https://pushpushpayments.app/api/public/v1/payments \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $PPP_KEY_ID" \
  -H "X-Timestamp: $TS" \
  -H "X-Signature: $SIG" \
  -d "$BODY"

• X-Api-Key — your key id (pk_…)
• X-Timestamp — Unix seconds, accepted within ±5 minutes of our clock
• X-Signature — hex HMAC-SHA256 of {timestamp}.{METHOD}.{path}.{rawBody} using your API secret
• Idempotency-Key — optional, safe retries on POST

// POST — sign the exact bytes you send
const base = `${ts}.POST./api/public/v1/payments.${body}`;

// GET — the body part is empty, the trailing dot stays
const base = `${ts}.GET./api/public/v1/payments/${id}.`;

const signature = crypto.createHmac("sha256", secret).update(base).digest("hex");

• METHOD is uppercase, path is the pathname only — no host, no query string.
• Sign the raw body string you actually transmit. Re-serialising the JSON after signing (different key order or whitespace) breaks the signature.
• Keep the secret on your server. A leaked secret lets anyone charge cards on your account — rotate it from the dashboard immediately if that happens.

{
  "error": {
    "code": "invalid_request",
    "message": "Request validation failed",
    "details": [ { "field": "customer.phone", "message": "Customer phone number is required" } ]
  }
}

A declined card is not an HTTP error: the request returns 200/201 with status: "failed" and a failure object.

Decline codes

failure.code on a failed payment is declined_<code>. Three-digit codes come from the payment route, one- and two-digit codes are the raw response of the card issuer.

Gateway / route codes

Route capacity & configuration limits

These declines are not caused by your request. The payload is valid and reached the processing route, but the route itself refused it because of a cap or a configuration rule. Do not change the request — retry later, or contact support so the limit can be raised.

Issuer (bank) codes

Use ISO 3166-1 alpha-2 codes (DE, GB, CA). The list reflects the card's issuing country: a supported billing address with a card issued elsewhere can still be declined by the route with declined_047.

• declined_050 — the card's issuing country is blocked on the route. A route-level restriction, not a request error. Retrying the same card will not help — ask the shopper for a card issued in another country.
• declined_047 — the country the card was issued in is not enabled on the route. Decided by the card BIN, not by the billing address, so the same address can succeed with a local card and fail with a foreign one. Retrying the same card never helps. We remember refused card ranges for 30 days and answer new attempts with them immediately: HTTP 400, card_country_not_supported. Ask the shopper for a card issued by another bank or in another country.
• declined_019 — the amount is below the route minimum. We now refuse these locally with amount_below_minimum before the request leaves our side: minimum 12.00 USD, 11.00 EUR, 10.00 GBP. Charging less is not possible on this route and every such attempt lowers your approval rate.
• Maximum 2 unsuccessful attempts per shopper per 30 minutes. Matched on e-mail and on card BIN + last 4. Further attempts get too_many_attempts instead of being sent to the issuer.
• A card refused for a permanent reason is not retried for 24 hours. Codes 002 (invalid or expired card), 003 (card blocked by the issuer), 016/017 (chargeback history) and 047 (card country not enabled) never change on a retry, so the same card answers too_many_attempts straight away. Ask the shopper for a different card. In our own data a second attempt on the same card converts at about 6% against 17% on the first one.
• No card-velocity blocking. High numbers of distinct cards per hour are monitored for card-testing patterns but never decline your payments.

There is no daily volume cap and no per-card attempt cap on the route. Payments are only answered locally with route_paused when an operator has manually paused processing during an incident, and with ftd_paused when first-time deposits are temporarily blocked while repeat payers keep going through.

What we check locally, and why

Redirect the shopper immediately. When the response contains requires_action with a next_action.redirect_url, send the browser there in the same user gesture. A payment whose 3-D Secure page is never opened is closed as expired after 30 minutes and still shows up as a failed attempt on the route.

For merchants who do not want to collect card data on their own server, create a checkout session and redirect the shopper to our hosted page. The shopper never leaves the pushpushpayments.app domain.

{
  "order_id": "A-1001",
  "amount": 4990,
  "currency": "EUR",
  "description": "Order A-1001",
  "return_url": "https://shop.example/thanks",
  "callback_url": "https://shop.example/hooks/pushpush",
  "customer": { "email": "buyer@example.com", "country": "DE" },
  "expires_in": 3600
}

{
  "id": "sess_...",
  "object": "checkout.session",
  "status": "created",
  "payment_url": "https://pushpushpayments.app/checkout/pay/sess_..."
}

Redirect the shopper to payment_url immediately. We collect the card and the billing details required by the acquirer, handle 3-D Secure, and return the shopper to return_url?payment_id=...&status=.... Anything you already know about the shopper can be passed in customer and is pre-filled on the page.

In sandbox mode the hosted page shows Approve/Decline buttons so you can test the full redirect flow without a real card.

A session is valid for 30 minutes by default and can be paid once. Pass expires_in (seconds, 300–86400) to issue a longer-lived link. Webhooks are delivered to callback_url exactly as with server-to-server payments. Server-to-server remains the primary integration; hosted checkout is an optional drop-in for merchants that prefer not to handle card data.

Send the exact payload you would send to /v1/payments — signed the same way — and see what would be rejected and what we would repair automatically. Nothing is created and no card is charged, so this is safe to run with live keys while debugging.

{
  "valid": true,
  "mode": "live",
  "errors": [],
  "repairs": [
    { "field": "customer.state", "message": "State set to \"Brunoy\" (processing route requires a region)" },
    { "field": "customer.phone", "message": "Phone normalised to +33333646988530" }
  ],
  "normalized_customer": { "city": "Brunoy", "state": "Brunoy", "country": "FR" },
  "note": "Dry run only — no payment was created and no card was charged."
}

errors is what would return HTTP 400. repairs is what we fix for you before the request leaves our platform.

For 3-D Secure 2 risk checks the acquirer needs a shopper browser fingerprint. If you are using the server-to-server integration, pass it explicitly so it matches the shopper's real device. If you use Hosted Checkout, we collect these values automatically from the shopper's browser.

• userAgent — browser User-Agent string
• acceptHeader — value of the Accept header
• language — browser language, e.g. en-GB
• colorDepth — screen color depth, e.g. 24
• screenWidth — screen width in pixels, e.g. 1920
• screenHeight — screen height in pixels, e.g. 1080
• timezoneOffset — timezone offset from UTC in minutes, e.g. 0
• ip — the shopper's public IP address. On server-to-server integrations the request reaches us from your server, so this is the only way the issuer can see the real cardholder. Send the address of the shopper's device, never your server's.

{
  "order_id": "A-1001",
  "amount": 4990,
  "currency": "EUR",
  "customer": { ... },
  "card": { ... },
  "browser": {
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 ...",
    "acceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
    "language": "en-GB",
    "colorDepth": "24",
    "screenWidth": "1920",
    "screenHeight": "1080",
    "timezoneOffset": "0",
    "ip": "203.0.113.24"
  }
}

Values you do not send are omitted from the authentication request rather than filled with defaults: a placeholder fingerprint repeated across many payments looks like automated traffic to the issuer and lowers your approval rate.

Collect the values on your checkout page (in the shopper's browser) and send them to your backend together with the order, then include them in the payment request:

// runs in the shopper's browser, on your checkout page
const browser = {
  userAgent: navigator.userAgent,
  acceptHeader: "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
  language: navigator.language,
  colorDepth: String(screen.colorDepth),
  screenWidth: String(screen.width),
  screenHeight: String(screen.height),
  timezoneOffset: String(new Date().getTimezoneOffset()),
};

// POST it to your own backend, which then calls
// POST https://pushpushpayments.app/api/public/v1/payments with { ..., browser }
await fetch("/your-backend/create-order", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ order_id: "A-1001", browser }),
});

The browser object must describe the cardholder's browser, not your backend HTTP client. If it is omitted and the API request comes from a server client (RestSharp, curl, HttpClient, requests, …), we do not forward that User-Agent upstream and the payment response contains a missing_browser_info warning — 3-D Secure risk checks degrade without it. Screen metrics and timezone must always be sent explicitly.

The confirmation link (payment_url / next_action.url) must be opened by the shopper's browser as a top-level navigation (window.top.location.href = payment_url). Fetching it from your backend or loading it in an iframe prevents 3-D Secure from starting and the payment will fail.

The signature base string uses an empty body: {timestamp}.GET./api/public/v1/payments/{id}. — note the trailing dot. The response is the same payment object returned by the create call. Retrieving a pending payment also triggers a status re-check against the acquirer, so this endpoint is a safe fallback if a webhook was missed. Poll no more than once every 10 seconds.

curl -X GET "https://pushpushpayments.app/api/public/v1/payments/1f0c..." \
  -H "X-Api-Key: $KEY_ID" \
  -H "X-Timestamp: $TS" \
  -H "X-Signature: $SIG"

{
  "payment_id": "1f0c...",   // required
  "amount": 2000,            // optional, minor units; omit to refund the full remaining balance
  "reason": "partial return" // optional, max 256 chars
}

{
  "id": "rfnd_...",
  "object": "refund",
  "payment_id": "1f0c...",
  "amount": 2000,
  "status": "succeeded",
  "created_at": "2026-01-01T10:05:00.000Z"
}

• Only succeeded and partially_refunded payments can be refunded — anything else returns 409 conflict.
• Multiple partial refunds are allowed while the sum stays within amount - refunded_amount. Exceeding it returns 409 conflict.
• Idempotency-Key is honoured here too: repeating a key returns the original refund instead of creating a second one.
• The parent payment moves to partially_refunded or refunded and a matching webhook is delivered.

The webhook is the authoritative result of a payment. It is sent to the callback_url of the payment, or to the default webhook URL configured in your dashboard.

{
  "id": "evt_...",
  "type": "payment.succeeded",
  "created_at": "2026-01-01T10:00:00.000Z",
  "data": { "id": "1f0c...", "status": "succeeded", "amount": 4990 }
}

Event types

• payment.succeeded — funds authorised and captured
• payment.failed — declined or errored
• payment.partially_refunded — partial refund processed
• payment.refunded — full refund processed

Verification

const base = `${req.headers["x-timestamp"]}.${rawBody}`;
const expected = crypto.createHmac("sha256", secret).update(base).digest("hex");
const valid = crypto.timingSafeEqual(
  Buffer.from(expected),
  Buffer.from(req.headers["x-signature"]),
);

• Verify against the raw request body, before any JSON parsing or re-serialisation.
• Reject events whose X-Timestamp is more than 5 minutes old — this blocks replay attacks.
• Deduplicate on the event id: a retry can deliver the same event twice, so your handler must be idempotent.
• Respond 2xx within 10 seconds. Any other response or a timeout is a failure.
• Retry schedule: up to 6 attempts at 30s, 2m, 10m, 1h, 6h, 6h. After that the delivery is marked failed and can be replayed manually from the dashboard.