다음은 고려해야 할 몇 가지 중요한 사용 사례와 현금 FOP를 구현하는 데 필요한 가이드라인 및 API입니다.
사용 사례
Reference Number API는 다양한 용도로 사용됩니다. 이 가이드에서는 두 가지 사용 사례를 설명하고 구현을 안내합니다.
현금
사용자는 편의점과 같은 오프라인 매장에서 현금으로 결제하여 Google에서 상품을 구매할 수 있습니다. 사용자는 거래를 식별하기 위해 매장으로 가져가 결제할 수 있는 참조 번호를 생성합니다. 또한 Google은 사용자에게 구매 완료 방법에 대한 안내를 표시합니다. 이상적으로는 사용자가 구매를 완료하는 즉시 통합업체가 Google에 이를 알려 Google에서 제품을 제공할 수 있도록 합니다.
Google 담당자가 일반적인 결제 안내 샘플을 요청할 것입니다. Google 담당자와 협력하여 메시지를 최적화하고 수정합니다.
Google이 제공하고 싶어 하는 사용자 경험은 고객 주문 상품이 매장에서 나갈 때 배송되는 것입니다. Google은 고객이 참조 번호를 지불한 후 3분 이내에 ReferenceNumberPaidNotification이 Google에 수신될 것으로 예상합니다. ReferenceNumberpaidNotification이 전송되면 통합업체가 거래를 되돌릴 수 없습니다.
VAN
사용자는 은행 계좌로 상품 가격을 지불할 수 있습니다. Google은 통합업체에 가상계좌번호를 요청하며 해당 번호와 안내가 사용자에게 표시됩니다. 그러면 사용자가 번호를 복사하여 은행 애플리케이션에 송금할 금액과 함께 입력합니다.
통합자는 송금된 금액이 referenceNumberGeneration 요청 금액과 일치하는지 확인한 다음 Google에 참조 번호가 지불되었음을 알려야 합니다.
Google이 ReferenceNumberPaidNotification을 수신하면 제품을 전송하며 통합업체가 거래를 취소할 수 없습니다.
사용자 서버와 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는 송금 및 정산을 처리합니다.
- RemittanceStatementNotification
- RemittanceStatementDetails
- AcceptRemittanceStatement/AcceptRemittanceStatement(수정 포함)
참조 번호를 생성하고 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"
}
샘플 Java
`String generateReferenceNumberJson = Utils.decryptAndDecode(encodedEncryptedGenerateReferenceNumberRequest);`
GenerateReferenceNumberRequest request = gson.fromJson(generateReferenceNumberJson, GenerateReferenceNumberRequest.class);
참조 번호 취소
Google은 참조 번호를 취소하고 사용자가 결제하지 못하도록 할 수 있습니다. 만료된 프로모션을 예로 들 수 있습니다. 이 요청에 성공적으로 응답한 후에는 참조 번호를 지불할 수 없는지 확인해야 합니다.
사용자가 이미 결제 프로세스를 시작한 경우(예: 판매 시점에서 참조 번호 조회) 서버는 USER_ACTION_IN_PROGRESS 상태로 요청 본문에 HTTP 423 응답 및 ErrorResponse로 응답해야 합니다.
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를 통합하면 송금할 준비가 됩니다. 송금은 모든 결제 수단에서 동일하게 작동합니다.
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를 참고하세요.
acceptRemittanceStatement 및 acceptRemittanceStatementWithModifications
통합자는 이러한 이벤트를 기록한 이벤트와 비교해야 합니다. 거래가 일치하지 않거나 누락된 거래는 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"
}