Beispiel-App für Issuing und Treasury

Verwenden Sie die Beispiel-App Stripe Next.js, um Ihre eigene Issuing- und Treasury-Integration durchzuführen.

Zusätzlich zu einer detaillierten Dokumentation und SDKs für Stripe Issuing und Treasury gibt es außerdem eine Next.js-Beispiel-App.

Eine Demo unserer Beispiel-App finden Sie unter baas.stripe.dev oder im GitHub-Repository.

Auf Code zugreifen

Bei der Beispiel-App handelt es sich um eine Next.js-App, die die Nutzeroberflächen von TypeScript, React und Material nutzt. Sie finden das Projekt im GitHub-Repository der Stripe-Beispiele und können die enthaltenen Komponenten als Ausgangspunkt für Ihre eigene App verwenden.

App-Funktionen

Die App bietet viele Anleitungsbeispiele, mit denen Sie z. B.:

Stripe Connect Onboarding nutzen, um KYC-Angaben (Know Your Customer) zu erfassen und ein konformes Onboarding Ihrer verbundenen Konten zu gewährleisten
Kontoinformationen und Guthaben anzeigen
Transaktionen im Treasury-Finanzkonto anzeigen
Das Senden von Geldern per ACH oder Überweisung an ein externes Konto simulieren
Den Erhalt von ACH-Gutschriften simulieren
Das Volumen der ein- und ausgehenden Geldbewegungen mit ApexCharts visualisieren
Karteninhaber/innen konform erstellen
Karten mit dem Treasury-Finanzkonto als auszustellendes Guthaben erstellen
Vertrauliche Kartennummern auf PCI-konforme Weise anzeigen
Kartenautorisierungen simulieren
Zahlungen per Zahlungslink empfangen und Guthaben aus Stripe-Zahlungen an das Finanzkonto übertragen
Mit Tools im Test-Modus Aktionen simulieren und herausfinden, wie sich diese auf das Konto auswirken

Aufschlüsselung der Komponenten

Die folgenden Abschnitte zeigen beispielhaft, wie die einzelnen Komponenten der Beispiel-App funktionieren.

Mehr erfahren über APIs und Funktionen von Issuing sowie die Treasury APIs und Treasury-Funktionen.

Kontoerstellung

Die Kontoerstellung besteht aus vier Schritten:

Erstellen Sie ein verbundenes Konto mit den folgenden Funktionen: transfers, card_issuing und treasury.

const account = await stripe.accounts.create({
  country: 'US',
  email: email,
  capabilities: {
    transfers: {requested: true},
    treasury: {requested: true},
    card_issuing: {requested: true},
  },
  controller: {
    dashboard: {type: "none"},
    losses: {payments: "application"},
    requirement_collection: "application",
    fees: {payer: "application"}
  },
});

Erstellen Sie ein Finanzkonto bei Stripe Treasury.

const financialAccount = await stripe.treasury.financialAccounts.create(
  {
    supported_currencies: ['usd'],
    features: {
      card_issuing: {requested: true},
      deposit_insurance: {requested: true},
      financial_addresses: {aba: {requested: true}},
      inbound_transfers: {ach: {requested: true}},
      intra_stripe_flows: {requested: true},
      outbound_payments: {
        ach: {requested: true},
        us_domestic_wire: {requested: true},
      },
      outbound_transfers: {
        ach: {requested: true},
        us_domestic_wire: {requested: true},
      },
    },
  },
  {stripeAccount: account.id},
);

Generieren Sie einen Link für Connect Onboarding und leiten über diesen neue verbundene Konten weiter. Anschließend können die erforderlichen Profilangaben für die angeforderten Funktionen erfasst werden.

const { url } = await stripe.accountLinks.create({
  type: 'account_onboarding',
  account: accountId,
  refresh_url: host + '/onboard',
  return_url: host + '/onboard',
  collect: 'eventually_due',
});

Kontostand

Die Kontoguthabenkarte verwendet nur die stripe.treasury.financialAccounts.list-API.

const financialAccounts = await stripe.treasury.financialAccounts.list({
  stripeAccount: StripeAccountID,
});
const financialAccount = financialAccounts.data[0];

Die Nutzlast des obigen Befehls enthält ein Guthabenobjekt, das aus den aktuellen Guthaben-Geldern (Bargeld) und ausgehenden Geldern besteht.

{
  "id": "fa_...",
 ...
  "balance": {
    "cash": { "usd": 534214 },
    "inbound_pending": { "usd": 0 },
    "outbound_pending": { "usd": 2200 }
  },
 ...
  "supported_currencies": [ "usd" ]
}

Tabelle zu eingehenden und ausgehenden Geldern

Das Diagramm für Geldbewegungen verwendet nur die stripe.treasury.transactions.list-API.

const fa_transactions = await stripe.treasury.transactions.list(
  {
    financial_account: financialAccount.id,
    order_by: 'created',
    limit: 100,
  },
  {stripeAccount: StripeAccountID},
);

Die Antworten werden nach positivem und negativem Saldo sowie Erstellungsdatum gruppiert. Die Daten werden dann in ApexCharts portiert, um eine dynamische Anzeige der Geldbewegungen zu erstellen.

{
  "id": "{{TRANSACTION_ID}}",
  "object": "treasury.transaction",
  "created": "{{T}}",
  ...
  "flow": "{{OUTBOUND_PAYMENT_ID}}",
  "flow_type": "outbound_payment",
  "status": "open",
  "amount": -1000,
  "currency": "usd",
  "balance_impact": {
    "cash": -1000,
    "inbound_pending": 0,
    "outbound_pending": 1000,
  },
  "entries": {
    "data": [
      {
        "id": "{{TRANSACTION_ENTRY_ID}}",
        "object": "treasury.transaction_entry",
        ...
        "created": "{{T}}",
        "effective_at": "{{T}}",
        "currency": "usd",
        "balance_impact": {
          "cash": -1000,
          "inbound_pending": 0,
          "outbound_pending": 1000,
        }
      }
    ],
    "has_more": false,
    "object": "list",
    "url": "/v1/treasury/transaction_entries?financial_account={{FINANCIAL_ACCOUNT_ID}}&transaction={{TRANSACTION_ID}}"
  }
}

Transaktionsliste

Die Transaktionsliste verwendet die stripe.treasury.transactions.list-API.

const fa_transactions = await stripe.treasury.transactions.list(
  {
    financial_account: financialAccount.id,
    order_by: 'created',
    limit: 100,
  },
  {stripeAccount: StripeAccountID},
);

Die Spalten in der Transaktionstabelle werden aus dem transaction-Objekt mithilfe der folgenden Zuordnung analysiert:

created → Datum
amount → Betrag/Währung
flow_type → Typ
status → Status
description → Beschreibung

Schnittstelle zum Senden von Geld

Die Funktion zum Senden von Geld in der Beispiel-App bedient sich der Funktion OutboundPayment von Stripe Treasury. Sie können OutboundPayments verwenden, um Geld an das externe Konto eines Drittanbieters zu senden.

const outboundPayment = await stripe.treasury.outboundPayments.create(
  {
    financial_account: financialAccount.id,
    amount: amount,
    currency: 'usd',
    statement_descriptor: req.descriptor,
    destination_payment_method_data: {
      type: 'us_bank_account',
      us_bank_account: {
        account_holder_type: 'individual',
        routing_number: '110000000',
        account_number: '000000000009',
      }
    }
  },
  {
    stripeAccount: StripeAccountId
  },
);

Erstellung von Issuing-Karteninhaber/innen

Sie müssen eine/n Cardholder erstellen, bevor Sie mit Stripe Issuing eine Karte ausstellen und Gelder vom Treasury-Finanzkonto ausgeben können. Verwenden Sie die API stripe.issuing.cardholders.create, um Karteninhaber/innen zu erstellen.

const cardholder = await stripe.issuing.cardholders.create(
  {
    type: 'individual',
    name: firstName + ' ' + lastName,
    email: email,
    individual: {
      first_name: firstName,
      last_name: lastName,
      dob: {day: day, month: month, year: year}
    },
    billing: {
      address: {
        city: city,
        line1: address1,
        state: state,
        postal_code: postalCode,
        country: country,
      },
    },
  },
  {
    stripeAccount: StripeAccountId,
  }
);

Karten ausstellen

Nachdem Sie eine/n Cardholder erstellt haben, können Sie diesem/dieser Cardholder mit der stripe.issuing.cards.create-API eine Karte ausstellen.

const card = await stripe.issuing.cards.create(
  {
    cardholder: req.body.cardholderid,
    financial_account: financialAccount.id,
    currency: 'usd',
    type: 'virtual',
    status: 'active',
  },
  {stripeAccount: StripeAccountId},
);

Kartenliste

Die Kartenliste wird mit Daten aus der stripe.issuing.cards.list-API angezeigt.

const cards = await stripe.issuing.cards.list(
  {limit: 10},
  {stripeAccount: StripeAccountID},
);

Autorisierungsliste für Karten

Mit der API stripe.issuing.authorizations.list können Sie Autorisierungen für eine bestimmte Karte abrufen. Im folgenden Beispiel wird die Liste auf die letzten zehn Autorisierungen beschränkt.

const card_authorizations = await stripe.issuing.authorizations.list(
  {
    card: cardId,
    limit: 10,
  },
  {stripeAccount: StripeAccountID},
);

Die Spalten in der Autorisierungstabelle werden mithilfe der folgenden Zuordnung aus dem Antwortobjekt analysiert:

created → Datum
amount → Betrag/Betragswährung
card.cardholder.name → Name auf der Karte
card.last4 → Letzte 4 Ziffern
approved → Genehmigt
status → Status
merchant_data.name → Händler
merchant_data.category → Händlerkategorie

Test Helper

Die Testfunktionen der Beispiel-App ermöglichen es Ihnen, bestimmte Aktionen durchzuführen, wie z. B. die Finanzierung Ihres Kontos, die Erstellung eines Zahlungslinks, um Gelder auf einem verbundenen Konto zu einzuziehen, und die Auszahlung von Geldern auf das Finanzkonto. Sie können auf die meisten Test Helper zugreifen, indem Sie auf die Schaltfläche Testdaten generieren oder auf Testdaten klicken.

Testhelfer für empfangene Gutschriften

In Testumgebungen können Sie mithilfe der ReceivedCredit-Test Helpers Gelder auf ein Treasury-Finanzkonto einzahlen. Der Test Helper simuliert den Empfang einer Überweisung von einem externen Bankkonto auf Ihr Finanzkonto.

const receivedCredit = await stripe.testHelpers.treasury.receivedCredits.create(
  {
    amount: 50000,
    currency: 'usd',
    financial_account: financialAccount.id,
    network: 'ach',
  },
  {stripeAccount: StripeAccountId},
);

Zahlungslinks und Auszahlungen

Über Zahlungslinks können Sie Gelder an verbundene Konten einzahlen, die mit einem Finanzkonto verknüpft sind:

Erstellen Sie einen Price, der den Betrag festlegt, der nach Zahlungsabschluss auf das verbundene Konto eingezahlt wird.

const prices = await stripe.prices.list(
  {
    limit: 1,
    active: true,
    type: 'one_time',
  },
  {stripeAccount: StripeAccountId,},
);

let price;

if (prices.data.length < 1) {
  price = await stripe.prices.create(
    {
      unit_amount: 1000,
      currency: 'usd',
      product_data:
        {
          name: 'Unit',
      },
    },
    {stripeAccount: StripeAccountId,},
  );
} else {
  price = prices.data[0];
}

Nachdem der Preis bekannt ist, erstellt Stripe einen PaymentLink und Sie leiten die Kundin/den Kunden weiter, um die Zahlung abzuschließen. Verwenden Sie die id Price aus dem vorherigen Schritt, um den Wert für den Parameter price festzulegen. Alternativ können Sie den Parameter auch weglassen und stattdessen einen Standardwert verwenden.

const paymentLink = await stripe.paymentLinks.create(
  {
    line_items: [
      {
        price: price.id,
        quantity: 1,
        adjustable_quantity: {enabled: true},
      },
    ],
  },
  {stripeAccount: StripeAccountId,},
);

Auszahlung aus dem Guthaben des verbundenen Kontos

Per Auszahlung können Sie Gelder von dem Guthaben eines verbundenen Kontos an sein jeweiliges Treasury-Finanzkonto senden. So führen Sie eine Auszahlung durch:

Prüfen Sie, ob für das verbundene Konto ein externes Konto konfiguriert ist. Verwenden Sie dazu die accounts.retrieve API, um das Account-Objekt abzurufen und zu überprüfen, ob die Eigenschaft external_account ausgefüllt ist.

const responseAccount = await stripe.accounts.retrieve(StripeAccountID);
const accountExternalAccount = responseAccount.external_accounts.data[0];

let hasExternalAccount = false;

if (accountExternalAccount) {
  hasExternalAccount = true;
}

Wenn das verbundene Konto kein externes Konto hat, können sie das Treasury.Finanzkonto als ihr externes Konto einrichten.

const financialAccounts = await stripe.treasury.financialAccounts.list(
  {expand: ['data.financial_addresses.aba.account_number']},
  {
    stripeAccount: StripeAccountId,
  },
);

const financialAccount = financialAccounts.data[0];

await stripe.accounts.createExternalAccount(StripeAccountId, {
  external_account: {
    object: 'bank_account',
    country: 'US',
    currency: 'usd',
    account_number:
      financialAccount.financial_addresses[0].aba.account_number,
    routing_number:
      financialAccount.financial_addresses[0].aba.routing_number,
  },
});

Veranlassen Sie eine Auszahlung auf das externe Konto des verbundenen Kontos. In diesem Fall handelt es sich bei dem externen Konto um das Treasury-Finanzkonto.

const balance = await stripe.balance.retrieve({
  stripeAccount: StripeAccountId,
});

const payout = await stripe.payouts.create(
  {
    amount: balance.available[0].amount,
    currency: 'usd',
  },
  {stripeAccount: StripeAccountId},
);