Skip to main content
This guide covers how to vault Plaid payment methods for recurring transactions. Before you begin, make sure you’ve configured your Plaid connection and understand the basic integration flow. You can vault a Plaid payment method by setting store: true on the first (customer-present) transaction. The system stores the Plaid access token and returns a payment_method.id. Use that ID for subsequent merchant-initiated charges without collecting a new Plaid Link token.
Identity and Identity Match checks are performed only on the initial transaction. Balance and Signal checks are performed on both the initial transaction and all subsequent recurring payments, as these checks evaluate transaction-specific risk factors that may change with each payment.
If you’re using Plaid Signal, configure your ruleset in Signal setup.

​
Step 1: First payment

Set store: true, mark it as payment_source: "recurring", and leave merchant_initiated / is_subsequent_payment false. 
var res = await sdk.Transactions.CreateAsync(
    transactionCreate: new TransactionCreate()
    {
        Amount = 1299,
        Currency = "USD",
        Country = "US",
        Intent = TransactionCreate.IntentEnum.Capture,
        
        PaymentMethod = TransactionCreatePaymentMethod.CreatePlaidPaymentMethodCreate(
            new PlaidPaymentMethodCreate()
            {
                Method = PlaidPaymentMethodCreate.MethodEnum.Plaid,
                Token = publicToken
            }
        ),
        
        Store = true,
        PaymentSource = TransactionCreate.PaymentSourceEnum.Recurring,
        MerchantInitiated = false,
        IsSubsequentPayment = false,
        PaymentServiceId = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    }
);

​
Step 2: Subsequent charge

Use the saved payment_method_id, set payment_source: "recurring", and mark it as merchant-initiated and subsequent. 
var res = await sdk.Transactions.CreateAsync(
    transactionCreate: new TransactionCreate()
    {
        Amount = 1299,
        Currency = "USD",
        Country = "US",
        Intent = TransactionCreate.IntentEnum.Capture,
        
        // Use the ID factory for stored payment methods
        PaymentMethod = TransactionCreatePaymentMethod.CreateId("xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"),
        
        PaymentSource = TransactionCreate.PaymentSourceEnum.Recurring,
        MerchantInitiated = true,
        IsSubsequentPayment = true,
        PaymentServiceId = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    }
);

​
Re-authenticating stored payment methods

Stored Plaid payment methods occasionally require re-authentication. This is typically needed when bank credentials expire, the bank requires new MFA, consent is nearing expiry, or the connection is in an error state. The main signal is a failed transaction on that stored method with error_code: payment_method_requires_action. You can also detect upcoming or expired mandates via webhooks. The system emits payment-method.authorization-expiring (token close to expiring) and payment-method.authorization-update-required (token expired) events when receiving updates from Plaid. When you see this error, create a new Link token for the stored payment method using the Sessions API. Include the stored payment method ID in the x-gr4vy-payment-method header and use this payload structure, where access_token is replaced by the system with the vaulted access token: 
using Gr4vy;
using Gr4vy.Models.Components;
using System.Collections.Generic;

var sdk = new Gr4vySDK(
    id: "example",
    server: SDKConfig.Server.Sandbox,
    bearerAuthSource: Auth.WithToken(privateKey),
    merchantAccountId: "default"
);

var session = await sdk.PaymentServiceDefinitions.SessionAsync(
    paymentServiceDefinitionId: "plaid-bank",
    sessionRequestBody: new SessionRequestBody()
    {
        Action = "create-link-token",
        Payload = new Dictionary<string, object>
        {
            ["access_token"] = "{{PLAID_ACCESS_TOKEN}}"
        }
    },
    // The payment method ID is passed via a specific optional parameter, usually mapped to the header
    xGr4vyPaymentMethod: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
);

Console.WriteLine($"Link token: {session.LinkToken}");
Present the returned Link token to the buyer for re-authentication. Once complete, retry the original transaction with the same stored payment method.
If the reauthorization happens outside of Plaid’s Update Mode, the system sends a payment-method.authorization-updated webhook. When using Update Mode, only your frontend receives confirmation; no webhook is emitted. See Plaid’s Update Mode documentation for details.