การใช้ Meta Pay API

เมื่อคุณประมวลผลการชำระเงินสำหรับ Meta Pay คุณต้องแจ้งให้ Meta ทราบถึงกิจกรรมสำหรับธุรกรรมการชำระเงิน เช่น การอนุญาตและการคืนเงิน โดยกระตุ้นการทำงานของ Webhooks ใน Meta Pay API กิจกรรมสำหรับธุรกรรมการชำระเงินจะแสดงในหน้าคำสั่งซื้อและการชำระเงินของบัญชี Facebook ของลูกค้า

หากต้องการเรียนรู้วิธีใช้ API ต่างๆ ของ Meta โปรดดูภาพรวม API กราฟ และโปรดทราบว่า API ที่อธิบายด้านล่างนี้มีความเกี่ยวข้องกับ URL โฮสต์ API กราฟ (https://graph.facebook.com) โปรดดูข้อมูลทั่วไปเพิ่มเติมที่ภาพรวมการผสานการทำงาน Meta Pay

การเริ่มต้นใช้งาน

ก่อนเริ่มใช้งาน Meta Pay API คุณควรดำเนินการดังนี้

• ดำเนินขั้นตอนการเริ่มต้นใช้งานทั่วไปให้เสร็จสิ้น
• ทบทวนการประมวลผลการชำระเงินใน Meta Pay

การเรียกใช้ Meta Pay API

คุณจะสร้างแอพพลิเคชั่นใหม่ในพอร์ทัล Meta for Developers โดยเป็นส่วนหนึ่งของขั้นตอนการเริ่มต้นใช้งานทั่วไป หลังจากที่คุณสร้างแอพพลิเคชั่น คุณจะได้รับ ID ของแอพและข้อมูลลับของแอพสำหรับแอพของคุณ

การเรียกใช้ในแต่ละครั้งที่คุณดำเนินการกับ Meta Pay API จะต้องใช้โทเค็นการเข้าถึงแอพที่ได้จาก ID ของแอพและข้อมูลลับของแอพ ส่งโทเค็นการเข้าถึงแอพโดยใช้ส่วนหัวเป็น Authorization ไม่ใช่พารามิเตอร์การสืบค้น access_token Meta Pay API จะปฏิเสธการเรียกใช้ด้วยโทเค็นผู้ใช้

ตัวอย่างเช่น ให้ใช้โค้ดดังนี้

Authorization: OAuth <APP_ACCESS_TOKEN>

ลายเซ็น

คำขอ HTTP ทุกรายการที่ดำเนินการกับ Meta Pay API จะต้องมีส่วนหัวคำขอเป็น FBPAY-SIGNATURE ค่าของส่วนหัวนี้คืออ็อบเจ็กต์ JSON Web Signature (JWS) ที่มีอัลกอริทึม ES256, Compact Serialization และเพย์โหลดที่แยกออก (ตาม https://tools.ietf.org/html/rfc7515#appendix-F) ค่าเพย์โหลดคือเนื้อหาของคำขอ HTTP POST คีย์ลายเซ็น JWS ต้องได้รับการระบุด้วยส่วนหัว x5c ซึ่งต้องมีใบรับรองที่เชื่อมโยงถึงรูทที่เชื่อถือได้ของพาร์ทเนอร์ ใบรับรองรูทของพาร์ทเนอร์จะแชร์ไว้กับ Meta โดยเป็นส่วนหนึ่งของกระบวนการเริ่มต้นใช้งาน (อ้างอิงถึงในชื่อใบรับรองลายเซ็น Meta Pay API)

ตัวอย่างคำขอที่มีลายเซ็นมีดังนี้

curl -i -X POST \
  -H "Content-Type: application/json" \
  -H "FBPAY_SIGNATURE: eyJhbGciOiJFUzI1NiIsIng1YyI6WyJNSUlCaERDQ0FTcWdBd0lCQWdJQkFUQUtCZ2dxaGtqT1BRUURBakFoTVI4d0hRWURWUVFEREJad1lYSjBibVZ5SUhOcFoyNWhkSFZ5WlNCalpYSjBNQjRYRFRJd01EY3hNekl5TWpVek1Gb1hEVEkwTURNeE1USXlNalV6TUZvd0lURWZNQjBHQTFVRUF3d1djR0Z5ZEc1bGNpQnphV2R1WVhSMWNtVWdZMlZ5ZERCWk1CTUdCeXFHU000OUFnRUdDQ3FHU000OUF3RUhBMElBQkFuRngwR1NKMklPZGZpcFdiMGMwZytBVThlbDh6QnRVS0kxdWRzT2kzN2thd1JRSFkzV29YaWRvRThIOHM1cVIySmo2ZkFKWVhOTURXY0NiditWMEJ1alV6QlJNQjBHQTFVZERnUVdCQlR4NlBGRkhjd2FUZnY5cVdzZUJcL1NjMWFPbVZ6QWZCZ05WSFNNRUdEQVdnQlR4NlBGRkhjd2FUZnY5cVdzZUJcL1NjMWFPbVZ6QVBCZ05WSFJNQkFmOEVCVEFEQVFIXC9NQW9HQ0NxR1NNNDlCQU1DQTBnQU1FVUNJUUNBRE9zZ0pZanRXVm9xNUZOSjc3U2JDeWtON1ZldUlKR2pXb3NBVUFNd1ZRSWdUTlVcL2ttc1wvN0cxVUx5Z01DRWVXemNiYTNrMVo4NEE4RmNlMXQzYUNGbGc9Il19..ZnT7ZR3EqsPYMQt3WdgUZYScBiyK9RI77zMaUKr-tkFRBHgBJQVTOORwM2fFh0QQCTLwOp1TiAzt_q9ofvw6JQ" "https://graph.facebook.com/1001200005002/notify_authorizations" \
  -d '{"notification":{"partner_merchant_id":"123e4567-e89b-12d3-a456-426614174000","container_id":"cGF5bWVudF9jb250YWluZAXI6MTIzNDU2NzhfX01FUkNIQU5UX1RFU1RfRTJFX19QU1BfVEVTVF8x","event_time":1582230020020,"type":"notify_authorizations"},"resource":{"partner_auth_id":"1234567890","auth_amount":{"currency":"USD","value":29508},"status":"SUCCEEDED","created_time":1582230019010,"metadata":[]},"idempotence_token":"ddbdf2cf-d339-4b0b-a27e-4731d8d37c9d"}'

คำขอข้างต้นเป็นการเข้าโค้ดของข้อมูลต่อไปนี้

{
  "notification": {
    "partner_merchant_id": "123e4567-e89b-12d3-a456-426614174000",
    "container_id": "cGF5bWVudF9jb250YWluZAXI6MTIzNDU2NzhfX01FUkNIQU5UX1RFU1RfRTJFX19QU1BfVEVTVF8x",
    "event_time": 1582230020020,
    "type": "notify_authorizations"
  },
  "resource": {
    "partner_auth_id": "1234567890",
    "auth_amount": {
      "currency": "USD",
      "value": 29508
    },
    "status": "SUCCEEDED",
    "created_time": 1582230019010,
    "metadata": []
  },
  "idempotence_token": "ddbdf2cf-d339-4b0b-a27e-4731d8d37c9d"
}

ด้านล่างนี้คือลายเซ็นจากคำขอก่อนหน้า โดยมีการถอดโค้ดแบบ Base64 และ JSON แล้วเพื่อความชัดเจน

base64url(
 json({
   "x5c": [
     "MIIBhDCCASqgAwIBAgIBATAKBggqhkjOPQQDAjAhMR8wHQYDVQQDDBZwYXJ0bmVyIHNpZ25hdHVyZSBjZXJ0MB4XDTIwMDcxMzIyMjUzMFoXDTI0MDMxMTIyMjUzMFowITEfMB0GA1UEAwwWcGFydG5lciBzaWduYXR1cmUgY2VydDBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABAnFx0GSJ2IOdfipWb0c0g+AU8el8zBtUKI1udsOi37kawRQHY3WoXidoE8H8s5qR2Jj6fAJYXNMDWcCbv+V0BujUzBRMB0GA1UdDgQWBBTx6PFFHcwaTfv9qWseB/Sc1aOmVzAfBgNVHSMEGDAWgBTx6PFFHcwaTfv9qWseB/Sc1aOmVzAPBgNVHRMBAf8EBTADAQH/MAoGCCqGSM49BAMCA0gAMEUCIQCADOsgJYjtWVoq5FNJ77SbCykN7VeuIJGjWosAUAMwVQIgTNU/kms/7G1ULygMCEeWzcba3k1Z84A8Fce1t3aCFlg="
   ],
   "alg": "ES256"
 })
) + // Protected Header
 "." +
 "" + // Payload is detached
 "." +
 "ZnT7ZR3EqsPYMQt3WdgUZYScBiyK9RI77zMaUKr-tkFRBHgBJQVTOORwM2fFh0QQCTLwOp1TiAzt_q9ofvw6JQ" // Signature

นิจพล

ช่อง idempotence_token ใช้เพื่อป้องกันการดำเนินการซ้ำกับคำขอ เมื่อมีการส่งคำขออีกครั้งหลังจากเครือข่ายล้มเหลวหรือหมดเวลา โทเค็นนิจพล (Idempotence Token) เป็นค่าที่ไม่ซ้ำกันที่ไคลเอ็นต์สร้างขึ้น และไคลเอ็นต์จะกำหนดวิธีสร้างโทเค็นนี้ ตัวอย่างเช่น คุณสามารถใช้ V4 UUID เพื่อสร้างโทเค็นนิจพลได้

เมื่อดำเนินการตามคำขอสำเร็จ หรือการเรียกใช้ไปยัง API ส่งคืนผลลัพธ์ที่ถูกต้องกลับมา ระบบจะบันทึกข้อมูลการตอบกลับด้วยโทเค็นนิจพล หากมีการลองดำเนินคำขอที่สำเร็จอีกครั้งหนึ่งด้วยโทเค็นนิจพลที่เคยใช้ก่อนหน้านี้ ระบบจะส่งคืนการตอบกลับที่บันทึกไว้ก่อนหน้านั้นโดยไม่รันโค้ดใดๆ ใหม่

เมื่อคำขอทำให้เกิดข้อผิดพลาด ระบบจะไม่บันทึกผลลัพธ์ใดๆ คุณสามารถลองส่งคำขอใหม่ และใช้โทเค็นนิจพลเดิมได้

หากคุณส่งคำขอ 2 รายการพร้อมกันด้วยโทเค็นนิจพลเดียวกัน จะมีเพียงคำขอเดียวที่จะส่งข้อมูลตอบกลับคืนมา

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

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

การกระทบยอดทีละหลายรายการ

เมื่อคุณประมวลผลการชำระเงิน คุณต้องแจ้งให้ Meta ทราบถึงกิจกรรมสำหรับธุรกรรมการชำระเงินโดยใช้ Webhooks ของ Meta Pay เมื่อกระตุ้นการทำงานของ Webhooks กิจกรรมสำหรับธุรกรรมการชำระเงินจะแสดงในหน้ากิจกรรม Facebook Pay ของบัญชี Facebook ของลูกค้าโดยเร็วที่สุด

Meta จะบันทึกการแจ้งเตือนที่ล้มเหลวระหว่างการกระทบยอดทีละหลายรายการและจะแสดงในบัญชี Facebook ของลูกค้าในภายหลัง

ในแต่ละวัน ให้คุณอัพโหลดไฟล์ที่มีการแจ้งเตือนที่คุณส่งให้ Meta ในวันนั้นๆ เพื่อใช้ประกอบการกระทบยอดทีละหลายรายการ ให้รวมการแจ้งเตือนทั้งที่สำเร็จและล้มเหลว โปรดดูรายละเอียดการอัพโหลดไฟล์ไปยัง Meta API ที่หัวข้ออัพโหลดไฟล์ไปยัง Facebook

การจัดการข้อผิดพลาด

Meta Pay API ใช้การจัดการข้อผิดพลาดของ API กราฟแบบมาตรฐาน

การเริ่มต้นการทำงานและอัพเดตผู้ขาย

หากต้องการเริ่มต้นการทำงานหรืออัพเดตข้อมูลสำหรับผู้ขายที่คุณสนับสนุน ให้ส่งคำขอ POST ไปยัง API กราฟของผู้ขาย/metapay_partner/merchant แล้วระบุพารามิเตอร์ผู้ขาย

https://graph.facebook.com/metapay_partner/merchant

พารามิเตอร์คำขอ

การตอบกลับ

หลังจากที่คุณส่งคำขอ POST ไปยัง API ผู้ขาย การตอบกลับ 200 OK จะระบุว่า POST ได้รับการประมวลผลสำเร็จแล้ว เนื้อหาการตอบกลับจะระบุสถานะของผู้ขาย ซึ่งอาจเป็น ENABLED หรือ DISABLED ตัวแก้ไขสถานะที่ไม่ได้เว้นว่างจะให้ข้อมูลเพิ่มเติม

การตอบกลับที่สำเร็จโดยทั่วไปจะมีลักษณะดังนี้

{
    "status":"ENABLED",
    "status_modifiers":[]
}

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

{
    "status":"DISABLED",
    "status_modifiers":["PENDING_SCREENING"]
}

รายการต่อไปนี้คือตัวแก้ไขสถานะที่อาจพบได้

ดูผู้ขาย

หากต้องการดึงข้อมูลผู้ขายที่ลงทะเบียนไว้ ให้ส่งคำขอ GET ไปที่ API กราฟของผู้ขาย /metapay_partner/merchant

https://graph.facebook.com/metapay_partner/merchants

พารามิเตอร์คำขอ

ระบบรองรับพารามิเตอร์คำขอเพิ่มเติมต่อไปนี้เป็นพารามิเตอร์ URL

การตอบกลับ

ผลลัพธ์จาก API ผู้ขาย GET จะได้รับการ แบ่งหน้า ไปที่หน้าที่ลิงก์เพื่อดูรูปแบบการตอบกลับทั่วไป แต่ละองค์ประกอบที่ส่งคืนกลับมาในอาร์เรย์ data จะอยู่ในรูปพารามิเตอร์คำขอผู้ขาย ตัวอย่าง:

curl -H "Authorization: OAuth $OAUTH" -X GET "https://graph.facebook.com/metapay_partner/merchants?partner_merchant_id=MERCHANT_TEST_1"
{
    "data": [
        {
            "partner_merchant_id": "MERCHANT_TEST_1",
            "merchant_status": "DISABLED",
            "display_name": "Test merchant 1",
            "business_uri": "https://facebook.com/",
            "icon_uri": "https://facebook.com/favicon.ico",
            "mcc_list": [7311],
            "support_email": "example@facebook.com",
            "support_phone": "+11234567890",
            "valid_origins": [
                "https://facebook.com/"
            ],
            "legal_structure": "COMPANY_TYPE_NOT_SPECIFIED",
            "status_modifiers":["BLOCKED"],
            "effective_merchant_status":"DISABLED"
        }
    ],
    "paging": {
        "cursors": {
            "before": "aaa...",
            "after": "bbb..."
        },
        "next": "https://graph.facebook.com/metapay_partner/merchants?limit=25&after=..."
    }
}

Webhooks

คุณต้องแจ้งให้ Meta ทราบถึงกิจกรรมสำหรับธุรกรรมการชำระเงิน โดยกระตุ้นการทำงาน Webhooks ของ Meta เมื่อใดก็ตามที่มีการอนุญาต การบันทึก การโต้แย้ง การชำระเงิน หรือการคืนเงินใดๆ เกิดขึ้น

การตอบกลับ 200 OK จะระบุว่า Webhook ได้รับการประมวลผลสำเร็จแล้ว เนื้อหาการตอบกลับที่สำเร็จจะส่งคืน container_id:

{
    "id":"cGF5bWVudF9jb250YWluZAXI6N2I3ODA1ZATYtZAmRiNS00Yzc4LWFjYjAtZATg3ZAjJhMzg2YTc5XzM2ODkyNjAzMTc4MDEzNzYZD"
}

หากกระตุ้นการทำงานของ Webhook ล้มเหลว โปรดลองอีกอย่างน้อย 3 ครั้งภายในอย่างน้อย 72 ชั่วโมงโดยเว้นระยะแต่ละครั้งมากขึ้นเรื่อยๆ หากการกระตุ้นการทำงานยังคงล้มเหลว คุณยังสามารถบันทึกการแจ้งเตือนในภายหลังได้ระหว่างการกระทบยอดทีละหลายรายการ

ภาพด้านล่างนี้เป็นแผนผังความสัมพันธ์ของเอนทิตี้สำหรับทรัพยากรที่จัดรูปแบบอยู่ใน Webhooks ของ Meta API คุณสมบัติที่มีจุดสีดำแสดงถึงคุณลักษณะที่จำเป็น

การแจ้งเตือน

ในแต่ละครั้งที่คุณกระตุ้นการทำงานของ Webhook ให้ใส่พารามิเตอร์การแจ้งเตือนไว้ในเนื้อหาของคำขอ และเพิ่มรายละเอียดประเภทการแจ้งเตือนในช่องทรัพยากร ตามที่อธิบายไว้ในส่วนที่ตามมา โครงสร้างทั่วไปสำหรับการแจ้งเตือนมีดังนี้

{
  idempotence_token: '<your token>',
  notification:
  {
    ...
  },
  resource:
  {
    ...
  }
}

พารามิเตอร์การแจ้งเตือน

แจ้งถึงการอนุญาต

ส่งคำขอ POST ไปยัง /<CONTAINER_ID>/notify_authorizations เพื่อแจ้งให้ Meta ทราบถึงกิจกรรมการอนุญาตสำหรับธุรกรรมการชำระเงิน

https://graph.facebook.com/<CONTAINER_ID>/notify_authorizations

ทรัพยากรในการอนุญาต

แจ้งถึงการบันทึก

ส่งคำขอ POST ไปยัง /<CONTAINER_ID>/notify_captures เพื่อแจ้งให้ Meta ทราบถึงกิจกรรมการบันทึกสำหรับธุรกรรมการชำระเงิน

https://graph.facebook.com/<CONTAINER_ID>/notify_captures

ทรัพยากรในการบันทึก

แจ้งถึงการโต้แย้ง

ส่งคำขอ POST ไปยัง /<CONTAINER_ID>/notify_disputes เพื่อแจ้งให้ Meta ทราบถึงกิจกรรมการโต้แย้งสำหรับธุรกรรมการชำระเงิน

https://graph.facebook.com/<CONTAINER_ID>/notify_disputes

ทรัพยากรในการโต้แย้ง

แจ้งถึงการชำระเงิน

ส่งคำขอ POST ไปยัง /<CONTAINER_ID>/notify_payments เพื่อแจ้ง Meta ถึงกิจกรรมการชำระเงินที่ไม่เกี่ยวข้องกับการดำเนินการโยกย้ายตัวเงิน เช่น คุณอาจตัดสินใจไม่ประมวลผลการชำระเงินของผู้ใช้รายหนึ่งเพราะไม่ผ่านการตรวจสอบความเสี่ยง

https://graph.facebook.com/<CONTAINER_ID>/notify_payments

ทรัพยากรการชำระเงิน

แจ้งถึงการคืนเงิน

ส่งคำขอ POST ไปยัง /<CONTAINER_ID>/notify_refunds เพื่อแจ้งให้ Meta ทราบถึงกิจกรรมการคืนเงินสำหรับธุรกรรมการชำระเงิน

https://graph.facebook.com/<CONTAINER_ID>/notify_refunds

ทรัพยากรในการคืนเงิน

อ็อบเจ็กต์จำนวนการแจ้งเตือน

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

อ็อบเจ็กต์จำนวน

อ็อบเจ็กต์ข้อผิดพลาดในการแจ้งเตือน

หากเกิดข้อผิดพลาดขึ้นเมื่อคุณประมวลผลการอนุญาต การบันทึก การชำระเงิน หรือการคืนเงิน ให้เพิ่มอ็อบเจ็กต์ error ใน resource เพื่อให้ข้อมูลเกี่ยวกับข้อผิดพลาด

อ็อบเจ็กต์ข้อผิดพลาด