# Payment Provider Selection

## Status
Working selection criteria for the product payment processor. Reviewed on 2026-03-10 against official provider materials.

## Goal
Pick a crypto payment path that fits `nproxy`:
- monthly crypto subscription
- manual renewal only
- fixed-price invoice checkout
- single-VPS deployment
- safe callback or polling-based reconciliation

## Hard requirements
- Crypto invoice API for fixed-price checkout.
- Manual renewal flow. The provider must not force native recurring billing.
- Stable external invoice identifier for reconciliation.
- Clear invoice lifecycle that can be mapped to `pending`, `paid`, `expired`, and `canceled`.
- Webhook support or a reliable status polling API. Both is preferred.
- Idempotent event handling. Duplicate callbacks or repeated status checks must not cause repeated subscription activation.
- Metadata or reference fields so the app can correlate `userId`, local `invoiceId`, and `subscriptionId`.
- Test mode, sandbox, or another safe way to validate integration without real funds.
- Merchant documentation clear enough to implement and operate without reverse engineering.
- Fees and supported chains viable for small monthly subscription invoices.

## noKYC requirement
`noKYC` is a hard selection criterion for the product.

For this repository, `noKYC` means all of the following in the normal operating path:
- The merchant can start accepting payments without mandatory KYC or KYB review.
- The payer can complete checkout without mandatory identity verification.
- The provider does not require custody of merchant funds unless that is an explicit deployment choice.

Track `crypto-to-crypto noKYC` separately from merchant onboarding:
- `merchant noKYC` asks whether `nproxy` can start operating without provider-side KYC or KYB.
- `crypto-to-crypto noKYC` asks whether a payer can complete an on-chain crypto payment from a normal wallet without entering an identity-verification flow.

The first one is the hard gate. The second one is still valuable and should be recorded in the comparison.

Evaluation rule:
- `pass`: official materials support operating without mandatory KYC in the normal path.
- `borderline`: marketing or docs imply low-friction onboarding, but the provider reserves the right to require KYC, hold funds, or escalate compliance checks.
- `fail`: official docs explicitly require merchant verification, or the product is clearly compliance-gated.

## Comparison matrix

| Provider | Model | Merchant noKYC | Crypto-to-crypto noKYC | API / webhooks | Test mode | Product fit | Notes |
| --- | --- | --- | --- | --- | --- | --- | --- |
| BTCPay Server | Self-hosted, self-custody | pass | pass | pass | pass | strong | Best fit for strict `noKYC`. Higher ops cost because the merchant runs the payment stack. |
| NOWPayments | Hosted processor | borderline | borderline to pass | pass | unclear | medium | Closest hosted option. Normal crypto-to-crypto flow appears low-friction, but official support docs reserve the right to request verification and hold suspicious transactions. |
| Cryptomus | Hosted processor | fail | unclear | pass | unclear | weak | Official help center says merchants need to pass KYC to use the platform. Reviewed materials did not give a clean official `crypto-to-crypto noKYC` promise for payers. |
| Coinbase Commerce / Coinbase Business | Hosted processor | fail | unclear | pass | pass | weak | Strong API surface, but the reviewed official materials do not support a strict `noKYC` posture. |

## Provider notes

### BTCPay Server
- Official BTCPay materials describe it as self-hosted and non-custodial.
- Official integration copy explicitly positions it as avoiding complicated KYC and keeping merchants in control of funds.
- This is the cleanest fit if `noKYC` must be enforced as a hard requirement rather than a preference.
- Tradeoff: the team must operate the service, wallet integration, backups, and chain support.

### NOWPayments
- Official API materials cover invoice creation and payment-status callbacks.
- Official support materials say account verification is not required in general, but NOWPayments may still request KYC details and put transactions on hold in suspicious cases.
- For the payer side, direct crypto-to-crypto checkout looks closer to `noKYC` than card or custodial account flows, but the official materials reviewed still leave compliance-escalation risk.
- That means it does not cleanly satisfy a strict `noKYC` rule. It is only acceptable if the product can tolerate compliance escalation risk.

### Cryptomus
- Official merchant docs cover invoice APIs and callbacks.
- Official help materials state that a merchant must pass KYC verification to use the platform.
- That merchant-side requirement is enough to fail the current hard gate even if a payer-side crypto path is relatively low-friction.
- This makes it a direct mismatch for the current product requirement.

### Coinbase Commerce / Coinbase Business
- Official Coinbase Commerce docs cover charges, webhooks, and test integration paths.
- Official Coinbase legal materials state that identity verification is required for customers to use Coinbase services.
- The reviewed official materials did not give a clean promise that external-wallet crypto-to-crypto checkout remains `noKYC` end to end.
- This is operationally mature, but it is not compatible with a strict `noKYC` requirement.

## Recommendation
- If `noKYC` is truly hard, prefer `BTCPay Server`.
- If a hosted processor is still desired, treat `NOWPayments` as the only current shortlist candidate from this review, but mark it as `borderline`, not `pass`.
- If the team later relaxes the hard gate from `merchant noKYC` to only `crypto-to-crypto noKYC`, rerun the comparison because the shortlist may widen.
- Do not choose `Cryptomus` or `Coinbase` while `noKYC` remains a hard requirement.

## Merchant KYC / AML risk
This section answers the practical merchant-side risk question: can a payment path create a real loss or freeze scenario if a customer pays with suspicious or "dirty" crypto.

### Short answer
- With a hosted or custodial processor, yes, there is a real risk of payout holds, extra KYC/KYB review, delayed settlement, or account restrictions if the provider flags a payment as suspicious.
- With a self-hosted and non-custodial path such as `BTCPay Server`, the processor itself does not hold your funds, so it cannot directly freeze coins that have already landed in your wallet.
- Even with self-custody, the risk is not gone. It moves downstream to whatever exchange, custodian, OTC desk, or banking ramp you use later.

### Can you lose all the money?
- The official materials reviewed support a real hold and compliance-escalation risk for hosted processors, especially around suspicious transactions.
- They do not, by themselves, prove guaranteed confiscation of all funds.
- The practical risk is usually loss of access, payout freeze, account closure, or long investigation windows rather than an automatic irreversible seizure.
- If your operating balance sits inside a custodial processor or exchange account during that event, the business impact can still feel like "losing the money" for an operationally important period.

### Why this matters for provider choice
- `NOWPayments` explicitly says verification may be requested and suspicious transactions may be put on hold.
- `Coinbase` documents identity verification and account restrictions as part of its compliance posture.
- `BTCPay Server` is self-hosted and non-custodial, so the payment processor layer is structurally less exposed to merchant-balance freezes.

### Inference for this repository
This is an inference from the official sources above:
- If minimizing merchant-side AML/KYC freeze risk is a priority, self-custody is materially safer than a hosted custodial processor.
- Self-custody does not make tainted-funds risk disappear. It mainly removes one counterparty that could hold or block your balance before it reaches your own wallet.
- The remaining exposure shows up when funds are consolidated, swapped, or off-ramped through third parties.

### Operational mitigations
- Prefer a non-custodial payment path.
- Keep payment receipt wallets segregated from treasury and personal wallets.
- Avoid commingling funds from unrelated customers before reconciliation.
- Keep invoice-to-transaction mapping so suspicious deposits can be isolated quickly.
- Assume any later exchange or off-ramp may apply AML screening even if the incoming payment path does not.

## Implementation consequence
Before starting issue `#9` or a real provider integration, keep the payment adapter contract provider-agnostic:
- `createInvoice`
- `getInvoiceStatus`
- `verifyWebhook`
- `expireInvoice` or an explicit documented fallback when provider-side expiry is passive only
- correlation metadata round-trip

## Official sources used for this review
- BTCPay Server homepage: https://btcpayserver.org/
- BTCPay Server Greenfield API: https://docs.btcpayserver.org/API/Greenfield/v1/
- NOWPayments API docs: https://nowpayments.io/payment-integration
- NOWPayments support on verification: https://support.nowpayments.io/hc/en-us/articles/21395546303389-Verification
- Cryptomus merchant API docs: https://doc.cryptomus.com/
- Cryptomus KYC verification help: https://help.cryptomus.com/legal-and-security/kyc-verification
- Coinbase Commerce docs: https://docs.cdp.coinbase.com/commerce/docs/welcome
- Coinbase identity verification help: https://help.coinbase.com/en/coinbase/getting-started/verify-my-account/how-do-i-verify-my-identity-when-using-the-mobile-app