pagou-com-br/skills

Pagou API의 신용카드 결제

pagou 스킬(환경, 백엔드 인증, 보안 및 불확실한 결과)의 규칙을 먼저 적용하세요. 이 스킬은 카드 결제 관련 결정 사항만 다룹니다. 필드와 페이로드는 아래 페이지에 있습니다. 구현 전에 반드시 읽어보세요.

구현 전에 읽어야 할 문서

• 결제 수단: 신용카드
• 카드 토큰화
• 결제 생성
• 결제 조회 및 목록
• 멱등성 및 재시도
• 참조(referências) 흐름: 고객(결제자) 생성, 카드 생성, 결제자 관리, 카드 관리
• 필요 시: 승인된 결제 캡처, 결제 취소, 결제 환불, 재시도, 결제 업데이트, 차지백
• 계정 활성화: 신용카드 가맹점 신청

전제 조건

활성 계정, 승인된 카드 가맹점 계약, 카드 수수료가 설정된 요금제, 유효한 API 키가 필요합니다. 가맹점 신청은 API가 아닌 대시보드에서 이루어집니다. 계정이 아직 승인되지 않은 경우 구현 전에 사용자에게 알리세요.

필수 아키텍처

1. 브라우저: 자체 체크아웃에서 카드 정보를 수집하고 Pagou 토큰화 라이브러리를 사용하여 토큰을 생성합니다. 이때 API 호출에 사용되는 환경과 동일한 환경이어야 합니다. 라이브러리의 공개 키는 X-API-KEY가 아닙니다.
2. 브라우저 → 백엔드: 토큰화된 card 객체와 구매 데이터만 스토어 서버로 전송합니다. 토큰화 후에는 숫자와 CVV를 폼 필드와 상태에서 모두 제거합니다.
3. 판매자 백엔드: X-API-KEY를 사용하여 API에서 결제를 생성합니다. API 키는 절대 브라우저에 있지 않습니다.

전체 카드 번호와 CVV는 API 계약의 일부가 아닙니다. 로그, 분석 도구 또는 브라우저 저장소에 숫자, CVV 또는 토큰을 기록하지 마세요. Pagou 체크아웃은 이미 토큰화를 수행합니다. 이 아키텍처는 자체 체크아웃에 적용됩니다.

결정 규칙

• 값은 정수 센트: value: 5000은 R$ 50.00을 나타냅니다. Pix 또는 Boleto의 단위를 재사용하지 마세요.

• 정확히 하나의 흐름 선택:

  1. 전체 데이터: customer 및 card 객체(토큰 포함).
  2. 참조: 동일한 결제자의 customer_id 및 card_id(인증된 계정 소유). 이 흐름에서는 새 토큰을 생성하지 마세요.

  두 흐름을 혼합하거나 쌍 중 하나만 보내지 마세요. 전체 흐름에서는 반환된 ID를 저장하여 나중에 재사용하세요.

• 사기 방지: 문서화된 요구 사항을 따르고 구매자의 실제 IP를 포함하세요. 예제의 예시 IP를 사용하지 마세요.

• 할부: 카드 브랜드의 한도를 준수하고 카드가 만료되지 않았는지 확인하세요.

• status를 통한 금융 결과: 201이 승인을 보장하지 않습니다. authorized(승인), captured(캡처), settled(결제 완료)를 구분하세요. unknown 상태는 통신 오류로 인한 불확실한 결과와 동일하지 않습니다.

• 캡처는 고정 단계가 아님: 결제 생성 시 이미 captured 상태로 반환될 수 있습니다. 명시적 캡처는 결제가 authorized 상태로 남아 있고 상업적 의도가 있을 때만 호출하세요. 타임아웃 해결을 위해 캡처를 사용하지 마세요.

• 취소 또는 환불: 취소는 보류 중인 결제에 적용됩니다. 승인, 캡처 또는 결제된 결제는 환불 규칙을 따르며, 현재 계약에서는 전액 환불만 가능합니다. 결정하기 전에 상태를 확인하세요.

• 재시도 (/retry): 이는 별도의 금융 작업이며, 확인된 실패(failed) 후에만, 고유한 키를 사용하고 문서화된 한도 내에서 수행하세요. 타임아웃 또는 불확실한 결과를 해결하기 위해 /retry를 사용하지 마세요.

• 차지백: 분쟁 작업에는 차지백의 id를 사용하십시오. 분쟁 상태는 결제의 charged_back 상태와 다릅니다. 방어 및 수락은 판매자의 결정입니다. 요청 시에만 구현하세요.

• Split: pagou-split 스킬을 따르세요. 카드 결제는 센트를 사용하지만 Split의 고정 금액은 레알을 사용합니다.

멱등성

• 각 상업 작업(고객 등록, 카드 등록, 결제 생성, 캡처, 환불, 재시도)에 대해 고유한 Idempotency-Key를 생성하고 첫 번째 요청 전에 요청과 함께 저장하세요.
• 동일한 작업을 반복하려면 동일한 키, 메서드, 경로 및 본문의 바이트(card_token 및 Split 배열 포함)를 유지하세요. JSON을 다시 구성하지 마세요.
• 새 구매에는 새 키가 필요합니다. customer_id 및 card_id는 재사용할 수 있습니다.
• 반복 루프 내에서 새 키를 생성하거나 타임아웃을 우회하기 위해 새 키를 생성하지 마세요.
• idempotency_key_conflict, idempotency_in_progress, idempotency_outcome_unknown 코드는 각각 다른 처리가 필요합니다. 멱등성 페이지를 읽어보세요. 불확실한 결과는 새 결제 대신 조회를 통해 조사해야 합니다.

MCP 도구

Pagou MCP는 카드 결제를 조회만 합니다:

도구	용도
get_card_charge	ID로 결제 조회
list_card_charges	상태 및 기간별로 목록 및 조정

MCP는 카드 결제를 생성, 캡처, 취소, 환불, 재시도하지 않으며, 결제자나 카드를 관리하지 않고, 차지백에 관여하지 않습니다. 결제 생성은 브라우저에서 토큰화 후 판매자 백엔드에서 이루어집니다. 에이전트에서 다른 경로로 카드 결제를 생성하려고 시도하지 마세요.

Sandbox 테스트

1. Sandbox 계정이 카드 전제 조건을 충족하는지 확인하세요.
2. Sandbox 환경에서 토큰화 페이지에 따라 테스트 카드 4111 1111 1111 1111를 토큰화하세요.
3. 애플리케이션 백엔드에서 https://api.pagou.cloud에 대해 Sandbox 키와 고유한 Idempotency-Key를 사용하여 결제를 생성하세요. Pix 시뮬레이션 경로는 카드에 적용되지 않습니다.
4. 반환된 status를 확인하고 동일한 결제를 조회하세요(get_card_charge 사용 가능).
5. 동일한 키로 동일한 요청을 반복하고 중복 결제가 생성되지 않는지 확인하세요.