pagou-com-br/skills

Kreditkarte in der Pagou API

Wende zuerst die Regeln der Skill pagou an (Umgebungen, Authentifizierung im Backend, Sicherheit und unsichere Ergebnisse). Diese Skill bringt nur die Entscheidungen für die Kreditkarte. Die Felder und Payloads befinden sich auf den folgenden Seiten: lies sie, bevor du implementierst.

Vor der Implementierung lesen

• Zahlungsmittel: Kreditkarte
• Tokenisieren einer Karte
• Erstellen einer Abbuchung
• Abfragen und Auflisten von Abbuchungen
• Idempotenz und Wiederholung
• Fluss über Referenzen: Erstellen eines Kunden (Zahlers), Erstellen einer Karte, Verwalten von Zahlern und Verwalten von Karten
• Wenn der Fluss es erfordert: Erfassen einer autorisierten Abbuchung, Stornieren einer Abbuchung, Rückerstatten einer Abbuchung, Durchführen eines Wiederholungsversuchs, Aktualisieren einer Abbuchung und Chargebacks
• Kontofreischaltung: Akzeptanz beantragen

Voraussetzungen

Aktives Konto, genehmigte Kartenakzeptanz, ein Tarifplan mit konfigurierter Kartengebühr und ein gültiger API-Schlüssel. Die Akzeptanz wird im Dashboard beantragt, nicht über die API. Wenn das Konto nicht akzeptiert ist, informiere den Nutzer, bevor du implementierst.

Erforderliche Architektur

1. Browser: Der eigene Checkout sammelt die Kartendaten und generiert den Token mit der Tokenisierungsbibliothek von Pagou in derselben Umgebung wie die API, die für die Abbuchung verwendet wird. Der öffentliche Schlüssel der Bibliothek ist nicht der X-API-KEY.
2. Browser zum Backend: Sende an den Shop-Server nur das tokenisierte card-Objekt und die Kaufdaten. Lösche Nummer und CVV aus den Feldern und dem Formularstatus nach der Tokenisierung.
3. Backend des Händlers: Erstellt die Abbuchung in der API mit dem X-API-KEY, der niemals im Browser liegt.

Vollständige Kartennummer und CVV gehören nicht zum API-Vertrag. Protokolliere Nummer, CVV oder Token nicht in Logs, Analytics oder im Browserspeicher. Der Pagou-Checkout führt die Tokenisierung bereits durch: Diese Architektur gilt für den eigenen Checkout.

Entscheidungsregeln

• Werte in ganzen Cent: value: 5000 entspricht R$ 50,00. Verwende nicht die Einheit von Pix oder Boleto.

• Wähle genau einen Fluss:

  1. Vollständige Daten: Objekte customer und card (mit dem Token).
  2. Referenzen: customer_id und card_id desselben Zahlers, beide aus dem authentifizierten Konto. Generiere in diesem Fluss keinen neuen Token.

  Mische die Flüsse nicht und sende nicht nur ein Element des Paares. Speichere im Vollständigen-Fluss die zurückgegebenen IDs für die spätere Wiederverwendung.

• Betrugsprävention: Folge den dokumentierten Anforderungen, einschließlich der echten IP des Käufers. Verwende niemals die Beispiel-IP aus den Beispielen.

• Ratenzahlung: Beachte das Limit des Kartenschemas und die Karte darf nicht abgelaufen sein.

• Finanzergebnis über den status: 201 garantiert keine Genehmigung. Unterscheide zwischen authorized (Autorisierung), captured (Erfassung) und settled (Abrechnung gebucht). Der Status unknown der Abbuchung ist nicht dasselbe wie ein Kommunikationsfehler mit unsicherem Ergebnis.

• Capturing ist kein fester Schritt: Die Erstellung kann bereits captured zurückgeben. Rufe die explizite Erfassung nur für eine Abbuchung auf, die authorized bleibt, und wenn dies die kommerzielle Absicht ist. Verwende Capturing niemals, um Timeouts zu beheben.

• Stornierung oder Rückerstattung: Stornierung gilt für eine ausstehende Abbuchung; eine autorisierte, erfasste oder abgerechnete Abbuchung folgt den Rückerstattungsregeln, die im aktuellen Vertrag vollständig sind. Prüfe den Status, bevor du dich entscheidest.

• Wiederholungsversuch (/retry): Es handelt sich um einen weiteren finanziellen Vorgang, nur nach bestätigtem Fehler (failed), mit eigenem Schlüssel und innerhalb des dokumentierten Limits. Verwende /retry niemals, um Timeouts oder unsichere Ergebnisse zu beheben.

• Chargebacks: Verwende die id des Chargebacks bei den Vorgängen der Streitigkeit; der Status der Streitigkeit ist anders als der Status charged_back der Abbuchung. Abwehr und Annahme sind Entscheidungen des Händlers: implementiere sie nur, wenn du dazu aufgefordert wirst.

• Split: Folge der Skill pagou-split; bei der Kreditkarte verwendet die Abbuchung Cent, aber der feste Split-Betrag verwendet Reais.

Idempotenz

• Generiere einen eindeutigen Idempotency-Key pro geschäftlichem Vorgang (Zahler anlegen, Karte anlegen, Abbuchung erstellen, erfassen, rückerstatten, wiederholen) und speichere ihn zusammen mit der Anfrage vor dem ersten Senden.
• Um denselben Vorgang zu wiederholen, behalte denselben Schlüssel, dieselbe Methode, denselben Pfad und dieselben Bytes des Körpers bei, einschließlich card_token und des Split-Arrays. Baue das JSON nicht neu auf.
• Ein neuer Kauf erfordert einen neuen Schlüssel; customer_id und card_id können wiederverwendet werden.
• Generiere keinen neuen Schlüssel innerhalb einer Schleife und auch nicht, um Timeouts zu umgehen.
• Die Codes idempotency_key_conflict, idempotency_in_progress und idempotency_outcome_unknown haben unterschiedliche Behandlungen: Lies die Idempotenz-Seite. Ein unsicheres Ergebnis erfordert eine Untersuchung durch Abfrage, keine neue Abbuchung.

MCP-Tools

Der Pagou-MCP liest nur Kartenabbuchungen:

Tool	Verwendung
get_card_charge	Eine Abbuchung anhand der ID abfragen
list_card_charges	Abbuchungen nach Status und Zeitraum auflisten und abgleichen

Der MCP erstellt keine Abbuchungen, erfasst, storniert, erstattet sie nicht zurück und versucht keine erneuten Abbuchungen von Kreditkarten. Er verwaltet keine Zahler oder Karten und greift nicht bei Chargebacks ein. Die Erstellung erfolgt im Backend des Händlers, nach der Tokenisierung im Browser. Versuche nicht, eine Kreditkartenabbuchung auf anderem Wege vom Agenten aus zu erstellen.

Test in der Sandbox

1. Bestätige, dass das Sandbox-Konto die Voraussetzungen für Kreditkarten erfüllt.
2. Tokenisiere die Testkarte 4111 1111 1111 1111 in der Sandbox-Umgebung gemäß der Tokenisierungsseite.
3. Erstelle die Abbuchung über das Backend der Anwendung gegen https://api.pagou.cloud mit dem Sandbox-Schlüssel und einem eigenen Idempotency-Key. Die Simulationsrouten von Pix gelten nicht für Karten.
4. Überprüfe den zurückgegebenen status und rufe dieselbe Abbuchung ab (auch mit get_card_charge).
5. Teste die Wiederholung derselben Anfrage mit demselben Schlüssel und bestätige, dass keine doppelte Abbuchung entsteht.