Payment Gateway SDK — PHP & Node.js Kit for High Risk Sites

Payment gateway SDK for high risk sites: card in, USDT out, no merchant account

This is the complete integration kit behind the WcPay high risk payment API: a
payment gateway SDK in PHP and Node.js, a callback handler that already
solves the four failures that cost real money, a working reference store you can run in
thirty seconds, fifty-one offline tests, full documentation and a Postman collection. You
buy it once, you own the source, and there is no renewal.

It exists for one situation: you are building a custom site or application, you need to
take card payments, and either no processor will underwrite your line of business or the
one that did has already dropped you. With this payment gateway SDK your customer pays with
a card, Apple Pay, Google Pay, Revolut, iDEAL, Klarna, UPI or Interac, and you receive USDT
at an address you control. No merchant account, no KYC file, and no chargebacks.

If you run WooCommerce, PrestaShop,
OpenCart or
WHMCS, take the dedicated
module instead — it does the same thing with no code. This payment gateway SDK is for everything
else: a Laravel application, an Express API, a Django back end calling it over HTTP, a
bespoke booking engine, an internal billing tool, a marketplace.

What is inside the payment gateway SDK

Every edition ships the same source. The three editions differ in how many production
domains you may deploy on and whether you may resell the integration — the code is
identical, and you get all of it.

The PHP payment gateway SDK

Eleven classes, no dependency, loadable with a single require so it works on
shared hosting where Composer is not available. A Composer package is provided as well if
you prefer it.

• Client — creates payments, creates hosted checkout pages, creates
  receiving addresses, converts currencies, lists providers and filters them by the amount
  your customer is actually paying.
• Callback — parses the confirmation the provider sends you, decides
  whether the order is paid, underpaid or still pending, and produces the exact response
  the provider expects.
• License — verifies your licence against wcpay.us and caches the
  answer so a network hiccup never blocks a sale.
• Http — a thin transport you can swap for your own, which is what
  makes the whole payment gateway SDK testable offline.
• Config — one place for the key, the tolerance and the endpoints.
• Four typed exceptions: ValidationException,
  NetworkException, LicenseException and the
  WcPayException they all extend, so you can catch exactly the failure you
  want to handle and let the rest bubble up.

Four runnable examples come with the PHP payment gateway SDK: a checkout, a callback handler, listing the methods
available for a given amount, and a licence check.

The Node.js payment gateway SDK

The Node payment gateway SDK offers the same surface in modern JavaScript. It is CommonJS
with no dependencies, so it requires cleanly into Express, Fastify, Koa or the built-in HTTP
server, and it uses nothing but the built-in Fetch
API that ships with the runtime.
There is no package to audit and nothing to keep up to date. An Express server example shows
the complete flow in one file you can read in ten minutes.

The reference store: the payment gateway SDK running end to end

A small but genuinely working shop in plain PHP: product list, payment page, callback
endpoint, order list. Run it and you see the entire funnel end to end.

cd reference-store
php -S localhost:8000

It starts in sandbox mode, which means no key, no network call and no account. You pick an
article and a payment method, then simulate a full payment, a partial payment or an
underpayment, and watch the order change state. This is the fastest way to understand what
the payment gateway SDK actually does before you write a line of your own code.

Three files carry the whole thing — index.php, pay.php and
cb.php — and they are written to be read, not just executed.

Fifty-one offline tests for the payment gateway SDK

Twenty-five for PHP, twenty-six for Node. They run with no key, no network and no
installation:

cd php  && php tests/run.php
cd node && node tests/run.js

They cover the parts of the payment gateway SDK that are expensive to get wrong: the exact callback response, the
underpayment threshold, the per-order address rule, the callback URL length limit, currency
conversion, provider filtering by minimum, and wallet address validation. If you modify the
payment gateway SDK — and you are meant to, you have the source — these tests
tell you in two seconds whether you broke the part that handles money.

Documentation and Postman

Two documents, both written as prose rather than as a reference dump.
docs/API.md describes every endpoint, every parameter and every error code.
docs/INTEGRATION.md is the one to read first: ten short chapters that take you
from “what do I store in my database” to “what do I do when a confirmation never arrives”.
The Postman collection lets you hit the live API before you write any code at all.

The two rules of a payment gateway SDK you must never break

Most integrations that fail in production fail on one of these two. They are not
negotiable and the payment gateway SDK enforces both.

One receiving address per order

Create a fresh receiving address for every single order. Reusing one address across
customers gets the link blocked, and you discover it when payments stop arriving. The payment gateway SDK will not let you create a payment whose callback URL has no
order-specific parameter,
precisely because that is the mistake that leads to a shared address.

A unique parameter in your callback URL

Your confirmation URL must carry at least one value that changes per order — an
order number, an invoice id. Something like ?o=1042. Without it, two orders
receive the same address and you can no longer tell which one was paid. The payment gateway SDK refuses the call rather than letting you find out later.

Four traps this payment gateway SDK already solved for you

These are the four failures that eat a week of debugging each. Every one of them is
handled in the shipped code, and every one has a test.

1. The exact callback response

When the provider confirms a payment, your page must answer with one precise string. Not
JSON, not an HTTP 200 with an empty body, not your framework’s default response. Anything
else and the provider treats the confirmation as failed and retries, which means a customer
who paid once can be marked paid several times, or never. The Callback class
produces the correct response and nothing else, and a test asserts it character by
character.

2. The callback URL length limit

Several providers silently reject a confirmation URL that is too long. The payment goes
through, your customer sees a thank-you page, and you never receive anything. Nothing fails
visibly, which makes it the worst kind of bug. Stay under 95 characters,
full URL included. The payment gateway SDK refuses to create a payment above that limit, so
you learn about it in development rather than after a week of lost orders.

Avoid	Prefer
https://shop.com/payment/confirmation/provider-return.php?number=1042	https://shop.com/cb.php?o=1042

3. The pre-encoded address

One parameter arrives already percent-encoded, in the sense defined by
RFC 3986, and must be passed through
untouched. Encode it a second time — which every helpful framework, and every reflex to
reach for rawurlencode(),
will do for you — and the payment is sent to an address that does not exist. This payment gateway SDK owns the encoding boundary itself, so the question never reaches your code.

4. Underpayment

The amount that arrives is almost never exactly the amount you asked for: the rate moves
between the click and the settlement, and the provider’s fee is taken on the way through. If
your code compares for equality, you will reject honest customers all day.

The payment gateway SDK accepts 60 % of the expected amount by default.
That is deliberately generous — collecting a slightly underpaid order beats turning
away a real buyer. If your margin is thin, tighten it:

new WcPay\Client(['tolerance' => 0.85]);   // refuse below 85 %

Use the same value when you create the payment and when you handle the confirmation,
otherwise your two calculations disagree and you get orders that are paid on one side and
pending on the other.

The payment methods your customer sees

One payment gateway SDK, more than twenty-five rails. You decide which ones appear, and the payment gateway SDK can filter them automatically by the amount of the order so a customer is never offered
a method whose minimum they do not reach.

Cards and wallets: Credit Card through Stripe, Credit Card through
PayPal, Apple Pay, Google Pay, Revolut Pay, Cash App, Binance Pay.
Local rails: iDEAL for the Netherlands, UPI and IMPS for India, Interac for
Canada, Klarna for parts of Europe.
On-ramps: Coinbase Pay, Blockchain.com, Ramp Network, MoonPay, Transak,
Banxa, Topper, Bitnovo, Robinhood, Simplex, Sardine, UTORG, TransFi, Meld, Particle
Network, Alchemy Pay.

Each rail has its own minimum, from around two dollars for cards up to a hundred for UPI
and Interac. The payment gateway SDK reads the live provider list and the live conversion
rate, so a method
that is temporarily unavailable or below its minimum simply does not appear. That single
behaviour removes the most avoidable cause of an abandoned payment: sending a buyer to a
refusal page.

$methods = $client->availableProviders(49.90, 'EUR');
// returns only the rails that actually work for 49.90 EUR, right now

USDT payouts, and what final settlement really means

The payment gateway SDK settles the same way whichever rail is used: your customer pays in their currency with a method they already trust. You receive USDT
at an address you control. Nothing sits in a platform balance, there is no payout schedule,
and no rolling reserve is held back against future disputes.

The consequence worth understanding is that settlement is final. A card payment can be
reversed by the buyer months later; a stablecoin transfer cannot be clawed back by the
sender. For a business a bank labels high risk, that single property is often worth more
than the processing fee, because it turns revenue you received into revenue you actually
kept. The current processing fees are published
per method, so you can price your product before you write a line of code.

It cuts both ways, and it would be dishonest not to say so. Your customer loses the
chargeback as a remedy, so your own conduct has to carry the trust the card network used to
underwrite. Deliver what you promised, answer your messages, and refund directly and quickly
when a refund is deserved. Businesses that do that find final settlement an advantage.
Businesses relying on the dispute process to absorb their own sloppiness should not use
this.

Refunds are covered in the documentation: because the settlement arrives in your wallet,
a refund is a transfer you make, not a reversal the network performs. The payment gateway SDK shows the pattern and the record-keeping that goes
with it.

Which payment gateway SDK edition should you buy

All three editions contain the same payment gateway SDK, the same reference store, the
same fifty-one tests and the same documentation. What differs is how many production domains
you may deploy on, and whether you may resell the integration.

	Developer	Agency	Unlimited
Production domains	1	10	Unlimited
PHP & Node.js SDKs, full source	Yes	Yes	Yes
Reference store, 51 tests, docs, Postman	Yes	Yes	Yes
All 25 payment methods, instant USDT payouts	Yes	Yes	Yes
Deploy on client projects	One project	Yes, up to 10	Yes, unlimited
Integration review on request	—	Yes	Yes
Right to resell the integration	—	—	Yes
Payout splitting and affiliate guide	—	—	Yes
Support	Setup included	Priority	Direct channel
Renewal	Never	Never	Never

A production domain is a domain that takes real payments. Local, staging and preview
environments do not count and are unlimited on every edition. example.com and
www.example.com are one domain. Domains register themselves on the first
successful live call, and you can release one when a project ends — the slot becomes
available again immediately.

Developer

For your own site, or a single client project. If you are integrating the payment gateway SDK once and you are not an agency, this is the edition. It pays for itself in under a day
of development time, because the four traps above are each worth more than a day on their
own.

Agency

For a studio shipping payment integrations for clients. Ten production domains, which
works out at ninety dollars a site, priority setup support, and an integration review on
request: send us your callback handler and the part that creates the payment, and we check
the four traps before your client goes live. It is the single thing that prevents the most
incidents. The edition ships an extra document on running client projects — who owns
the receiving address, who holds the licence, and where the API key must not live.

Unlimited

For platforms, resellers and anyone deploying at scale. Unlimited production domains, the
right to resell the integration as part of your own work, a direct support channel, and the
payout splitting and affiliate material. Splitting lets you divide a single payment between
two addresses — yours and a partner’s — which is what a marketplace, a revenue
share or a platform commission taken at source needs. The edition adds a worked example in
both PHP and Node, commented line by line, plus a document on the three mistakes that cause
split payouts to fail in production.

To be precise about resale, because the word is ambiguous: you may integrate the payment gateway SDK into a product or a
site and deliver that to a client, with or without your branding, as many
times as you like. You may not publish the kit itself for download — a public
repository, a theme marketplace, a bundle sold as-is. You sell your integration work, not
our source.

What this kit does not do

A product page that only lists strengths is not worth trusting, so here are the limits in
plain terms.

It is not a plugin. There is no admin screen and nothing to click. You
are expected to write code. If you want a checkbox, take the WooCommerce, PrestaShop,
OpenCart or WHMCS module instead.

It does not give you a merchant account. There is no underwriting
because there is nothing to underwrite: the money never passes through an account in your
name at a bank. That is the point, and it is also why the usual guarantees of a merchant
account do not apply.

A mistyped wallet address loses the funds. A stablecoin transfer cannot
be reversed. The payment gateway SDK validates the format before sending, which catches
typos, but it cannot know whether a correctly-formed address is actually yours. Check it
once, carefully.

Provider availability depends on third parties. Rails occasionally pause
a country or a category without notice. The payment gateway SDK is built so one rail going quiet never stops the
others, which is the practical reason to keep several methods enabled. No uptime figure
is promised, because promising one for someone else’s infrastructure would be a lie.

It does not handle your tax or your accounting. It takes payments and
tells you they arrived. What you do with that in your books is yours.

Requirements for the payment gateway SDK

• PHP 7.4 or later, with cURL or allow_url_fopen. No
  extension beyond the standard set, no Composer required. 7.4 is the floor, not the
  recommendation — check the
  official PHP support calendar
  and run 8.1 or above on anything public.
• Node.js 18 or later for the JavaScript payment gateway SDK, which
  uses the built-in Fetch API and has zero dependencies. The
  Node.js release table
  tells you which lines are still Current or LTS and which are already end of life.
• An HTTPS endpoint that the provider can reach, for the confirmation
  callback. It must be publicly reachable; a localhost tunnel works for development.
• A wallet address you control, to receive settlements.
• Any language that can make an HTTPS request can use the API directly — the two
  SDKs are a convenience, not a requirement, and the documentation gives you the raw
  endpoints.

Security: what the payment gateway SDK keeps out of your code

The less your server touches, the less you have to defend. This payment gateway SDK is
built so the sensitive parts never reach you in the first place.

Card details never arrive. The customer is redirected to the provider’s
own page to type their number, expiry and security code. Those values do not transit your
server, are not written to your logs, and are not yours to store. The scope of what you must
protect shrinks to your API key and your wallet address. That redirect model is also what
keeps a merchant in the lightest self-assessment bracket,
PCI DSS SAQ A
— though your acquirer, not us, decides which questionnaire applies to you.

Your key stays in the environment. Every example shipped with this payment gateway SDK
reads WCPAY_API_KEY from the environment rather than from a file in the repository.
That is not decoration: an API key committed to a client’s Git history is the most common
way these integrations leak, and it usually surfaces months later.

The callback is authenticated by construction. Your confirmation URL
carries a token that only you and the provider know. The Callback class checks
it before it will mark anything paid, so a third party who guesses your endpoint cannot
forge a payment. The reference store shows the pattern in cb.php, and if you want
a second layer you can sign your own order reference with
hash_hmac()
and verify it in the same handler.

Nothing phones home with your data. The only outbound calls the payment gateway SDK makes are the payment API itself and the licence check, and the licence check
sends your key and your domain, nothing else. You can read both in the source, which is why
you get the source.

How this compares with the usual alternatives

Three roads lead out of the same problem, and this payment gateway SDK is only one of
them. Choosing honestly is cheaper than choosing fast.

A traditional processor. Better rates, familiar dashboard, real
chargeback protection for your buyer. If your line of business is accepted and stays
accepted, use one. The risk is not the fee; it is the suspension that arrives after three
good months, with a balance held and a reserve retained.

A high risk merchant account through a broker. It works, and it is
legitimate. Expect a rolling reserve between five and ten per cent held for six months, a
setup fee, a monthly minimum, and an underwriting file. If your volume justifies that
overhead, it may well beat this payment gateway SDK on cost.

This kit. One payment, no underwriting, settlement that cannot be
reversed, and code you own. The trade is that you write the integration, your buyer has no
chargeback remedy, and availability depends on providers you do not control. For a
developer who can spend an afternoon on it and wants the account risk gone, that trade is
usually the right one.

Whichever you pick, the questions are the same: who holds the money between the sale and
your bank, who can freeze it, and for how long. A payment gateway SDK that settles directly
to an address you control answers all three the same way — nobody, nobody, and not at
all.

Your first payment with the payment gateway SDK, step by step

This is the whole sequence. On a site that already exists, it is an afternoon.

1. Run the reference store. Sandbox mode, no key, no network. Make a
   full payment, a partial one and an underpayment, and watch the order states. Ten
   minutes, and you now understand the model.
2. Read docs/INTEGRATION.md. Chapter 2 tells you exactly
   what to store in your database. Getting that right at the start saves a migration
   later.
3. Drop the payment gateway SDK in. One require for PHP,
   one import for Node.
4. Write your callback endpoint. Copy cb.php from the
   reference store and adapt it. Keep the URL short — under 95 characters — and
   keep the order id in it.
5. Create your first payment against the sandbox, then against the live
   API with a small real amount.
6. Check the four traps with the test suite, then go live.

Agency and Unlimited customers can send the callback handler and the payment creation
code to support for review before going live. Take that offer; it is free and it catches
what a test suite cannot.

Questions we are asked before purchase

Do I need a merchant account or a KYC file?

No. There is no underwriting and no account application. You buy the licence, you set a
wallet address, and you can take your first payment the same day.

What exactly do I receive when I buy?

A ZIP download, immediately after payment, containing the PHP payment gateway SDK, the
Node.js SDK, the reference store, the fifty-one tests, both documents, the Postman
collection and your licence file. Your activation key arrives by email.

Is the licence a subscription?

No. It is a one-time payment with no renewal, on all three editions. Updates are
included: for life on Agency and Unlimited, and for the life of the licence on Developer.

Can my customer pay with an ordinary bank card?

Yes, and that is the common case. “Credit Card” appears like any other method. Your
customer never needs a wallet, never creates an account and never sees anything unusual
— they enter their card details on the provider’s secure page, and that is the end of
it.

Are card details handled by my server?

Never. The customer is handed to the provider’s own payment page, which is where the card
number is typed. Those details do not pass through your code and are not stored by you,
which keeps the heaviest part of payment compliance off your shoulders.

Which currencies can I charge in?

Eighteen, including USD, EUR, GBP, CAD, CHF, AED, INR and BRL. Some providers settle only
in USD; when one of those is used, the amount is converted at the rate in force so the
invoice total is preserved. The payment gateway SDK exposes the conversion endpoint, so you
can show the converted figure before the customer commits.

What happens if a confirmation never arrives?

Chapter 8 of the integration guide is about exactly that. In short: you never treat the
customer’s return to your thank-you page as proof of payment, you reconcile against the
confirmation, and the payment gateway SDK shows you the polling pattern for the rare case where a
confirmation is lost.

Can I use one licence for both my site and a client’s?

Developer covers one production domain, so no. Agency covers ten, Unlimited covers any
number. You can also upgrade later and pay the difference — write to support.

Does the payment gateway SDK work with Laravel, Symfony, Express or NestJS?

Yes. The payment gateway SDK is framework-agnostic: it is plain PHP and plain JavaScript
with no container, no service provider and no global state. Wire it in wherever you like.
The only framework-specific advice is to make sure your router does not re-encode the one
pre-encoded parameter, which chapter 3 covers.

Can I try it before buying?

The reference store in sandbox mode is the trial, and it is the honest version of one:
the whole funnel, running on your machine, with no key and no network. What it cannot show
you is a live provider page, because that requires a real key.

What if I need something the kit does not do?

Write to support@wcpay.us before you buy and describe it. If it is not possible we will
say so, which is cheaper for both of us than a refund request.

Payment gateway SDK support, updates and what happens next

Setup support is included on every edition. Agency adds priority handling and an
integration review on request; Unlimited adds a direct channel. Updates are free, and the
payment gateway SDK is versioned so you can see exactly what changed before you upgrade a
live site.

After purchase you receive the download and your activation key by email. The key is what
the licence check validates; keep it out of your public repository, and load it from the
environment as the examples do.

If something is broken, we would rather hear about it than have you work around it. The four traps documented above are in this payment gateway SDK precisely
because other integrators hit them
first and told us. If you are weighing this payment gateway SDK against a
module, or you are not sure which
edition fits your project, ask us before you buy
— a pre-sales question costs you nothing and saves a refund request.