Product Capabilities · 产品与开发者页

Integrable International Payment Gateway & API Architecture

Unified payment gateway supporting Hosted Checkout, Embedded flows, and REST APIs—connecting order creation, 3DS2 authentication, webhooks, and refunds.

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.

Payment Gateway & APIOne-Time User-Initiated Payments Only

Capability definition

Capability Definition & Scope

A reliable payment gateway isolates your core application from channel complexity. Cropay provides standardized order state machines, idempotent API design, signed asynchronous webhooks, and clear error codes across Web and mobile environments.

Use cases

Applicable Use Cases

Hosted Payment Page
Embedded Checkout Experience
Server-to-Server Order & Refund APIs
Signed Asynchronous Webhooks

Transaction types

Verified Transaction Scope

User-initiated one-time transactions
Refunds, cancellations, and status queries (subject to verified channel scope)
Excludes automated recurring billing or self-serve subscription management

Integration modes

Integration Modes

Hosted

Best for platforms preferring gateway-hosted payment pages.

Embedded

Best for platforms requiring an in-page experience with corresponding security controls.

API

Best for server-side order creation, status queries, refunds, and webhook integration.

Process steps

Integration & Processing Workflow

01
01 Server Order Creation
Your backend submits merchant order ID, amount, currency, return URL, and webhook URL to create a payment session.
02
02 Customer Checkout & 3DS2
The cardholder completes payment authorization and 3DS2 authentication via Hosted or Embedded checkout.
03
03 Webhook Signature Verification
Your server validates the webhook signature and idempotently updates the order status before fulfilling digital goods.
04
04 Reconciliation & Refund Sync
Query order statuses for edge cases and synchronize refund or dispute events with your internal ledger.

Verified scope & limitations

Verified Scope & Limitations

Verified Supported Scope

Integration Options: Hosted Checkout, Embedded checkout components, and RESTful APIs State Reliability: Idempotent requests, signed webhooks, and active order status query endpoints Security Prerequisite: Integration mode selection must match merchant PCI DSS compliance scope

Limitations & Boundaries

Browser return URLs only indicate user navigation; order fulfillment must always rely on verified server webhooks or API queries. Direct handling of raw cardholder data requires corresponding PCI DSS certification; most merchants should use Hosted or tokenized flows. All merchants must pass signature, webhook retry, timeout, and refund tests in sandbox prior to receiving live credentials.

Gateway sequence diagram

One-Time Checkout, 3DS2 & Signed Webhook Sequence Architecture

Cropay International Payment Gateway One-Time Checkout, 3D Secure 2 and Signed Webhook Sequence Diagram — Figure 1: End-to-end transaction state machine across cardholder checkout, merchant server session creation, 3DS2 authentication, and idempotent signed webhook fulfillment.

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

Should we choose Hosted Checkout or Embedded integration?

Hosted Checkout is recommended for faster launch and lower PCI compliance scope; Embedded flows require additional security review.

How should our system handle delayed or duplicate webhooks?

Design your webhook handler to verify signatures first and process events idempotently using unique transaction IDs.

When can our engineering team access the full API reference?

Detailed API endpoints, sandbox keys, and webhook schemas are provided once initial business pre-review is completed.

Business assessment

Discuss Payment Gateway Integration for Your Platform

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