Verwendung von Finanzkonten für Plattformen, um Geld zu bewegen

Homebox ist ein fiktives vertikales SaaS-Unternehmen, das Software für Unternehmen im Bereich Haushaltsdienstleistungen wie HLK, Reinigungsdienste und Klempner entwickelt. Diese Beispielintegration beschreibt einige grundlegende Geldbewegungen unter Verwendung der Treasury-Endpoints der Stripe API. Informationen dazu, wie das Unternehmen ein Finanzkonto einrichten und Zahlungskarten ausstellen kann, finden Sie unter Verwendung von Finanzkonten für Plattformen zur Einrichtung von Finanzkonten und Karten.

Externe Bankkonten verwenden

Finanzkonten für Plattformen bietet Plattformen eine Suite von API-Endpoints für die Kontoerstellung und Geldbewegung, um die Aufbewahrung, Verwaltung und Bewegung verbundener Kontogelder zu unterstützen. Plattformen können ein Finanzkonto finanzieren und Geld zwischen Finanzkonten und externen Bankkonten bewegen.

Die Stripe API bietet InboundTransfer und OutboundTransfer, um Geldbewegungen zwischen den externen Bankkonten der verbundenen Konten und ihren Finanzkonten zu erleichtern. Die Stripe API bietet außerdem OutboundPayment, um Geldbewegungen von den Finanzkonten der verbundenen Konten auf externe Bankkonten von Drittanbietern zu ermöglichen. Alle diese Objekte können PaymentMethods verwenden, um externe Bankdaten wie Routingnummern und Kontonummern zu speichern.

Erläuterungen zu PaymentMethods

Innerhalb der Stripe-API können Sie Angaben zur Zahlungsmethode mit einem PaymentMethod-Objekt speichern. So könnte Homebox zum Beispiel die Konten seiner Anbieter als PaymentMethods speichern, um Geld zu senden, ohne die Daten erneut eingeben und erfassen zu müssen.

PaymentMethods mit externen Bankkontodaten können mit Kundinnen und Kunden (für Geldsendungen an Dritte) oder mit einem Stripe-Konto (für Abbuchungen bzw. Überweisungen an das externe Bankkonto von Stripe-Kontoinhaber/innen) verknüpft werden. Der „Kunde“ ist dabei das Kunde-Objekt in der Stripe API und gibt die externe Partei an. In Finanzkonten für Plattformen handelt es sich bei Kunden meist um Verkäufer, die Zahlungen von Stripe-Kontoinhaber/innen erhalten und selbst keine Zahlungen an die Strip-Kontoinhaber tätigen. Zur Einrichtung kunden- und kontospezifischer PaymentMethod-Objekte verwenden Sie das SetupIntent-Objekt.

Die relevanten API-Objekte, die Sie mit einer PaymentMethod verwenden können, hängen davon ab, wie sie zugeordnet sind:

• Kundenbezogen: Verwenden Sie OutboundPayments.
• Kontobezogen: Verwenden Sie InboundTransfers und OutboundTransfers.

PaymentMethod-Ablauf

Überblick über InboundTransfers und OutboundTransfers

Per InboundTransfer können Sie Geld vom externen Bankkonto eines Stripe-Kontos einziehen und dann per OutboundTransfer an ein anderes externes Bankkonto übertragen.

Damit Geld per InboundTransfer auf ein Finanzkonto eingezogen werden kann, müssen die externen Bankkonten von dem/der Inhaber/in des Stripe-Kontos verifiziert werden. Bei Bankkonten, die für Überweisungen von Finanzkonten per OutboundTransfer genutzt werden, ist dagegen keine derartige Verifizierung erforderlich.

Wenn ein externes Bankkonto entweder für InboundTransfers oder OutboundTransfers verwendet wird, müssen Sie die entsprechende PaymentMethod dem Stripe-Konto (und nicht einer Kundin/einem Kunden) zuordnen. Sie tun dies, indem Sie den Parameter attach_to_self=true anstelle des Parameters Kundin/Kunde verwenden, wenn Sie die PaymentMethod mit SetupIntent erstellen.

Überblick über die InboundTransfers- und OutboundTransfers-Abläufe.

OutboundPayments

Plattformen verwenden die OutboundPayment-API, um Gelder von einem Finanzkonto an ein externes von einem Drittanbieter geführtes Bankkonto zu senden.

Sie müssen PaymentMethods einer Kundin/einem Kunden zuordnen, um sie mit OutboundPayments zu verwenden. Bankkonten, die für OutboundPayments verwendet werden, müssen Sie nicht verifizieren.

OutboundPayments-Ablauf

Ein externes Konto hinzufügen

Homebox möchte die eigenen externen Bankkonten seiner Kundinnen und Kunden mit deren Finanzkonten verknüpfen. Die verbundenen Konten von Homebox wollen ihr gesamtes Geschäftskapital in ihren Finanzkonten belassen und mithilfe von eingehenden Transfers Geld von Ihrem externen Konto auf Ihr Finanzkonto übertragen. Um Gelder einzuzahlen und abzuheben, erstellt Homebox einen SetupIntent mit den erforderlichen Parametern und ordnet diesen einer mit dem Konto verknüpften PaymentMethod zu:

curl https://api.stripe.com/v1/setup_intents \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d attach_to_self=true \
  -d "flow_directions[]"=inbound \
  -d "flow_directions[]"=outbound \
  -d "payment_method_types[]"=us_bank_account \
  -d "payment_method_data[type]"=us_bank_account \
  -d "payment_method_data[us_bank_account][routing_number]"=110000000 \
  -d "payment_method_data[us_bank_account][account_number]"=000123456789 \
  -d "payment_method_data[us_bank_account][account_holder_type]"=company \
  -d "payment_method_data[billing_details][name]"="Company Corp" \
  -d confirm=true \
  -d "mandate_data[customer_acceptance][type]"=online \
  -d "mandate_data[customer_acceptance][online][ip_address]"="123.123.123.123" \
  --data-urlencode "mandate_data[customer_acceptance][online][user_agent]"="curl/1.2.3"

Um Geld über OutboundTransfers oder InboundTransfers zu senden und zu empfangen, muss Homebox ein externes Bankkonto mit dem Parameter payment_method_data[us_bank_account] angeben. Bevor der Link zum externen Live-Bankkonto erstellt wird, testet Homebox den Ablauf mit den von Stripe bereitgestellten Testkontonummern.

Wie im vorherigen Beispiel gezeigt, hat Homebox das externe Bankkonto festgelegt (payment_method_data[us_bank_account]) und attach_to_self auf true gesetzt. So können die Bankkontodaten dem/der Stripe-Kontoinhaber/in (anstelle eines Dritten) zugeordnet werden. Wenn die Plattform die Anfrage übermittelt, antwortet die API mit einem SetupIntent:

{
  "id": "{{SETUP_INTENT_ID}}",
  "object": "setup_intent",
  "application": "{{APPLICATION_ID}}",
  "attach_to_self": true,
  "cancellation_reason": null,
  "client_secret": "{{SETUP_INTENT_SECRET}}",
  "created": 1642520861,
  "customer": null,
  "description": null,
  "flow_directions": [
    "inbound",
    "outbound"
  ],
  "last_setup_error": null,
  "latest_attempt": "{{ATTEMPT_ID}}",
  "livemode": false,
  "mandate": "{{MANDATE_ID}}",
  "metadata": {
  },
  "next_action": {
    "type": "verify_with_microdeposits",
    "verify_with_microdeposits": {
      "arrival_date": 1642579200,
      "hosted_verification_url": "https://payments.stripe.com/microdeposit/sacs_test_xxx",
      "microdeposit_type": "amounts"
    }
  },
  "on_behalf_of": null,
  "payment_method": "{{PAYMENT_METHOD_ID}}",
  "payment_method_options": {
    "us_bank_account": {
      "verification_method": "automatic"
    }
  },
  "payment_method_types": [
    "us_bank_account"
  ],
  "single_use_mandate": null,
  "status": "requires_confirmation",
  "usage": "off_session"
}

Ein externes Konto verifizieren

Homebox hat im vorherigen Abschnitt ein externes Bankkonto verknüpft. Das Bankkonto muss verifiziert werden, bevor Homebox es für InboundTransfers verwenden kann. Die Verifizierung des Bankkontos ermöglicht es der/dem Kontoinhaber/in, die Inhaberschaft des externen Bankkontos zu bestätigen. Zur Verifizierung kann Homebox Stripe Financial Connections für eine sofortige Verifizierung oder Mikroeinzahlungen (die mehr Zeit in Anspruch nehmen) verwenden.

Stripe Financial Connections

Sie können Financial Connections verwenden, um ein eigenes Bankkonto sofort zu verifizieren. Financial Connections ist ein von Stripe gehosteter Ablauf, der sowohl auf der Client- als auch auf der Serverseite der Anwendung integriert ist.

Drei Schritte, die erforderlich sind, damit Homebox Bankkontodaten über Financial Connections erfassen und überprüfen kann:

1. Erstellen Sie einen SetupIntent mit der Eigenschaft attach_to_self (ersetzen Sie dabei die Eigenschaft customer_id) und dem Wert instant für die Eigenschaft verification_method.

2. Geben Sie das client_secret an, damit die Frontend-Anwendung Bankkontodaten mit stripe.collectBankAccountForSetup erfassen, eine PaymentMethod erstellen und diese PaymentMethod an den SetupIntent anhängen kann.

   Notiz

   Der Name der Kontoinhaber/innen im Parameter billing_details ist erforderlich, um eine PaymentMethod für ein US-Bankkonto zu erstellen.

3. Zeigen Sie die Mandatsbedingungen an, um die Autorisierung für die PaymentMethod-Verwendung einzuholen.

Für Schritt 1 entwickelt Homebox den folgenden Code, um serverseitig einen SetupIntent zu erstellen und die Informationen an eine handlebars.js-Vorlage zu übergeben. Bei diesem Code wird vorausgesetzt, dass Nutzer/innen durch die Anwendung bei Stripe angemeldet sind und die Anwendung die Stripe-Konto-ID mit dem Session-Objekt (req.session.accountId) übergibt.

const stripe = require("stripe")(process.env.STRIPE_SECRET_KEY);
router.get('/add_bank_account', async (req, res) => {
  const account = await stripe.accounts.retrieve(req.session.accountId);
  const setupIntent = await stripe.setupIntents.create({
    attach_to_self: true,
    flow_directions: ['inbound', 'outbound'],
    payment_method_types: ['us_bank_account'],
    payment_method_options: {us_bank_account: {verification_method: "automatic"}}
  },{
    stripeAccount: account.id,
  });
  let client_secret= setupIntent.client_secret;
  res.render('add_bank_account', { account: account, client_secret: client_secret, stripe_pk: process.env.STRIPE_PUBLISHABLE_KEY });
});

Schritt 2 beginnt, wenn Homebox die folgenden Daten an die Render-Funktion übergibt:

• Die Stripe-Konto-ID
• Das vom SetupIntent abgerufene Client-Geheimnis, das als Kennung verwendet wird
• Den veröffentlichbaren API-Schlüssel der Plattform

Bei diesem Beispiel wird die clientseitige Seite mit einer Schaltfläche gerendert, über die Nutzer/innen ihr Bankkonto mit Financial Connections validieren können.

Modal zum Hinzufügen eines Bankkontos

Homebox erstellt den folgenden Code für die Logik hinter der vorangehenden Schaltfläche.

const getBankAccount = async e => {
  paymentMethodButton.setAttribute("disabled", "disabled");
  // Calling this method triggers the Financial Connections modal to display.
  const response = await stripe.collectBankAccountForSetup("{{ client_secret }}", {
    billing_details: {
      name: "John Doe",
      email: "test@test.com",
    },
  });
  if (response.error)
  {
    console.error(response.error);
  }
  if (response.status == "requires_confirmation")
  {
    //Show confirmation modal
    AcceptBankAccountModal.classList.remove("hidden");
  }
};

In diesem Codebeispiel ruft das Script die Methode collectUsBankAccountForSetup auf und übergibt das client_secret aus dem SetupIntent. Nutzer/innen werden in einem Anwendungsdialogfeld durch die Verknüpfung ihres Bankkontos geführt.

Workflow zum Hinzufügen eines Bankkontos

Schritt 3 beginnt mit dem erfolgreichen Abschluss des vorherigen Workflows, wenn der SetupIntent-Status zu requires_confirmation übergeht und ein Modalfenster eine Autorisierungsmeldung für die Bestätigung auf Nutzerseite anzeigt.

Autorisierungsmeldung

Nachdem Nutzer/innen auf Akzeptieren geklickt haben, ruft der Code die Methode confirmUsBankAccountSetup auf. Dann wird das Bankkonto als verifiziert gespeichert. Jetzt kann das Bankkonto für InboundTransfers verwendet werden.

const acceptBankAccount = async e => {
  acceptButton.setAttribute("disabled", "disabled");
  const response = await stripe.confirmUsBankAccountSetup("{{ client_secret }}");
  if (response.setupIntent.status == "requires_payment_method") {
    // Confirmation failed. Attempt again with a different payment method.
    console.log("Requires payment method")
  } else if (response.setupIntent.status == "succeeded") {
    // Confirmation succeeded! The account is now saved.
    // Display a message to customer.
    AcceptBankAccountModal.classList.add("hidden");
    console.log("Account added");
  } else if (response.setupIntent.next_action?.type == "verify_with_microdeposits") {
    // The account needs to be verified through microdeposits.
    // Display a message to consumer with next steps (consumer waits for
    // microdeposits, then enters an amount on a page sent to them through email).
    console.log("The account needs to be verified with microdeposits")
  }
};

Testeinzahlungen

Testeinzahlungen sind kleine Beträge (in der Regel ein Bruchteil eines US-Dollars), die Stripe auf ein externes Bankkonto einzahlt. Kontoinhaber/innen können die Inhaberschaft des Kontos durch Bestätigung der entsprechenden Einzahlungsbeträge verifizieren.

Das von Homebox im vorherigen Abschnitt erstellte SetupIntent-Objekt enthält eine PaymentMethod-ID.

{
  "id": "{{SETUP_INTENT_ID}}",
  …
  "on_behalf_of": null,
  "payment_method": "{{PAYMENT_METHOD_ID}}",
  "payment_method_options": {
…
 }
}

Der SetupIntent enthält auch ein next_action-Objekt mit einer URL, die im Wert hosted_verification_url festgelegt ist.

{
  "id": "{{SETUP_INTENT_ID}}",
…
   "next_action": {
    "type": "verify_with_microdeposits",
    "verify_with_microdeposits": {
      "arrival_date": 1642579200,
      "hosted_verification_url": "https://payments.stripe.com/microdeposit/sacs_test_xxx",
      "microdeposit_type": "amounts"
    }
…
 }

Homebox stellt dem/der Inhaber/in des verbundenen Kontos die URL bereit, um die Verifizierung abzuschließen. Diese/r muss der URL folgen, um den Erhalt durch Eingabe des zugehörigen Deskriptorcodes der Testeinzahlung zu bestätigen (verwenden Sie in Testumgebungen den Wert SM11AA).

Verifizierung einer Mikroeinzahlung

PaymentMethods mit InboundTransfers verwenden

Homebox kann mit der Erstellung von InboundTransfers beginnen, indem ein Bankkonto verwendet wird, das mit einer der zuvor beschriebenen Methoden verifiziert wurde.

Bei der folgenden Anfrage werden 200 USD mit einer mit einem Konto verknüpften Zahlungsmethode auf das Finanzkonto mit der angegebenen ID überwiesen. Der Stripe-Account-Header-Wert gibt das verbundene Stripe-Konto an, das sowohl das Finanzkonto als auch die Zahlungsmethode enthält.

curl https://api.stripe.com/v1/treasury/inbound_transfers \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d origin_payment_method=
"{{PAYMENT_METHOD_ID}}" \
  -d financial_account=
"{{FINANCIAL_ACCOUNT_ID}}" \
  -d amount=20000 \
  -d currency=usd \
  -d description="Funds for repair" \
  -d statement_descriptor="Invoice 12"

Bei Erfolg stellt die Antwort das Objekt InboundTransfer bereit. Dieses enthält eine hosted_regulatory_receipt_url, die dem Kontoinhaber/der Karteninhaberin weitere Angaben zur Transaktion auf der Homebox Plattform bereitstellt.

{
    "id": "{{INBOUND_TRANSFER_ID}}",
    "object": "inbound_transfer",
    "amount": 20000,
    "created": 1648071297,
    "currency": "usd",
    "description": "Funds for repair",
    "financial_account": "{{FINANCIAL_ACCOUNT_ID}}",
    "hosted_regulatory_receipt_url": "https://payments.stripe.com/regulatory-receipt/{{IBT_URL}}",
    "linked_flows": null,
    "livemode": false,
    "metadata": {},
    "origin_payment_method": "{{PAYMENT_METHOD_ID}}",
    ...
    "statement_descriptor": "Invoice 12",
    "status": "processing",
    ...
}

PaymentMethods mit OutboundPayments verwenden

PaymentMethod kann auch verwendet werden, um über die OutboundPayment-Objekte Geld an das externe Bankkonto eines Dritten zu senden.

Homebox möchte auf wiederkehrender Basis Gelder an Anbieter/innen eines der verbundenen Konten senden, um Materialien zu bezahlen. Dazu muss die Plattform zunächst die Kunden-ID über den Customers-Endpoint anfordern.

curl https://api.stripe.com/v1/customers \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d description="Test Customer"

Die Antwort stellt die Kund/innen für das entsprechende verbundene Konto bereit. Homebox identifiziert die richtigen Kund/innen und erfasst ihre IDs.

{
  "id": "{{CUSTOMER_ID}}",
  "object": "customer",
  "address": null,
  "balance": 0,
  "created": 1642523420,
  "currency": null,
  "default_source": null,
  "delinquent": false,
  "description": "Test Customer",
  "discount": null,
  "email": null,
  "invoice_prefix": "96A50A92",
  "invoice_settings": {
    "custom_fields": null,
    "default_payment_method": null,
    "footer": null
  },
  "livemode": false,
  "metadata": {
  },
  "name": null,
  "next_invoice_sequence": 1,
  "phone": null,
  "preferred_locales": [

  ],
  "shipping": null,
  "tax_exempt": "none"
}

Homebox erstellt dann einen SetupIntent mithilfe der ID. Da OutboundPayments für Zahlungen an Dritte verwendet wird, setzt Homebox flow_directions auf outbound und verwendet attach_to_self nicht, sondern gibt stattdessen eine/n customer an.

curl https://api.stripe.com/v1/setup_intents \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d customer=
"{{CUSTOMER_ID}}" \
  -d "flow_directions[]"=outbound \
  -d "payment_method_types[]"=us_bank_account \
  -d "payment_method_data[type]"=us_bank_account \
  -d "payment_method_data[us_bank_account][routing_number]"=110000000 \
  -d "payment_method_data[us_bank_account][account_number]"=000123456789 \
  -d "payment_method_data[us_bank_account][account_holder_type]"=individual \
  -d "payment_method_data[billing_details][name]"="John doe" \
  -d confirm=true

Ein erfolgreicher Aufruf gibt das folgende Objekt zurück, um die Zuordnung der PaymentMethod zum/zur Kund/in zu bestätigen.

{
  "id": "{{SETUP_INTENT_ID}}",
  "object": "setup_intent",
  "application": "{{APPLICATION_ID}}",
  "cancellation_reason": null,
  "client_secret": "{{SETUP_INTENT_SECRET}}",
  "created": 1642528487,
  "customer": "{{CUSTOMER_ID}}",
  "description": null,
  "flow_directions": [
    "outbound"
  ],
  "last_setup_error": null,
  "latest_attempt": null,
  "livemode": false,
  "mandate": null,
  "metadata": {
  },
  "next_action": null,
  "on_behalf_of": null,
  "payment_method": "{{PAYMENT_METHOD_ID}}",
  "payment_method_options": {
  },
  "payment_method_types": [
    "us_bank_account"
  ],
  "single_use_mandate": null,
  "status": "succeeded",
  "usage": "off_session"
}

OutboundPayment ohne PaymentMethod erstellen

PaymentMethods sind beim Senden/Verwenden von OutboundPayments nicht erforderlich, wenn das Bankkonto der Empfängerin/des Empfängers nicht gespeichert werden muss (z. B. bei einmaligen Zahlungen).

Homebox musste einem Anbieter 50 USD Materialkosten bezahlen. Dazu ruft die Plattform OutboundPayments mit den externen Kontodaten auf.

curl https://api.stripe.com/v1/treasury/outbound_payments \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d "destination_payment_method_data[type]"=us_bank_account \
  -d "destination_payment_method_data[us_bank_account][routing_number]"=110000000 \
  -d "destination_payment_method_data[us_bank_account][account_number]"=000123456789 \
  -d "destination_payment_method_data[us_bank_account][account_holder_type]"=individual \
  -d "destination_payment_method_data[billing_details][name]"="John Doe" \
  -d financial_account=
"{{FINANCIAL_ACCOUNT_ID}}" \
  -d statement_descriptor=payment_1 \
  -d amount=5000 \
  -d currency=usd

Der erfolgreiche Aufruf gibt das folgende Objekt zurück:

{
  "id": "{{OUTBOUNDPAYMENT_ID}}",
  "object": "treasury.outbound_payment",
  "amount": 5000,
  "cancelable": true,
  "created": 1643033124,
  "currency": "usd",
  "customer": null,
  "description": null,
  "destination_payment_method": null,
  "destination_payment_method_details": {
    "billing_details": {
      "address": {
        "city": null,
        "country": null,
        "line1": null,
        "line2": null,
        "postal_code": null,
        "state": null
      },
      "email": null,
      "name": "John Doe",
      "phone": null
    },
    "type": "us_bank_account",
    "us_bank_account": {
      "account_holder_type": "individual",
      "bank_name": "STRIPE TEST BANK",
      "fingerprint": "SzrMIps1gg91aVKG",
      "last4": "6789",
      "network": "ach",
      "routing_number": "110000000"
    }
  },
  "end_user_details": {
    "present": false,
    "ip_address": null
  },
  "expected_arrival_date": 1643068800,
  "financial_account": "{{FINANCIAL_ACCOUNT_ID}}",
  "hosted_regulatory_receipt_url": "https://payments.stripe.com/regulatory-receipt/bot_test_xxx",
  "livemode": false,
  "metadata": {
  },
  "statement_descriptor": "payment_1",
  "status": "processing",
  "status_transitions": {
    "canceled_at": null,
    "failed_at": null,
    "posted_at": null,
    "processing_at": 1643033124,
    "returned_at": null
  },
  "transaction": "{{TRANSACTION_ID}}"
}