EMSCTS Payment API Integration Guide

字段说明 (Field Descriptions)

Field	Description
`frontend`	UUID per your website (we can add new site UUIDs on request)
`address`	Billing street address
`state`	Required for US/CA; optional elsewhere
`country`	ISO‑2 country code (required)
`postal_code`	Postal or ZIP code (required)
`brand`	Your brand name (displayed on payment page)
`order_id`	Your internal order identifier (required)
`amount`	string, two‑digit precision (required)
`currency`	Currency code (e.g. USD, HKD) (required)
`first_name`	Customer name (required)
`last_name`	Customer name (required)
`email`	Customer email (required)
`phone`	Customer phone (required)
`subject`	Description of charge (required)
`return_url`	URL to redirect customer after payment (required)
`notify_url`	Server endpoint for payment notifications (required)
`env`	`sandbox` or `production` (required)

1. 获取支付链接 (Initiate Payment)

Use this cURL to retrieve your payment_link:

curl -X POST https://pay.emscts.com/checkout/checkout \
  -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "frontend":      "SITE_UUID",
    "order_id":      "ORDER_12345",
    "amount":        "100.00",
    "currency":      "USD",
    "first_name":    "John",
    "last_name":     "Doe",
    "email":         "john@doe.com",
    "phone":         "12345678",
    "address":       "1 Bay Street",
    "state":         "CA",
    "country":       "US",
    "postal_code":   "90210",
    "brand":         "YourBrand",
    "subject":       "货物",
    "notify_url":    "https://your.site/checkout/callback",
    "return_url":    "https://your.site/checkout/return",
    "env":           "sandbox",
    "sign":          "CALCULATED_SIGNATURE"
  }'

Example Response

{
  "payment_link": "https://pay.emscts.com/checkout/pay/e6dcde1b-5b56-4ac4-834c-5ddd4df724af"
}

2. 签名生成 (Signature Creation)

Before sending, compute your request sign:

php
// 1. Sort parameters alphabetically
ksort($params);

// 2. Build a query string
$signingString = http_build_query($params);

// 3. Append your secret code
$secretCode = 'YOUR_SECRET_CODE';
$signingString .= $secretCode;

// 4. SHA‑512 hash
$signature = hash('SHA512', $signingString);

// 5. Add to payload
$params['sign'] = $signature;

// 6. Send via cURL / HTTP client

3. 签名验证示例 (Return & Callback Verification)

After payment or 3DS, you’ll receive:

{
  "amount":             "100.00",
  "currency":           "USD",
  "merchant_reference": "c5e4c3b8-400a-4925-8eb1-23a4ab5ee3b3",
  "request_reference":  "4a6e3e0e-abeb-47c1-a60a-b7d99fb392c5",
  "status":             "1",
  "sign":               "23fba0060475173495cf1d34fae85b1f0131e2f73ba906be7f624ce89de795e1dea0c7133a1603a0b304f435f685d1d53e1ffbab553b1efe343685f5d8449fa9"
}

Validate exactly as above:

php
// 1. Extract & remove 'sign'
$received = $_REQUEST['sign'] ?? '';
unset($_REQUEST['sign']);

// 2. Sort & build
ksort($_REQUEST);
$qs = http_build_query($_REQUEST);

// 3. Append your secret
$qs .= $secretCode;

// 4. Hash
$calc = hash('SHA512', $qs);

// 5. Compare
if (hash_equals($calc, $received)) {
  // Valid
} else {
  // Invalid signature
}

Signature Generator

Fill in each field, supply your secret, then click Generate Signature.

frontend (SITE UUID) order_id

amount

currency

first_name

last_name

email phone address

state (US/CA only)

country

postal_code brand subject return_url notify_url env Secret Code