Integrate with third-party payment processors

In the Dashboard, create the custom payment method type your customers will pay with. Custom payment method types allow you to specify branding for the custom payment methods you define for each customer. For example, if you’re using SamplePay as another processor, you might want to create a SamplePayCard to represent cards that you process with SamplePay.

Go to Custom payment method types in the Dashboard. At the end of these steps, you’ll have one or more custom payment method types defined that you can offer your customers when they checkout.

1. Create a custom payment method type.
2. Set the display name and logo for the custom payment method type.

1. Click Create to make a new payment method type, SamplePayCard, which you can then use to set up a custom payment method.
2. You can see the created custom payment method type details in the Dashboard.
3. Custom payment method types aren’t retrievable through the API. We recommend storing the ID in your database and retrieving it during payment method creation.
4. After you configure custom payment methods, you can add them in either the Payment Element or directly to your custom payment page.

Collect customer information (email address, billing address, and shipping address) and the price your customer selected. Then make a request to the server to create a new Stripe Customer and Subscription.

curl https://api.stripe.com/v1/subscriptions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "customer=
{{CUSTOMER_ID}}" \
  -d "items[0][price]=
{{PRICE_ID}}" \
  -d payment_behavior=default_incomplete \
  -d "payment_settings[save_default_payment_method]=on_subscription" \
  -d "expand[0]=latest_invoice"

At this point the subscription is incomplete with an open invoice.

Redirect the customer to your payment form to collect payment. Collect payment details for the payment method selected, and send a request to your server to initiate a payment session:

const response = await fetch('/create_payment_session', {
  method: 'POST',
  data: {
    // If needed, include an identifier for the processor selected by the customer
  }
});
// Redirect customer to processor to complete payment
window.location.href = response.redirectUrl;

Create a server-side handler to start a new payment session on your third-party processor. Then, send a return URL to redirect your customer to where they can complete payment.

app.post('/create_payment_session', async (req, res) => {

  const paymentSession = processorSdk.createPaymentSession({
    amount: invoice.amount_due,
    currency: invoice.currency,
    return_url: '/payment_session_completed'
  });
  return {
    redirectUrl: paymentSession.redirectUrl
  };
});

When Stripe creates an invoice for a charge_automatically subscription, it automatically creates a default PaymentIntent object to attempt payment collection. Because you’re processing payments through your own processor and reporting the outcome with a PaymentRecord, Stripe cancels this default PaymentIntent. As a result, you see a Canceled payment entry next to your reported payment on each invoice. This is expected behavior and doesn’t affect the invoice or subscription status.

const stripe = new Stripe(
'sk_test_BQokikJOvBiI2HlWgH4olfQ2', {
  apiVersion: '2026-03-25.dahlia'
});

app.post('/payment_session_completed', async (req, res) => {
  // `paymentReference` refers to the response object provided by your third-party processor
  // to indicate completion of payment. The exact contents vary based on the third-party processor.
  const paymentMethod = await stripe.paymentMethods.create({
    type: 'custom',
    custom: {
      // Set to the ID of the custom payment method type created in Step 1
      type: 
'{{CUSTOM_PAYMENT_METHOD_TYPE_ID}}',
    },
    metadata: {
      // Store any information specific to your third-party processor
      // that's needed to perform off-session payments
      {{PROCESSOR_AGREEMENT_ID_KEY}}: '{{PROCESSOR_AGREEMENT_ID}}',
    }
  });

Attaching a payment record to the invoice marks it as paid and transitions the associated subscription to active. You must report a payment within 23 hours of creating the subscription, or the subscription transitions to incomplete_expired and you need to recreate it.

To process future payments for a charge_automatically subscription, configure a handler to receive webhook events. Specifically, you’ll handle the invoice.payment_attempt_required webhook, which Stripe sends when a new invoice is finalized and requires payment through your custom payment method:

const stripe = new Stripe(
'sk_test_BQokikJOvBiI2HlWgH4olfQ2', {
  apiVersion: '2026-03-25.dahlia'
});

app.post('/webhook', async (request, response) => {
  const payload = request.body;
  const sig = request.headers['stripe-signature'];

  let event;

  try {
    event = stripe.webhooks.constructEvent(payload, sig, endpointSecret);
  } catch (err) {
    return response.status(400).send(`Webhook Error: ${err.message}`);
  }

  switch (event.type) {
    case 'invoice.payment_attempt_required':
      const invoiceId = event.data.object.id;

When a failed payment is reported, the invoice remains open. If the Subscription was created in an incomplete status, it remains incomplete until successful payment is reported, or it expires.

If the Subscription was previously active, it transitions to past_due. If retries are configured, then the Subscription moves into dunning and we send subsequent invoice.payment_attempt_required webhook events when retries are attempted.

You can configure retries using custom retry schedules or automations. We don’t support Smart Retries.

For custom retry schedules, if you exhaust all retries, the invoice and subscription might transition depending on your configured retry settings. You can also manually cancel the subscription earlier if you can’t collect payment.

When retrying a failed payment, report the new attempt against the existing PaymentRecord object using report_payment_attempt or report_payment_attempt_guaranteed. Don’t create a new PaymentRecord with report_payment. Creating a separate PaymentRecord for each attempt results in multiple distinct payment entries on the invoice (for example, one Failed and one Succeeded), rather than a single payment with a consolidated history of attempts.

To handle payment retries, extend the handler implemented in the Configure webhook handler section:

async function processOffSessionPayment(invoice) {
  const customPaymentMethod = await stripe.paymentMethods.retrieve(invoice.defaultPaymentMethod);

  // No changes needed, collect payment as before from the third-party processor
  const paymentResult = await processorSdk.collectPayment({
    amount: invoice.amount_remaining,
    agreement_id: customPaymentMethod.metadata['{{PROCESSOR_AGREEMENT_ID_KEY}}']
  });

  // Query for any existing payment records, which indicate a prior payment attempt
  const invoicePayments = await stripe.invoicePayments.list({
    invoice: invoice.id,
    payment: { type: 'payment_record' }
  });

  if (invoicePayments.data.length) {

You can report canceled payments to Stripe when using the asynchronous payment flow. Use this option when a payment is initiated but later canceled.

To report a canceled payment, first create a payment record indicating the payment is initiated (as shown in Record payment).

When the payment is canceled, report the cancellation to Stripe:

const stripe = new Stripe(
'sk_test_BQokikJOvBiI2HlWgH4olfQ2', {
  apiVersion: '2026-03-25.dahlia'
});

app.post('/payment_session_canceled', async (req, res) => {
  await stripe.paymentRecords.reportPaymentAttemptCanceled(paymentRecord.id, {
    canceled_at: Date.now()
  });
});

When your third-party processor processes a refund, you can report it to Stripe to maintain accurate payment records. You can report both full and partial refunds, but only after the original payment is successfully recorded in Stripe.

To report a refund, you need to provide the refund reference from your third-party processor, which must be unique for each Payment Record. For a partial refund, specify the amount parameter.

To maintain accurate accounting data, log refunds on issued invoices by using Credit Notes to adjust the invoice amounts.

const stripe = new Stripe(
'sk_test_BQokikJOvBiI2HlWgH4olfQ2', {
  apiVersion: '2026-03-25.dahlia'
});

app.post('/payment_refunded', async (req, res) => {
  const paymentRecordRefund = await stripe.paymentRecords.reportRefund(paymentRecord.id, {
    // `refundReference` refers to the response object provided by your third-party processor
    // when the refund is issued. The exact contents vary based on the third-party processor.
    processor_details: {
      type: 'custom',
      custom: {
        refund_reference: refundReference.id
      }
    },
    outcome: 'refunded',
    refunded: {
      refunded_at: Date.now()
    }
  });

  const invoicePayments = await stripe.invoicePayments.list({
    payment: {
      type: 'payment_record',
      payment_record: paymentRecordId
    }
  });

  // Create a credit note to reflect the refund on the invoice
  await stripe.creditNotes.create({
    invoice: invoicePayments.data[0].invoice,
    refunds: [{
        type: 'payment_record_refund',
        // amount_refunded is an optional field. If not provided, the credit note is created for the full amount of the PaymentRecord refund.
        amount_refunded: paymentRecordRefund.refund_details[0].amount_refunded.value,
        payment_record_refund: {
          payment_record: paymentRecordRefund.id,
          refund_group: refundReference.id
        }
      }
    ]
  });
});