Sử dụng API Meta Pay

Khi xử lý các khoản thanh toán cho Meta Pay, bạn phải thông báo cho Meta về hoạt động giao dịch thanh toán (ví dụ: ủy quyền và hoàn tiền) bằng cách gọi webhook trong API Meta Pay. Hoạt động giao dịch thanh toán sẽ hiện trên trang Đơn đặt hàng và thanh toán trong tài khoản Facebook của khách hàng.

Nếu bạn muốn tìm hiểu cách sử dụng các API của Meta, hãy xem bài viết Tổng quan về API Đồ thị và lưu ý rằng những API được mô tả bên dưới đều liên quan đến URL lưu trữ API Đồ thị tiêu chuẩn (https://graph.facebook.com). Để biết thêm thông tin chung, hãy xem bài viết Tổng quan về quá trình tích hợp Meta Pay.

Tích hợp

Bạn cần hoàn tất các bước sau thì mới có thể bắt đầu sử dụng API Meta Pay:

• Hoàn tất các bước tích hợp chung
• Xem bài viết Xử lý thanh toán trong Meta Pay

Gọi API Meta Pay

Trong các bước tích hợp chung, bạn sẽ tạo một ứng dụng mới trên Cổng thông tin Meta for Developers. Sau khi tạo ứng dụng, bạn sẽ nhận được ID ứng dụng và khóa bí mật của ứng dụng cho ứng dụng của mình.

Mỗi lệnh gọi mà bạn thực hiện đến API Meta Pay đều cần có một mã truy cập ứng dụng được lấy từ ID ứng dụng và khóa bí mật của ứng dụng. Hãy gửi mã truy cập ứng dụng bằng cách sử dụng tiêu đề Authorization, chứ không phải thông số truy vấn access_token. API Meta Pay sẽ từ chối các lệnh gọi bằng mã người dùng.

Ví dụ: sử dụng mã sau đây:

Authorization: OAuth <APP_ACCESS_TOKEN>

Chữ ký

Mọi yêu cầu HTTP gửi đến API Meta Pay đều phải chứa một tiêu đề yêu cầu FBPAY-SIGNATURE. Giá trị của tiêu đề này là một đối tượng Chữ ký web JSON (JWS) có thuật toán ES256, phương thức nối tiếp hóa nhỏ gọn và phần tải dữ liệu tách biệt (theo https://tools.ietf.org/html/rfc7515#appendix-F). Giá trị phần tải dữ liệu là phần nội dung yêu cầu HTTP POST. Khóa chữ ký JWS phải được xác định bằng tiêu đề x5c. Tiêu đề này phải chứa một chứng chỉ liên kết với gốc tin cậy của đối tác. Chứng chỉ gốc của đối tác được chia sẻ với Meta trong quy trình tích hợp (được gọi là chứng chỉ ký API Meta Pay).

Ví dụ về yêu cầu có chữ ký

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"}'

Yêu cầu trước đó mã hóa dữ liệu sau đây:

{
  "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"
}

Sau đây là chữ ký từ yêu cầu trước đó, Base64 và JSON được giải mã để dễ hiểu:

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

Tích lũy đẳng

Trường idempotence_token được dùng để ngăn tình trạng thực thi trùng lặp các yêu cầu khi yêu cầu được gửi lại do lỗi mạng hoặc hết thời gian chờ. Mã tích lũy đẳng là giá trị duy nhất do ứng dụng tạo ra và ứng dụng sẽ quyết định cách tạo mã này. Ví dụ: bạn có thể sử dụng UUID V4 để tạo mã tích luỹ đẳng.

Khi một yêu cầu hoàn tất thành công hoặc lệnh gọi đến API trả về kết quả hợp lệ, dữ liệu phản hồi sẽ được lưu kèm theo mã tích luỹ đẳng. Khi bạn thử lại một yêu cầu thành công bằng mã tích luỹ đẳng từng sử dụng, phản hồi đã lưu trước đó sẽ được trả về mà không cần chạy lại mã nào.

Khi một yêu cầu bị lỗi, kết quả sẽ không được lưu. Bạn có thể thử lại yêu cầu đó và sử dụng cùng một mã tích lũy đẳng.

Nếu bạn gửi đồng thời 2 yêu cầu bằng một mã tích lũy đẳng, chỉ một yêu cầu trả về dữ liệu phản hồi.

Mã tích lũy đẳng chỉ mang tính tạm thời và chỉ được dùng để thử lại lệnh gọi API trong trường hợp xảy ra lỗi. Nếu thử lại một yêu cầu sau một thời gian, bạn có thể nhận được phản hồi khác với lệnh gọi trước đó.

Các thông số yêu cầu được bỏ qua. Nếu bạn thay đổi nội dung yêu cầu theo cách nào đó, hãy tạo mã tích luỹ đẳng mới cho yêu cầu.

Đối chiếu hàng loạt

Khi xử lý các khoản thanh toán, bạn sẽ thông báo cho Meta về hoạt động giao dịch thanh toán thông qua webhook dành cho Meta Pay. Khi bạn gọi webhook, hoạt động giao dịch thanh toán sẽ xuất hiện ở trang Hoạt động trên Facebook Pay trong tài khoản Facebook của khách hàng ngay khi có thể.

Những thông báo không thành công sẽ được Meta ghi lại trong quá trình đối chiếu hàng loạt và xuất hiện trong tài khoản Facebook của khách hàng sau đó.

Để hỗ trợ đối chiếu hàng loạt, mỗi ngày, hãy tải lên một file có chứa các thông báo mà bạn đã gửi đến Meta vào ngày đó. Hãy đưa vào cả thông báo thành công lẫn thông báo không thành công. Để biết chi tiết về cách tải file lên Meta API, hãy xem phần Tải file lên Facebook.

Xử lý lỗi

API Meta Pay sử dụng phương thức xử lý lỗi API Đồ thị tiêu chuẩn.

Khởi tạo và cập nhật người bán

Để khởi tạo hoặc cập nhật dữ liệu cho một người bán mà bạn hỗ trợ, hãy gửi yêu cầu POST đến API Đồ thị cho người bán /metapay_partner/merchant và chỉ định thông số người bán.

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

Thông số yêu cầu

Phản hồi

Sau khi bạn gửi yêu cầu POST đến API người bán, phản hồi 200 OK sẽ cho biết rằng POST đã được xử lý thành công. Phần nội dung phản hồi cho biết trạng thái của người bán là ENABLED hay DISABLED. Thông số sửa đổi trạng thái không trống sẽ cung cấp thông tin bổ sung.

Một phản hồi thành công thường gặp sẽ có dạng như sau:

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

Một phản hồi dành cho người bán đang được sàng lọc tạm thời sẽ có dạng như sau:

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

Sau đây là các thông số sửa đổi trạng thái có thể có.

Lấy người bán

Để tìm nạp danh sách những người bán đã đăng ký, hãy gửi yêu cầu GET đến API Đồ thị cho người bán /metapay_partner/merchants.

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

Thông số yêu cầu

Sau đây là các thông số yêu cầu không bắt buộc được hỗ trợ dưới dạng thông số URL:

Phản hồi

Khi gửi yêu cầu GET đến API Người bán, bạn sẽ nhận được kết quả theo trang. Hãy xem định dạng phản hồi chung trên trang được liên kết. Mỗi thành phần được trả về trong mảng data sẽ có định dạng như thông số yêu cầu của Người bán. Ví dụ:

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

Bạn phải thông báo cho Meta về hoạt động giao dịch thanh toán bằng cách gọi webhook của Meta bất cứ khi nào diễn ra hoạt động ủy quyền, giữ lại, tranh chấp, thanh toán hoặc hoàn tiền.

Phản hồi 200 OK cho biết rằng webhook đã được xử lý thành công. Nội dung phản hồi thành công sẽ trả về container_id:

{
    "id":"cGF5bWVudF9jb250YWluZAXI6N2I3ODA1ZATYtZAmRiNS00Yzc4LWFjYjAtZATg3ZAjJhMzg2YTc5XzM2ODkyNjAzMTc4MDEzNzYZD"
}

Nếu gọi webhook không thành công, hãy thử gọi lại ít nhất 3 lần trong tối thiểu 72 giờ với thời gian chờ tăng dần. Nếu lệnh gọi này vẫn không thành công, hệ thống có thể ghi lại thông báo sau trong quá trình đối chiếu hàng loạt.

Sau đây là sơ đồ mối quan hệ thực thể cho các tài nguyên được lập mô hình trong webhook của Meta API. Chấm đen biểu thị thuộc tính bắt buộc.

Thông báo

Mỗi khi bạn gọi một webhook, hãy thêm thông số thông báo vào phần nội dung yêu cầu và thông tin chi tiết về loại thông báo vào trường tài nguyên, như được mô tả trong phần tiếp theo. Cấu trúc chung của thông báo sẽ như sau:

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

Thông số thông báo

Thông báo về hoạt động ủy quyền

Hãy gửi yêu cầu POST đến /<CONTAINER_ID>/notify_authorizations để thông báo cho Meta về hoạt động ủy quyền đối với một giao dịch thanh toán.

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

Tài nguyên về hoạt động ủy quyền

Thông báo về hoạt động giữ lại

Hãy gửi yêu cầu POST đến /<CONTAINER_ID>/notify_captures để thông báo cho Meta về hoạt động giữ lại đối với một giao dịch thanh toán.

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

Tài nguyên về hoạt động giữ lại

Thông báo về hoạt động tranh chấp

Hãy gửi yêu cầu POST đến /<CONTAINER_ID>/notify_disputes để thông báo cho Meta về hoạt động tranh chấp đối với một giao dịch thanh toán.

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

Tài nguyên về hoạt động tranh chấp

Thông báo về hoạt động thanh toán

Hãy gửi yêu cầu POST đến /<CONTAINER_ID>/notify_payments để thông báo cho Meta về hoạt động thanh toán không liên quan đến hoạt động chuyển tiền. Ví dụ: bạn có thể quyết định không xử lý khoản thanh toán của người dùng nếu thấy khoản thanh toán đó có rủi ro khi kiểm tra.

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

Tài nguyên về hoạt động thanh toán

Thông báo về hoạt động hoàn tiền

Hãy gửi yêu cầu POST đến /<CONTAINER_ID>/notify_refunds để thông báo cho Meta về hoạt động hoàn tiền đối với một giao dịch thanh toán.

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

Tài nguyên về hoạt động hoàn tiền

Đối tượng số tiền thông báo

Hãy sử dụng đối tượng số tiền để biểu thị giá trị tiền tệ bằng một đơn vị tiền tệ cụ thể cho các thông báo về hoạt động ủy quyền, giữ lại, tranh chấp và hoàn tiền.

Đối tượng số tiền

Đối tượng lỗi thông báo

Nếu xảy ra lỗi khi bạn xử lý hoạt động ủy quyền, giữ lại, thanh toán hoặc hoàn tiền, hãy thêm đối tượng error vào resource để cung cấp thông tin về lỗi.

Đối tượng lỗi