> ## Documentation Index
> Fetch the complete documentation index at: https://yn-c9bb3266.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```json theme={"theme":{"light":"github-dark","dark":"github-dark"}}
{
  "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"`:

<CodeGroup>
  ```javascript Node.js theme={"theme":{"light":"github-dark","dark":"github-dark"}}
  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
  ```

  ```python Python theme={"theme":{"light":"github-dark","dark":"github-dark"}}
  import requests

  response = requests.post(
      'https://api-sandbox.y.uno/v1/payments',
      headers={
          'public-api-key': YUNO_PUBLIC_KEY,
          'private-secret-key': YUNO_PRIVATE_KEY,
          'Content-Type': 'application/json',
      },
      json={
          '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',
      },
  )

  payment = response.json()
  # Save: payment['vaulted_token_id'], payment['network_transaction_id']
  ```
</CodeGroup>

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

```json theme={"theme":{"light":"github-dark","dark":"github-dark"}}
{
  "id": "pay_abc123",
  "status": "SUCCEEDED",
  "vaulted_token_id": "vt_xyz789",
  "network_transaction_id": "ntid_123456789",
  "payment_method": { "type": "CARD", "brand": "VISA", "last_four": "1111" }
}
```

<Warning>
  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.
</Warning>

## Subsequent Transaction (MIT)

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

<CodeGroup>
  ```javascript Node.js theme={"theme":{"light":"github-dark","dark":"github-dark"}}
  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',
    }),
  });
  ```

  ```python Python theme={"theme":{"light":"github-dark","dark":"github-dark"}}
  import requests

  response = requests.post(
      'https://api-sandbox.y.uno/v1/payments',
      headers={
          'public-api-key': YUNO_PUBLIC_KEY,
          'private-secret-key': YUNO_PRIVATE_KEY,
          'Content-Type': 'application/json',
      },
      json={
          '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',
      },
  )
  ```
</CodeGroup>

## 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.

<Note>
  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.
</Note>

## 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.

<Warning>
  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.
</Warning>