Dodo Payments

The Dodo Payments integration works in two directions:

• Facts in. Dodo payments, refunds, lost disputes, and subscriptions become purchase Events, purchase adjustments, and Subscription facts in your Project. Your server does not send them to the RefRef API.
• Rewards out. RefRef delivers a Program's account credit to the customer's Dodo wallet and its discounts as single-use Dodo discount codes.

You connect one Dodo account to each Project. A Sandbox Project connects a Dodo test-mode account, and a Live Project connects a live-mode account. Start in the Sandbox Project.

Connect Dodo PaymentsCopy Anchor Link

1. In the Dodo dashboard, switch to the mode of the Project (test mode for a Sandbox Project) and create an API key.

2. In RefRef, open the Project's Settings → Integrations, paste the key under Connect Dodo Payments, and select Connect. RefRef checks the key with Dodo and stores it encrypted.

3. The connection shows its webhook URL, which ends in /integrations/v1/dodo/webhooks/<connectionId>. Copy it.

4. In the Dodo dashboard, in the same mode, add a webhook endpoint with that URL and subscribe it to these events:

   Dodo event	What RefRef records
   payment.succeeded	A purchase Event. A subscription payment is an invoice; a one-time payment is an order.
   refund.succeeded	A refund purchase adjustment
   dispute.lost, dispute.accepted	A dispute_loss purchase adjustment
   subscription.active, subscription.renewed	The start of the Subscription
   subscription.paused, subscription.unpaused	A pause and a resume
   subscription.cancelled, subscription.expired	The end of the Subscription

5. Copy the endpoint's signing secret (whsec_…), paste it into the connection's Signing secret field in RefRef, and select Save. Until you save it, RefRef refuses the endpoint's events.

RefRef checks the signature of each event (Standard Webhooks) and refuses a changed body, a timestamp more than five minutes old, or another secret. A repeated event is stored once.

Name the customer at checkoutCopy Anchor Link

RefRef never matches a Dodo customer by email. Your server names the participant in the metadata when it creates the checkout session (or the subscription):

const response = await fetch("https://test.dodopayments.com/checkouts", {
  method: "POST",
  headers: {
    authorization: `Bearer ${process.env.DODO_API_KEY}`,
    "content-type": "application/json",
  },
  body: JSON.stringify({
    product_cart: [{ product_id: "pdt_…", quantity: 1 }],
    customer: { email: user.email, name: user.name },
    metadata: {
      refref_external_id: user.id,
      // The context ID that your capture backend keeps in its signed cookie.
      refref_context_id: refrefContextId,
    },
    return_url: "https://example.com/thanks",
  }),
});
const { checkout_url } = await response.json();

Dodo copies the checkout metadata onto the subscription and onto each renewal payment, so you write it once. A payment or subscription without refref_external_id gives no fact.

What RefRef does with the factsCopy Anchor Link

• First purchase. The start of the Subscription carries the attribution context, so it binds the referral. The first payment then gets the referral as its attribution.
• Renewals. Each renewal payment inherits the Subscription's referral without a new click, also after the attribution window. A Program rule that pays on each purchase earns a Reward on each renewal.
• Paid history. Before RefRef evaluates a purchase Reward, it reads the referee's Dodo payments between the referral and the purchase, so that a "first purchase" rule counts only a first purchase.
• Refunds and disputes. A refund or a lost dispute reduces the purchase by its share of the payment total. Rewards calculated from that purchase get a matching adjustment. RefRef does not take back a Reward that it already delivered: void the Reward in the Console to take back its credit.
• Missed events. Every five minutes RefRef reads the payments, refunds, and subscriptions that Dodo created recently, and the lost disputes of the last 120 days, and records any that an event did not bring. Dodo lists subscriptions by creation time only, so a later cancellation of an older subscription arrives only by its event.

Deliver Rewards in DodoCopy Anchor Link

In the Program's settings, open Delivery and choose Dodo for the Reward kinds that you want RefRef to deliver:

RefRef delivers to the Dodo customer of the beneficiary. It learns the customer from the beneficiary's own payments; for a referrer who has not paid through Dodo, send the customer ID as billingId with PUT /v1/participants. A Reward whose beneficiary has no Dodo customer yet waits.

A delivery is Dodo's success answer. RefRef does not read whether the customer later used the credit or the code.

Not available: plan changes as a Reward, and payouts to referrers through Dodo.

Test the integrationCopy Anchor Link

1. Connect a Dodo test-mode key to your Sandbox Project and add the webhook endpoint in test mode.
2. Create a referral link for a participant and open it in a browser that runs your capture backend.
3. Create a checkout session with the metadata, and pay with a Dodo test card.
4. In the Sandbox Project, check Referrals and Rewards. A Reward that RefRef delivered through Dodo shows its Dodo reference.
5. Refund the payment in Dodo and check the adjustment on the Reward.