Stored Credentials

Process merchant-initiated transactions with stored payment credentials

Overview

The Stored Credential Framework enables merchants to save payment credentials and reuse them for subsequent transactions. This is essential for subscriptions, recurring billing, and merchant-initiated charges such as no-show fees or delayed charges.

Card networks (Visa, Mastercard) require merchants to properly flag stored credential transactions with the correct initiator, type, and network transaction ID. Non-compliance can result in higher decline rates, increased interchange fees, or penalties.

Key Concepts

Cardholder-Initiated Transaction (CIT)

A CIT is a transaction where the cardholder is actively participating. The initial transaction in a stored credential series must always be a CIT, as the cardholder must consent to storing their credentials.

Merchant-Initiated Transaction (MIT)

A MIT is a transaction initiated by the merchant without the cardholder being present. MITs rely on a prior agreement (established during the initial CIT) and must reference the original transaction.

MIT Types

Type	Description	Example
RECURRING	Fixed-amount, fixed-schedule payments	Monthly subscription ($9.99/month)
INSTALLMENT	Fixed number of payments for a single purchase	6 monthly payments of $50
UNSCHEDULED	Variable-amount, variable-timing payments	Auto-reload when balance drops below threshold
RESUBMISSION	Retry a previously declined transaction	Retry after soft decline
DELAYED_CHARGE	Charge after service delivery	Hotel minibar charge posted after checkout
NO_SHOW	Charge for missed reservation	Hotel no-show fee

API Parameters

The stored_credential object must be included in the payment request:

{
  "stored_credential": {
    "type": "RECURRING",
    "initiator": "CARDHOLDER",
    "network_transaction_id": null
  }
}

Field	Required	Description
type	Yes	MIT type: RECURRING, INSTALLMENT, UNSCHEDULED, RESUBMISSION, DELAYED_CHARGE, NO_SHOW
initiator	Yes	CARDHOLDER for initial CIT, MERCHANT for subsequent MIT
network_transaction_id	For MITs	Network Transaction ID from the initial CIT response

Initial Transaction (CIT)

The first transaction must be cardholder-initiated. Include vaulted_token: true to save the card and stored_credential with initiator: "CARDHOLDER":

Node.js

const initialPayment = await fetch('https://api-sandbox.y.uno/v1/payments', {
  method: 'POST',
  headers: {
    'public-api-key': process.env.YUNO_PUBLIC_KEY,
    'private-secret-key': process.env.YUNO_PRIVATE_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    checkout_session: 'session-id',
    payment_method: {
      type: 'CARD',
      token: 'one-time-token-from-sdk',
      vaulted_token: true,
    },
    amount: { currency: 'USD', value: 9.99 },
    country: 'US',
    customer_id: 'cust_abc123',
    stored_credential: {
      type: 'RECURRING',
      initiator: 'CARDHOLDER',
    },
    description: 'Monthly subscription - first payment',
  }),
});

const payment = await initialPayment.json();
// Save these for subsequent transactions:
// payment.vaulted_token_id
// payment.network_transaction_id

The response includes the network_transaction_id and vaulted_token_id needed for subsequent MITs:

{
  "id": "pay_abc123",
  "status": "SUCCEEDED",
  "vaulted_token_id": "vt_xyz789",
  "network_transaction_id": "ntid_123456789",
  "payment_method": { "type": "CARD", "brand": "VISA", "last_four": "1111" }
}

Store the network_transaction_id and vaulted_token_id from the initial CIT response. These are required for all subsequent MITs and cannot be retrieved later.

Subsequent Transaction (MIT)

For recurring or merchant-initiated charges, use the vaulted token and reference the original network transaction ID:

Node.js

const recurringPayment = await fetch('https://api-sandbox.y.uno/v1/payments', {
  method: 'POST',
  headers: {
    'public-api-key': process.env.YUNO_PUBLIC_KEY,
    'private-secret-key': process.env.YUNO_PRIVATE_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    payment_method: {
      type: 'CARD',
      vaulted_token_id: 'vt_xyz789',
    },
    amount: { currency: 'USD', value: 9.99 },
    country: 'US',
    customer_id: 'cust_abc123',
    stored_credential: {
      type: 'RECURRING',
      initiator: 'MERCHANT',
      network_transaction_id: 'ntid_123456789',
    },
    description: 'Monthly subscription - March 2026',
  }),
});

Card Network Requirements

Visa

• Network Transaction ID: Required for all MITs. Must reference the original CIT.
• Stored Credential indicator: Must be sent on all subsequent transactions.
• Retry limits: Maximum 15 attempts within 30 days for a declined MIT.

Mastercard

• Network Transaction ID: Required for all MITs.
• Recurring Payment Indicator: Must distinguish between recurring, installment, and unscheduled.
• Retry limits: Maximum 10 attempts within 24 hours for the same card and amount. After 24 hours, the same card can be retried with a maximum of 35 attempts over 30 days.

Yuno automatically maps the stored_credential fields to the correct card network format (Visa VSDC, Mastercard RPDI). You do not need to handle network-specific formatting.

Compliance Considerations

1. Customer consent: Always obtain explicit consent before storing credentials. Record the consent with a timestamp.
2. Cancellation: Provide an easy mechanism for customers to cancel recurring payments and delete stored credentials.
3. Notification: Notify customers before each MIT charge (required in many jurisdictions).
4. Amount changes: If the recurring amount changes, notify the customer in advance and obtain updated consent if required by local regulation.
5. Credential updates: When a card expires or is replaced, card networks may provide updated credentials via Account Updater services. Check with your Yuno account manager for availability.

Failing to properly flag stored credential transactions may result in penalties from card networks, increased decline rates, or loss of processing privileges. Always include the stored_credential object for any transaction using saved payment credentials.