Coflnet.Payments.Client 0.24.1

Payments

Handles payments, and access to digital goods and services

Configuration

Configuration is handled via asp.net configuration providers Keys with defaults are set in appsettings.json

Credit-terms rollout

At startup Payments downloads LEGAL_MANIFEST_URL and verifies the manifest, every referenced legal document, the bilingual Terms acceptance hash and the Premium declaration hashes. Startup fails if the production source is not https://coflnet.com, a file is unavailable, or a hash does not match. Terms/withdrawal version and acceptance-hash evidence for top-ups is stamped onto the § 312f payment confirmation from the verified manifest. Terms versions and hashes are not duplicated in Payments. Acceptance enforcement is canaried for internal user account 7, then applies to all accounts from 2026-08-08T00:00:00Z; earlier would-be blocks for other accounts are logged.

Google Play completion idempotency

Raw Google Play purchase tokens are not stored. Their SHA-256 hashes and Google order IDs are recorded with the completed response to make retries durable and prevent duplicate crediting. Production does not apply migrations automatically. Apply these migrations in order before deploying this code:

1. 20260728120000_PaymentConfirmationOutbox
2. 20260728122000_GooglePlayCompletions
3. 20260728180315_CoflCoinServiceDeclarations

How purchases work

1. Start top up
2. wait till payment is verified
3. (optional) plan purchase (locks some amount of balance)
4. purchase product/service

Setup

Becuase it is the esiest by default stripe is used. To configure stripe get your stripe KEY and SIGNING_SECRET from stripe.com and set them as configuration. (either modify appsettings.json or set the enviromentvariables STRIPE__KEY and STRIPE__SIGNING_SECRET)
Next create a webhook callback to /Callback/stripe that triggers on confirmed purchase.

Stripe — Minimal API Key Permissions

The Stripe API key (STRIPE__KEY) is used for Checkout Sessions and pre-capture country validation:

Webhook verification uses the signing secret. Card and Link use per-method manual capture without disabling other methods. When Stripe supplies a payment-method country it is authoritative; otherwise the country or locale supplied at session creation must match the independently looked-up IP country. Disallowed automatically captured payments are marked for manual refund and are not credited.

Restricted key: Enable only Checkout Sessions → Read & Write, Payment Intents → Read & Write, and Payment Methods → Read.

CoinGate country verification

CoinGate requests must set TopUpOptions.Country from an explicit user selection and TopUpOptions.UserIp from the trusted ingress. The service looks up the IP country using IP_COUNTRY__BASE_URL (default: https://ipapi.co/) and falls back to IP_COUNTRY__FALLBACK_BASE_URL (default: https://api.country.is/). It creates the order only when both ISO country codes match and the country is eligible.

Paypal

Paypal can be configured with PAYPAL__SECRET, PAYPAL__ID and PAYPAL__IS_SANDBOX Create a webhook callback to /Callback/paypal to allow for payments to be verified.

PayPal — Minimal API Permissions

PayPal uses the Orders API v2 (PayPalCheckoutSdk). The REST API app credentials (PAYPAL__ID / PAYPAL__SECRET) are used for three operations:

The code handles these webhook events (no API key needed — events carry their own data):

• CHECKOUT.ORDER.APPROVED → triggers capture
• PAYMENT.CAPTURE.COMPLETED → updates transaction reference
• PAYMENT.CAPTURE.REFUNDED → reverts purchase locally

No PayPal Payouts, Disputes, Subscriptions, Invoicing, Vault, or Transaction Search APIs are used.

Live app features: In the PayPal Developer Dashboard, enable only the "Accept payments" feature for the live REST API app. Disable Payouts, Customer disputes, Transaction search, Invoicing, Subscriptions, Partner referrals, Vault, and Webhooks management.

Events

This microservice can produce transaction events into a Kafka Topic. To configure it set the configuration variables KAFKA_HOST and KAFKA__TRANSACTION_TOPIC__NAME. The format and fields of the events can be seen in the TransactionEvent class