Atome App Redirection

รับชำระเงินออนไลน์จากผู้ใช้ Atome ผ่านเว็บไซต์ของคุณด้วยช่องทางการชำระเงิน Atome

Atome เป็นบริการซื้อก่อนจ่ายทีหลัง (buy now, pay later หรือ BNPL) ที่ให้ลูกค้าแบ่งชำระค่าซื้อสินค้าเป็นงวด ๆ เอกสารนี้ครอบคลุมขั้นตอนการชำระเงินแบบ เปลี่ยนเส้นทาง (redirect) บนเว็บไซต์ ซึ่งลูกค้าจะอนุมัติการชำระเงินบนหน้าชำระเงินของ Atome สำหรับขั้นตอนแบบสแกน QR โค้ดที่หน้าร้าน โปรดดู Atome QR

คู่มือนี้จะแนะนำขั้นตอนการชำระเงินและรายละเอียดวิธีการนำไปใช้งาน

🔓 วิธีเปิดใช้งาน

• ประเทศที่รองรับ: ไทย, สิงคโปร์, มาเลเซีย
• เวอร์ชัน API ขั้นต่ำ: 2017-11-02

หากต้องการเปิดใช้งาน Atome ให้ส่งอีเมลแจ้งความประสงค์ไปที่ support@omise.co คุณจะต้องตรวจสอบและยอมรับข้อกำหนดและเงื่อนไขฉบับใหม่

💳 ขั้นตอนการชำระเงิน

Atome รองรับการชำระเงินทั้งบนเว็บไซต์เดสก์ท็อปและมือถือ ลูกค้าที่ชำระเงินผ่าน Atome จะผ่านขั้นตอนการชำระเงินแบบ เปลี่ยนเส้นทาง (redirect) กล่าวคือ ลูกค้าจะถูกเปลี่ยนเส้นทางจากเว็บไซต์ของคุณไปยังหน้าชำระเงินที่ปลอดภัยของ Atome ซึ่งลูกค้าจะอนุมัติและยืนยันการชำระเงินที่นั่น ภาพหน้าจอต่อไปนี้แสดงขั้นตอนตลอดกระบวนการ

การชำระเงินผ่านเดสก์ท็อป

❶ ลูกค้าเลือกชำระเงินด้วย Atome ❷ และถูกเปลี่ยนเส้นทางไปยังหน้าชำระเงินที่ปลอดภัยของ Atome ❸ ลูกค้าเปิดแอป Atome บนโทรศัพท์แล้วสแกน QR โค้ดบนหน้าชำระเงินด้วยแอปดังกล่าว ❹ จากนั้นลูกค้าจะเห็นแผนผ่อนชำระและยืนยันการชำระเงิน ❺ เมื่อชำระเงินเสร็จสิ้น ลูกค้าจะถูกเปลี่ยนเส้นทางไปยังหน้ายืนยันการชำระเงินของร้านค้าโดยอัตโนมัติ

การชำระเงินผ่านมือถือ (ชำระผ่านเบราว์เซอร์)

❶ ลูกค้าเลือกชำระเงินด้วย Atome ❷ และถูกเปลี่ยนเส้นทางไปยังหน้าชำระเงินที่ปลอดภัยของ Atome ❸ ลูกค้าคลิกเพื่อชำระเงินในเบราว์เซอร์ ❹ ลูกค้าจะเห็นแบบฟอร์มเข้าสู่ระบบ ❺ หลังจากลูกค้าเข้าสู่ระบบแล้ว จะเห็นแผนผ่อนชำระ ❻ ลูกค้ายืนยันการชำระเงินและถูกเปลี่ยนเส้นทางไปยังหน้ายืนยันการชำระเงินของร้านค้าโดยอัตโนมัติ

การชำระเงินผ่านมือถือ (ชำระผ่านแอป)

❶ ลูกค้าเลือกชำระเงินด้วย Atome ❷ และถูกเปลี่ยนเส้นทางไปยังหน้าชำระเงินที่ปลอดภัยของ Atome ❸ ลูกค้าคลิกเพื่อชำระเงินผ่านแอป ❹ ลูกค้าจะถูกเปลี่ยนเส้นทางไปยังแอปของตนและเห็นแผนผ่อนชำระ ❺ ลูกค้ายืนยันการชำระเงินและถูกเปลี่ยนเส้นทางไปยังหน้ายืนยันการชำระเงินของร้านค้าโดยอัตโนมัติ

🛠️ การนำไปใช้งาน

หากต้องการสร้าง charge โดยใช้ Atome ให้เรียก API ตามขั้นตอนต่อไปนี้

1. สร้าง source การชำระเงิน (type: atome) โดยใช้ Omise.js หรือ mobile SDK อย่างใดอย่างหนึ่ง (iOS และ Android)
2. สร้าง charge โดยใช้ identifier ของ source ที่สร้างในขั้นตอนที่ 1
3. หลังจากได้รับ webhook event การชำระเงินเสร็จสมบูรณ์ (charge completion) ให้เรียกดูข้อมูล charge เพื่อตรวจสอบสถานะ (ไม่บังคับ แต่แนะนำให้ทำ)

ใช้ public key เพื่อสร้าง source ของ Atome ฝั่ง client (เบราว์เซอร์หรือโทรศัพท์มือถือของลูกค้า) ใช้ secret key เพื่อสร้าง charge ของ Atome ฝั่ง server

การสร้าง source ของ Atome

เมื่อลูกค้ายืนยันว่าต้องการชำระเงินด้วยช่องทางนี้ ให้สร้าง source โดยระบุ amount, currency, items, phone_number, shipping และ type

ตัวอย่างต่อไปนี้แสดงการสร้าง source ของ Atome ใหม่จำนวน ฿500 ให้แทนที่ตัวแปร omise_public_key และ $OMISE_PUBLIC_KEY ด้วย test public key จากแดชบอร์ดของคุณ

Omise.setPublicKey(omise_public_key);

Omise.createSource('atome', {
  "amount": 50000,
  "currency": "THB",
  "phone_number": "+66876543210",
  "shipping":
    {
      "street1": "1448/4 Praditmanutham Road",
      "postal_code": "10320",
      "country": "TH"
    },
  "items":
    [
      {
        "sku": "AAA111",
        "name": "water bottle",
        "amount": 25000,
        "quantity": 2
      }
    ],
}, function(statusCode, response) {
  console.log(response)
});

สำหรับการทดสอบ คุณสามารถสร้างคำขอเดียวกันได้โดยใช้ curl

curl https://api.omise.co/sources \
  -u $OMISE_PUBLIC_KEY: \
  -d "amount=50000" \
  -d "currency=THB" \
  -d "type=atome" \
  --data-urlencode "phone_number=+66876543210" \
  -d "shipping[postal_code]=10320" \
  -d "shipping[country]=TH" \
  -d "shipping[street1]=1448/4 Praditmanutham Road" \
  -d "items[0][sku]=AAA111" \
  -d "items[0][name]=water bottle" \
  -d "items[0][quantity]=2" \
  -d "items[0][amount]=25000"

{
  "object": "source",
  "id": "src_test_5vz4s25jpdlpt9ggmem",
  "livemode": false,
  "location": "/sources/src_test_5vz4s25jpdlpt9ggmem",
  "amount": 50000,
  "barcode": null,
  "bank": null,
  "created_at": "2023-06-02T08:53:34Z",
  "currency": "THB",
  "email": null,
  "flow": "redirect",
  "installment_term": null,
  "absorption_type": null,
  "name": null,
  "mobile_number": "+66876543210",
  "phone_number": "+66876543210",
  "platform_type": null,
  "scannable_code": null,
  "billing": null,
  "shipping": {
    "city": null,
    "country": "TH",
    "postal_code": "10320",
    "state": null,
    "street1": "1448/4 Praditmanutham Road",
    "street2": null
  },
  "items": [
    {
      "sku": "AAA111",
      "name": "water bottle",
      "brand": null,
      "category": null,
      "amount": 25000,
      "quantity": 2,
      "item_uri": null,
      "image_uri": null
    }
  ],
  "references": null,
  "store_id": null,
  "store_name": null,
  "terminal_id": null,
  "type": "atome",
  "zero_interest_installments": null,
  "charge_status": "unknown",
  "receipt_amount": null,
  "discounts": []
}

แอตทริบิวต์ id คือ identifier ของ source (ขึ้นต้นด้วย src)

การสร้าง source ของ Atome สำหรับประเทศไทยโดยไม่ระบุ shipping

เนื่องจาก shipping ไม่บังคับสำหรับประเทศไทย คุณจึงสามารถละเว้นได้ทั้งหมดเมื่อสร้าง source สำหรับประเทศไทย

curl https://api.omise.co/sources \
  -u $OMISE_PUBLIC_KEY: \
  -d "amount=50000" \
  -d "currency=THB" \
  -d "type=atome" \
  --data-urlencode "phone_number=+66876543210" \
  -d "items[0][sku]=AAA111" \
  -d "items[0][name]=water bottle" \
  -d "items[0][quantity]=2" \
  -d "items[0][amount]=25000"

การตอบกลับจะเหมือนกับ source สำหรับประเทศไทยที่ระบุ shipping ยกเว้นว่า shipping จะเป็น null มีบางฟิลด์ที่ถูกละไว้ด้านล่างเพื่อความกระชับ โดยการตอบกลับฉบับเต็มจะมีฟิลด์ครบถ้วนเหมือนกับตัวอย่างแรก

{
  "object": "source",
  "id": "src_test_5vz4s25jpdlpt9ggmem",
  "livemode": false,
  "location": "/sources/src_test_5vz4s25jpdlpt9ggmem",
  "amount": 50000,
  "currency": "THB",
  "flow": "redirect",
  "mobile_number": "+66876543210",
  "phone_number": "+66876543210",
  "billing": null,
  "shipping": null,
  "items": [
    {
      "sku": "AAA111",
      "name": "water bottle",
      "amount": 25000,
      "quantity": 2
    }
  ],
  "type": "atome",
  "charge_status": "unknown"
}

การสร้าง charge ของ Atome

สร้าง charge โดยระบุพารามิเตอร์ return_uri, source, amount และ currency

• return_uri ระบุตำแหน่งบนเว็บไซต์ของคุณที่ลูกค้าจะถูกเปลี่ยนเส้นทางไปหลังจากทำขั้นตอนอนุมัติการชำระเงินเสร็จสิ้น ข้อกำหนด: URL ต้องอยู่ในรูปแบบ HTTPS
• source ระบุ identifier ของ source
• amount และ currency ต้องตรงกับ amount และ currency ของ source

ตัวอย่างต่อไปนี้แสดงวิธีสร้าง charge โดยใช้ curl ให้แทนที่ $OMISE_SECRET_KEY ด้วย test secret key จากแดชบอร์ดของคุณ และแทนที่ $SOURCE_ID ด้วย id ของ source

curl https://api.omise.co/charges \
  -u $OMISE_SECRET_KEY: \
  -d "amount=50000" \
  -d "currency=THB" \
  -d "return_uri=http://example.com/orders/345678/complete" \
  -d "source=$SOURCE_ID"

{
  "object": "charge",
  "id": "chrg_test_5vz4s29fbc4obd1tym0",
  "location": "/charges/chrg_test_5vz4s29fbc4obd1tym0",
  "amount": 50000,
  "net": 47250,
  "fee": 2750,
  "fee_vat": 0,
  "interest": 0,
  "interest_vat": 0,
  "funding_amount": 50000,
  "refunded_amount": 0,
  "transaction_fees": {
    "fee_flat": "0.0",
    "fee_rate": "5.5",
    "vat_rate": "0.0"
  },
  "platform_fee": {
    "fixed": null,
    "amount": null,
    "percentage": null
  },
  "currency": "THB",
  "funding_currency": "THB",
  "ip": null,
  "refunds": {
    "object": "list",
    "data": [],
    "limit": 20,
    "offset": 0,
    "total": 0,
    "location": "/charges/chrg_test_5vz4s29fbc4obd1tym0/refunds",
    "order": "chronological",
    "from": "1970-01-01T00:00:00Z",
    "to": "2023-06-02T08:53:35Z"
  },
  "link": null,
  "description": null,
  "metadata": {},
  "card": null,
  "source": {
    "object": "source",
    "id": "src_test_5vz4s25jpdlpt9ggmem",
    "livemode": false,
    "location": "/sources/src_test_5vz4s25jpdlpt9ggmem",
    "amount": 50000,
    "barcode": null,
    "bank": null,
    "created_at": "2023-06-02T08:53:34Z",
    "currency": "THB",
    "email": null,
    "flow": "redirect",
    "installment_term": null,
    "absorption_type": null,
    "name": null,
    "mobile_number": "+66876543210",
    "phone_number": "+66876543210",
    "platform_type": null,
    "scannable_code": null,
    "billing": null,
    "shipping": {
      "city": null,
      "country": "TH",
      "postal_code": "10320",
      "state": null,
      "street1": "1448/4 Praditmanutham Road",
      "street2": null
    },
    "items": [
      {
        "sku": "AAA111",
        "name": "water bottle",
        "brand": null,
        "category": null,
        "amount": 25000,
        "quantity": 2,
        "item_uri": null,
        "image_uri": null
      }
    ],
    "references": null,
    "store_id": null,
    "store_name": null,
    "terminal_id": null,
    "type": "atome",
    "zero_interest_installments": null,
    "charge_status": "pending",
    "receipt_amount": null,
    "discounts": []
  },
  "schedule": null,
  "customer": null,
  "dispute": null,
  "transaction": null,
  "failure_code": null,
  "failure_message": null,
  "status": "pending",
  "authorize_uri": "https://pay.omise.co/payments/pay2_test_5vz4s29ibio0cyi0j15/authorize",
  "return_uri": "http://example.com/orders/345678/complete",
  "created_at": "2023-06-02T08:53:34Z",
  "paid_at": null,
  "expires_at": "2023-06-09T08:53:34Z",
  "expired_at": null,
  "reversed_at": null,
  "zero_interest_installments": false,
  "branch": null,
  "terminal": null,
  "device": null,
  "authorized": false,
  "capturable": false,
  "capture": true,
  "disputable": false,
  "livemode": false,
  "refundable": false,
  "reversed": false,
  "reversible": false,
  "voided": false,
  "paid": false,
  "expired": false
}

การสร้าง source และ charge ของ Atome พร้อมกัน

หรืออีกวิธีหนึ่งคือสร้างและชำระ source ได้ในคำขอ API เดียว

curl https://api.omise.co/charges \
  -u $OMISE_SECRET_KEY: \
  -d "amount=50000" \
  -d "currency=THB" \
  -d "return_uri=http://example.com/orders/345678/complete" \
  -d "source[type]=atome" \
  --data-urlencode "source[phone_number]=+66876543210" \
  -d "source[shipping][postal_code]=10320" \
  -d "source[shipping][country]=TH" \
  -d "source[shipping][street1]=1448/4 Praditmanutham Road" \
  -d "source[items][0][sku]=AAA111" \
  -d "source[items][0][name]=water bottle" \
  -d "source[items][0][quantity]=2" \
  -d "source[items][0][amount]=25000"

การตั้งค่าให้ charge ของ Atome หมดอายุ

โดยค่าเริ่มต้น charge จะหมดอายุ 12 ชั่วโมงหลังจากสร้าง

คุณสามารถกำหนดระยะเวลาหมดอายุที่แตกต่างกันให้กับแต่ละ charge ได้ โดยระบุ timestamp ที่อยู่ระหว่าง 30 วินาทีถึง 12 ชั่วโมงนับจากเวลาปัจจุบันในฟิลด์ expires_at ของ Charge API หากระบุ timestamp ถูกต้อง charge จะหมดอายุตามเวลาที่กำหนดแทนระยะเวลาเริ่มต้น

หลังจากสร้าง charge แล้ว คุณสามารถเรียก Expire API ด้วยตนเองเพื่อทำให้ charge ที่อยู่ในสถานะ pending หมดอายุได้

curl https://api.omise.co/charges \
  -u $OMISE_SECRET_KEY: \
  -d "amount=50000" \
  -d "currency=THB" \
  -d "source[type]=atome" \
  --data-urlencode "source[phone_number]=+66876543210" \
  -d "source[shipping][postal_code]=10320" \
  -d "source[shipping][country]=TH" \
  -d "source[shipping][street1]=1448/4 Praditmanutham Road" \
  -d "source[items][0][sku]=AAA111" \
  -d "source[items][0][name]=water bottle" \
  -d "source[items][0][quantity]=2" \
  -d "source[items][0][amount]=25000" \
  -d "expires_at=2020-12-17T00:00:00Z"

การทำให้ charge ของ Atome เสร็จสมบูรณ์

คุณได้สร้าง charge ใหม่ที่มี status เป็น pending แล้ว ค่าอื่น ๆ ที่เป็นไปได้ของ status ของ charge ได้แก่ successful, failed และ expired

หัวข้อต่อไปนี้จะอธิบายรายละเอียดวิธีอนุมัติ charge, การรับ webhook event เมื่อทำรายการเสร็จสมบูรณ์ และการอัปเดตสถานะ

แผนภาพลำดับเหตุการณ์ (sequence diagram) นี้แสดงขั้นตอนทั้งหมด

การอนุมัติ charge ของ Atome

เปลี่ยนเส้นทางลูกค้าไปยังตำแหน่งที่ระบุใน authorize_uri เพื่อให้ลูกค้าสามารถอนุมัติ charge ได้

คุณสามารถจำลองขั้นตอนการอนุมัตินี้ในโหมดทดสอบได้ โดยเข้าไปที่ authorize_uri เพื่อทำเครื่องหมาย charge เป็น Successful หรือ Failed ด้วยตนเอง หลังจากลูกค้าทำขั้นตอนการอนุมัติเสร็จสิ้น ลูกค้าจะถูกเปลี่ยนเส้นทางไปยังตำแหน่งที่คุณระบุใน return_uri

การรับ event เมื่อ charge ของ Atome เสร็จสมบูรณ์

วิธีที่ดีที่สุดในการรับการแจ้งเตือนเมื่อ charge เสร็จสมบูรณ์คือการใช้webhook events ให้ตั้งค่าตำแหน่งบนเซิร์ฟเวอร์ของคุณเพื่อรับ webhook events แล้วเพิ่มตำแหน่งนี้เป็น webhook endpoint บนแดชบอร์ด

เมื่อ charge เสร็จสมบูรณ์ ระบบจะส่งคำขอ POST ที่มีข้อมูล response ของ charge ฝังอยู่มายัง endpoint นี้

แอตทริบิวต์ key ของ event object จะมีค่าเป็น charge.complete และแอตทริบิวต์ data จะมี charge object อยู่ ดู Events API สำหรับโครงสร้างของ event object

การตรวจสอบสถานะของ charge ของ Atome

หลังจากได้รับ event นี้ ให้เรียกดูข้อมูล charge โดยใช้ id และตรวจสอบว่า status ตรงกับ status ของ charge ที่อยู่ใน event

หากค่าของ status เป็น successful แสดงว่าการชำระเงินสำเร็จ หากค่าของ status เป็น failed ให้ตรวจสอบ failure_code และ failure_message ใน charge object เพื่อดูสาเหตุ

รหัสความล้มเหลวที่เป็นไปได้มีดังนี้

💸 การยกเลิกและการคืนเงิน

charge ของ Atome สามารถคืนเงินได้บางส่วนหรือทั้งหมดภายใน 60 วันนับจากวันที่ทำรายการ

📊 วงเงินและข้อจำกัด

ไทย

• ขั้นต่ำ: 2000 (THB 20.00)
• สูงสุด: ขึ้นอยู่กับวงเงินเครดิต Atome ของลูกค้าแต่ละราย

สิงคโปร์

• ขั้นต่ำ: 150 (SGD 1.50)
• สูงสุด: 300000 (SGD 3,000.00)

มาเลเซีย

• ขั้นต่ำ: 1000 (MYR 10.00)
• สูงสุด: 500000 (MYR 5,000.00)

❓ คำถามที่พบบ่อย

Atome กับ Atome QR ต่างกันอย่างไร เอกสารนี้ (Atome) ใช้ขั้นตอนแบบ เปลี่ยนเส้นทาง (redirect) คือลูกค้าจะถูกส่งไปยังหน้าชำระเงินของ Atome เพื่ออนุมัติการชำระเงินแบบออนไลน์ ส่วน Atome QR ใช้ขั้นตอนแบบ offline แทน โดยเว็บไซต์จะสร้าง QR โค้ดให้ลูกค้าสแกนด้วยแอป Atome (เช่น ที่อุปกรณ์ POS)

หากลูกค้าไม่ทำการอนุมัติให้เสร็จก่อน charge หมดอายุจะเกิดอะไรขึ้น status ของ charge จะเปลี่ยนเป็น expired และไม่สามารถอนุมัติได้อีกต่อไป ให้สร้าง source และ charge ใหม่เพื่อให้ลูกค้าลองทำรายการอีกครั้ง

หากลูกค้ายกเลิกหรือยืนยันตัวตนไม่สำเร็จบนหน้าชำระเงินของ Atome จะเกิดอะไรขึ้น status ของ charge จะเปลี่ยนเป็น failed ให้ตรวจสอบ failure_code (payment_expired, payment_rejected หรือ failed_processing) และ failure_message ใน charge object เพื่อดูสาเหตุ

จะทดสอบสถานการณ์ที่ล้มเหลวก่อนใช้งานจริงได้อย่างไร ในโหมดทดสอบ ให้เข้าไปที่ authorize_uri ด้วยตนเองแล้วทำเครื่องหมาย charge เป็น Successful หรือ Failed เพื่อจำลองผลลัพธ์ทั้งสองแบบโดยไม่ต้องมีบัญชี Atome จริง

สามารถคืนเงินบางส่วนได้มากกว่าหนึ่งครั้งภายในระยะเวลา 60 วันหรือไม่ ✅ ได้ — สามารถคืนเงินบางส่วนได้หลายครั้งสำหรับ charge เดียวกัน จนกว่าจะคืนเงินครบเต็มจำนวน

Atome รองรับการชำระเงินแบบประจำ (recurring) หรือแบบตั้งเวลาล่วงหน้าหรือไม่ 🚫 ไม่รองรับ — Atome ไม่รองรับการชำระเงินแบบประจำหรือแบบตั้งเวลาล่วงหน้า

วงเงินขั้นต่ำ/สูงสุดใช้ต่อ charge หรือต่อลูกค้าหนึ่งราย 📌 ต่อธุรกรรม — วงเงินขั้นต่ำและสูงสุดจะบังคับใช้ต่อธุรกรรม

👉 ขั้นตอนถัดไป

• Atome QR (ขั้นตอนการชำระเงินแบบสแกน QR โค้ด แบบ offline)
• Charge API
• Source API
• Webhooks API