# Transaction Ingestion

Transaction ingestion submits issuer card authorization events and settled transaction events for reward processing.

| Endpoint | Purpose |
|  --- | --- |
| `POST /api/v1/incoming-auth` | Submit card authorization events. |
| `POST /api/v1/incoming-txn` | Submit settled transaction events. |


These endpoints accept either one object or an array of objects. A fully accepted request returns `204`. If some events fail and some are accepted, the response is `200` with an array of failures. If every submitted event fails, the response is `400` with an array of failures.

## Required Fields

Card authorization event ingestion requires a stable issuer `id`, `amount`, `currency`, `merchantDescriptor`, `mcc`, `createdAt`, `cardLast4`, `network`, `cardholderId`, `cardId`, `authMethod`, and `state`.

Settled transaction event ingestion requires the same base fields plus settled-transaction-specific fields in the OpenAPI schema, including `arn` where available and related card authorization event data when provided by the issuer processor.

## Sandbox Matching

The transaction `merchantId` field represents the merchant identifier from the ISO 8583 transaction message. In production, treat it as merchant data supplied by the issuer or processor.

Sandbox does not perform intelligent brand matching for the MVP. In sandbox only, Percents overloads `merchantId` as a forced-match input: set it to the Percents `mp_` merchant partner id you want the transaction event to match. This field is not related to API authentication.

```json
{
  "id": "issuer-auth-0001",
  "amount": 12500,
  "currency": "usd",
  "merchantDescriptor": "Sandbox Coffee",
  "mcc": "5814",
  "createdAt": "2026-07-01T18:42:00.000Z",
  "cardLast4": "4242",
  "network": "visa",
  "cardholderId": "issuer-cardholder-1",
  "cardId": "issuer-card-1",
  "authMethod": "online",
  "state": "approved",
  "merchantId": "mp_33333333-3333-4333-8333-333333333333"
}
```

## Processing Semantics

Card authorization events can create preview reward effects and a `qualified_auth` webhook when the event qualifies. Settlements post final effects and can create a `qualified_settlement` webhook. Work with the Percents account manager to validate refund flows.

Use the transaction reward detail endpoints to reconcile a specific transaction after processing:

- `GET /api/v2/chg/{chgId}/transaction/{txnId}/reward-detail`
- `POST /api/v2/chg/{chgId}/transactions/reward-overviews`