Stored Credentials

Depending on how and when a payment is processed, it can originate from either customer-initiated transactions (CIT) or merchant-initiated transactions (MIT). To ensure the responsible storage and use of cardholder information, Visa and Mastercard have established guidelines and regulations for stored credentials. Yuno has streamlined the process for you to comply with these scheme rules, enabling you to securely store card details in Yuno for future use while maintaining compliance.

Important: This is not the same as SubscriptionsThink of who’s in control of recurrence:

Stored Credentials: You control recurrence and are responsible for sending each transaction according to your own schedule and recurrence logic.
Subscription API: Yuno controls it. You provide instructions once, then Yuno automatically sends transactions on your behalf. See Subscriptions.

Categorization
General considerations
Create a payment
Subscription agreement ID
Network transaction ID
Wallet-originated tokens (Apple Pay and Google Pay)

Categorization

Category	Customer-initiated transactions (CIT)	Merchant-initiated transactions (MIT)
Definition	Transactions initiated by the customer, such as online and in-store purchases, or ATM withdrawals.	Transactions initiated by the merchant or service provider without the customer’s active involvement.
Examples	Includes online purchases, in-store purchases, and ATM withdrawals.	Includes recurring payments, automatic subscription renewals, and recurring billing.
Authentication	Typically requires cardholder authentication to ensure security.	Requires initial customer authentication to set up, with potential additional authentication based on security regulations and card issuer policies for subsequent transactions.

Determining whether a transaction is initiated by the merchant or the customer has significant implications for security, user experience, fraud prevention, and regulatory compliance.

General considerations

Responsibility: In the context of strong customer authentication (SCA) under PSD2 regulation in the European Union, CIT generally requires higher authentication compared to MIT.
Frequency: MIT transactions are often recurring and periodic, while CIT are more ad hoc events based on customer actions.

Create a payment with processing type

To specify a payment with a processing type, use the stored_credentials structure inside the payment_method.detail.card when creating a payment.

Parameter	Type	Description
`reason`	enum	Indicates the reason for storing credentials for the transaction. `CARD_ON_FILE` `SUBSCRIPTION` `UNSCHEDULED_CARD_ON_FILE`
`usage`	enum	A credit card can be stored with or without an initial payment. This field indicates if this is the first time the vaulted_token/network_token is used or reused. `FIRST` `USED`
`subscription_agreement_id`	string	The ID of the agreement with the customer, mandatory for certain markets (e.g., MX).
`network_transaction_id`	string	The ID provided by Visa/Mastercard in the response of the initial payment, which is highly recommended for future use in merchant-initiated transactions (MIT).

Critical: Complete All Required Fields

When working with CIT and MIT transactions, it’s essential to correctly populate the usage, reason, and network_transaction_id fields. Failing to complete these fields properly can result in decreased approval rates and loss of chargeback disputes.
Some providers (e.g., Adyen) require that the reason field remains consistent across the transaction lifecycle. If your first transaction (usage=FIRST) uses reason=SUBSCRIPTION, all subsequent transactions (usage=USED) must also use reason=SUBSCRIPTION.

Store credential reasons

Reason	Description
`CARD_ON_FILE`	A customer-initiated payment using a previously enrolled credit card where the cardholder is present. Allows customers one-click payment for a frictionless payment experience.
`SUBSCRIPTION`	Used for merchant-initiated payments as part of a subscription. This does not create a new subscription - use the Subscription API for automated recurring billing.
`UNSCHEDULED_CARD_ON_FILE`	A merchant-initiated payment using stored credit card details that is not related to a subscription schedule or amount. Payment can occur at any given time.

Request example

Request (cURL)

curl --request POST \
     --url https://api-sandbox.y.uno/v1/payments \
     --header 'X-Idempotency-Key: <Your idempotency-key>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'private-secret-key: <Your private-secret-key>' \
     --header 'public-api-key: <Your public-api-key>' \
     --data '
{
    "description": "Test",
    "account_id": "{{account-code}}",
    "merchant_order_id": "0000023",
    "country": "DE",
    "merchant_reference" : "reference-{{$randomUUID}}",
    "amount": {
        "currency": "EUR",
        "value": 5000
    },
    "customer_payer": {
        "id":"967ecd18-d898-4b88-9400-dd5b01b18edc"
    },
    "workflow": "DIRECT",
    "payment_method": {
        "type":"CARD",
        "vaulted_token": "eb8caa17-6407-457b-960e-125d8d7a90c1",
        "detail": {
           "card": {
               "stored_credentials":{
                  "reason":"CARD_ON_FILE",
                  "usage": "USED",
                  "network_transaction_id":"583103536844189"
              }
           }
        }
    }
}
'

Wallet-originated tokens (Apple Pay and Google Pay)

A wallet CIT with vault_on_success: true also produces a vaulted_token: Apple Pay and Google Pay decrypt to a card network token, so the stored instrument is a CARD record with parent_payment_method_type set to the wallet type.

Store the token from the payment responseThe vaulted_token is returned only in the CIT payment response. Wallet-vaulted instruments are intentionally not included in Retrieve Enrolled Payment Methods — an empty payment_methods list for a wallet-only customer is expected, even though the token is valid and chargeable. Persist the vaulted_token (plus any display metadata you need, such as brand and last four digits) on your side when the CIT succeeds. A stored token can still be resolved individually with Retrieve Enrolled Payment Method by ID.

Where stored_credentials goes depends on the step. On the first charge the payment method is still the wallet, so the object sits under detail.wallet. Once the instrument is vaulted it is a CARD record, and later charges on the vaulted_token use detail.card, exactly as for cards (PayPal is the exception, see the note below):

Step	`payment_method.type`	Token field	`stored_credentials` node	`reason`	`usage`
First charge (wallet sheet shown, instrument vaulted)	`APPLE_PAY` or `GOOGLE_PAY`	`token` (SDK) or `detail.wallet.payment_token` (direct)	`detail.wallet.stored_credentials`	`SUBSCRIPTION`	`FIRST`
Later charges in the same recurring series (MIT)	`CARD` (the wallet type is also accepted with a `vaulted_token`)	`vaulted_token`	`detail.card.stored_credentials`	`SUBSCRIPTION`	`USED`
Customer-present one-click purchase on the stored token	`CARD` (the wallet type is also accepted with a `vaulted_token`)	`vaulted_token`	`detail.card.stored_credentials`	`CARD_ON_FILE`	`USED`

Do not place stored_credentials under detail.card on a wallet CITdetail.wallet is the only node Yuno guarantees to read on a wallet payment. An object placed under detail.card on an Apple Pay or Google Pay first payment is not validated: it can still reach the provider, but the two-step SDK flow does not carry it into the saved payment method, which leaves the record without stored-credential flags and without a network_transaction_id. Later charges on that record then run as plain purchases instead of a recurring series.

PayPal is the exceptionAn instrument vaulted through PAYPAL_ENROLLMENT stays a wallet record, so stored_credentials (including subscription_agreement_id) goes under detail.wallet on the later charges as well, not under detail.card.

Yuno attaches the network_transaction_id from the usage: FIRST payment automatically, exactly as for cards. Keep reason consistent within a series. See the “Critical: Complete All Required Fields” note under Create a payment with processing type. Full request examples are on the Apple Pay SDK, Apple Pay direct, Google Pay SDK and Google Pay direct pages.

Subscription agreement

For certain markets (MX for example) and payment processors, when a subscription-related payment is made, the ID of the agreement with the customer needs to be specified in the payment request to ensure correct processing. To facilitate this, Yuno has enabled the subscription_agreement_id field inside the stored_credentials struct, allowing you to share the agreement made with the customer.

NoteThe subscription_agreement_id and network_transaction_id are independent fields. Including a subscription_agreement_id does not replace the need for a network_transaction_id. Both should be provided when applicable to ensure optimal approval rates and chargeback protection.

"payment_method": {
        "type":"CARD",
        "vaulted_token": "eb8caa17-6407-457b-960e-125d8d7a90c1",
        "detail": {
           "card": {
               "stored_credentials":{
                  "reason":"CARD_ON_FILE",
                  "usage": "USED",
                  "subscription_agreement_id":"AA0001",
                  "network_transaction_id":"583103536844189"
              }
           }
        }
    }

Network transaction ID

A network transaction ID is a unique identifier assigned to a transaction by the card network. It is used to track and reference specific transactions, particularly in recurring payment scenarios, ensuring consistency and traceability across the payment lifecycle. If the transaction is customer-initiated (CIT), the network transaction reference will be available in the card.stored_credentials.network_transaction_id field. This field represents the transaction ID for Visa and the trace ID for Mastercard, which are recommended for future subscription payments.

"payment_method": {
        "type":"CARD",
        "vaulted_token": "eb8caa17-6407-457b-960e-125d8d7a90c1",
        "detail": {
           "card": {
               "stored_credentials":{
                  "reason":"CARD_ON_FILE",
                  "usage": "USED",
                  "network_transaction_id":"583103536844189"
              }
           }
        }
    }

Use

Yuno associates the network_transaction_id with the vaulted_token for future transactions, so you don’t have to manage the logic for each case. Yuno performs the association when a payment is created with:

Payment method:
- A card vaulted_token, or
- Card data with vault_on_success set to true
Stored credentials:
- usage set to FIRST

When using vault_on_success = true in a direct integration, you must create the customer first and pass its customer_payer.id in the payment request. Sending customer details inline does not create the customer on Yuno’s side, so the card cannot be stored and no vaulted_token will be returned.

If you already have the network_transaction_id for the card, you can include it in the payment in the corresponding field. If not, for MIT payments (with stored_credentials.usage=USED), Yuno sends the network_transaction_id associated with the vaulted_token to the provider.

Remember to specify the usage in the stored_credentials section, as Yuno triggers the network_transaction_id logic based on those fields. A stored_credentials object that carries reason but no usage is accepted, but no network_transaction_id is recorded for that payment.

Recurring payments across providers

The network_transaction_id belongs to the card network, not to the provider that processed the first payment. Yuno stores it on the vaulted_token and sends it on every merchant-initiated payment, whichever provider your routing selects. This is what makes a stored card portable: a subscription that started on one provider can be billed on another without asking the customer to authenticate again. You always send the same fields (usage, reason, and optionally network_transaction_id); Yuno translates them into each provider’s own stored-credential format and reference fields. Because of this, you can:

Route renewals, retries, and fallbacks to the provider with the best approval rate or cost. The TRANSACTION_TYPE routing condition distinguishes CIT, MIT, and RECURRING payments, so a route can treat first charges and later charges differently.
Recover failed renewals with Smart Retries when Yuno runs the subscription, or with the Retry Subscription endpoint. If you run billing on your own side, retry the MIT on the vaulted token exactly as you would charge it the first time.
Move a merchant-initiated series between providers during a migration, because the network reference travels with the token rather than with the connection.

For Mastercard, the transaction link ID (TLID) is separate from the network_transaction_id, which carries the Mastercard trace ID. Yuno stores the TLID returned on a successful payment sent with usage: FIRST and reuses it on later USED charges on the same vaulted_token. Another successful FIRST payment can replace the stored value with the TLID returned by that payment. TLID replay depends on support from the receiving provider. Continue sending usage and reason as usual. You do not need to send the TLID yourself or add a new field to your payment request.

The reason consistency rule still applies when a series moves to another provider: keep the same reason you used on the first payment, whichever provider processes the later ones.

Getting Started

Core Concepts

Using Yuno

Direct Integration Use Cases

Payment Features

Payouts and Disputes

Webhooks

Wallets

AI Capabilities

Security and Compliance

Plugins

Additional Services

Categorization

General considerations

Create a payment with processing type

Request example

Wallet-originated tokens (Apple Pay and Google Pay)

Subscription agreement

Network transaction ID

Use

Recurring payments across providers

​Categorization

​General considerations

​Create a payment with processing type

​Request example

​Wallet-originated tokens (Apple Pay and Google Pay)

​Subscription agreement

​Network transaction ID

​Use

​Recurring payments across providers

Categorization

General considerations

Create a payment with processing type

Request example

Wallet-originated tokens (Apple Pay and Google Pay)

Subscription agreement

Network transaction ID

Use

Recurring payments across providers