feat(payment): standalone ZarinPal broker on pay.flatrender.ir
A generic multi-client payment gateway so FlatRender, meezi.ir and bargevasat.ir can all pay through ZarinPal's single verified callback domain (pay.flatrender.ir). New Go service services/payment (clones the notification skeleton + vendored deps): - migration 31_payment_broker.sql — `payment` schema: client_apps, transactions, webhook_deliveries. - ZarinPal v4 client ported from the proven identity PaymentService (request.json -> StartPay -> verify.json; codes 100/101). - client API: POST /v1/pay/request + /v1/pay/inquiry, authed by X-Api-Key + HMAC body signature; GET /callback/zarinpal (the single verified endpoint) verifies, then 302s the user back to the site's return_url (signed) and fires a signed, retried webhook. - per-client ZarinPal merchant override (default = shared merchant); amount stored canonically in Rial, unit to ZarinPal env-configurable. - admin API /v1/admin/* (FlatRender admin JWT): client-app CRUD + key issue/rotate + transactions list. Deploy wiring: payment-svc in docker-compose.v2.yml (host port 1607), pay.flatrender.ir server block in mirror-nginx conf, ENV_FILE + README updates (cert SAN + manual migration note). Admin UI: src/components/admin/PaymentsAdmin.tsx (client apps with one-time key reveal + rotate, transactions table) + /admin/payments page + nav link + fa/en strings; pay-admin proxy route to payment-svc. Docs/SDK: deploy/PAYMENTS.md (integration contract) + deploy/sdk/flatpay.js (zero-dep Node client + webhook verifier) for meezi/any site. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
soroush.asadi
@@ -0,0 +1,110 @@
|
||||
package models
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"time"
|
||||
|
||||
"github.com/google/uuid"
|
||||
)
|
||||
|
||||
// APIError is the standard error envelope across FlatRender services.
|
||||
type APIError struct {
|
||||
Code string `json:"code"`
|
||||
Message string `json:"message"`
|
||||
}
|
||||
|
||||
// ── Client apps (tenants of the broker — each site that pays through it) ───────
|
||||
|
||||
type ClientApp struct {
|
||||
ID uuid.UUID `json:"id"`
|
||||
TenantID *uuid.UUID `json:"tenant_id,omitempty"`
|
||||
Name string `json:"name"`
|
||||
Slug string `json:"slug"`
|
||||
APIKey string `json:"api_key"`
|
||||
Secret string `json:"secret,omitempty"` // returned only on create / rotate
|
||||
ZarinPalMerchantID *string `json:"zarinpal_merchant_id,omitempty"`
|
||||
ZarinPalSandbox *bool `json:"zarinpal_sandbox,omitempty"`
|
||||
AllowedReturnOrigins []string `json:"allowed_return_origins"`
|
||||
WebhookURL *string `json:"webhook_url,omitempty"`
|
||||
IsActive bool `json:"is_active"`
|
||||
CreatedAt time.Time `json:"created_at"`
|
||||
UpdatedAt time.Time `json:"updated_at"`
|
||||
}
|
||||
|
||||
// ── Transactions ──────────────────────────────────────────────────────────────
|
||||
|
||||
type Transaction struct {
|
||||
ID uuid.UUID `json:"id"`
|
||||
ClientAppID uuid.UUID `json:"client_app_id"`
|
||||
ClientSlug string `json:"client_slug,omitempty"` // joined for admin views
|
||||
Status string `json:"status"`
|
||||
Gateway string `json:"gateway"`
|
||||
AmountRial int64 `json:"amount_rial"`
|
||||
Currency string `json:"currency"`
|
||||
Description *string `json:"description,omitempty"`
|
||||
ClientRef *string `json:"client_ref,omitempty"`
|
||||
ReturnURL string `json:"return_url"`
|
||||
Metadata json.RawMessage `json:"metadata,omitempty"`
|
||||
PayerMobile *string `json:"payer_mobile,omitempty"`
|
||||
PayerEmail *string `json:"payer_email,omitempty"`
|
||||
Authority *string `json:"authority,omitempty"`
|
||||
RefID *string `json:"ref_id,omitempty"`
|
||||
CardPan *string `json:"card_pan,omitempty"`
|
||||
FeeRial *int64 `json:"fee_rial,omitempty"`
|
||||
GatewayResponse json.RawMessage `json:"gateway_response,omitempty"`
|
||||
FailureReason *string `json:"failure_reason,omitempty"`
|
||||
PaidAt *time.Time `json:"paid_at,omitempty"`
|
||||
FailedAt *time.Time `json:"failed_at,omitempty"`
|
||||
ExpiresAt *time.Time `json:"expires_at,omitempty"`
|
||||
CreatedAt time.Time `json:"created_at"`
|
||||
UpdatedAt time.Time `json:"updated_at"`
|
||||
}
|
||||
|
||||
// Transaction status values (kept as plain text — no PG enum, for flexibility).
|
||||
const (
|
||||
StatusCreated = "Created"
|
||||
StatusPending = "Pending"
|
||||
StatusPaid = "Paid"
|
||||
StatusFailed = "Failed"
|
||||
StatusCancelled = "Cancelled"
|
||||
StatusExpired = "Expired"
|
||||
)
|
||||
|
||||
// ── Client-facing request/response shapes ─────────────────────────────────────
|
||||
|
||||
// PayRequest is the body a client site POSTs to /v1/pay/request.
|
||||
type PayRequest struct {
|
||||
Amount int64 `json:"amount"` // in `currency` units
|
||||
Currency string `json:"currency,omitempty"` // "IRR" (Rial, default) or "IRT" (Toman)
|
||||
Description string `json:"description,omitempty"`
|
||||
ClientRef string `json:"client_ref,omitempty"`
|
||||
ReturnURL string `json:"return_url"`
|
||||
Mobile string `json:"mobile,omitempty"`
|
||||
Email string `json:"email,omitempty"`
|
||||
Metadata json.RawMessage `json:"metadata,omitempty"`
|
||||
}
|
||||
|
||||
// PayResponse is returned from /v1/pay/request.
|
||||
type PayResponse struct {
|
||||
ID uuid.UUID `json:"id"`
|
||||
Status string `json:"status"`
|
||||
PaymentURL string `json:"payment_url"`
|
||||
Authority string `json:"authority"`
|
||||
AmountRial int64 `json:"amount_rial"`
|
||||
}
|
||||
|
||||
// WebhookPayload is the signed body POSTed to a client's webhook_url.
|
||||
type WebhookPayload struct {
|
||||
Event string `json:"event"` // payment.paid | payment.failed
|
||||
ID uuid.UUID `json:"id"`
|
||||
Status string `json:"status"`
|
||||
AmountRial int64 `json:"amount_rial"`
|
||||
Currency string `json:"currency"`
|
||||
ClientRef string `json:"client_ref,omitempty"`
|
||||
RefID string `json:"ref_id,omitempty"`
|
||||
Authority string `json:"authority,omitempty"`
|
||||
CardPan string `json:"card_pan,omitempty"`
|
||||
Metadata json.RawMessage `json:"metadata,omitempty"`
|
||||
PaidAt *time.Time `json:"paid_at,omitempty"`
|
||||
CreatedAtTs int64 `json:"ts"`
|
||||
}
|
||||
Reference in New Issue
Block a user