Quickstart: your first sandbox payment

Getting startedTutorial · about 10 minutes

Yuno is the AI operating system for payments, and a payment is the first thing you run on it. You send your first sandbox payment in about 10 minutes once you have sandbox credentials.

Create a connectionSend one payment with a test cardSee it in the dashboard

Before you start

You need these facts for every call on this page.

Fact	Value
Account code	`account_id` in the dashboard, under Developers
Keys	`public-api-key` and `private-secret-key`, both starting with `sandbox_`
Base URL	`https://api-sandbox.y.uno/v1` (keep the `/v1`)
Amounts	`amount.value` is a number next to a `currency`. This page sends `25` with `USD`
Tools	Node 18 or later, or `curl`

Get your sandbox credentials

Account code, shown as account_id in the dashboard
public-api-key
private-secret-key

Sandbox keys start with sandbox_. Production keys are different and start with prod_.

If you do not have an account yet, ask your Yuno contact or write to sales@y.uno. There is no self-serve signup today.Set your credentials as environment variables:

Shell

export YUNO_PUBLIC_API_KEY="sandbox_..."
export YUNO_PRIVATE_SECRET_KEY="sandbox_..."
export YUNO_ACCOUNT_ID="your-account-code"

Prove the keys by creating a customer. The base URL is https://api-sandbox.y.uno/v1.

curl --request POST \
  --url https://api-sandbox.y.uno/v1/customers \
  --header "public-api-key: $YUNO_PUBLIC_API_KEY" \
  --header "private-secret-key: $YUNO_PRIVATE_SECRET_KEY" \
  --header "content-type: application/json" \
  --data '{
    "merchant_customer_id": "customer-0001",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com"
  }'

const res = await fetch("https://api-sandbox.y.uno/v1/customers", {
  method: "POST",
  headers: {
    "public-api-key": process.env.YUNO_PUBLIC_API_KEY,
    "private-secret-key": process.env.YUNO_PRIVATE_SECRET_KEY,
    "content-type": "application/json",
  },
  body: JSON.stringify({
    merchant_customer_id: "customer-0001",
    first_name: "John",
    last_name: "Doe",
    email: "john.doe@example.com",
  }),
});
const customer = await res.json();
console.log(customer.id);

import os
import requests

res = requests.post(
    "https://api-sandbox.y.uno/v1/customers",
    headers={
        "public-api-key": os.environ["YUNO_PUBLIC_API_KEY"],
        "private-secret-key": os.environ["YUNO_PRIVATE_SECRET_KEY"],
    },
    json={
        "merchant_customer_id": "customer-0001",
        "first_name": "John",
        "last_name": "Doe",
        "email": "john.doe@example.com",
    },
)
print(res.json()["id"])

The response includes an id. Save it as YUNO_CUSTOMER_ID, the payment steps use it.

Gate passed when POST /v1/customers answers 201.

401 means the key pair is wrong. Copy both sandbox keys again from Developers.
404 with an empty body means /v1 is missing from the base URL.

Connect the Yuno Test Payment Gateway and publish a route

The Yuno Test Payment Gateway simulates a card provider. It works in sandbox only and needs no credentials.

Open Connections, search for Yuno Test Payment Gateway, click Connect, name the connection, and click Save.
Open Routing, open the Not published tab, find Card, and click Set Up.
Click + Create new route, name it, and click Save.
Click the arrow, choose Add step, select Yuno Test Payment Gateway, and click Publish.
Open Checkout builder, turn on Card, and publish the settings.

Gate passed when a new checkout session lists CARD. Create a session as in step 4 and save its checkout_session as YUNO_CHECKOUT_SESSION. Then call GET /v1/checkout/sessions/{checkout_session}/payment-methods and look for "type": "CARD" in the list.If CARD is missing, check the three settings: the Test Payment Gateway is connected, the Card route is under Published, and Card is on in the Checkout builder.

Choose how the payment is created

The workflow field tells Yuno who creates the payment. Pick one, then use the matching tab in step 4.

Workflow	Who creates the payment	Use it when
`SDK_SEAMLESS`	The SDK creates the payment	You want the fewest moving parts. Recommended
`SDK_CHECKOUT` plus a `createPayment` callback	Your backend creates it, from the one-time token the SDK hands you	You add order data, fraud checks or idempotency on your server
`DIRECT`	Your backend sends the raw card data	You have PCI DSS scope. Otherwise use it for sandbox tests only

A session and an integration that disagree end in INTERNAL_ERROR. See Get started with the Yuno SDK and Direct flow for each path in full.

Gate passed when you can name the workflow you will send: SDK_SEAMLESS, SDK_CHECKOUT or DIRECT. The checkout session (SDK paths) or the payment (DIRECT) carries it in the workflow field.

Send the payment

DIRECT
SDK_SEAMLESS
SDK_CHECKOUT

Sending raw card numbers from your server is for sandbox testing. In production it requires PCI DSS scope. Otherwise use the Yuno SDK or Secure Fields to collect card data.

The DIRECT workflow is a back-to-back payment where your server sends the card data. Use the customer id you saved as YUNO_CUSTOMER_ID in step 1.Create the payment with a test card. Send a new X-Idempotency-Key with each payment.

curl --request POST \
  --url https://api-sandbox.y.uno/v1/payments \
  --header "public-api-key: $YUNO_PUBLIC_API_KEY" \
  --header "private-secret-key: $YUNO_PRIVATE_SECRET_KEY" \
  --header "X-Idempotency-Key: $(uuidgen)" \
  --header "content-type: application/json" \
  --data '{
    "account_id": "'"$YUNO_ACCOUNT_ID"'",
    "merchant_order_id": "order-0001",
    "description": "First test payment",
    "country": "US",
    "amount": { "currency": "USD", "value": 25 },
    "workflow": "DIRECT",
    "customer_payer": { "id": "'"$YUNO_CUSTOMER_ID"'" },
    "payment_method": {
      "type": "CARD",
      "detail": { "card": { "card_data": {
        "number": "4507990000000002",
        "expiration_month": 11,
        "expiration_year": 28,
        "security_code": "123",
        "holder_name": "John Doe"
      } } }
    }
  }'

const res = await fetch("https://api-sandbox.y.uno/v1/payments", {
  method: "POST",
  headers: {
    "public-api-key": process.env.YUNO_PUBLIC_API_KEY,
    "private-secret-key": process.env.YUNO_PRIVATE_SECRET_KEY,
    "X-Idempotency-Key": crypto.randomUUID(),
    "content-type": "application/json",
  },
  body: JSON.stringify({
    account_id: process.env.YUNO_ACCOUNT_ID,
    merchant_order_id: "order-0001",
    description: "First test payment",
    country: "US",
    amount: { currency: "USD", value: 25 },
    workflow: "DIRECT",
    customer_payer: { id: process.env.YUNO_CUSTOMER_ID },
    payment_method: {
      type: "CARD",
      detail: { card: { card_data: {
        number: "4507990000000002",
        expiration_month: 11,
        expiration_year: 28,
        security_code: "123",
        holder_name: "John Doe",
      } } },
    },
  }),
});
const payment = await res.json();
console.log(payment.status, payment.sub_status);

import os
import uuid
import requests

res = requests.post(
    "https://api-sandbox.y.uno/v1/payments",
    headers={
        "public-api-key": os.environ["YUNO_PUBLIC_API_KEY"],
        "private-secret-key": os.environ["YUNO_PRIVATE_SECRET_KEY"],
        "X-Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "account_id": os.environ["YUNO_ACCOUNT_ID"],
        "merchant_order_id": "order-0001",
        "description": "First test payment",
        "country": "US",
        "amount": {"currency": "USD", "value": 25},
        "workflow": "DIRECT",
        "customer_payer": {"id": os.environ["YUNO_CUSTOMER_ID"]},
        "payment_method": {
            "type": "CARD",
            "detail": {"card": {"card_data": {
                "number": "4507990000000002",
                "expiration_month": 11,
                "expiration_year": 28,
                "security_code": "123",
                "holder_name": "John Doe",
            }}},
        },
    },
)
payment = res.json()
print(payment["status"], payment["sub_status"])

The payment succeeds when the response looks like this:

Response (trimmed)

{
  "id": "6c44ed29-cc51-4479-a5eb-108afdaadd50",
  "status": "SUCCEEDED",
  "sub_status": "APPROVED",
  "amount": { "currency": "USD", "value": 25 }
}

The SDK_SEAMLESS tab splits the work. Your server creates a checkout session, and the browser loads the SDK and starts the transaction.On your server, create the checkout session. Use workflow: "SDK_SEAMLESS" so the SDK creates the payment for you. Without it the transaction ends in INTERNAL_ERROR.

curl --request POST \
  --url https://api-sandbox.y.uno/v1/checkout/sessions \
  --header "public-api-key: $YUNO_PUBLIC_API_KEY" \
  --header "private-secret-key: $YUNO_PRIVATE_SECRET_KEY" \
  --header "content-type: application/json" \
  --data '{
    "account_id": "'"$YUNO_ACCOUNT_ID"'",
    "merchant_order_id": "order-0001",
    "payment_description": "First test payment",
    "country": "US",
    "amount": { "currency": "USD", "value": 25 },
    "workflow": "SDK_SEAMLESS"
  }'

const res = await fetch("https://api-sandbox.y.uno/v1/checkout/sessions", {
  method: "POST",
  headers: {
    "public-api-key": process.env.YUNO_PUBLIC_API_KEY,
    "private-secret-key": process.env.YUNO_PRIVATE_SECRET_KEY,
    "content-type": "application/json",
  },
  body: JSON.stringify({
    account_id: process.env.YUNO_ACCOUNT_ID,
    merchant_order_id: "order-0001",
    payment_description: "First test payment",
    country: "US",
    amount: { currency: "USD", value: 25 },
    workflow: "SDK_SEAMLESS",
  }),
});
const session = await res.json();
console.log(session.checkout_session);

import os
import requests

res = requests.post(
    "https://api-sandbox.y.uno/v1/checkout/sessions",
    headers={
        "public-api-key": os.environ["YUNO_PUBLIC_API_KEY"],
        "private-secret-key": os.environ["YUNO_PRIVATE_SECRET_KEY"],
    },
    json={
        "account_id": os.environ["YUNO_ACCOUNT_ID"],
        "merchant_order_id": "order-0001",
        "payment_description": "First test payment",
        "country": "US",
        "amount": {"currency": "USD", "value": 25},
        "workflow": "SDK_SEAMLESS",
    },
)
print(res.json()["checkout_session"])

In the browser, load the SDK from the CDN, then start a transaction with the checkout_session value from your server.

Browser

<div id="payment-form"></div>
<script src="https://sdk-web.y.uno/v2.1.2/main.js"></script>
<script>
  async function startYuno() {
    const sdkPayments = await SdkPayments.initialize("your-public-api-key");
    const transaction = sdkPayments.transaction({
      checkoutSession: "checkout-session-from-your-server",
      countryCode: "US",
      elementSelector: "#payment-form",
      onStatus: (result) => console.log("Final status:", result.status),
    });
    await transaction.start({ paymentMethod: { type: "CARD" } });
  }

  if (window.SdkPayments) {
    startYuno();
  } else {
    window.addEventListener("sdk-payments-ready", startYuno);
  }
</script>

The form renders in #payment-form. Enter the test card 4507 9900 0000 0002, expiry 11/28, CVV 123, name John Doe, then click Pay. The result arrives in onStatus with the status SUCCEEDED.For iOS, Android, and every option, see the SDK Get started.

Your server creates the checkout session with workflow: "SDK_CHECKOUT". The browser starts the transaction and passes a createPayment callback. The SDK hands the callback a one-time token, and your backend creates the payment from it.On your server, create the checkout session with the customer from step 1:

cURL

curl --request POST \
  --url https://api-sandbox.y.uno/v1/checkout/sessions \
  --header "public-api-key: $YUNO_PUBLIC_API_KEY" \
  --header "private-secret-key: $YUNO_PRIVATE_SECRET_KEY" \
  --header "content-type: application/json" \
  --data '{
    "account_id": "'"$YUNO_ACCOUNT_ID"'",
    "merchant_order_id": "order-0001",
    "payment_description": "First test payment",
    "country": "US",
    "customer_id": "'"$YUNO_CUSTOMER_ID"'",
    "amount": { "currency": "USD", "value": 25 },
    "workflow": "SDK_CHECKOUT"
  }'

In the browser, start the transaction and override createPayment. Send token.token and token.checkout_session to your backend:

Browser

<div id="payment-form"></div>
<script src="https://sdk-web.y.uno/v2.1.2/main.js"></script>
<script>
  async function startYuno() {
    const sdkPayments = await SdkPayments.initialize("your-public-api-key");
    const transaction = sdkPayments.transaction({
      checkoutSession: "checkout-session-from-your-server",
      countryCode: "US",
      elementSelector: "#payment-form",
      createPayment: async (token) => {
        await fetch("/api/pay", {
          method: "POST",
          headers: { "content-type": "application/json" },
          body: JSON.stringify({
            token: token.token,
            checkout_session: token.checkout_session,
          }),
        });
      },
      onStatus: (result) => console.log("Final status:", result.status),
    });
    await transaction.start({ paymentMethod: { type: "CARD" } });
  }

  if (window.SdkPayments) {
    startYuno();
  } else {
    window.addEventListener("sdk-payments-ready", startYuno);
  }
</script>

Settle the promise on every path, including a network failure, or the transaction stays in progress. See createPayment.On your server again, your /api/pay handler creates the payment with POST /v1/payments. Send the token in payment_method.token and the session in checkout.session:

Node.js

// token and checkoutSession come from the browser request body
async function createPayment({ token, checkoutSession }) {
  const res = await fetch("https://api-sandbox.y.uno/v1/payments", {
    method: "POST",
    headers: {
      "public-api-key": process.env.YUNO_PUBLIC_API_KEY,
      "private-secret-key": process.env.YUNO_PRIVATE_SECRET_KEY,
      "X-Idempotency-Key": crypto.randomUUID(),
      "content-type": "application/json",
    },
    body: JSON.stringify({
      account_id: process.env.YUNO_ACCOUNT_ID,
      merchant_order_id: "order-0001",
      description: "First test payment",
      country: "US",
      amount: { currency: "USD", value: 25 },
      customer_payer: { id: process.env.YUNO_CUSTOMER_ID },
      payment_method: { token },
      checkout: { session: checkoutSession },
    }),
  });
  return res.json();
}

Enter the test card 4507 9900 0000 0002, expiry 11/28, CVV 123, name John Doe, then click Pay. The response has the same shape as the DIRECT response above.

Gate passed when the payment status is SUCCEEDED with the test card 4507 9900 0000 0002 (11/28, CVV 123, John Doe).

See the result

Check status and sub_status in the response. SUCCEEDED with APPROVED means the gateway approved the payment.
Open Payments in the dashboard, find your payment, and open it to see its details.
To receive the result on your server, configure a webhook and verify its signature (HMAC).

Payment statuses are listed in Payment statuses.

Gate passed when the payment shows as SUCCEEDED in the dashboard Payments list and in the status field of your response.

Go live

GuideLive keys, a published route, verified webhooks and a first real payment.

Troubleshooting

The API returns 401

The public-api-key or private-secret-key header is missing or wrong. Sandbox and production use different keys, so check that you copied the sandbox keys from the dashboard in Test Mode. See Authentication.

The payment ends in INTERNAL_ERROR

The workflow does not match your integration. Use DIRECT when your server sends the card, and SDK_SEAMLESS on the checkout session when the Web SDK creates the payment.

No provider processes the payment

Card has no published route. Open Routing and check that the Card route with the Yuno Test Payment Gateway is under the Published tab, and that Card is turned on in the Checkout builder.

The card is declined

Test cards are specific to a provider. The cards in this Quickstart only work when your sandbox routes Card to the Yuno Test Payment Gateway. Other results are listed on the Yuno Test Payment Gateway page.

Stuck on a term? See the Glossary. For URLs, keys, and specs see Developers.

Getting Started

Quickstart: your first sandbox payment

Before you start

Get your sandbox credentials

Connect the Yuno Test Payment Gateway and publish a route

Choose how the payment is created

Send the payment

See the result

Next

Go live

Troubleshooting

​Before you start

Get your sandbox credentials

Connect the Yuno Test Payment Gateway and publish a route

Choose how the payment is created

Send the payment

See the result

​Next

Go live

​Troubleshooting

Before you start

Next

Troubleshooting