Meta Pay API 사용

Meta Pay의 결제를 처리할 때는 Meta Pay API에서 Webhooks를 호출하여 Meta에 결제 거래 활동(예: 승인, 환불)에 대해 알려야 합니다. 결제 거래 활동은 고객 Facebook 계정의 주문 및 결제 페이지에 표시됩니다.

Meta API를 사용하는 방법에 대한 자세한 내용은 그래프 API 개요를 참조하세요. 아래에서 설명하는 API는 표준 그래프 API 호스트 URL(https://graph.facebook.com)에 상대적입니다. 자세한 일반 정보는 Meta Pay 통합 개요를 참조하세요.

온보딩

Meta Pay API를 사용하기 전에 다음 단계를 완료해야 합니다.

• 일반 온보딩 단계 완료
• Meta Pay의 결제 처리 검토

Meta Pay API 호출

일반 온보딩 단계의 일환으로 Meta for Developers 포털에서 새 앱을 만듭니다. 앱을 만들면 앱 ID와 앱 시크릿 코드를 얻습니다.

Meta Pay API로 호출을 보낼 때마다 앱 ID 및 앱 시크릿 코드에서 얻은 앱 액세스 토큰이 필요합니다. access_token 쿼리 매개변수가 아니라 Authorization 헤더를 사용하여 앱 액세스 토큰을 보냅니다. Meta Pay API는 사용자 토큰이 포함된 호출을 거부합니다.

예를 들어 다음과 같은 코드를 사용합니다.

Authorization: OAuth <APP_ACCESS_TOKEN>

서명

Meta Pay API로 HTTP 요청을 보낼 때마다 FBPAY-SIGNATURE 요청 헤더를 포함해야 합니다. 이 헤더의 값은 ES256 알고리즘, 콤팩트 직렬화, 분리된 페이로드(https://tools.ietf.org/html/rfc7515#appendix-F 참조)를 포함한 JWS(JSON Web Signature) 개체입니다. 페이로드 값은 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 필드는 네트워크 장애가 발생하거나 시간이 초과된 이후에 요청을 다시 시도할 때 요청의 중복 실행을 방지하는 데 사용합니다. 멱등 토큰은 클라이언트에서 생성한 고유 값이며, 클라이언트가 이 토큰의 생성 방법을 결정합니다. 예를 들어 V4 UUID를 사용하여 멱등 토큰을 생성할 수 있습니다.

요청이 성공적으로 완료되거나 API로 보낸 호출에서 유효한 값이 반환되면 응답 데이터가 멱등 토큰과 함께 저장됩니다. 이전에 사용한 멱등 토큰으로 성공한 요청을 다시 시도할 경우 코드를 다시 실행하지 않고 앞서 저장한 응답을 반환합니다.

요청에서 오류가 발생하면 결과가 저장되지 않습니다. 요청을 다시 시도하고 동일한 멱등 토큰을 사용할 수 있습니다.

동일한 멱등 토큰으로 동시에 요청을 2개 보낼 경우 하나만 응답 데이터를 반환합니다.

멱등 토큰은 API 호출이 실패할 경우 다시 시도하기 위한 목적으로만 임시로 사용합니다. 어느 정도 시간이 지나서 요청을 다시 시도하면 이전의 호출과 다른 응답을 수신할 수 있습니다.

요청 매개변수는 무시됩니다. 그래도 요청 내용을 변경하고자 할 경우 해당 요청에 새 멱등 토큰을 만드세요.

일괄 조정

결제를 처리할 때 Meta Pay Webhooks를 사용하여 Meta에 결제 거래 활동에 대해 알리세요. Webhooks를 호출하면 결제 거래 활동이 최대한 빠르게 고객 Facebook 계정의 Facebook Pay 활동 페이지에 표시됩니다.

실패한 알림은 일괄 조정 시 Meta에서 캡처하고 나중에 고객 Facebook 계정에 표시됩니다.

일괄 조정을 지원하려면 그날에 Meta로 보낸 알림이 포함된 파일을 매일 업로드합니다. 성공한 알림과 실패한 알림을 모두 포함합니다. Meta API에 파일을 업로드하는 방법에 대한 자세한 내용은 Facebook에 파일 업로드를 참조하세요.

오류 처리

Meta Pay API는 표준 그래프 API 오류 처리를 사용합니다.

판매자 초기화 및 업데이트

지원하는 판매자의 데이터를 초기화하거나 업데이트하려면 POST 요청을 판매자 그래프 API/metapay_partner/merchant로 보내고 판매자 매개변수를 지정합니다.

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

요청 매개변수

응답

판매자 API로 POST 요청을 보낸 후 200 OK 응답을 받으면 POST가 성공적으로 처리되었다는 것을 의미합니다. 응답 본문은 판매자 상태를 ENABLED 또는 DISABLED로 나타냅니다. 비어 있지 않은 상태 수정자는 추가 정보를 제공합니다.

일반적으로 성공한 응답은 다음과 같습니다.

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

임시 검사를 진행하고 있는 판매자에 대한 응답은 다음과 같습니다.

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

사용 가능한 상태 수정자는 다음과 같습니다.

판매자 가져오기

등록된 판매자의 리스트를 가져오려면 판매자 그래프 API /metapay_partner/merchants로 GET 요청을 보내세요.

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

요청 매개변수

다음 선택적 요청 매개변수는 URL 매개변수로 지원됩니다.

응답

GET 판매자 API에서 얻은 결과는 페이지 매김됩니다. 일반적인 응답 형식은 링크된 페이지를 참조하세요. 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 응답은 Webhooks가 성공적으로 처리되었다는 것을 나타냅니다. 요청에 성공한 응답 본문에서는 container_id를 반환합니다.

{
    "id":"cGF5bWVudF9jb250YWluZAXI6N2I3ODA1ZATYtZAmRiNS00Yzc4LWFjYjAtZATg3ZAjJhMzg2YTc5XzM2ODkyNjAzMTc4MDEzNzYZD"
}

Webhooks 호출이 실패하는 경우, 재시도 간격을 점차 늘려가며 최소 72시간 동안 3회 이상 호출을 다시 시도하세요. 그래도 호출이 실패할 경우 나중에 일괄 조정 시 알림을 캡처할 수 있습니다.

Meta API Webhooks에서 모델링된 리소스의 엔터티 관계 다이어그램은 다음과 같습니다. 검은색 점이 있는 속성은 필수 속성을 나타냅니다.

알림

Webhooks를 호출할 때마다 요청 본문의 알림 매개변수와 리소스 필드의 알림 유형에 대한 상세 정보를 아래의 섹션에 나와 있는 대로 포함합니다. 알림의 일반 구조는 다음과 같습니다.

{
  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

환불 리소스

알림 금액 개체

금액 개체를 사용하여 승인, 캡처, 분쟁 및 환불에 대한 알림의 각 통화 단위의 금액을 나타냅니다.

금액 개체

알림 오류 개체

승인, 캡처, 결제 또는 환불을 처리할 때 오류가 발생하는 경우 resource에 error 개체를 포함해 오류에 대한 정보를 제공합니다.

오류 개체