Direct API Integration

Server-to-server integration for full control over the payment flow

Overview

Direct API integration gives you complete control over the payment lifecycle through server-to-server REST API calls. This approach is ideal for backend-driven systems, recurring payments, or scenarios where you manage your own checkout UI.

Direct API integration for card payments requires PCI DSS Level 1 certification because your servers handle raw card data. If you are not PCI Level 1 certified, use one of the SDK integrations instead.

New to Yuno? Follow this progression:

1. Create your first payment. Start with a simple card payment
2. Handle captures and cancels. Learn two-step authorization flows
3. Process refunds. Handle returns and partial refunds
4. Add local payment methods. Expand to PIX, SEPA, iDEAL, and more
5. Optimize with routing. Maximize approval rates across providers

Payment Flow

The Direct API payment flow consists of three steps:

1. Create a checkout session

   Every payment starts with a checkout session that groups the transaction context:

   curl -X POST https://api-sandbox.y.uno/v1/checkout/sessions \
     -H "public-api-key: YOUR_PUBLIC_KEY" \
     -H "private-secret-key: YOUR_PRIVATE_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "amount": { "currency": "USD", "value": 100.00 },
       "country": "CO",
       "merchant_order_id": "order-789"
     }'
   

   The response includes a checkout_session ID used in subsequent API calls.

2. Tokenize payment data

   For card payments, create a one-time token with the raw card data:

   curl -X POST https://api-sandbox.y.uno/v1/payment-methods/tokens \
     -H "public-api-key: YOUR_PUBLIC_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "card": {
         "number": "4111111111111111",
         "expiration_month": "12",
         "expiration_year": "2028",
         "cvv": "123",
         "holder_name": "Dee Hock"
       }
     }'
   

   For alternative payment methods (PIX, bank transfers), tokenization is not required.

3. Create the payment

   Submit the payment with the token and customer details:

   curl -X POST https://api-sandbox.y.uno/v1/payments \
     -H "public-api-key: YOUR_PUBLIC_KEY" \
     -H "private-secret-key: YOUR_PRIVATE_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "checkout_session": "session-id",
       "payment_method": { "type": "CARD", "token": "one-time-token" },
       "amount": { "currency": "USD", "value": 100.00 },
       "country": "CO"
     }'
   

   See Create a Payment for complete examples.

4. Handle the result

   The payment response contains a status field:

   Status	Meaning	Action
   SUCCEEDED	Payment approved	Fulfill the order
   PENDING	Awaiting async confirmation	Wait for webhook
   DECLINED	Payment declined	Show error, allow retry
   REQUIRES_ACTION	3DS or redirect needed	Redirect the customer

Authentication

All API requests require two authentication headers:

Header	Description
public-api-key	Your public API key.
private-secret-key	Your private secret key. Server side only.

The account_id value from the Dashboard is not an HTTP header. Place it inside the account_id field of request bodies on endpoints like POST /v1/checkout/sessions and POST /v1/payments.

Never expose your private-secret-key in client-side code or version control. Use environment variables.

Base URLs

Environment	Base URL
Sandbox	https://api-sandbox.y.uno
Production	https://api.y.uno

Next Steps

Create a Payment

Detailed payment creation with method-specific examples.

Capture & Cancel

Two-step authorization flows.

Refunds

Process full and partial refunds.

Webhooks

Receive real-time payment notifications.