Token für die sichere Übermittlung von Kontodaten verwenden

Bevor wir Zahlungen und Auszahlungen für verbundene Konten aktivieren können, müssen Sie die Know Your Customer (KYC)-Anforderungen erfüllen. Stellen Sie zu diesem Zweck Stripe Informationen zur Identitätsprüfung über Ihre Konten zur Verfügung, die dann von uns verifiziert werden. Konto-Token und Personen-Token stellen eine sichere und zuverlässige Möglichkeit dar, diese Aufgabe durchzuführen. Die Token stellen sicher, dass personenbezogene Daten (PII) nicht mit Ihren Servern in Kontakt kommen, sodass Ihre Integration sicher ist. Über die Token kann Stripe außerdem potenziellen Betrug besser erkennen.

Token können nur für Folgendes verwendet werden:

• Angaben zur juristischen Person (Informationen über das Unternehmen oder die Einzelperson)
• Angaben zur Person
• Zustimmung zur Vereinbarung für verbundene Konten von Stripe angeben

Token können nicht für andere Kontoinformationen verwendet werden, darunter:

• Konfigurationseinstellungen für das Konto (zum Beispiel Auszahlungspläne)
• Nicht vertrauliche Informationen zum Konto (zum Beispiel Support-URL, Telefonnummer des Supports)
• Das Land des verbundenen Kontos

Token werden mit Stripe.js, der API oder einer der mobilen Client-Bibliotheken erstellt. Der Ablauf ist im Wesentlichen identisch mit der Tokenisierung von Zahlungsdetails oder externen Konten. Die Informationen Ihrer verbundenen Konten werden direkt an Stripe gesendet und gegen ein Token ausgetauscht, das in API-Aufrufen vom Typ create und update verwendet werden kann.

Token erstellen und verwenden

Token benötigen sowohl clientseitigen als auch serverseitigen Code:

1. Erstellen Sie das HTML-Formular, das die Eingabe der Nutzer/innen aufnimmt.
2. Fügen Sie JavaScript hinzu, das die Formulardaten an Stripe sendet, im Gegenzug ein Token enthält und dieses Token an Ihren Server sendet.
3. Verwenden Sie das Token in einem serverseitigen Stripe-API-Aufruf.

Das folgende Beispiel zeigt, wie Konto-Token und Personen-Token verwendet werden können. Beide Typen sind erforderlich, wenn Sie Angaben zu juristischen Personen und Personen für Unternehmen bereitstellen. Beim Onboarding von Einzelpersonen benötigen Sie keine Personen-Token. Erstellen Sie stattdessen Konto-Token und übergeben Sie den Einzelpersonen-Hash im Account-Objekt, um die erforderlichen Informationen anzugeben.

Schritt 1: HTML-Formular erstellen

Im ersten Schritt wird ein HTML-Formular erstellt, das die erforderlichen Informationen für das Konto und die Person erfasst. Dies beinhaltet auch die Zustimmung zur Stripe-Vereinbarung für verbundene Konten.

Konto- und Personendaten erfassen

Erstellen Sie Formularelemente, um die erforderlichen Informationen zu erfassen, z. B. Name, Adresse und alle anderen Angaben, die im Land der Nutzer/innen erforderlich sind.

<form class="my-form" action="/create-person" method="post">
  <input type="hidden" name="token-account" id="token-account">
  <input type="hidden" name="token-person" id="token-person">
  <label>
    <span>Business Name</span>
    <input class="inp-company-name">
  </label>
  <fieldset>
    <legend>Business Address</legend>
    <label>
      <span>Street Address Line 1</span>

Stripe-Vereinbarung für verbundene Konten vorlegen

Als Plattform müssen Sie Ihre Nutzerinnen und Nutzer darauf hinweisen, dass die Verarbeitung von Zahlungen der Stripe-Vereinbarung für verbundene Konten unterliegt. Die Zustimmung zur Stripe-Vereinbarung für verbundene Konten ist erforderlich, wenn ein Konto-Token zur Erstellung eines neuen verbundenen Kontos verwendet wird.

Wir empfehlen Ihnen, Sprachen wie die folgenden aufzunehmen, einschließlich Links zu unserer Vereinbarung und zu Ihren allgemeinen Geschäftsbedingungen.

<p>By clicking, you agree to <a href="#">our terms</a> and the <a href="https://stripe.com/connect-account/legal">Stripe Connected Account Agreement</a>.</p>

Schritt 2: JavaScript hinzufügen

Als Nächstes benötigt die Seite JavaScript, das Folgendes ausführt:

1. Die Formularübermittlung wird unterbrochen.
2. Ruft die Methode stripe.createToken() auf, um Konto- und Personen-Token anzufordern.
3. Sendet die IDs der erhaltenen Token an Ihren Server.

Zur Vereinfachung werden die Datenvalidierung und die Fehlerbehebung im nachstehenden Code weggelassen. Denken Sie jedoch daran, beides in Ihre eigentliche Integration aufzunehmen.

Übergeben Sie zwei Argumente an die Methode stripe.createToken():

• Den Wert für account oder person, um die Art des zu erstellenden Tokens anzugeben
• Ein generisches Objekt mit Informationen

Das als zweites Argument angegebene JavaScript-Objekt muss der Struktur des Account- oder Person-Objekts entsprechen, das Sie tokenisieren. Konto-Token benötigen die Top-Level-Eigenschaft Unternehmen oder Einzelperson und Personen-Token benötigen die Top-Level-Eigenschaft Person. Folgen Sie der Struktur des Objekts durch alle erforderlichen Attribute. Beispielsweise wird line1 in address im nachstehenden Codeblock als person.address.line1 bereitgestellt.

Um die Zustimmung der Nutzer/innen zur Stripe-Vereinbarung für verbundene Konten darzustellen, geben Sie die Top-Level-Eigenschaft tos_shown_and_accepted mit dem Wert „true“ an (hierfür werden nur Konto-Token verwendet).

Sie müssen weiterhin Token mithilfe von serverseitigem Code verwenden, um eine Person zu erstellen oder zu aktualisieren. Sie können die Token-ID so an Ihren Server senden, wie es für Ihre Anwendung sinnvoll ist (zum Beispiel über eine XHR-Anfrage). Zur Vereinfachung wird in diesem Codebeispiel die Token-ID in einer verborgenen Formulareingabe gespeichert und das Formular anschließend abgesendet.

// Assumes you've already included Stripe.js!
const stripe = Stripe(
'pk_test_TYooMQauvdEDq54NiTphI7jx');
const myForm = document.querySelector('.my-form');
myForm.addEventListener('submit', handleForm);

async function handleForm(event) {
  event.preventDefault();

  const accountResult = await stripe.createToken('account', {
    business_type: 'company',
    company: {
      name: document.querySelector('.inp-company-name').value,
      address: {
        line1: document.querySelector('.inp-company-street-address1').value,
        city: document.querySelector('.inp-company-city').value,
        state: document.querySelector('.inp-company-state').value,
        postal_code: document.querySelector('.inp-company-zip').value,
      },
    },
    tos_shown_and_accepted: true,
  });

  const personResult = await stripe.createToken('person', {
    person: {
      first_name: document.querySelector('.inp-person-first-name').value,
      last_name: document.querySelector('.inp-person-last-name').value,
      address: {
        line1: document.querySelector('.inp-person-street-address1').value,
        city: document.querySelector('.inp-person-city').value,
        state: document.querySelector('.inp-person-state').value,
        postal_code: document.querySelector('.inp-person-zip').value,
      },
    },
  });

  if (accountResult.token && personResult.token) {
    document.querySelector('#token-account').value = accountResult.token.id;
    document.querySelector('#token-person').value = personResult.token.id;
    myForm.submit();
  }
}

Nach erfolgreichem Erhalt der Token von Stripe speichert JavaScript die Token-IDs in einer verborgenen Formulareingabe und sendet das Formular dann (an Ihren Server). Bei den letzten Schritten verwendet Ihr serverseitiger Code die Token, um ein Konto und eine Person zu erstellen.

Schritt 3: Konto erstellen

Verwenden Sie die Konto-Token-ID, um das Konto zu erstellen. Das Land und der Unternehmenstyp werden außerhalb des Tokens angegeben.

curl https://api.stripe.com/v1/accounts \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d "controller[stripe_dashboard][type]"=none \
  -d "controller[fees][payer]"=application \
  -d "controller[losses][payments]"=application \
  -d "controller[requirement_collection]"=application \
  -d country=US \
  -d "capabilities[card_payments][requested]"=true \
  -d "capabilities[transfers][requested]"=true \
  -d account_token=
{{ACCOUNT_TOKEN_ID}}

Wenn Sie beim Erstellen eines Konto-Tokens tos_shown_and_accepted auf „true“ setzen, werden die Attribute date, ip und user_agent des Attributs tos_acceptance des Account-Objekts mit Daten gefüllt. Wenn Sie ein Konto erstellen, ohne ein Konto-Token zu verwenden, müssen Sie Werte für diese Objekte bereitstellen.

Notieren Sie unbedingt die zurückgegebene Konto-ID, damit Sie diese zum Erstellen von Personenobjekten für das Konto verwenden können.

Schritt 4: Person erstellen

Erstellen Sie eine Person, indem Sie die ID des Personen-Tokens als Wert für den Parameter person_token angeben (Sie benötigen auch die Konto-ID, für die die Person bestimmt ist). Sie können den Anforderungs-Hash für das Account-Objekt verwenden, um zu ermitteln, welche Informationen von welchen Personen erfasst werden müssen.

curl https://api.stripe.com/v1/accounts/
{{CONNECTED_ACCOUNT_ID}}
/persons \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d first_name=Jane \
  -d last_name=Diaz \
  -d person_token=
{{PERSON_ID}}

Konto-Token mit den mobilen SDKs erstellen

Sie können auch ein Konto-Token mit unseren SDKs für Android oder iOS erstellen. Beachten Sie, dass zurzeit nur Konto-Token auf Mobilgeräten unterstützt werden. Dies ist zur Erstellung eines individuellen Kontos ausreichend. Sie müssen jedoch Stripe.js verwenden, um das Personen-Token zu erstellen, dass Sie für ein Unternehmenskonto benötigen. Unterstützung für Personen-Token in den mobilen SDKs wird in einer zukünftigen Version verfügbar sein.

import UIKit
import StripePayments

let companyParams = STPConnectAccountCompanyParams()
companyParams.name = company.name
companyParams.address = STPConnectAccountAddress()
companyParams.address.line1 = company.address_line_1
companyParams.address.city = company.address_city
companyParams.address.state = company.address_state
companyParams.address.country = company.address_country
companyParams.address.postalCode = company.address_postal_code

guard let accountParams = STPConnectAccountParams(tosShownAndAccepted: true, company: companyParams) else {
  // The TOS was not accepted
  return
}

STPAPIClient.shared.createToken(withConnectAccount: accountParams) { (accountToken, error) in
    if let error = error {
        // display an error to your user
    }
    else {
        // use account token to create a Connect account server-side
    }
}

Datei-Upload abwickeln

Wenn ein verbundenes Konto Stripe Stripe einen Scan eines Ausweisdokuments, zum Beispiel eines Reisepasses, zur Verfügung stellen muss, können Sie ein Konto-Token verwenden. Das JavaScript ist jedoch komplizierter, da die Datei als Teil einer XHR-Anfrage an Stripe gesendet werden muss. Bei diesem Ablauf führt JavaScript Folgendes durch:

1. Die Formularübermittlung wird unterbrochen.
2. Wenn eine Datei hochgeladen wurde, wird diese an Stripe gesendet, woraufhin im Gegenzug ein Datei-Token ausgegeben wird.
3. Die Datei-Token-ID dem generischen Objekt für die Token-Anforderung des Kontos hinzugefügt.
4. Die Methode stripe.createToken() wird aufgerufen, um ein Token anzufordern.
5. Die ID des ausgegebenen Konto-Tokens wird zur Verwendung an Ihren Server gesendet.

Fügen Sie zunächst ein Dateielement in das Formular ein. Bei der hochgeladenen Datei muss es sich um ein Farbbild (kleiner als 8.000 x 8.000 Pixel) im JPG-, PNG- oder PDF-Format handeln, das nicht größer als 10 MB ist.

<input type="file" id="id-file" name="id-file" accept=".jpeg,.jpg,.png">

Als Nächstes senden Sie in Ihrem JavaScript, das die Übermittlung des Formulars abwickelt, die hochgeladene Datei an Stripe. Dies muss vor der Erstellung des Konto-Tokens geschehen.

const data = new FormData();
data.append('file', document.querySelector('#id-file').files[0]);
data.append('purpose', 'identity_document');
const fileResult = await fetch('https://uploads.stripe.com/v1/files', {
  method: 'POST',
  headers: {'Authorization': 'Bearer 
pk_test_TYooMQauvdEDq54NiTphI7jx
'},
  body: data,
});
const fileData = await fileResult.json();

Schließlich fügen Sie die zurückgegebene Datei-ID als Wert verification.document.front in das generische Objekt ein, das an den Aufruf createToken() übergeben wird:

const result = await stripe.createToken('account', {
  person: {
    first_name: document.querySelector('.inp-first-name').value,
    last_name: document.querySelector('.inp-last-name').value,
    address: {
      line1: document.querySelector('.inp-street-address1').value,
      city: document.querySelector('.inp-city').value,
      state: document.querySelector('.inp-state').value,
      postal_code: document.querySelector('.inp-zip').value,
    },
    verification: {
        document: {
            front: fileData.id,
            },
        },
    },
  tos_shown_and_accepted: true,
});

Angaben zur juristischen Person und zur Person aktualisieren

Sie können Token verwenden, um die Informationen zur juristischen Person und zur Person eines bestehenden Kontos auf sichere Weise zu aktualisieren. Erstellen Sie einfach die benötigten Token mit der gleichen Kombination aus HTML und JavaScript wie oben und führen Sie dann einen Aufruf zur Aktualisierung des Kontos oder zur Aktualisierung der Person unter Angabe der neuen Token-ID durch.

Sie müssen einen neuen Token erstellen und bereitstellen, wenn Sie Angaben zur juristischen Person aktualisieren, die zuvor mit einem Konto-Token festgelegt wurden.

curl https://api.stripe.com/v1/accounts/
{{CONNECTED_ACCOUNT_ID}} \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d account_token=
{{ACCOUNT_TOKEN_ID}}

Bei Verwendung von Token für Aktualisierungen:

• Ein vorhandener Wert wird durch einen neuen Wert ersetzt.
• Wird kein neuer Wert angegeben, bleibt der bestehende Wert erhalten.
• Sie können einen vorhandenen Wert nicht deaktivieren.
• Der Parameter tos_shown_and_accepted wird ignoriert und kann weggelassen werden.
• Sie können ein Konto- oder Personen-Token für eine Aktualisierung verwenden, unabhängig davon, ob bei der Erstellung des Kontos oder der Person ursprünglich ein Token verwendet wurde oder nicht.
• Wenn das Konto oder die Person ursprünglich mit einem Konto-Token erstellt wurde, können Sie die Werte nur mit einem anderen Token aktualisieren.

Wenn ein Konto beispielsweise mit einem Token erstellt wird, das nur den Namen und das Geburtsdatum enthält, erstellen Sie ein weiteres Token, das nur die Adressdaten enthält, und führen dann einen Aufruf zur Kontoaktualisierung durch, um dem Konto die Adressdaten hinzuzufügen.

Angaben zur juristischen Person und zur Person entfernen

Um Angaben zu juristischen Personen oder Personen zu löschen oder einen Wert explizit als Null festzulegen, übergeben Sie eine leere Zeichenfolge in einem Aufruf zur Aktualisierung eines Kontos oder Aktualisierung einer Person. Verwenden Sie einen Aktualisierungsaufruf und kein Token, auch wenn Sie ursprünglich ein Token verwendet haben. Sie können leere Zeichenfolgen nur optionalen Attributen zuweisen (zum Beispiel der zweiten Zeile einer Adresse). Sie können sie keinen erforderlichen Attributen zuweisen.