Stripe Payment Gateway

คู่มือการใช้งาน API

Base URL https://api-payment-stripe.numedapp.com Currency USD Version v1.0

API Endpoints

20+

Payment · Webhook · Audit

Payment Methods

Link · Intent · Checkout

Database

PostgreSQL

History · Logs · Callbacks

📋

ภาพรวม

API สำหรับเชื่อมต่อ Stripe Payment Gateway รองรับ Payment Link, Payment Intent, Checkout Session, Webhook และ Audit Log

1ระบบของคุณเรียก POST /api/payments/generate-url

2API สร้าง Stripe Payment Link → คืน paymentUrl

3ส่ง link ให้ลูกค้าเปิดชำระเงินผ่าน Stripe

4Stripe ส่ง Webhook → POST /api/webhooks/stripe

5API บันทึกประวัติ + ส่ง callback ไประบบของคุณ

{ }

รูปแบบ Response

ทุก API ตอบกลับเป็น JSON ในรูปแบบเดียวกัน

JSON

{
  "status": true,
  "code": 200,
  "message": "OK",
  "data": { }
}

// Error Response
{
  "status": false,
  "code": 400,
  "message": "error message",
  "data": null
}

💚

Health Check

ตรวจสอบสถานะระบบ, database และ Stripe config

GET /api/health Health check แบบละเอียด

Response

JSON

{
  "status": true,
  "code": 200,
  "message": "OK",
  "data": {
    "service": "api-payment-stripe",
    "version": "1.0.0",
    "uptime": 120,
    "checks": {
      "database": { "status": "up", "latencyMs": 68 },
      "stripe": { "status": "up", "secretKey": true },
      "callback": { "status": "optional", "configured": false }
    }
  }
}

GET /api/health/live Liveness probe

Response

JSON

{ "status": true, "code": 200, "message": "OK", "data": { "status": "alive" } }

GET /api/health/ready Readiness probe

Response

JSON

{ "status": true, "code": 200, "message": "OK", "data": { "status": "ready" } }

คืน HTTP 503 ถ้า database หรือ Stripe ไม่พร้อม

🔗

Payment Link

สร้าง Stripe Payment Link ให้ลูกค้าเปิดชำระเงินผ่านหน้า hosted ของ Stripe

POST /api/payments/generate-url สร้าง URL ชำระเงิน

Request Body

Field	Type	Description
`amount`required	number	จำนวนเงิน (USD)
`productName`	string	ชื่อสินค้า/บริการ
`description`	string	รายละเอียด
`successUrl`	string	URL redirect หลังชำระสำเร็จ
`firstName`	string	ชื่อ
`familyName`	string	นามสกุล
`uid`	string	รหัสผู้ใช้ / รหัสอ้างอิง
`metadata`	object	ข้อมูลเพิ่มเติม เช่น orderId

ตัวอย่าง cURL

cURL

curl -X POST https://api-payment-stripe.numedapp.com/api/payments/generate-url \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500,
    "productName": "Premium Plan",
    "description": "Order #1234",
    "firstName": "John",
    "familyName": "Doe",
    "uid": "USER001",
    "successUrl": "https://api-payment-stripe.numedapp.com/success",
    "metadata": { "orderId": "1234" }
  }'

Response

JSON

{
  "status": true,
  "code": 201,
  "message": "Payment URL generated",
  "data": {
    "paymentUrl": "https://buy.stripe.com/xxx",
    "paymentLinkId": "plink_xxx",
    "amount": 500,
    "currency": "usd",
    "active": true,
    "firstName": "John",
    "familyName": "Doe",
    "uid": "USER001",
    "metadata": {
      "orderId": "1234",
      "firstName": "John",
      "familyName": "Doe",
      "uid": "USER001"
    }
  }
}

POST /api/payments/payment-link สร้าง Payment Link

Request body เหมือน generate-url แต่ response คืน url แทน paymentUrl

GET /api/payments/payment-link/:paymentLinkId ดูข้อมูล Payment Link

POST /api/payments/payment-link/:id/deactivate ปิดการใช้งาน Link

💳

Payment Intent

ฝังฟอร์มชำระเงินใน frontend ด้วย Stripe Elements

POST /api/payments/payment-intent สร้าง Payment Intent

Request Body

Field	Type	Description
`amount`required	number	จำนวนเงิน (USD)
`description`	string	รายละเอียด
`customerEmail`	string	อีเมลลูกค้า
`metadata`	object	ข้อมูลเพิ่มเติม

Response

JSON

{
  "status": true,
  "code": 201,
  "message": "Payment intent created",
  "data": {
    "clientSecret": "pi_xxx_secret_xxx",
    "paymentIntentId": "pi_xxx",
    "amount": 50000,
    "currency": "usd",
    "status": "requires_payment_method"
  }
}

GET /api/payments/payment-intent/:id ดูสถานะการชำระ

GET /api/payments/payment-intent/:id/session ดึง session สำหรับหน้าชำระเงิน

GET /api/payments/config ดึง Stripe Publishable Key

🛒

Checkout Session

สร้าง Stripe Checkout Session แบบ redirect

POST /api/payments/checkout-session สร้าง Checkout Session

Request Body

Field	Type	Description
`amount`required	number	จำนวนเงิน (USD)
`productName`	string	ชื่อสินค้า
`successUrl`required	string	URL หลังชำระสำเร็จ
`cancelUrl`required	string	URL เมื่อยกเลิก
`customerEmail`	string	อีเมลลูกค้า

Response

JSON

{ "status": true, "code": 201, "message": "Checkout session created", "data": { "sessionId": "cs_xxx", "url": "https://checkout.stripe.com/..." } }

↩️

Refund

คืนเงินให้ลูกค้าผ่าน Payment Intent ID

POST /api/payments/refund คืนเงิน

Request Body

Field	Type	Description
`paymentIntentId`required	string	Payment Intent ID
`amount`	number	จำนวนเงินคืน (ไม่ใส่ = คืนเต็มจำนวน)
`reason`	string	duplicate / fraudulent / requested_by_customer

ตัวอย่าง cURL

cURL

curl -X POST https://api-payment-stripe.numedapp.com/api/payments/refund \
  -H "Content-Type: application/json" \
  -d '{ "paymentIntentId": "pi_xxx" }'

📊

รายการชำระเงิน

ดูรายการชำระเงินที่บันทึกใน PostgreSQL

GET /api/payments ดูรายการชำระเงินทั้งหมด

Query Parameters

Param	Description
`status`	pending · succeeded · failed · refunded
`limit`	จำนวนรายการ (default: 50, max: 100)
`offset`	offset สำหรับ pagination

🔔

Stripe Webhook

รับ callback จาก Stripe เมื่อมี event เกิดขึ้น

POST /api/webhooks/stripe รับ Webhook จาก Stripe

การตั้งค่า Stripe Dashboard

Steps

1. Developers → Webhooks → Add endpoint
2. URL: https://api-payment-stripe.numedapp.com/api/webhooks/stripe
3. เลือก events:
   - payment_intent.succeeded
   - payment_intent.payment_failed
   - checkout.session.completed
   - charge.refunded
4. คัดลอก Signing secret → STRIPE_WEBHOOK_SECRET

ทดสอบ local ด้วย Stripe CLI

Shell

stripe listen --forward-to https://api-payment-stripe.numedapp.com/api/webhooks/stripe
stripe trigger checkout.session.completed

GET /api/webhooks/config ดู webhook config

📡

Events & Callback

ดู webhook events และ callback logs ที่บันทึกใน database

GET /api/webhooks/events ดู webhook events ล่าสุด

Query Parameters

Param	Description
`limit`	จำนวนรายการ (default: 50)
`offset`	pagination offset

GET /api/webhooks/callbacks ดู callback logs

Query: `success` (true/false), `webhookEventId`

Callback Payload ที่ส่งไประบบของคุณ

JSON

{
  "eventId": "evt_xxx",
  "eventType": "checkout.session.completed",
  "action": "checkout_completed",
  "message": "Checkout session completed",
  "data": {
    "sessionId": "cs_xxx",
    "paymentIntentId": "pi_xxx",
    "amountTotal": 500,
    "currency": "usd",
    "paymentStatus": "paid",
    "metadata": { "orderId": "1234" }
  }
}

🕐

ประวัติการชำระเงิน

ดู timeline ทุก event ของการชำระเงิน

GET /api/payments/history ดูประวัติทุก event

Query Parameters

Param	Description
`paymentId`	กรองตาม payment ID
`paymentIntentId`	กรองตาม Payment Intent
`eventType`	payment_created · payment_succeeded · refund_created
`limit` / `offset`	pagination

📝

System Logs

ดู system logs ที่บันทึกจาก API requests, webhooks และ errors

GET /api/logs/logs ดู system logs

Query Parameters

Param	Description
`level`	info · warn · error
`source`	http · webhook · payment · error
`limit` / `offset`	pagination

คู่มือการใช้งาน API

ภาพรวม

รูปแบบ Response

Health Check

Response

Response

Response

Payment Link

Request Body

ตัวอย่าง cURL

Response

Payment Intent

Request Body

Response

Checkout Session

Request Body

Response

Refund

Request Body

ตัวอย่าง cURL

รายการชำระเงิน

Query Parameters

Stripe Webhook

การตั้งค่า Stripe Dashboard

ทดสอบ local ด้วย Stripe CLI

Events & Callback

Query Parameters

Query: success (true/false), webhookEventId

Callback Payload ที่ส่งไประบบของคุณ

ประวัติการชำระเงิน

Query Parameters

System Logs

Query Parameters

Query: `success` (true/false), `webhookEventId`