Skip to main content

​
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

SourceTypical pathVerification level
Payment webhookMerchant payment processor confirms a successful payment and returns AAP metadata.Verified checkout conversion only after authentication and reconciliation checks pass.
Merchant conversion reportMerchant reports sessionId, orderReference, and transaction value.Pending validation.
Milestone updateMerchant reports progress after an initial conversion, such as install or activation.Depends on configured flow.
Refund or dispute webhookMerchant 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:
FieldDescription
sessionIdThe AAP session that led to the recommendation.
orderReferenceMerchant-side order, application, policy, or payment reference.
transactionValueGross 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 typeExample milestones
instant_checkoutpayment_received, order_confirmed
quote_applicationquote_requested, application_submitted, application_approved, payment_received
install_activationorder_placed, install_scheduled, install_completed, service_activated
policy_startquote_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.