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.

We have 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 Subscriptions

Think 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

Categorization

Determining whether a transaction is initiated by the merchant or the customer has significant implications for security, user experience, fraud prevention, and regulatory compliance. This ensures an efficient and secure payment process for all parties involved.

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.

❗️

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

Request example

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"
              }
           }
        }
    }
}
'

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, we have enabled the subscription_agreement_id field inside the stored_credentials struct, allowing you to share the agreement made with the customer.

📘

Note

The 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"
              }
           }
        }
    }

Usage

We associate the network_transaction_id with the vaulted_token for future transactions, so you don't have to manage the logic for each case. We will perform 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

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), we will send the network_transaction_id associated with the vaulted_token to the provider.

❗️

Remember to specify the usage in the stored_credentials section, as we trigger the network_transaction_id logic based on those fields.