Conversions

A conversion is the ledger record that connects an agent recommendation to a merchant outcome. Conversions are not created by the agent. They are created when Rako can reconcile the recommendation with payment, merchant, or milestone evidence.

Rako’s hosted payment-verification path is still being hardened. Public docs use “verified” to describe the intended conversion state after authenticated payment events and reconciliation checks pass. Until webhook authentication, AAP Code verification on webhook receipt, payload matching, amount matching, and payment-status checks are deployed and tested, treat payment-observed conversions as beta evidence rather than a trustless production guarantee.

Conversion sources

Source	Typical path	Verification level
Payment webhook	Merchant payment processor confirms a successful payment and returns AAP metadata.	Verified checkout conversion only after authentication and reconciliation checks pass.
Merchant conversion report	Merchant reports `sessionId`, `orderReference`, and transaction value.	Pending validation.
Milestone update	Merchant reports progress after an initial conversion, such as install or activation.	Depends on configured flow.
Refund or dispute webhook	Merchant payment processor reports refund, chargeback, or dispute lifecycle events.	Used for clawback/reconciliation.

Verified checkout conversions

For instant checkout, Rako expects platform-side payment evidence from a payment processor or payment orchestration layer. In the production design, Rako authenticates the event, reads AAP metadata, verifies the signed AAP Code, checks the payload and amount against the recommendation, and records a verified conversion only when those checks pass. Handled successful payment event names include:

payment_intent.payment_succeeded
payment_intent.succeeded
payment_succeeded

The current beta flow reads payment metadata, looks up the recorded recommendation, computes commission, and inserts a conversion with conversionPath: "verified_payment". The full production gate also requires webhook authentication plus AAP Code, payload, amount, and payment-status verification before that label should be treated as production-grade.

{
  "received": true,
  "status": "conversion_recorded",
  "conversionId": "01K...",
  "verification": "beta_payment_observed"
}

The conversion starts as pending while validation, refund, dispute, and settlement windows remain open.

Merchant-reported conversions

Merchants can report a completed sale or payable action with:

POST /v1/conversions
Authorization: Bearer <merchant-api-key>
Content-Type: application/json

{
  "sessionId": "01KN6KV0TWMH8VS6TDS3S7V2EJ",
  "orderReference": "ORD-100045",
  "transactionValue": 10
}

Required fields:

Field	Description
`sessionId`	The AAP session that led to the recommendation.
`orderReference`	Merchant-side order, application, policy, or payment reference.
`transactionValue`	Gross value used to calculate percentage or hybrid commission.

Response:

{
  "conversionId": "01K...",
  "sessionId": "01KN6KV0TWMH8VS6TDS3S7V2EJ",
  "orderReference": "ORD-100045",
  "transactionValue": 10,
  "commission": {
    "amount": 8,
    "networkFee": 1.6,
    "builderPayout": 6.4,
    "type": "cpa"
  },
  "status": "pending",
  "validationPeriodDays": 30
}

Merchant-reported conversions are useful for verticals where the payable outcome is not a simple checkout payment: broadband installation, insurance policy start, regulated applications, recurring subscriptions, or first-bill milestones.

Conversion flows and milestones

Some products require multiple events before a commission should settle. Rako supports merchant-configured conversion flows such as:

Flow type	Example milestones
`instant_checkout`	`payment_received`, `order_confirmed`
`quote_application`	`quote_requested`, `application_submitted`, `application_approved`, `payment_received`
`install_activation`	`order_placed`, `install_scheduled`, `install_completed`, `service_activated`
`policy_start`	`quote_requested`, `policy_issued`, `cooling_off_complete`, `first_bill_paid`

Merchants record milestones against a conversion:

POST /v1/conversions/{conversionId}/milestones
Authorization: Bearer <merchant-api-key>
Content-Type: application/json

{
  "step": "service_activated",
  "status": "completed",
  "metadata": {
    "activatedAt": "2026-04-15T10:30:00Z",
    "serviceReference": "BB-88391"
  }
}

Milestones do not replace the conversion record. They provide the audit trail needed to validate, delay, settle, or claw back commission.

Refunds, disputes, and clawbacks

Payment webhook handling also reconciles negative lifecycle events:

refund.succeeded or charge.refunded marks the conversion clawed_back
dispute.opened or charge.dispute.created marks the conversion disputed
dispute.closed resolves the dispute according to the configured policy

This is designed to keep the AAP ledger aligned with the merchant’s payment reality instead of relying on agent self-reporting. The production trust level depends on the payment webhook being authenticated and reconciled against the signed AAP metadata.

Settlement fields

Each conversion stores the values Rako needs for invoicing and payouts:

transactionValue
commissionAmount
networkFee
builderPayout
conversionPath
status
orderReference
recommendationId, sessionId, merchantId, and agentId

For registered builders, the standard split is 80% builder payout and 20% Rako network fee. Anonymous agent traffic can still be attributed, but builder payout is zero until the builder is registered.

​Conversions

​Conversion sources

​Verified checkout conversions

​Merchant-reported conversions

​Conversion flows and milestones

​Refunds, disputes, and clawbacks

​Settlement fields

Conversions

Conversion sources

Verified checkout conversions

Merchant-reported conversions

Conversion flows and milestones

Refunds, disputes, and clawbacks

Settlement fields