Skip to main content
Cards are the most universal payment method in Yuno’s network. Yuno handles tokenization, 3DS authentication, and provider routing — your backend never touches raw card numbers unless you hold PCI DSS certification.

​
How card payments work

The standard card flow follows three stages:
  1. Create a checkout session — your backend calls POST /v1/checkout/sessions and returns a session ID to the frontend.
  2. Customer enters card details — the Yuno SDK collects the card data in a PCI-compliant iframe and produces a one-time-use token (OTT).
  3. Your backend creates the payment — using the OTT, your server calls POST /v1/payments. Yuno routes to the configured provider.
One-time tokens expire after a single use. If the payment creation fails, the SDK generates a new token automatically when the customer retries.

​
Integration steps

1

Create a checkout session (backend)

Call POST /v1/checkout/sessions with your customer ID, amount, and country. Return the checkout_session value to your frontend.
curl --request POST \
  --url https://api-sandbox.y.uno/v1/checkout/sessions \
  --header 'Content-Type: application/json' \
  --header 'public-api-key: YOUR_PUBLIC_KEY' \
  --header 'private-secret-key: YOUR_SECRET_KEY' \
  --header 'account-code: YOUR_ACCOUNT_CODE' \
  --data '{
    "country": "US",
    "customer_payer": { "id": "customer-123" },
    "amount": { "currency": "USD", "value": "2500" }
  }'
2

Initialize the Yuno SDK (frontend)

Pass the checkout_session to the SDK. The SDK renders the payment method list, including the card form.
import { Yuno } from '@yuno-payments/sdk-web';

const yuno = await Yuno.initialize('YOUR_PUBLIC_KEY');

yuno.startCheckout({
  checkoutSession: 'SESSION_ID_FROM_BACKEND',
  elementSelector: '#payment-form',
  countryCode: 'US',
  async yunoCreatePayment(oneTimeToken) {
    await fetch('/api/create-payment', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ one_time_token: oneTimeToken })
    });
    // Required for 3DS and async methods
    yuno.continuePayment();
  }
});

yuno.mountCheckout();
3

Create the payment (backend)

Your backend receives the OTT from the frontend and calls the payments endpoint.
curl --request POST \
  --url https://api-sandbox.y.uno/v1/payments \
  --header 'Content-Type: application/json' \
  --header 'private-secret-key: YOUR_SECRET_KEY' \
  --header 'account-code: YOUR_ACCOUNT_CODE' \
  --data '{
    "merchant_order_id": "order-001",
    "checkout_session": "SESSION_ID",
    "country": "US",
    "amount": { "value": 2500, "currency": "USD" },
    "payment_method": {
      "type": "CARD",
      "token": "ONE_TIME_TOKEN_FROM_SDK"
    }
  }'
A successful response returns status: "SUCCEEDED" for synchronous approvals, or status: "PENDING" when 3DS or further processing is required.

​
3D Secure (3DS)

3DS authentication is triggered automatically by Yuno when required by the card issuer, the acquirer, or regional regulation (e.g., PSD2 in Europe). You do not need to detect or initiate it manually. How it works:
  1. Your backend creates the payment normally.
  2. If 3DS is required, the API response includes sdk_action_required: true.
  3. You must call yuno.continuePayment() in the SDK callback. Yuno opens the 3DS challenge in an iframe and waits for completion.
  4. After the customer authenticates, the SDK fires yunoPaymentResult with the final status.
If you do not call continuePayment() after receiving sdk_action_required: true, the payment will remain stuck in PENDING status and may eventually expire.

​
Card vaulting

To save a card for future payments without requiring the customer to re-enter details, set vault_on_success: true in the payment request: 
{
  "merchant_order_id": "order-001",
  "checkout_session": "SESSION_ID",
  "country": "US",
  "amount": { "value": 2500, "currency": "USD" },
  "payment_method": {
    "type": "CARD",
    "token": "ONE_TIME_TOKEN"
  },
  "vault_on_success": true
}
On success, the response contains a vaulted_token you can store in your database and reuse for subsequent payments. The customer does not need to re-enter their card.
Vaulting requires a customer_payer.id in the checkout session. The vaulted token is scoped to that customer.

​
Sandbox test cards

Use these card numbers in the sandbox environment. Use any future expiry date and any 3-digit CVV (4 digits for Amex).
Card numberResult
4111 1111 1111 1111Approved
4000 0000 0000 0002Declined
4000 0000 0000 30633DS required (challenge flow)
4000 0000 0000 32203DS required (frictionless)
All sandbox payments with 4111 1111 1111 1111 return SUCCEEDED. Use declined and 3DS cards to test your error-handling and continuePayment flows before going live.

​
Custom card forms

If the Yuno SDK’s default card form does not fit your design, use Secure Fields to build your own card UI while Yuno handles secure data collection inside isolated iframes. Secure Fields guide →