Report Off-Yuno Transactions - Yuno API Documentation

POST

reporting

transactions

curl --request POST \
  --url https://api-sandbox.y.uno/v1/reporting/transactions \
  --header 'Content-Type: application/json' \
  --data '
{
  "account_id": "3f2a1b6c-8d4e-4f5a-9b0c-1d2e3f4a5b6c",
  "events": [
    {
      "report_id": "merchant-rpt-000123",
      "merchant_order_id": "order_45678",
      "country": "US",
      "payment_method_type": "CARD",
      "result": "SUCCEEDED",
      "amount": {
        "currency": "USD",
        "value": 99
      },
      "provider_id": "ADYEN"
    }
  ]
}
'

{
  "accepted": 2,
  "duplicates": 1,
  "rejected": [
    {
      "report_id": "merchant-rpt-000124",
      "code": "INVALID_EVENT",
      "messages": [
        "The field 'event_type' must be one of: PURCHASE, AUTHORIZE, VERIFY."
      ]
    }
  ]
}

{
  "code": "INVALID_REQUEST",
  "messages": [
    "The field 'events' must contain between 1 and 500 events."
  ]
}

{
  "code": "NOT_AUTHENTICATED",
  "messages": [
    "Missing or invalid PUBLIC-API-KEY / PRIVATE-SECRET-KEY headers."
  ]
}

{
  "code": "PRODUCT_NOT_ENABLED",
  "messages": [
    "The Transaction Reporting API is enabled per organization. Contact your Key Account Manager (KAM) to activate it."
  ]
}

This endpoint gives Yuno visibility over the traffic you process directly with your providers, outside Yuno’s transaction path. Each accepted event is persisted as a regular Yuno payment, differentiated by the origin field:

origin: YUNO — payments processed by Yuno (every existing payment).
origin: REPORTED — payments that entered through this API.

Reported payments appear in the dashboard, in GET /v1/payments, and in analytics — filtered by origin — but Yuno never processes them: no routing, no provider calls, no retries, and no money movement. The money already moved at your provider; Yuno records the fact.

Enabled per organizationThis API requires activation for your organization. Contact your Key Account Manager (KAM) to enable it.

How it works

You process a transaction directly with your provider (for example a purchase on your own Adyen account).
You report it here: one event or a batch of up to 500. For latency-sensitive integrations, batches of up to 100 events are recommended. The full 500-event batch is processed synchronously and can take several seconds.
Each accepted event creates one payment with one transaction, with the status derived from result and the event type:
- A PURCHASE with result SUCCEEDED lands the payment SUCCEEDED.
- An AUTHORIZE with result SUCCEEDED lands PENDING with sub-status AUTHORIZED. An approved authorization is not captured money; it mirrors how Yuno-processed authorizations behave.
- A VERIFY with result SUCCEEDED lands SUCCEEDED with sub-status VERIFIED. The verification completed and no money moves; it mirrors how Yuno-processed verifications persist.
- DECLINED lands DECLINED, and ERROR lands ERROR.

In this version the supported operations are PURCHASE (default), AUTHORIZE, and VERIFY. A VERIFY reports a card verification (zero-dollar authorization), typically reported with amount.value: 0. Lifecycle events (captures, refunds, chargebacks) are on the roadmap.

Retries and deduplication

There is no idempotency header on this endpoint, and none is needed. The report_id you generate per event is the deduplication key. An event whose report_id was already ingested is counted in duplicates and never ingested twice, no matter when or in which batch it arrives. Retrying a whole batch after a network failure is always safe. Because report_id alone decides, an event that reuses an already-ingested report_id with a different payload is also counted as a duplicate and silently discarded — never reuse a report_id across different transactions. The batch is processed per event: one invalid event lands in rejected[] with its reason, and the rest of the batch is unaffected.

Card BIN for BIN-level routing statistics

On CARD events you can send the card’s BIN in payment_method_details.card.bin — the first 6 or 8 digits of the card number, exactly. The BIN is not cardholder data: it identifies the issuer and card range, never the card. When present, Yuno stores it on the reported payment (payment_method.detail.card.card_data.iin on the transaction) and uses it to segment your statistics per BIN in the Routing Recommendations API, so a payment on the same BIN can be ranked on that BIN’s own history instead of the country-wide one.

payment_method_details is keyed by the payment method type — today only card, and only on events whose payment_method_type is CARD. A card.bin on an event of any other type, or a container with any other key, rejects the event.
The BIN must be exactly 6 or 8 digits. A 7-digit value, a longer value, or anything that is not all digits rejects the event with INVALID_EVENT.
Omitting payment_method_details, or sending it empty ({} or {"card": {}}), keeps the event exactly as before: no BIN is stored and the event feeds the country and payment-method statistics only.

The raw provider response

If you include raw_provider_response (the provider’s response payload, verbatim, up to 64 KB), Yuno stores it with defensive card-data redaction applied — primary account numbers and security codes are removed before anything is persisted. It is never returned by any API. Sending it is recommended: it lets Yuno enrich the reported payment later (network transaction references, decline reasons) without asking you for anything new.

Never send card data in the event fields. Reported events carry references and outcomes, not cardholder data. The BIN in payment_method_details.card.bin is the only card-derived value accepted, and it is not a card number. The only place a card number may transit is inside raw_provider_response, where it is redacted on ingestion.

Operations on reported payments

Reported payments cannot be operated through Yuno — a refund or capture request on a payment with origin: REPORTED returns 403 OPERATION_NOT_ALLOWED_FOR_REPORTED_PAYMENT. Perform the operation at your provider and report it as a new event when lifecycle events become available.

Errors

Errors return a code and a messages array.

HTTP	`code`	When
400	`INVALID_REQUEST`	Malformed body, missing required field, or a batch over 500 events.
400	`INVALID_ACCOUNT_ID`	The `account_id` does not exist or does not belong to your organization.
401	`NOT_AUTHENTICATED` / `INVALID_CREDENTIALS`	Missing or invalid `PUBLIC-API-KEY` / `PRIVATE-SECRET-KEY` headers.
403	`PRODUCT_NOT_ENABLED`	”The Transaction Reporting API is enabled per organization. Contact your Key Account Manager (KAM) to activate it.”

Per-event rejections: `INVALID_EVENT`

INVALID_EVENT is not an HTTP error — the batch itself is accepted (202), and each invalid event is returned individually inside rejected[] with this code and its reason, while the rest of the batch is ingested normally:

{
  "accepted": 2,
  "duplicates": 0,
  "rejected": [
    { "report_id": "merchant-rpt-000124", "code": "INVALID_EVENT", "messages": ["The field 'event_type' must be one of: PURCHASE, AUTHORIZE, VERIFY."] }
  ]
}

Causes: invalid enum value, wrong field type, unknown field, a payment_method_details.card.bin that is not exactly 6 or 8 digits (or sent on a non-CARD event), or raw_provider_response over 64 KB.

Headers

PUBLIC-API-KEY

string

Your public API key.

PRIVATE-SECRET-KEY

string

Your private secret key. Never expose it client-side.

Body

application/json

account_id

string<uuid>

required

UUID of the Yuno account the reported payments belong to.

events

object[]

required

One event or a batch of up to 500. Events are processed per item: one invalid event never rejects the batch.

Required array length: 1 - 500 elements

Show child attributes

Response

Batch accepted and processed per event.

accepted

integer

Events ingested as payments.

duplicates

integer

Events skipped because their report_id was already ingested.

rejected

object[]

Events that failed validation, each with its reason. The rest of the batch is unaffected.

Show child attributes

curl --request POST \
  --url https://api-sandbox.y.uno/v1/reporting/transactions \
  --header 'Content-Type: application/json' \
  --data '
{
  "account_id": "3f2a1b6c-8d4e-4f5a-9b0c-1d2e3f4a5b6c",
  "events": [
    {
      "report_id": "merchant-rpt-000123",
      "merchant_order_id": "order_45678",
      "country": "US",
      "payment_method_type": "CARD",
      "result": "SUCCEEDED",
      "amount": {
        "currency": "USD",
        "value": 99
      },
      "provider_id": "ADYEN"
    }
  ]
}
'

{
  "accepted": 2,
  "duplicates": 1,
  "rejected": [
    {
      "report_id": "merchant-rpt-000124",
      "code": "INVALID_EVENT",
      "messages": [
        "The field 'event_type' must be one of: PURCHASE, AUTHORIZE, VERIFY."
      ]
    }
  ]
}

{
  "code": "INVALID_REQUEST",
  "messages": [
    "The field 'events' must contain between 1 and 500 events."
  ]
}

{
  "code": "NOT_AUTHENTICATED",
  "messages": [
    "Missing or invalid PUBLIC-API-KEY / PRIVATE-SECRET-KEY headers."
  ]
}

{
  "code": "PRODUCT_NOT_ENABLED",
  "messages": [
    "The Transaction Reporting API is enabled per organization. Contact your Key Account Manager (KAM) to activate it."
  ]
}

​How it works

​Retries and deduplication

​Card BIN for BIN-level routing statistics

​The raw provider response

​Operations on reported payments

​Errors

​Per-event rejections: INVALID_EVENT

Headers

Body

Response

How it works

Retries and deduplication

Card BIN for BIN-level routing statistics

The raw provider response

Operations on reported payments

Errors

Per-event rejections: `INVALID_EVENT`