Cash App Pay Integration Guide

The customer opens the merchant's payment page
        |
        v
The merchant backend calls POST /transactions
        |
        v
Synswi creates a Stripe PaymentIntent
        |
        v
Synswi returns clientSecret and stripeConnectedAccountId
        |
        v
The merchant frontend initializes Stripe.js and displays Payment Element
        |
        v
The customer confirms the Cash App Pay payment
        |
        v
Stripe sends an asynchronous webhook to Synswi
        |
        v
Synswi creates a succeeded transaction with the merchant's tags

https://api-dev.synswi.com

AUTH_TOKEN = eyJ...

{{AUTH_TOKEN}}

{
  "tags": {
    "orderId": "ORDER-10001",
    "customerId": "CUSTOMER-20001"
  }
}

type CreateCashAppPaymentRequest = {
  accountId: string;
  amount: number;
  orderId: string;
  customerId?: string;
};

type CreateCashAppPaymentResponse = {
  clientSecret: string;
  stripeConnectedAccountId: string;
};

export async function createCashAppPayment(
  request: CreateCashAppPaymentRequest,
): Promise<CreateCashAppPaymentResponse> {
  const response = await fetch("https://api-dev.synswi.com/transactions", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.SYNSWI_ACCESS_TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      accountId: request.accountId,
      amount: request.amount,
      type: "pull",
      channel: "online",
      method: "cashapp",
      tags: {
        orderId: request.orderId,
        ...(request.customerId
          ? { customerId: request.customerId }
          : {}),
      },
    }),
  });

  const data = await response.json();

  if (!response.ok) {
    throw new Error(data.message || "Unable to create Cash App payment");
  }

  return data;
}

{
  "clientSecret": "pi_xxx_secret_xxx",
  "stripeConnectedAccountId": "acct_xxx"
}

import { loadStripe } from "@stripe/stripe-js";

const stripePromise = loadStripe(
  "<SYNSWI_PLATFORM_PUBLISHABLE_KEY>",
  {
    stripeAccount: stripeConnectedAccountId,
  },
);

The client_secret provided does not match any associated PaymentIntent on this account.

import {
  Elements,
  PaymentElement,
  useElements,
  useStripe,
} from "@stripe/react-stripe-js";
import { loadStripe } from "@stripe/stripe-js";
import { FormEvent, useMemo } from "react";

function PaymentForm() {
  const stripe = useStripe();
  const elements = useElements();

  async function handleSubmit(event: FormEvent<HTMLFormElement>) {
    event.preventDefault();

    if (!stripe || !elements) return;

    const { error } = await stripe.confirmPayment({
      elements,
      confirmParams: {
        return_url: "https://merchant.example.com/payment/result",
      },
    });

    if (error) {
      console.error(error.code, error.message);
      // Display error.message near the payment form.
    }
  }

  return (
    <form onSubmit={handleSubmit}>
      <PaymentElement />
      <button type="submit" disabled={!stripe}>
        Pay with Cash App
      </button>
    </form>
  );
}

type PaymentPageProps = {
  clientSecret: string;
  stripeConnectedAccountId: string;
};

export function PaymentPage(props: PaymentPageProps) {
  const stripePromise = useMemo(
    () =>
      loadStripe("<SYNSWI_PLATFORM_PUBLISHABLE_KEY>", {
        stripeAccount: props.stripeConnectedAccountId,
      }),
    [props.stripeConnectedAccountId],
  );

  return (
    <Elements
      stripe={stripePromise}
      options={{ clientSecret: props.clientSecret }}
    >
      <PaymentForm />
    </Elements>
  );
}

payment_intent
payment_intent_client_secret
redirect_status

{
  "accountId": "acc-123",
  "tags": {
    "orderId": "ORDER-10001"
  },
  "limit": 10
}

{
  "transactions": [
    {
      "id": "txn-xxx",
      "accountId": "acc-123",
      "amount": 1280,
      "currency": "USD",
      "type": "pull",
      "subtype": "payment",
      "channel": "online",
      "method": "cashapp",
      "status": "succeeded",
      "referenceId": "stripe-pi_xxx",
      "tags": {
        "orderId": "ORDER-10001",
        "customerId": "CUSTOMER-20001"
      }
    }
  ],
  "totalCount": 1
}

{
  "message": "Error description"
}

const { error } = await stripe.confirmPayment(...);

console.log(error?.type);
console.log(error?.code);
console.log(error?.decline_code);
console.log(error?.message);