Skip to main content
POST
/
dry-run
/
provider-events
Register provider request / response / webhook payloads
curl --request POST \
  --url https://api-sandbox.y.uno/v1/dry-run/provider-events \
  --header 'Content-Type: application/json' \
  --data '
{
  "merchant_reference": "ORD-12345",
  "events": [
    {
      "type": "REQUEST",
      "http_method": "POST",
      "operation_type": "PURCHASE",
      "base_url": "https://api.stripe.com",
      "endpoint": "/v1/charges",
      "headers": "eyBDb250ZW50LVR5cGU6IGFwcGxpY2F0aW9uL2pzb24gfQ==",
      "body": "eyBhbW91bnQ6IDIwMDAsIGN1cnJlbmN5OiAidXNkIiB9"
    }
  ],
  "payment_id": "fb9e5fa4-684c-4747-9755-9d332617f16f",
  "account_id": "a389f417-ecd1-4355-89f5-7489564f264d",
  "provider_id": "STRIPE",
  "payment_method_type": "CREDIT_CARD"
}
'
{
  "id": "drun_1209fnkw428ufwd",
  "status": "REGISTERED",
  "merchant_reference": "ORD-12345",
  "payment_id": "fb9e5fa4-684c-4747-9755-9d332617f16f",
  "account_id": "a389f417-ecd1-4355-89f5-7489564f264d",
  "provider_id": "STRIPE",
  "payment_method_type": "CARD",
  "operation_type": "PURCHASE"
}

Documentation Index

Fetch the complete documentation index at: https://docs.y.uno/llms.txt

Use this file to discover all available pages before exploring further.

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

  1. Your integration makes its normal call to the provider (e.g. Stripe, Adyen, dlocal).
  2. 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.
  3. 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.
  4. 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 + CREDIT_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
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,
CREDIT_CARD,
CREDIT_CARD_REFERENCE_TRANSACTION,
DEBIT_CARD,
EPX_TOKEN,
TEST_CREDIT_CARD,
UPC_TOKEN_TRANSACTION,
APPLE_PAY,
GOOGLE_PAY,
PIX,
PSE,
OXXO,
BOLETO,
ALI_PAY,
AMAZON_PAY,
GCASH,
IDEAL,
KAKAO_PAY,
KLARNA,
MOMO_PAY,
NAVER_PAY,
OVO,
PAYPAL,
PAYPAL_CREDIT,
PAYPAY,
PAZE,
TOSS_PAY,
UPI,
VENMO,
ACH,
BANK_TRANSFER,
CRYPTO,
CASH
Example:

"CREDIT_CARD"

Response

Dry-run registered

​
id
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
enum<string>
Available options:
,
CARD,
CREDIT_CARD,
CREDIT_CARD_REFERENCE_TRANSACTION,
DEBIT_CARD,
EPX_TOKEN,
TEST_CREDIT_CARD,
UPC_TOKEN_TRANSACTION,
APPLE_PAY,
GOOGLE_PAY,
PIX,
PSE,
OXXO,
BOLETO,
ALI_PAY,
AMAZON_PAY,
GCASH,
IDEAL,
KAKAO_PAY,
KLARNA,
MOMO_PAY,
NAVER_PAY,
OVO,
PAYPAL,
PAYPAL_CREDIT,
PAYPAY,
PAZE,
TOSS_PAY,
UPI,
VENMO,
ACH,
BANK_TRANSFER,
CRYPTO,
CASH
Example:

"CARD"

​
operation_type
string
Example:

"PURCHASE"