คู่มือเชื่อมต่อ API

# Bash: set CHECKSLIPS_TENANT_ID and CHECKSLIPS_API_KEY on your server first.
curl --fail-with-body --max-time 90 https://api.checkslips.com/v1/verify \
  -H "X-Tenant-ID: $CHECKSLIPS_TENANT_ID" \
  -H "Authorization: Bearer $CHECKSLIPS_API_KEY" \
  -F "image=@/path/to/slip.jpg" \
  -F "match_amount=100.00" \
  -F "receiver_validation_mode=tenant" \
  -F "remark=order-123"

# Save data.verification_id from the response, then set VERIFICATION_ID.
# Repeat this GET every 3 seconds while status is pending or processing.
curl --fail-with-body --max-time 20 \
  "https://api.checkslips.com/v1/verify/$VERIFICATION_ID" \
  -H "X-Tenant-ID: $CHECKSLIPS_TENANT_ID" \
  -H "Authorization: Bearer $CHECKSLIPS_API_KEY"

{
  "success": true,
  "data": {
    "verification_id": "11111111-2222-4333-8444-555555555555",
    "status": "processing",
    "estimated_completion_ms": 60000,
    "expected_receiver_commitment": null
  },
  "message": "Verification queued successfully"
}

# Server-side Bash. Use the order's trusted amount and destination, not browser input.
# CHECKSLIPS_EXPECTED_* must come from the merchant's stored order destination.
curl --fail-with-body --max-time 90 https://api.checkslips.com/v1/verify \
  -H "X-Tenant-ID: $CHECKSLIPS_TENANT_ID" \
  -H "Authorization: Bearer $CHECKSLIPS_API_KEY" \
  -F "image=@/path/to/slip.jpg" \
  -F "match_amount=100.00" \
  -F "remark=order-123" \
  -F "receiver_validation_mode=request" \
  -F "expected_receiver_bank_code=$CHECKSLIPS_EXPECTED_BANK" \
  -F "expected_receiver_account_number=$CHECKSLIPS_EXPECTED_ACCOUNT" \
  -F "expected_receiver_account_name=$CHECKSLIPS_EXPECTED_NAME"

# Persist data.verification_id AND data.expected_receiver_commitment from this 202
# alongside the original order and tenant. Never replace them from a later result.
# Poll the SAME id using the GET example above, then call canAcceptPayment.

async function canAcceptSlipOnly(result, order, confirmMerchantReceiver) {
  if (!result || !order || typeof confirmMerchantReceiver !== 'function') return false;
  if (result.is_sandbox !== false || result.status !== 'verified' ||
      result.authenticity_status !== 'verified' || result.bank_record_found !== true ||
      result.is_duplicate !== false || result.receiver_validation_mode !== 'none') return false;
  if (order.paymentStatus !== 'unpaid' || !order.expectedDestination ||
      typeof order.id !== 'string' || !order.id || result.remark !== order.id ||
      typeof order.verificationId !== 'string' || !order.verificationId ||
      result.verification_id !== order.verificationId ||
      typeof result.trans_ref !== 'string' || !result.trans_ref.trim()) return false;
  if (!Array.isArray(result.flags) || result.flags.some(flag =>
      typeof flag !== 'string' || flag.includes('DUPLICATE'))) return false;
  if (typeof result.amount !== 'number' || !Number.isFinite(result.amount) || result.amount <= 0) return false;
  const satang = Math.round(result.amount * 100);
  if (!Number.isSafeInteger(order.amountSatang) || order.amountSatang <= 0 ||
      !Number.isSafeInteger(satang) || Math.abs(result.amount * 100 - satang) >= 0.000001 ||
      satang !== order.amountSatang) return false;
  const transferred = Date.parse(result.transaction_date);
  const opened = Date.parse(order.createdAt), expires = Date.parse(order.expiresAt);
  if (![transferred, opened, expires].every(Number.isFinite) || expires < opened ||
      transferred < opened - 60000 || transferred > expires) return false;
  try {
    return await confirmMerchantReceiver({ receiver: result.receiver,
      receiverBankCode: result.receiver_bank_code, receiverType: result.receiver_type,
      transactionReference: result.trans_ref, expectedDestination: order.expectedDestination }) === true;
  } catch { return false; }
}

// Send receiver_validation_mode=none and remark=the stored order id.
// Save data.verification_id from POST 202 under the authenticated tenant.
// Read the final result from the authenticated API; never accept result JSON from a browser.
// confirmMerchantReceiver is YOUR server-owned recipient validation function.
// It must check the bank/payment rail and account against the order's trusted destination.
// If masking leaves insufficient evidence, return false for manual review.
// Do not substitute matching names or last four digits alone for destination proof.
// None-mode payment_assessment.ready=false is expected: CheckSlips did not check your destination.

// Before credit, in ONE database transaction:
// Lock the order; require unpaid; rerun this guard against its stored binding.
// Claim UNIQUE (tenant_id, verification_id) AND UNIQUE (tenant_id, trans_ref).
// Record the order, receipt, and credit/ledger once; commit all or roll back all.
// Webhook and polling retries must return the existing outcome on a unique conflict.

// Synthetic test only. This does not call a bank or confirm a real payment.
const base = 'https://api.checkslips.com/v1/sandbox';
const headers = { 'X-Tenant-ID': process.env.CHECKSLIPS_TENANT_ID };
const pause = ms => new Promise(resolve => setTimeout(resolve, ms));
async function readResult(id, maxWaitMs = 60000) {
  const started = Date.now();
  const terminal = new Set(['verified', 'flagged', 'rejected', 'failed', 'duplicate']);
  while (true) {
    const response = await fetch(base + '/verify/' + encodeURIComponent(id), {
      headers, signal: AbortSignal.timeout(15000)
    });
    if (!response.ok) throw new Error('GET failed: ' + response.status + '; keep id=' + id);
    const body = await response.json();
    if (!body.success || !body.data) throw new Error('Invalid response; keep id=' + id);
    const result = body.data;
    if (terminal.has(result.status)) return result;
    if (!['pending', 'processing'].includes(result.status)) {
      throw new Error('Unknown status; keep id=' + id);
    }
    if (Date.now() - started >= maxWaitMs) return { ...result, verification_id: id };
    await pause(3000);
  }
}

const acceptedResponse = await fetch(base + '/verify?async_mode=true&scenario=success', {
  method: 'POST', headers
});
if (acceptedResponse.status !== 202) throw new Error('Sandbox was not accepted');
const accepted = await acceptedResponse.json();
const id = accepted.data?.verification_id;
if (!accepted.success || !id || accepted.data.is_sandbox !== true) throw new Error('Invalid Sandbox job');
// Save id before polling; readResult uses the same 3-second polling above.
const resultUrl = base + '/verify/' + encodeURIComponent(id);
// A success fixture completes after about 2 seconds; pending stays processing.
// State expires after 15 minutes. Keep GET polling separate from POST submission.
const result = await readResult(id);
if (result.is_sandbox !== true) throw new Error('Expected synthetic evidence');

if (['pending', 'processing'].includes(result.status)) {
  console.log('Still processing; resume GET later with id:', id);
} else {
  // After completion, retrieve a signed, deterministic local webhook fixture:
  const response = await fetch(resultUrl + '/webhook', { headers });
  if (!response.ok) throw new Error('Fixture is not ready');
  const fixture = await response.json();
  // Feed fixture.raw_payload + fixture.headers to your LOCAL webhook handler twice.
  // Use fixture.signing_secret only in the isolated Sandbox test configuration.
  // Both deliveries have the same event_id; your handler must record ONE outcome.
  // delivery_sent is false: CheckSlips has not sent any callback.
  console.log('Synthetic fixture only:', fixture.payload?.event_id);
}
// Never use this public test secret or is_sandbox:true evidence in production.

import crypto from 'node:crypto';
function validSignature(rawBody, signature, secret) {
  if (!secret || typeof signature !== 'string' || !/^sha256=[a-f0-9]{64}$/.test(signature)) return false;
  const supplied = Buffer.from(signature.slice(7), 'hex');
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest();
  return supplied.length === expected.length && crypto.timingSafeEqual(supplied, expected);
}
// For Express: use express.raw({ type: 'application/json' }) BEFORE express.json().
// validSignature(req.body, req.get('X-SlipVerify-Signature'), process.env.CHECKSLIPS_WEBHOOK_SECRET)
// Reject false with 401. Parse req.body only after validation.
// Persist event.event_id + event.data to a durable queue/database before returning 2xx.
// Use event_id as a unique key; a repeated event must not confirm an order twice.