Cropay Developer Center & Payment Integration Architecture
Technical overview of Cropay’s payment gateway integration—covering API authentication, order sessions, 3DS2 redirects, signed webhooks, and sandbox testing.
Scope & readiness
Business & Capability Verification
Supported regions, card schemes, settlement cycles, and technical integration modes are verified item by item based on your merchant entity, business model, and acquiring approval.
Our engineering philosophy is simple: technical documentation must match live, verified gateway behavior. Below is the architectural blueprint for integrating Cropay; full endpoint references and sandbox credentials are provisioned after initial business pre-review.
Core Technical Integration Modules
Authentication & Request Signing
Authenticate server-to-server requests using merchant API credentials and cryptographic signatures with idempotency keys.
Payment Session & 3DS2 Lifecycle
Create one-time payment orders, handle 3DS2 challenge redirects, and manage order expiration timers.
Signed Webhooks & Retry Policy
Verify webhook signatures, process payment and refund events idempotently, and return HTTP 200 acknowledgments.
Order Query & Refund Endpoints
Poll order statuses for network edge cases and trigger full or partial refunds programmatically.
Standard Engineering Integration Path
01 Business Pre-Review & Sandbox Provisioning
Submit your business profile to receive sandbox merchant credentials and API specifications.
02 Order & Webhook Implementation
Build server-side session creation, signature verification, and idempotent webhook handlers.
03 Sandbox Test Matrix Execution
Verify test cases for 3DS2 success, 3DS2 failure, insufficient funds, timeout, and refund callbacks.
04 Production Cutover Check
Bind whitelisted production domains, configure live webhook endpoints, and switch to production keys.
Capabilities, Evidence & Compliance Boundaries
Server-Side Authority Only
Never fulfill orders based solely on client-side return URL parameters; always verify server webhooks or query responses.
Strict Credential Isolation
Keep API secret keys and webhook signing secrets strictly on your backend server; never expose them in frontend bundles.
No Unverified SDK Claims
Supported languages, SDKs, and webhook payload schemas are governed by the official specification version issued during onboarding.
Gateway sequence diagram
One-Time Checkout, 3DS2 & Signed Webhook Sequence Architecture
Technical comparison matrix
Hosted vs. Embedded vs. Server API Integration Comparison
Comparison of Cropay payment gateway integration modes across PCI DSS compliance scope, 3DS2 handling, and engineering effort.
| Integration Mode | PCI DSS Scope | Checkout UX & Control | 3DS2 & Webhook Flow | Recommended Platform Scenario |
|---|---|---|---|---|
| Hosted Checkout | Lowest (SAQ A eligible; gateway hosts card entry) | Redirect to Cropay-hosted responsive checkout page | Gateway manages 3DS2 redirect; server verifies signed webhook | Fast cross-border launch for web & mobile dating/streaming platforms |
| Embedded Checkout | Moderate (requires approved security & domain review) | In-page embedded payment component within merchant UI | Component handles 3DS2 challenge frame + server webhook confirmation | Platforms requiring uninterrupted in-app/in-room top-up experience |
| Server-to-Server API | Strictest (requires full PCI DSS certification if handling raw PAN) | Full custom merchant-controlled order & status orchestration | Idempotent REST session creation + HMAC/RSA webhook + query API | High-concurrency wallet ledgers, automated refund & reconciliation sync |
Integration payload & webhook blueprint
One-Time Payment Session & Signed Webhook Reference Pattern
Architectural payload pattern illustrating idempotent one-time order creation and server-side webhook verification. Live sandbox endpoints and merchant keys are issued after business pre-review.
1. POST /v1/payment-sessions (Server-to-Server)
{
"merchantOrderId": "ord_20261026_98231",
"idempotencyKey": "idem_7f83b165-4a2b-4c9e",
"amount": "29.99",
"currency": "USD",
"captureMethod": "automatic",
"transactionModel": "one_time_user_initiated",
"threeDSecure": { "mode": "dynamic_step_up" },
"productContext": {
"itemCode": "coin_pack_300",
"itemDescription": "300 Virtual Coins (One-Time Purchase)"
},
"returnUrl": "https://merchant.example.com/checkout/return",
"webhookUrl": "https://merchant.example.com/api/webhooks/cropay"
}2. Signed Asynchronous Webhook Event (payment.succeeded)
// Header: X-Cropay-Signature: t=1761472800,v1=hmac_sha256(secret, t + "." + rawBody)
{
"eventId": "evt_01J9Z8K4M2P5X",
"eventType": "payment.succeeded",
"gatewayTransactionId": "txn_cp_88492019",
"merchantOrderId": "ord_20261026_98231",
"amount": "29.99",
"currency": "USD",
"threeDSecureResult": {
"version": "2.2.0",
"authenticated": true,
"flow": "frictionless"
},
"capturedAt": "2026-10-26T09:00:00Z"
}FAQ
Frequently Asked Questions
How can our engineering team obtain sandbox API keys?
Submit your project details via the Contact page. Once initial business pre-review is completed, we issue sandbox credentials and the API specification.
What happens if our webhook endpoint is temporarily unreachable?
The gateway retries unacknowledged webhooks on a backoff schedule, and your server can also call the Order Query API to reconcile status.
Does the API support automated recurring billing or subscription webhooks?
No. The API currently supports one-time user-initiated payment sessions, status queries, cancellations, and refunds.
Business assessment
Request Sandbox Access & API Documentation
Submit your corporate entity, website or app URL, target markets, billing items, transaction model, and preferred integration mode for a structured onboarding review.
Submit Onboarding Assessment