API는 일련의 HTTP API 표준을 따르며 멱등성을 지원하여 더 강력한 통합을 용이하게 합니다.
Google 호스팅 URL
각 Google 호스팅 메서드 문서에서는 메서드 이름과 주 버전 번호가 포함된 기본 URL을 제공합니다. 끝 부분에 호출자의 결제 통합업체 계정 ID를 추가하면 전체 URL이 생성됩니다. 예를 들어 Google 호스팅 에코 메서드에 관한 문서에서는 다음 URL을 지정합니다.
https://vgw.googleapis.com/gsp/chargeback-alert-v1/echo
호출자의 결제 통합업체 계정 ID가 INTEGRATOR_1인 경우 다음과 같이 URL의 끝 부분에 추가할 수 있습니다.
https://vgw.googleapis.com/gsp/chargeback-alert-v1/echo/INTEGRATOR_1
파트너 호스팅 URL
각 파트너 호스팅 API 메서드 문서에서는 메서드 이름과 주 버전 번호가 포함된 기본 URL을 제공합니다. 호스팅하는 URL에 결제 통합업체 계정 ID(PIAID)를 포함해서는 안 됩니다.
샌드박스 및 프로덕션 환경
Google은 샌드박스(개발 및 테스트용)와 프로덕션 모두에서 Chargeback Alert API를 호스팅합니다. Google 샌드박스 환경에서 요청하는 경우 실질적인 금전적 책임이 발생하지 않습니다. 샌드박스 환경과 프로덕션 환경은 완전히 별개이며 키 또는 트랜잭션 정보를 공유하지 않습니다.
Google은 샌드박스를 사용하여 변경사항 및 새로운 기능을 먼저 테스트하므로 샌드박스를 지속적으로 사용할 수 있을 것으로 기대합니다.
Google의 샌드박스 기본 경로
https://vgw.sandbox.google.com/gsp/
Google의 프로덕션 기본 경로
https://vgw.googleapis.com/gsp/
이 가이드에서는 프로덕션 엔드포인트를 사용합니다.
콘텐츠 유형 및 인코딩
PGP 암호화를 사용하는 메시지 페이로드는application/octet-stream; charset=utf-8 콘텐츠 유형을 사용해야 합니다.
JWE 암호화를 사용하는 메시지 페이로드는 application/jose; charset=utf-8 콘텐츠 유형을 사용해야 합니다.
요청 본문은 rfc4648 §5에 정의된 대로 base64url 인코딩을 사용하여 전송해야 합니다.
HTTP 상태 코드
Chargeback Alert API는 서버에서 처리할 수 있는 모든 요청에 대해 HTTP 200 상태 코드를 반환하도록 설계되었습니다. 여기에는 비즈니스 또는 애플리케이션 로직의 관점에서 성공한 요청과 거부된 요청이 모두 포함됩니다. 처리할 수 없는 요청은 Google과 파트너 간의 오류를 나타내므로 HTTP 200 상태 코드가 발생해서는 안 됩니다. 대신 API 응답에서 선택형 ErrorResponse 객체와 함께 아래와 같이 적절한 HTTP 상태 코드를 사용해야 합니다.
| HTTP 오류 및 이유 | |
|---|---|
| 400 |
BAD REQUEST
클라이언트가 잘못된 인수를 지정했습니다. 시스템이 작업 실행에 필요한 상태가 아니기 때문에 작업이 거부된 경우에도 이 값이 반환될 수 있습니다. 시스템 상태가 명시적으로 수정될 때까지 요청 재시도가 성공할 수 없는 경우에 사용하세요. 예를 들어 환불 요청이 존재하지 않는 캡처를 참조하여 실패하면 통합업체 시스템에 캡처가 존재할 때까지 재시도가 실패합니다.
|
| 401 |
UNAUTHORIZED
요청에 작업과 관련된 올바른 사용자 인증 정보가 없습니다. 예를 들어 잘못된 서명 또는 알 수 없는 서명은 401을 반환합니다. |
| 403 |
FORBIDDEN / PERMISSION DENIED
호출자에게 지정한 작업을 실행할 권한이 없습니다. |
| 404 |
NOT FOUND
결제 또는 사용자 등 일부 요청 항목을 찾을 수 없습니다. |
| 409 |
CONFLICT / ABORTED
작업이 취소되었습니다. 일반적으로 시퀀서 확인 실패, 트랜잭션 취소 등의 동시 실행 문제 때문입니다. |
| 412 |
PRECONDITION FAILED
이 코드는 멱등성 키가 여러 매개변수와 함께 재사용되는 상황에서 사용해야 합니다. |
| 429 |
RESOURCE EXHAUSTED / TOO MANY REQUESTS
일부 시스템 리소스가 소진되었습니다. |
| 499 |
CANCELLED
작업이 취소되었습니다. 대개 호출자에 의해 취소됩니다. |
| 500 |
INTERNAL ERROR
내부 오류가 발생했습니다. 이는 기본 시스템에서 기대하는 일부 불변량이 손상되었음을 의미합니다. |
| 501 |
UNIMPLEMENTED
이 서비스에 작업이 구현되어 있지 않거나 지원되지 않거나 사용 설정되어 있지 않습니다. |
| 503 |
UNAVAILABLE
현재 서비스를 사용할 수 없습니다. 일시적인 상태일 가능성이 높으며 재시도하여 수정할 수 있습니다. |
| 504 |
GATEWAY TIMEOUT / DEADLINE EXCEEDED
작업을 완료하기 전에 기한이 지났습니다. 시스템의 상태를 변경하는 작업의 경우 작업이 정상적으로 완료되어도 이 오류가 반환될 수 있습니다. 예를 들어 서버의 성공 응답이 오래 지연되어 기한이 지났을 수 있습니다. |
멱등성 요청
멱등성 요청은 Google과 파트너 간에 안정적이고 내결함성이 보장되는 시스템 상호작용을 위해 사용되는 Chargeback Alert API에서 가장 중요한 전략입니다. 멱등 요청은 여러 번 전송될 수 있지만 단일 요청과 효과가 동일한 요청입니다. 이 전략은 재시도를 안전하게 함으로써 시스템 간의 eventual consistency를 용이하게 하여 시스템이 리소스 상태에 동의하도록 합니다.
Google의 API는 멱등성을 활용하여 다음을 수행합니다.
- 모든 작업을 쉽게 추적하고 감사할 수 있게 하여 조정 문제를 줄입니다.
- 동일한 클라이언트의 동일한 여러 요청이 서로 다른 최종 상태로 이어지지 않도록 하여 경합 상태를 방지합니다.
- 요청을 고립시켜 인식할 수 있는 방식으로 상태를 최소화하고, 데이터 보관으로 인해 발생하는 서버 부하를 제거하여 성능 및 처리량이 향상됩니다.
- 요청이 재시도인지 여부를 나타내기 위해 추가 필드를 사용하지 않아도 됩니다.
예
예 1: 응답을 수신하기 전에 연결 끊김
시나리오:
- Google에서 통합업체에 캡처 요청을 보냅니다.
- 통합업체 서버가 이 요청을 받아 성공적으로 처리합니다.
- Google 서버가 2단계에서 응답을 받기 전에 전원이 끊깁니다.
- Google의 서버 전원이 복원되고, 동일한 캡처 요청(요청 ID와 요청 세부정보는 동일하고
requestTimestamp만 업데이트됨)이 똑같은 매개변수와 함께 통합업체의 서버로 전송됩니다.
결과:
이 경우 responseTimestamp를 제외한 모든 매개변수가 동일하므로 통합업체 서버는 2단계에 제공된 것과 동일한 내용으로 응답해야 합니다.
사용자는 2단계에서 한 번만 인출합니다. 4단계는 사용자에게 금전적인 영향을 주지 않습니다.
예 2: 유지보수 작업이 진행 중인 서버에 전송된 요청
시나리오:
- 통합업체 서버의 데이터베이스가 유지보수를 위해 중단되었습니다.
- Google이 통합업체에 요청을 보냅니다.
- 통합업체가
UNAVAILABLE상태 코드를 올바르게 반환합니다. - Google 서버가 응답을 수신하고 재시도를 예약합니다.
- 통합업체 서버의 서버 데이터베이스가 다시 온라인 상태가 됩니다.
- Google이 2단계에서 요청을 다시 보냅니다(요청 ID와 요청 세부정보는 동일하고
requestTimestamp만 업데이트됨). 두 요청의 요청 ID는 동일해야 합니다. - 통합업체 서버가 요청을 수신하고 전체 응답과 함께 OK 상태 코드를 반환합니다.
결과:
이 경우 통합업체 서버는 7단계에서 요청을 처리하고 HTTP 503(UNAVAILABLE)을 반환하지 않습니다. 대신 통합업체 서버는 요청을 완전히 처리하고 적절한 메시지와 함께 OK를 반환합니다. 시스템이 UNAVAILABLE 상태일 때 Google은 2단계와 비슷한 요청을 반복할 수 있습니다. 각 요청에서 3단계와 비슷한 메시지를 표시합니다.
최종적으로 6단계와 7단계가 진행됩니다.
예 3: 복구 오류로 인해 재시도한 메시지가 초기 메시지와 일치하지 않음
시나리오:
- Google이 통합업체에 요청을 보냅니다.
- 통합업체 서버가 이 요청을 받아 성공적으로 처리합니다.
- Google 서버가 2단계에서 응답을 받기 전에 전원이 끊깁니다.
- Google의 서버 전원이 복원되고 동일한 요청을 보내려고 시도하지만 일부 매개변수가 다릅니다.
결과:
이 경우 통합업체 서버는 이 시스템에 오류가 있음을 나타내는 HTTP 412(PRECONDITION FAILED) 오류 코드로 응답합니다.