Cash FOP (AKA Reference Number API) 가이드

다음은 고려해야 할 몇 가지 중요한 사용 사례와 현금 FOP 구현에 필요한 가이드라인 및 API입니다.

사용 사례

Reference Number API는 다양한 용도로 사용됩니다. 이 가이드에서는 두 가지 사용 사례에 대해 논의하고 구현을 안내합니다.

  • 현금: 사용자가 오프라인 매장에서 현금으로 결제합니다.
  • VAN: 사용자가 가상계좌번호로 송금합니다.

현금

사용자는 편의점과 같은 물리적 위치에서 현금으로 결제하여 Google로부터 제품을 구매할 수 있습니다. 사용자는 거래를 식별하기 위해 참조 번호를 생성하여 매장으로 가져가 결제할 수 있습니다. 또한 Google은 사용자에게 구매를 완료하는 방법에 대한 안내를 표시합니다. 이상적으로는 사용자가 구매를 완료하는 즉시 통합업체에서 Google이 제품을 배송할 수 있도록 Google에 알립니다.

Google 담당자가 일반적인 결제 안내 샘플을 요청합니다. Google 담당자와 협력하여 메시지를 최적화하고 미세 조정합니다.

Google이 제공하고자 하는 사용자 경험은 고객이 매장을 떠나는 순간에 주문 상품이 배송되는 것입니다. 고객이 참조 번호를 결제한 후 3분 이내에 ReferenceNumberPaidNotification이 Google에 전송될 것으로 예상합니다. ReferenceNumberpaidNotification이 전송된 후에는 통합업체가 거래를 취소할 수 없습니다.

VAN

사용자가 은행 계좌로 상품을 결제할 수 있습니다. Google은 통합업체에 가상계좌번호를 요청하여 사용자에게 번호와 안내를 제시합니다. 그런 다음 사용자는 번호를 복사하여 송금할 금액과 함께 은행 신청서에 입력합니다.

통합업체는 송금된 금액이 referenceNumberGeneration 요청 금액과 일치하는지 확인한 후 참조 번호가 결제되었음을 Google에 알려야 합니다.

Google이 ReferenceNumberPaidNotification을 수신하면 Google은 제품을 배송하며 통합업체는 거래를 취소할 수 없습니다.

사용자 서버와 Google 서버 간에 메시지 전송

사용자 서버와 Google 서버 간에 또는 그 반대의 경우 메시지를 보낼 때는 다음 가이드라인을 따르세요.

수신 요청 - DecryptWithVendorPrivateKey(Base64UrlDecode(request))

발신 응답 - Base64UrlEncode(EncryptWithGooglePublicKey(request))

Google 요청 - Base64UrlEncode(EncryptWithGooglePublicKey(request))

Google 응답 - DecryptWithVendorPrivateKey(Base64UrlDecode(request))

다음은 요청 및 응답 처리를 보여주는 Java의 PGP 라이브러리샘플입니다.

멱등 동작 따르기

멱등성은 이미 성공적으로 처리된 요청 (예: 결제)을 다시 처리하려고 해서는 안 된다는 의미입니다. 대신 성공적인 처리에 대한 응답이 보고되어야 합니다.

중요한 이유

Google은 Google 측의 상태가 공급업체 측의 상태와 동일한지 확인하기 위해 일부 요청을 재시도할 수 있습니다. 시스템에서 이 거래를 또 다른 거래로 간주해서는 안 됩니다. 따라서 멱등성은 매우 중요합니다. 즉, 통합업체는 이미 성공적으로 처리된 항목을 재처리해서는 안 됩니다. 이러한 경우 이전 응답을 대신 전송해야 합니다.

멱등성 구현 방법

Google에서 재시도를 보내면 요청 ID는 동일하고 콘텐츠는 동일하지만 타임스탬프는 다릅니다. 이전에 보낸 것과 동일한 응답으로 응답합니다. 첫 번째 응답이 200 (성공)이면 Google은 다른 타임스탬프가 있는 동일한 응답을 예상할 것입니다.

이전 응답이 오류 (400 또는 500 등)였다면 해당 요청을 새 요청으로 처리하고 다시 확인해야 합니다. 이는 서버가 처음 다운된 경우에 유용하며, 다시 시도하면 요청이 성공적으로 처리될 수 있습니다.

자세한 내용은 상세 가이드를 참고하세요.

결제 통합업체 계정 ID (PIAID) 사용

Google과 통합하려면 Google의 다른 비즈니스 법인과 통합해야 할 수 있습니다. 예를 들어 Google Play는 YouTube, 또 다른 법인은 Google Ads입니다. 여기에는 이러한 각 구성을 나타내는 여러 판매자 계정이 포함됩니다.

Google 내 각 법인에서 각 판매자 계정으로의 매핑을 위해 Google은 결제 통합업체 계정 ID (PIAID)를 제공합니다. 현금 FOP API의 예는 generateReferenceNumber를 참조하세요. 다음은 이 매핑을 사용하는 샘플입니다.

Google 내 각 법인에서 각 판매자 계정으로의 매핑을 위해 Google은 결제 통합업체 계정 ID (PIAID)를 제공합니다. 현금 FOP API 사용 예는 generateReferenceNumber를 참조하세요. 다음은 이 매핑을 사용하는 샘플입니다.


{
  "requestHeader": {
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    },
    "requestId": "bWVyY2hhbnQgdHJhbnNhY3Rpb24gaWQ",
    "requestTimestamp": "1502220196077"
  },
  "paymentIntegratorAccountId": "InvisiCashUSA_USD",
  "transactionDescription": "Google - Music",
  "currencyCode": "USD",
  "amount": "2000000"
}

강조표시된 부분을 확인하세요. 여기서 필요한 두 가지 값은 Google 담당자가 제공한 paymentIntegratorAccountId과 판매자 계정입니다.

또한 통합업체는 서비스를 제공하는 각 국가에 따라 다른 계정을 가질 수 있습니다. 이는 다양한 세법과 국가마다 다른 차이점이 있기 때문일 수 있습니다. 이 경우 국가별로 다른 PIAID가 생성될 수 있습니다.

통합할 API

다음 API는 참조 번호 생성 및 결제 알림을 처리합니다.

다음 API는 송금 및 정산을 처리합니다.

참조 번호를 생성하고 Google과 정산하려면 위의 모든 API를 통합해야 합니다.

참조 번호 생성

구매를 시작하면 Google에서 GenerateReferenceNumber를 호출합니다. 거래 또는 계정을 식별하는 참조 번호를 포함하여 답장해 주시기 바랍니다. 예상 지연 시간은 3초 미만입니다.

현금 거래의 경우 최대 12자까지 참조 번호를 입력할 수 있습니다.

URL: POST https://[your basepath]/v1/generateReferenceNumber

JSON 요청

{
"requestHeader": {
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    },
    "requestId": "cf9fde73-3735-4463-8e6e-c999fda35af6",
    "requestTimestamp": "1561678470395"
  },
  "paymentIntegratorAccountId": "Sample_Cash_Vendor_282",
  "transactionDescription": "Google Play - Tester",
  "currencyCode": "USD",
  "amount": "10000000"
}

응답 JSON

{
  "responseHeader": {
    "responseTimestamp": "1561678947659"
  },
  "result": "SUCCESS",
  "referenceNumber": "38a41c05-ba7b-4040-a909-4331d0b9ce46"
}

샘플 자바

`String generateReferenceNumberJson = Utils.decryptAndDecode(encodedEncryptedGenerateReferenceNumberRequest);`
GenerateReferenceNumberRequest request = gson.fromJson(generateReferenceNumberJson, GenerateReferenceNumberRequest.class);

참조 번호 취소

Google은 참조 번호를 취소하고 사용자가 참조 번호를 결제하지 못하도록 선택할 수 있습니다. 만료된 프로모션을 사용 사례로 들 수 있습니다. 이 요청에 대해 성공적으로 응답한 후에는 참조 번호가 지불될 수 없는지 확인해야 합니다.

사용자가 이미 결제 프로세스를 시작한 경우(예: 판매 시점에 참조 번호 조회) 서버는 요청 본문에 HTTP 423 응답 및 ErrorResponse로 USER_ACTION_IN_PROGRESS 상태로 응답해야 합니다.

URL: POST https://[your basepath]/v1/cancelReferenceNumber

JSON 요청

{
"requestHeader": {
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    },
    "requestId": "51e00f16-36ba-4490-b228-0a670d202206",
    "requestTimestamp": "1561678947926"
  },
  "paymentIntegratorAccountId": "Sample_Cash_Vendor_282",
  "referenceNumber": "38a41c05-ba7b-4040-a909-4331d0b9ce46"
}

응답 JSON

{
  "responseHeader": {
    "responseTimestamp": "1561680406459"
  },
  "result": "SUCCESS"
}

referenceNumberPaidNotification

결제가 수락되고 거래가 완료되면 서비스가 Google에 거래가 완료되었음을 알리고 제품을 사용자에게 제공해야 합니다. Google에 이 알림이 접수되면 거래가 완료되고 예약이 불가능할 것으로 예상합니다.

referenceNumberPaidNotification 엔드포인트 URL:


POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/referenceNumberPaidNotification/[PIAID]

JSON 요청

{
 "requestHeader": {
    "requestTimestamp": "1561748625577",
    "requestId": "ae8e310a-92de-436a-a32c-0bd753ae4e4b",
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    }
  },
  "paymentIntegratorTransactionId": "cf9fde73-3735-4463-8e6e-c999fda35af6",
  "referenceNumber": "e4e15b5d-8154-4068-b6eb-560e2a65ac48",
  "paymentLocation": {
    "brandName": "TestMart",
    "locationId": "1234"
  },
   "paymentIntegratorAccountId": "Sample_Cash_Vendor_282",
  "paymentTimestamp": "1561748625577"
}

응답 JSON

{
  "responseHeader": {
    "responseTimestamp": "1561748642600"
  },
  "result": "SUCCESS"
}

송금 구현

특정 FOP의 API를 통합하고 나면 송금할 준비가 된 것입니다. 송금은 모든 FOP에서 동일하게 진행됩니다.

remittanceStatementNotification

거래 2일 후 Google에서 당일에 Google에서 기록한 거래 요약을 포함하는 remittanceStatementNotification을 전송합니다. 샘플 알림은 다음과 같이 거래일로부터 2일 후에 표시됩니다.

POST https://www.integratordomain.com/v1/remittanceStatementNotification

JSON 요청


{
  "requestHeader": {
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    },
    "requestId": "0123434-statement-abc",
    "requestTimestamp": "1502632800000"
  },
  "paymentIntegratorAccountId": "InvisiCashUSA_USD",
  "remittanceStatementSummary": {
    "statementDate": "1502607600000",
    "billingPeriod": {
      "startDate": "1502434800000",
      "endDate": "1502521199000",
    },
    "dateDue": "1503212400000",
    "currencyCode": "INR",
    "totalDueByIntegrator": "1076000000",
  }
}

totalDueByIntegrator 매핑을 확인합니다. 이 줄에서는 통합업체가 지불해야 하는 순 금액을 확인할 수 있습니다 (마이크로). 또한 이 메시지에는 통화의 날짜와 유형이 표시되며, 결제 기간은 각각 가장 빠른 거래일과 최근 거래일의 00:00:00.000과 23:59:59.999를 나타냅니다.

조정 (remittanceStatementDetails)

조정을 위해 통합자는 remittanceStatementDetails를 호출하여 remittanceStatementNotification에 포함된 이벤트 목록을 가져옵니다.

Google은 페이지로 나눈 이벤트 목록으로 remittanceStatementDetails 요청에 응답합니다. 총 트랜잭션 수가 1,000보다 크면 remittanceStatementDetails를 여러 번 호출해야 합니다. 요청은 순차적으로 이루어질 필요가 없으며 동시에 처리될 수 있습니다.

요청 URL

POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/remittanceStatementDetails

샘플 요청 본문

{
  "requestHeader": {
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    },
    "requestId": "statement_detail_request_139932019",
    "requestTimestamp": "1502551332087"
  },
  "paymentIntegratorAccountId": "InvisiCashUSA_USD",
  "statementId": "0123434-statement-abc",
  "numberOfEvents": 4
}

다음은 캡처 이벤트 (트랜잭션) 두 개를 설명하는 더 큰 응답의 짧은 스니펫입니다.

"captureEvents": [ {
    {
      "eventRequestId": "bWVyY2hhbnQgdHJhbnNhY3Rpb24gaWQ",
      "paymentIntegratorEventId": "ioj32SOIjf23oijSDfoij",
      "eventCharge": "700000000",
      "eventFee": "-28000000"
    },
    {
      "eventRequestId": "Ggghvh78200PQ3Yrpb",
      "paymentIntegratorEventId": "iasdf23dSdfijSDfoij",
      "eventCharge": "800000000",
      "eventFee": "-32000000"
    }
  }

자세한 내용은 remittanceStatementDetails를 참고하세요.

acceptRemittanceStatementacceptRemittanceStatementWithModifications

통합자는 이러한 이벤트를 자신이 기록한 이벤트와 비교해야 합니다. 거래가 일치하지 않거나 거래가 누락된 경우 추가 조사를 위해 Google에 문의하세요. 모든 거래가 일치하고 처리 수수료에 세금이 포함되어 있지 않으면 acceptRemittanceStatement를 호출합니다. 세금이 포함된 경우 acceptRemittanceStatementWithModifications를 호출합니다.

acceptRemittanceStatement 메서드는 수수료에 세금이 없는 경우 사용됩니다.

세금을 포함하려면 acceptRemittanceStatementWithModifications를 호출하여 세율을 정의합니다. 세율이 변경되면 세율을 업데이트해야 합니다. acceptRemittanceStatement이(가) 완료되면 Google 계정으로 은행 송금을 시작합니다.

acceptRemittanceStatement의 요청 URL

POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/acceptRemittanceStatement

샘플 요청 본문

{
  "requestHeader": {
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    },
    "requestId": "0123434-abc",
    "requestTimestamp": "1502545413098"
  },
  "paymentIntegratorAccountId": "InvisiCashUSA_USD",
  "statementId": "0123434-statement-abc"
}

샘플 응답

{
  "responseHeader": {
    "responseTimestamp": "1519996752221"
  }
  "acceptRemittanceStatementResultCode": "SUCCESS"
}

acceptRemittanceStatementWithModifications의 요청 URL

POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/acceptRemittanceStatementWithModifications

샘플 요청 본문

{
  "requestHeader": {
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    },
    "requestId": "0123434-abc",
    "requestTimestamp": "1502545413098"
  },
  "paymentIntegratorAccountId": "InvisiCashUSA_USD",
  "statementId": "0123434-statement-abc"
  "feeToVatModification": {
    "vatToFeeRatioInMicros": "150000"
  }
}

샘플 응답

{
  "responseHeader": {
    "responseTimestamp": "1519996752221"
  }
  "acceptRemittanceStatementWithModificationsResultCode": "SUCCESS"
}