Semak setiap kaedah API yang disahkan mengikut gerbang pembayaran.

For every AIO or Direct Gateway payment, set the merchant HTTPS receiver for that transaction in payok_url. Different payments may use different URLs. PayCore makes no delivery when payok_url is omitted.

{
  "merchant_order_no": "ORDER202608310001",
  "amount": 2250,
  "currency": "TWD",
  "item_name": "PayCore test product",
  "payok_url": "https://merchant.example.com/webhooks/paycore",
  "success_url": "https://merchant.example.com/payment/success",
  "cancel_url": "https://merchant.example.com/payment/cancel"
}

• success_url and cancel_url are browser destinations only and are not proof of payment.
• Fulfil only after a verified PayCore webhook or a payment query returning status=paid.
• payok_url must be a publicly reachable HTTPS hostname. IPv4/IPv6 literals, localhost, loopback, private, and reserved IP targets are rejected.

Each PayCore API Key has its own Callback Secret. Generate and store it securely from API Key management, then use it to verify PayCore signatures.

• Keep the Callback Secret on the merchant server only; never expose it in JavaScript, browsers, apps, public source, or logs.
• The Callback Secret is not X-API-KEY and is not provider gateway_credentials.
• After rotating the Callback Secret, the old secret becomes invalid immediately and the receiver must be updated.

POST /webhooks/paycore HTTP/1.1
Content-Type: application/json
X-PayCore-Event-Id: evt_20260831080530ABCDEFGH
X-PayCore-Timestamp: 1788134730
X-PayCore-Signature: v1=4d7f...

• X-PayCore-Event-Id：Unique event identifier used for idempotency.
• X-PayCore-Timestamp：Unix timestamp when PayCore generated the notification.
• X-PayCore-Signature：HMAC-SHA256 signature calculated with the Callback Secret.

PayCore sends payment.paid after confirming payment. AIO preserves the public master payment, while Direct Gateway uses the actual gateway and method.

PayCore AIO

{
  "event_id": "evt_20260831080530ABCDEFGH",
  "event_type": "payment.paid",
  "payment_no": "PAY20260831080000ABCDEFGH",
  "merchant_order_no": "ORDER202608310001",
  "gateway": "paycore",
  "method": "aio",
  "amount": 2250,
  "currency": "twd",
  "status": "paid",
  "paid_at": "2026-08-31T08:05:30+08:00"
}

Direct Gateway

{
  "event_id": "evt_20260831081530DIRECT01",
  "event_type": "payment.paid",
  "payment_no": "PAY20260831081000DIRECT01",
  "merchant_order_no": "ORDER202608310002",
  "gateway": "ecpay",
  "method": "credit",
  "amount": 980,
  "currency": "twd",
  "status": "paid",
  "paid_at": "2026-08-31T08:15:30+08:00"
}

• event_id：Unique event identifier; it remains unchanged during retries.
• event_type：The current successful-payment event is payment.paid.
• payment_no：Public PayCore payment number.
• merchant_order_no：Merchant order number supplied when creating payment.
• gateway、method：AIO uses paycore/aio; Direct uses the actual gateway and method.
• amount、currency：Must be checked against the merchant order.
• status：Only paid means PayCore has confirmed payment.
• paid_at：ISO-8601 payment completion time including timezone.

Use the exact raw request body for signature verification. Do not parse, reorder, or re-encode JSON first. In production, reject notifications more than five minutes away from the current time and use hash_equals for constant-time comparison.

signed_payload = X-PayCore-Timestamp + "." + raw_request_body
expected_signature = "v1=" + HMAC-SHA256(signed_payload, callback_secret)

Store the Callback Secret in the merchant Laravel environment and read it through config/services.php; never hard-code it in application code.

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;

Route::post('/webhooks/paycore', function (Request $request) {
    $rawBody = $request->getContent();
    $timestamp = (string) $request->header('X-PayCore-Timestamp', '');
    $eventId = (string) $request->header('X-PayCore-Event-Id', '');
    $received = (string) $request->header('X-PayCore-Signature', '');
    $secret = (string) config('services.paycore.callback_secret');

    if (! ctype_digit($timestamp) || abs(time() - (int) $timestamp) > 300) {
        return response('Invalid timestamp', 401);
    }

    $expected = 'v1=' . hash_hmac(
        'sha256',
        $timestamp . '.' . $rawBody,
        $secret
    );

    if ($eventId === '' || ! hash_equals($expected, $received)) {
        return response('Invalid signature', 401);
    }

    $payload = json_decode($rawBody, true, 512, JSON_THROW_ON_ERROR);

    if (($payload['event_id'] ?? null) !== $eventId) {
        return response('Event ID mismatch', 422);
    }

    if (($payload['event_type'] ?? null) !== 'payment.paid'
        || ($payload['status'] ?? null) !== 'paid') {
        return response('Unsupported event', 422);
    }

    // Enforce idempotency with a UNIQUE event_id, verify the order and amount,
    // then commit the merchant transaction before returning HTTP 2xx.

    return response('OK', 200);
});

Return any HTTP 2xx only after signature verification and the merchant transaction complete. PayCore determines delivery success from the HTTP status only; the response body does not require a fixed JSON format.

HTTP/1.1 200 OK
Content-Type: text/plain

OK

For non-2xx responses, connection failures, or timeouts, PayCore makes up to five total delivery attempts by default:

1. Immediately after payment succeeds.
2. One minute after the first failure.
3. Five minutes after the second failure.
4. Fifteen minutes after the third failure.
5. Sixty minutes after the fourth failure for the final attempt.

event_id remains unchanged across retries. Enforce a UNIQUE event_id or equivalent idempotency lock to prevent duplicate fulfilment.

1. Preserve the raw request body.
2. Validate the timestamp tolerance.
3. Verify the HMAC using the Callback Secret for the API Key that created the payment.
4. Compare header and body event_id values and enforce idempotency by event_id.
5. Verify payment_no, merchant_order_no, amount, currency, and status=paid.
6. When needed, call GET /api/paycore/payments/{paymentNo} to confirm status again.
7. Return HTTP 2xx only after completing the merchant transaction.

Common mistakes

• Verifying re-encoded JSON instead of the raw body, causing signature mismatch.
• Using X-API-KEY, a provider HashKey, or gateway_credentials as the Callback Secret.
• Failing to verify the amount and merchant order number after receiving payment.paid.
• Treating a success_url browser return as proof of payment.
• Not enforcing idempotency by event_id and processing retries more than once.
• Returning HTTP 200 before the internal transaction completes, preventing retries after a later failure.