การเชื่อมต่อแบบ White-label ใหม่

ระบบผ่อนชำระช่วยแบ่งการชำระเงินค่าสินค้าหรือบริการออกเป็นงวดย่อยๆ เมื่อมีรายการผ่อนชำระเกิดขึ้นฝั่งร้านค้าจะได้รับเงินเต็มจำนวน ส่วนผู้ซื้อสามารถเลือกแบ่งชำระได้สูงสุด 36 เดือนขึ้นอยู่กับเงื่อนไขของแต่ละธนาคาร โดยจะเป็นการแบ่งชำระยอดเท่าๆ กันทุกเดือนและกำหนดยอดขั้นต่ำ 3,000 บาทต่อรายการ

การเปิดรับชำระเงิน

• ประเทศที่รองรับ: ประเทศไทย
• API เวอร์ชันล่าสุดที่รองรับ: 2017-11-02

ร้านค้าที่ต้องการเปิดใช้ระบบ การเชื่อมต่อแบบ White-label กรุณาส่งอีเมลมาที่ support@opn.ooo ทางทีมงานโอมิเซะจะส่งข้อกำหนดและเงื่อนไขการใช้บริการให้ร้านค้าได้พิจารณาและลงลายมือชื่อก่อนเปิดใช้งานจริง

บัตรที่รองรับการผ่อนชำระ

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

ในกรณีที่ลูกค้าเลือกจ่ายเงินด้วยวิธีผ่อนชำระ หน้าเช็คเอาท์ของคุณ (ร้านค้า) จะแสดงข้อมูลการผ่อนชำระที่เกี่ยวข้องให้ลูกค้าเลือกเพื่อทำรายการต่อ

เมื่อลูกค้ากรอกข้อมูลบัตรและยืนยันการชำระเงินแล้ว บัตรจะถูกเรียกเก็บเงิน โดยมีขั้นตอนเหมือนกับการชำระเงินผ่านบัตรเครดิต นั่นหมายความว่าการตั้งค่าประมวลผลการชำระเงินที่คุณใช้อยู่ จะถูกปรับใช้กับธุรกรรมการผ่อนชำระแบบ white-label ทุกรายการ โดยระบบจะส่งลูกค้าไปที่หน้าเว็บของผู้ออกบัตร เพื่อให้ลูกค้าทำการยืนยันตัวตนแบบ 3DS เมื่อดำเนินการยืนยันตัวตนสำเร็จแล้ว ลูกค้าจะถูกส่งกลับมาที่หน้าเว็บไซต์ของคุณ

ตัวอย่างภาพหน้าจอที่แสดงขั้นตอนการชำระเงิน เมื่อลูกค้าเลือกจ่ายเงินด้วยวิธีการผ่อนชำระในหน้าเช็คเอาท์

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

การตั้งค่าผู้รับภาระดอกเบี้ย

ฝ่ายใดฝ่ายหนึ่งระหว่างร้านค้ากับผู้ซื้อจะต้องเป็นผู้รับภาระดอกเบี้ยสำหรับรายการแบบผ่อนชำระ กรณีที่เป็นการผ่อนชำระแบบ 0% แปลว่าร้านค้าเป็นผู้รับภาระดอกเบี้ยแทนผู้ซื้อ

การตั้งค่าพื้นฐาน

ร้านค้าสามารถตั้งค่าให้ฝ่ายร้านค้าหรือฝ่ายผู้ซื้อเป็นผู้รับภาระดอกเบี้ยได้จากแดชบอร์ด และสามารถปรับเปลี่ยนได้ตามรายการ

การตั้งค่าตามรายการ

ร้านค้าสามารถปรับแปลี่ยนการตั้งค่าของผู้รับภาระดอกเบี้ยในรายการผ่อนชำระได้โดยการส่ง boolean parameter zero_interest_installments ในทั้ง source และ การสร้าง charge

เมื่อตั้งค่าเป็น true ฝ่ายร้านค้าจะเป็นผู้รับภาระดอกเบี้ย ในทางกลับกัน ถ้าตั้งค่าเป็น false ผู้ซื้อจะเป็นผู้รับภาระดอกเบี้ย หากการตั้งค่าไม่ได้มีการปรับเปลี่ยนระบบจะใช้ผู้รับภาระดั้งเดิมในการรับภาระดอกเบี้ย ค่าของตัวแปรใน source และ การสร้าง charge จะต้องมีค่าตรงกัน

ในกรณีที่มีการ charge จาก source โดยตรง ให้ส่ง parameter นี้ตั้งแต่การสร้าง charge

การติดตั้งใช้งาน

ในการสร้างรายการรับชำระเงินผ่าน การเชื่อมต่อแบบ White-label ให้ร้านค้าส่งคำสั่ง API ดังนี้

1. สร้าง token ด้วย Omise.js, omise-ios หรือ omise-android
2. สร้าง payment source (type: installment_wlb_bay, installment_wlb_bbl, installment_wlb_first_choice, installment_wlb_kbank, installment_wlb_ktc, installment_wlb_scb, หรือ installment_wlb_ttb) โดยใช้ Omise.js, omise-ios หรือ omise-android
3. สร้าง charge โดยใช้ token และ source จากขั้นตอนแรกและขั้นตอนที่ 2
4. เมื่อผู้ซื้อทำรายการสำเร็จและร้านค้าได้รับ webhook event หรือ charge.complete แล้ว เราแนะนำให้ตรวจสอบสถานะรายการด้วยตนเองอีกครั้งเพื่อความแม่นยำ

การสร้าง source เพื่อรับชำระเงินผ่านการเชื่อมต่อแบบ White-label จะเกิดขึ้นในฝั่งของผู้ซื้อ (client-side) เช่นบนเว็บไซต์หรือโทรศัพท์มือถือของผู้ซื้อ ร้านค้าจะต้องใช้ public key

ส่วนการสร้างรายการ (charge) เพื่อรับชำระเงินผ่านการเชื่อมต่อแบบ White-label จะเกิดขึ้นในฝั่งของร้านค้า (server-side) ร้านค้าจะต้องใช้ secret key

หมายเหตุ: หากมีความจำต้องสร้างทั้งรายการและ source ในฝั่งร้านค้า (server-side) สามารถทำพร้อมกันได้เลยโดยการส่งคำสั่ง API เพียงครั้งเดียว และใช้งาน secret key

การสร้างโทเค็นบัตร

Omise.js เป็นไลบรารี่ JavaScript ฝั่งผู้ซื้อที่มีแบบฟอร์มตรวจสอบสถานะการชำระเงิน ช่วยให้คุณสามารถจัดเก็บข้อมูลบัตรลูกค้าได้ง่าย โดยจะส่งข้อมูลบัตรผ่านเซิรฟ์เวอร์นิรภัยของเรา เพื่อแปลงเป็นโทเคนกลับมาแทน

เมื่อลูกค้ายืนยันว่าต้องการชำระเงินผ่านบัตร ระบบจะสร้างโทเคนใหม่ขึ้นมา โดยระบุข้อมูลบัตรใน object card โทเคนสามารถใช้งานได้แค่ครั้งเดียว

ตัวอย่างการสร้างโทเคนบัตรขึ้นมาใหม่ สำหรับรายการชำระเงิน 4,000 บาท เราจะใส่ test public key ของคุณแทนค่าตัวแปร omise_public_key และ $OMISE_PUBLIC_KEY ซึ่ง test public key ของคุณจะอยู่ในแดชบอร์ด https://dashboard.omise.co/test/keys

การใช้ Omise.js คือ parameter (type) ที่จะถูกใช้เป็น argument แรกในวิธีการสร้างโทเคน

Omise.setPublicKey(omise_public_key);

Omise.createToken('card', {
  "name": "Somchai Prasert",
  "number": "4242424242424242",
  "expiration_month": "10",
  "expiration_year": "2022",
  "city": "Bangkok",
  "postal_code": "10320",
  "security_code": "123"
}, function(statusCode, response) {
  console.log(response)
});

ถ้าร้านค้าต้องการทดสอบ ให้สร้าง request โดยใช้ curl

curl https://vault.omise.co/tokens \
  -X POST \
  -u $OMISE_PUBLIC_KEY: \
  -d "card[name]=Somchai Prasert" \
  -d "card[city]=Bangkok" \
  -d "card[postal_code]=10320" \
  -d "card[number]=4242424242424242" \
  -d "card[security_code]=123" \
  -d "card[expiration_month]=12" \
  -d "card[expiration_year]=2024"

{
  "object": "token",
  "id": "tokn_test_5yz286bfz172216am2a",
  "livemode": false,
  "location": "https://vault.omise.co/tokens/tokn_test_5yz286bfz172216am2a",
  "used": false,
  "charge_status": "unknown",
  "card": {
    "object": "card",
    "id": "card_test_5yz286bemif06to1kzm",
    "livemode": false,
    "location": null,
    "deleted": false,
    "street1": null,
    "street2": null,
    "city": "Bangkok",
    "state": null,
    "phone_number": null,
    "postal_code": "10320",
    "country": "us",
    "financing": "credit",
    "bank": "JPMORGAN CHASE BANK N.A.",
    "brand": "Visa",
    "fingerprint": "b3ejUqhKT6DjGjtnathYRJk8oifeVAFXPhgtoQMhZIs=",
    "first_digits": null,
    "last_digits": "4242",
    "name": "Somchai Prasert",
    "expiration_month": 12,
    "expiration_year": 2024,
    "security_code_check": true,
    "tokenization_method": null,
    "created_at": "2024-03-04T07:27:32Z"
  },
  "created_at": "2024-03-04T07:27:32Z"
}

attribute id คือ ตัวระบุโทเค็น (ขึ้นต้นด้วย tokn)

การสร้าง source


เมื่อผู้ซื้อเลือกชำระเงินผ่านช่องทางนี้ ให้ร้านค้าสร้าง source ผ่าน source API โดยกำหนด amount, currency, installment_term, และ type


ตัวอย่างด้านล่างนี้เป็นการสร้าง source สำหรับรายการ การเชื่อมต่อแบบ White-label จำนวน ฿4,000 ให้แทนค่าของ omise_public_key และ $OMISE_PUBLIC_KEY ด้วย test public key ของร้านค้าซึ่งสามารถคัดลอกได้จาก แดชบอร์ด

หากใช้ Omise.js parameter type เป็นตัวแปรที่จำเป็นของฟังก์ชัน createSource

Omise.setPublicKey(omise_public_key);

Omise.createSource('installment_wlb_ktc', {
  "amount": 400000,
  "currency": "THB",
  "installment_term": 4
}, function(statusCode, response) {
  console.log(response)
});

หากร้านค้าต้องการทดสอบให้สร้าง request โดยใช้ curl

curl https://api.omise.co/sources \
  -u $OMISE_PUBLIC_KEY: \
  -d "amount=400000" \
  -d "currency=THB" \
  -d "type=installment_wlb_ktc" \
  -d "installment_term=4"

{
  "object": "source",
  "id": "src_test_5yz286gge3rwms0smuj",
  "livemode": false,
  "location": "/sources/src_test_5yz286gge3rwms0smuj",
  "amount": 400000,
  "barcode": null,
  "bank": null,
  "created_at": "2024-03-04T07:27:33Z",
  "currency": "THB",
  "email": null,
  "flow": "redirect",
  "installment_term": 4,
  "ip": "35.198.236.178",
  "absorption_type": "customer",
  "name": null,
  "mobile_number": null,
  "phone_number": null,
  "platform_type": null,
  "scannable_code": null,
  "billing": null,
  "shipping": null,
  "items": [],
  "references": null,
  "provider_references": null,
  "store_id": null,
  "store_name": null,
  "terminal_id": null,
  "type": "installment_wlb_ktc",
  "zero_interest_installments": false,
  "charge_status": "unknown",
  "receipt_amount": null,
  "discounts": []
}

ตัวแปรของ id คือ source identifier (เริ่มต้นด้วย src)

การสร้างรายการรับชำระเงิน

สร้างรายการรับชำระเงินโดยระบุ parameter return_uri, source, card, amount และ currency

• return_uri จะเป็นตำแหน่งบนเว็บไซต์ของร้านค้าที่ผู้ซื้อจะถูกส่งไปเมื่อยืนยันรายการสำเร็จ
• source จะเป็นตัวกำหนด source identifier
• card จะเป็นตัวกำหนด token identifier
• amount และ currency จะต้องมีค่าตรงกับ amount และ currency ของ source

ตัวอย่างด้านล่างนี้แสดงให้เห็นถึงการสร้างรายการรับชำระเงินขึ้นมาใหม่ โดยใช้ curl ในการสร้างรายการให้ร้านค้า

• แทน $OMISE_SECRET_KEY ด้วย test secret key ของร้านค้าซึ่งสามารถคัดลอกได้จากแดชบอร์ด
• แทน $SOURCE_ID ด้วย id ของ source
• แทน $TOKEN_ID ด้วย id ของ card token

สำหรับรายการผ่อนชำระ ร้านค้าจะต้องส่งข้อมูล parameter เหล่านี้มาด้วย:

• zero_interest_installments จำนวนจะต้องตรงกันกับจำนวนที่ระบุใน source

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

{
  "object": "charge",
  "id": "chrg_test_5yz286k0q8c0lkmgc1r",
  "location": "/charges/chrg_test_5yz286k0q8c0lkmgc1r",
  "amount": 400000,
  "acquirer_reference_number": null,
  "net": 384378,
  "fee": 14600,
  "fee_vat": 1022,
  "interest": 0,
  "interest_vat": 0,
  "funding_amount": 400000,
  "refunded_amount": 0,
  "transaction_fees": {
    "fee_flat": "0.0",
    "fee_rate": "3.65",
    "vat_rate": "7.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_5yz286k0q8c0lkmgc1r/refunds",
    "order": "chronological",
    "from": "1970-01-01T00:00:00Z",
    "to": "2024-03-04T07:27:34Z"
  },
  "link": null,
  "description": null,
  "metadata": {},
  "card": {
    "object": "card",
    "id": "card_test_5yz285vojqmxmwz5hf9",
    "livemode": false,
    "location": null,
    "deleted": false,
    "street1": null,
    "street2": null,
    "city": "Bangkok",
    "state": null,
    "phone_number": null,
    "postal_code": "10320",
    "country": "us",
    "financing": "credit",
    "bank": "JPMORGAN CHASE BANK N.A.",
    "brand": "Visa",
    "fingerprint": "b3ejUqhKT6DjGjtnathYRJk8oifeVAFXPhgtoQMhZIs=",
    "first_digits": null,
    "last_digits": "4242",
    "name": "Somchai Prasert",
    "expiration_month": 9,
    "expiration_year": 2025,
    "security_code_check": true,
    "tokenization_method": null,
    "created_at": "2024-03-04T07:27:30Z"
  },
  "source": {
    "object": "source",
    "id": "src_test_5yz285hrlxfb2f0n5qx",
    "livemode": false,
    "location": "/sources/src_test_5yz285hrlxfb2f0n5qx",
    "amount": 400000,
    "barcode": null,
    "bank": null,
    "created_at": "2024-03-04T07:27:29Z",
    "currency": "THB",
    "email": null,
    "flow": "redirect",
    "installment_term": 4,
    "ip": "35.198.236.178",
    "absorption_type": "customer",
    "name": null,
    "mobile_number": null,
    "phone_number": null,
    "platform_type": null,
    "scannable_code": null,
    "billing": null,
    "shipping": null,
    "items": [],
    "references": null,
    "provider_references": null,
    "store_id": null,
    "store_name": null,
    "terminal_id": null,
    "type": "installment_wlb_ktc",
    "zero_interest_installments": false,
    "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_5yz286k25fv0vh12emj/authorize",
  "return_uri": "https://example.com/orders/345678/complete",
  "created_at": "2024-03-04T07:27:34Z",
  "paid_at": null,
  "expires_at": "2024-03-11T07:27: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,
  "partially_refundable": false,
  "reversed": false,
  "reversible": false,
  "voided": false,
  "paid": false,
  "expired": false,
  "can_perform_void": true,
  "approval_code": null
}

การสร้าง source และรายการรับชำระเงิน

ร้านค้าสามารถสร้างทั้ง source และ รายการรับชำระเงิน (charge) ผ่านการเรียกใช้ API เพียงครั้งเดียว

curl https://api.omise.co/charges \
  -u $OMISE_SECRET_KEY: \
  -d "amount=400000" \
  -d "currency=THB" \
  -d "return_uri=http://example.com/orders/345678/complete" \
  -d "card=$TOKEN_ID_CHARGE_SOURCE" \
  -d "source[type]=installment_wlb_ktc" \
  -d "source[installment_term]=4"

การสร้าง source และ charge โดยฝ่ายผู้ซื้อเป็นผู้รับภาระดอกเบี้ย

ร้านค้าสามารถปรับเปลี่ยนการตั้งค่าของผู้รับภาระดอกเบี้ยได้โดยการส่ง parameter zero_interest_installments สามารถดูว่าใครเป็นผู้รับภาระได้ดอกเบี้ยได้ที่การตั้งค่าผู้รับภาระดอกเบี้ย

curl https://api.omise.co/charges \
  -u $OMISE_SECRET_KEY: \
  -d "amount=400000" \
  -d "currency=THB" \
  -d "return_uri=http://example.com/orders/345678/complete" \
  -d "zero_interest_installments=false" \
  -d "card=$TOKEN_ID_CHARGE" \
  -d "source[type]=installment_wlb_ktc" \
  -d "source[installment_term]=4"

สร้างรายการสำเร็จ

เมื่อร้านค้าสร้างรายการรับชำระเงินขึ้นมาแล้ว จะพบว่าสถานะของรายการแสดงเป็น pending หรือ status==pending โดยสถานะของรายการรับชำระเงินสามารถเป็นได้ทั้ง successful, failed และ expired

ในส่วนต่อไปเราจะอธิบายวิธีอนุมัติรายการ, การรับ event แจ้งเตือนเมื่อรายการเสร็จสิ้นผ่าน webhook และการตรวจสอบสถานะรายการ

ภาพด้านล่างนี้แสดงให้เห็นถึงขั้นตอนทั้งหมดในการรับชำระเงินแต่ละรายการ

การอนุมัติรายการรับชำระเงิน

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

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

การรับ event แจ้งเตือนรายการสำเร็จ

ร้านค้าสามารถรับการแจ้งเตือนเมื่อมีการทำรายการเสร็จสิ้นโดยใช้งาน webhook events

ในการติดตั้งให้ร้านค้ากำหนดตำแหน่งบนเซิร์ฟเวอร์เพื่อรับ webhook events และเพิ่มตำแหน่งเดียวกันนี้เป็น webhook endpoint บนแดชบอร์ด

เมื่อมีรายการเสร็จสิ้น ระบบจะส่ง POST request ไปยัง endpoint นี้ พร้อมทั้งแนบสถานะการตอบกลับของรายการนั้นๆ ไปด้วย

ตัวแปรหลักหรือ key สำหรับ event object ประกอบไปด้วย charge.complete และตัวแปร data ที่มี charge object

อ่านเพิ่มเติมได้ที่ Events API

การตรวจสอบสถานะรายการ

เมื่อได้รับ event ของรายการที่เสร็จสิ้นแล้ว ร้านค้าสามารถตรวจสอบสถานะรายการหรือ status โดยใช้ Charge API

หากค่าของ charge.status เป็น successful หมายถึงว่ารายการรับชำระเงินสำเร็จ หากค่าของ charge.status เป็น failed รายการรับชำระเงินนั้นไม่สำเร็จ ร้านค้าสามารถตรวจสอบ failure_code และ failure_message ได้ใน charge object เพื่ออ่านคำอธิบายเพิ่มเติม

สาเหตุขัดข้องที่อาจเกิดขึ้นได้มีดังนี้

การคืนเงิน

สามารถตรวจสอบวิธีการคืนเงินรายการผ่อนชำระได้ที่ Refund API

หมายเหตุ: รายการผ่อนชำระสามารถทำการคืนเงินแบบเต็มจำนวนเท่านั้น ไม่สามารถคืนเงินบางส่วนได้

ข้อจำกัด

• จำนวนรับชำระขั้นต่ำ: 200000 (THB2,000.00)
• จำนวนรับชำระสูงสุด: 15000000 (THB150,000.00)

บัตรเครดิตแต่ละใบมียอดชำระขั้นต่ำ ต่อเดือนที่ไม่เท่ากัน โดยขึ้นอยู่กับบัตรเครดิตที่ใช้กับระยะเวลาที่เลือกผ่อนชำระ

ตัวอย่าง: ผู้ซื้อมียอดชำระทั้งหมด 3,300 บาท และต้องการจ่ายแบบผ่อนชำระเป็นเวลา 10 เดือน ผู้ซื้อจะมียอดผ่อนชำระ 330 บาทต่อเดือน ซึ่งต่ำกว่ายอดชำระขั้นต่ำของบัตรเครดิตธนาคารกรุงเทพ แต่สูงกว่ายอดชำระขั้นต่ำของบัตรธนาคารกสิกรเป็นต้น

ขั้นตอนต่อไป

• Charge API
• Source API
• Webhooks API