Register a dry-run provider event - Yuno API Documentation

Dry-run is a pre-production validation surface. It receives the API calls your integration sends to a payment provider — request, response, and webhook payloads — and correlates them with the equivalent Yuno public-API call you make in parallel with the Dry-run: true header set. Yuno then executes an automated validation pipeline that grades the quality of the public-API request against the provider payload: missing fields, shape mismatches, wrong enum values, unmapped metadata, and any other inconsistency that would cause the real payment to fail or behave differently once you go live.

How the pair works

Your integration makes its normal call to the provider (e.g. Stripe, Adyen, dlocal).
Your integration also calls the relevant Yuno public-API endpoint (e.g. POST /v1/payments) with the header Dry-run: true. Yuno accepts the request, does not route it to any provider, and stores it for comparison.
Your integration calls POST /v1/dry-run/provider-events with the raw provider exchange (request, response, webhook) it just performed, correlated to the same merchant_reference.
Yuno pairs the two records by merchant_reference + account_id and runs the validation pipeline. Results are available through the dashboard and via GET /v1/dry-run/provider-events/{id} (read API, separate reference).

The outcome tells you whether the public-API request you are building today would produce the same provider behavior once Yuno starts routing it — without touching production money or sending a live transaction to the provider through Yuno.

When to use it

Pre-launch: certify your public-API integration against the provider behavior you already have working.
Provider migrations: verify a new provider accepts the fields Yuno forwards before switching traffic.
Regression checks: re-run dry-runs in CI to catch drift when your integration or the provider’s contract changes.

One call can carry up to 10 event entries (REQUEST, RESPONSE, and/or WEBHOOK), all tied to the same payment via merchant_reference. See the correlation rules.

This endpoint has a companion: POST /v1/payments accepts a Dry-run: true request header that tells Yuno to validate instead of routing. Both legs must share the same merchant_reference so validation can pair them.

Use X-Idempotency-Key for safe retries. Same key + same payload returns the original response; same key + different payload returns 409.

PCI boundaryheaders and body are sent base64-encoded. Yuno base64-decodes on ingest, applies deterministic PAN/CVV/auth-token redaction, and persists only the redacted form. See PCI Compliance.

Correlation

merchant_reference is always required and uniquely identifies the order on your side. Yuno uses it to resolve the event to a payment asynchronously when payment_id is not supplied.
payment_id, if supplied, is resolved immediately. If the id is unknown for your account the request returns 404 PAYMENT_NOT_FOUND.
provider_id + payment_method_type optionally identify which integration surface the dry-run exercises (e.g. stripe + CARD). if omitted, Yuno uses the information from the associated payment.

Headers

PUBLIC-API-KEY

string

Public API key. One of PUBLIC-API-KEY / PRIVATE-SECRET-KEY required.

PRIVATE-SECRET-KEY

string

Private secret key for server-to-server calls. One of PUBLIC-API-KEY / PRIVATE-SECRET-KEY required.

X-Idempotency-Key

string

Free-form string (MAX 64). 24-hour replay window.

Maximum string length: 64

Body

application/json

merchant_reference

string

required

Merchant-assigned identifier (MAX 255; MIN 3). Unique per account.

Required string length: 3 - 255

Example:

"ORD-12345"

events

object[]

required

1–10 HTTP exchange entries for this dry-run (MAX 10; MIN 1).

Required array length: 1 - 10 elements

Show child attributes

Example:

[
  {
    "type": "REQUEST",
    "http_method": "POST",
    "operation_type": "PURCHASE",
    "base_url": "https://api.stripe.com",
    "endpoint": "/v1/charges",
    "headers": "eyBDb250ZW50LVR5cGU6IGFwcGxpY2F0aW9uL2pzb24gfQ==",
    "body": "eyBhbW91bnQ6IDIwMDAsIGN1cnJlbmN5OiAidXNkIiB9"
  }
]

payment_id

string<uuid>

Yuno payment UUID. If supplied, resolved immediately.

Example:

"fb9e5fa4-684c-4747-9755-9d332617f16f"

account_id

string<uuid>

Yuno account UUID — same shape as account_id in POST /v1/payments.

Example:

"a389f417-ecd1-4355-89f5-7489564f264d"

provider_id

enum<string>

Provider identifier. Allowed values aligned to the Yuno catalog.

Available options:

STRIPE,

ADYEN,

CYBERSOURCE,

BRAINTREE,

NMI,

CHECKOUT,

WORLDPAY,

PAYPAL,

EBANX,

GLOBALPAYMENTS,

NUVEI,

CIELO,

MPGS,

PRISMA,

FISERV,

WORLDLINE,

ANTOM,

ORBITAL,

GOCARDLESS,

AUTHORIZE_NET,

SONY,

CITI,

EPX,

HPAY,

PAYSTACK,

PLAID,

SAFERPAY,

SIKA_HEALTH,

VALIDIFI,

WEPAY,

CARD_CONNECT,

GMO_PG,

MONERIS,

BLUESNAP,

QUICK_GATEWAY,

TWENTYFOUR_HOUR_FITNESS,

MERCHANT_ESOLUTIONS,

NETS,

FAT_ZEBRA,

WINDCAVE,

CHASE_MOBILITY,

HELIX,

ANB,

AMAZON_PAY,

OPAYO,

IP_PAYMENTS,

KLARNA,

BILLDESK,

WELLS_FARGO,

SAGEPAY,

PLANET

Example:

"STRIPE"

payment_method_type

enum<string>

Payment method exercised by this dry-run. Same vocabulary as payment_method.type in POST /v1/payments.

Available options:

CARD,

APPLE_PAY,

GOOGLE_PAY,

PIX,

PSE,

OXXO,

BOLETO,

WALLET,

BANK_TRANSFER,

CRYPTO,

CASH

Example:

"CARD"

Response

Dry-run registered

string

required

Public identifier of the dry-run registration (nano_id, 21 chars).

Example:

"drun_1209fnkw428ufwd"

status

enum<string>

required

Lifecycle state.

Available options:

REGISTERED

Example:

"REGISTERED"

merchant_reference

string

required

Example:

"ORD-12345"

payment_id

string<uuid> | null

Example:

"fb9e5fa4-684c-4747-9755-9d332617f16f"

account_id

string<uuid> | null

Example:

"a389f417-ecd1-4355-89f5-7489564f264d"

provider_id

string

Example:

"STRIPE"

payment_method_type

string

Example:

"CARD"

operation_type

string

Example:

"PURCHASE"

Documentation Index

​How the pair works

​When to use it

​Correlation

Headers

Body

Response

How the pair works

When to use it

Correlation