AI Agent Instructions

​

When to use Yuno

• Accepting payments across multiple countries, currencies, or payment methods (cards, bank transfers, wallets, BNPL) through a single integration instead of one per processor.
• Routing a transaction to different payment providers/acquirers (smart routing, retries, failover) without hardcoding provider-specific logic.
• Building a checkout, enrollment, or subscription flow that needs a hosted checkout session, a one-time token (OTT), or a vaulted payment method.
• Implementing a marketplace or platform that splits a payment between a merchant and sub-recipients (Recipients for Marketplace, split payments).
• Verifying or constructing webhook payloads from Yuno (payment status changes, dispute updates, payout events).

​

Installation

npm install @yuno-payments/sdk-web

<script src="https://sdk-web.y.uno/v1.10/main.js"></script>

pod 'YunoSDK', '~> 2.11.1'

dependencies: [
    .package(url: "https://github.com/yuno-payments/yuno-sdk-ios", from: "2.11.1")
]

maven { url "https://yunopayments.jfrog.io/artifactory/snapshots-libs-release" }

dependencies {
    implementation 'com.yuno.payments:android-sdk:2.11.0'
}

npm install @yuno-payments/yuno-sdk-react-native
cd ios && pod install

flutter pub add yuno

​

Configuration

• account_id identifies the account inside request bodies (the sample project calls it ACCOUNT_CODE).
• Yuno uses a 60-second timeout for all endpoints.
• Docs MCP for coding tools: https://docs.y.uno/mcp (HTTP transport, no auth). Setup at https://docs.y.uno/setup-mcp.
• API MCP, hosted: https://mcp.prod.y.uno/mcp with headers public-api-key, private-secret-key, and account-code.
• API MCP, local: npx @yuno-payments/yuno-mcp@latest with env vars YUNO_PUBLIC_API_KEY, YUNO_PRIVATE_SECRET_KEY, and YUNO_ACCOUNT_CODE.

​

Usage

1. Create a customer. Yuno returns a customer ID used in every later step.
2. Create a checkout session (SDK and Checkout integrations). It links the customer to the payment and loads the payment methods enabled on your account. Direct server-to-server integrations skip this step.
3. Collect payment details. The SDK captures card data and returns a one-time token (OTT). Direct integrations send the details themselves and require PCI compliance.
4. Create the payment with the customer ID, the checkout session, and the token. Yuno reports later status changes through webhooks.

curl --request POST \
     --url https://api-sandbox.y.uno/v1/checkout/sessions \
     --header 'X-Idempotency-Key: <UUID>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'public-api-key: <PUBLIC_API_KEY>' \
     --header 'private-secret-key: <PRIVATE_SECRET_KEY>' \
     --data '{
       "account_id": "<ACCOUNT_ID>",
       "merchant_order_id": "1717681150",
       "payment_description": "Test Cards",
       "country": "US",
       "customer_id": "<CUSTOMER_ID>",
       "amount": { "currency": "USD", "value": 100 }
     }'

curl --location 'https://api-sandbox.y.uno/v1/payments' \
--header 'X-Idempotency-Key: <UUID>' \
--header 'public-api-key: <PUBLIC_API_KEY>' \
--header 'private-secret-key: <PRIVATE_SECRET_KEY>' \
--header 'Content-Type: application/json' \
--data '{
    "description": "SDK Checkout",
    "account_id": "<ACCOUNT_ID>",
    "merchant_order_id": "123456",
    "merchant_reference": "reference_001",
    "country": "US",
    "amount": { "currency": "USD", "value": 100 },
    "checkout": { "session": "<CHECKOUT_SESSION>" },
    "customer_payer": { "id": "<CUSTOMER_ID>" },
    "payment_method": { "token": "<ONE_TIME_TOKEN>" }
}'

​

Resources

• https://docs.y.uno/llms.txt (page index; append .md to any docs URL for plain Markdown)
• https://docs.y.uno/llms-full.txt
• https://docs.y.uno/openapi.json
• https://docs.y.uno/openapi.yaml
• https://docs.y.uno/setup-mcp
• https://docs.y.uno/auth.md
• https://docs.y.uno/docs/developers
• https://docs.y.uno/reference/getting-started/api-reference-overview
• https://docs.y.uno/reference/getting-started/authentication
• https://docs.y.uno/reference/reference-lists
• https://docs.y.uno/docs/glossary (Yuno terminology)
• https://docs.y.uno/sitemap.md (markdown sitemap of every page)

​

Conventions

• Keep private-secret-key on the server. Never embed it in client-side code, and never commit it to public repositories such as GitHub or Bitbucket. The public API key is the one used for client-side SDK initialization.
• Start in Sandbox (Test Mode) with sandbox keys. A new organization has access only to Test Mode; Live Mode requires an activation request and separate keys.
• Retry an unclear failure (timeout, connection error, 500) with the same X-Idempotency-Key. Use a new key only for a new order or a new attempt after a decline or IDEMPOTENCY_DUPLICATED.
• If metadata drives routing rules, set it on the checkout session, not only on the payment.
• Treat webhook deliveries as at-least-once: Yuno retries up to seven times, so dedupe on data.idempotency_key and verify the HMAC SHA256 signature before trusting a payload.
• After creating a payment through an SDK, check sdk_action_required and call continuePayment() when it is true.

​

Sitemap