> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Rekomi

> Chạy chương trình affiliate trên cửa hàng Dodo Payments của bạn với Rekomi. Chỉ cần dán một API key để kết nối hai nền tảng, sau đó Rekomi theo dõi doanh số và thanh toán cho các affiliate của bạn.

## Giới thiệu

[Rekomi](https://rekomi.com) là nền tảng theo dõi và quản lý affiliate có tích hợp native với Dodo Payments. Một người chia sẻ liên kết affiliate, Rekomi ghi nhận lượt nhấp, và khi khách truy cập đó mua hàng, doanh số được gửi từ Dodo Payments đến đúng affiliate một cách tự động. Rekomi tính hoa hồng và cũng thanh toán cho các affiliate của bạn, tại hơn 150 quốc gia, bao gồm cả biểu mẫu thuế.

Việc kết nối chỉ cần dán một lần: bạn cung cấp cho Rekomi một Dodo Payments API key đã bật quyền ghi, Rekomi sẽ xác thực key, tạo webhook endpoint ngay trong tài khoản Dodo Payments của bạn và lấy signing secret trực tiếp. Bạn không cần điền biểu mẫu webhook hay dán thông tin nào ngược lại vào Dodo Payments.

<Info>
  Một "doanh số" được ghi nhận cho affiliate khi khách hàng được giới thiệu hoàn tất thanh toán một lần, bắt đầu gói đăng ký trả phí hoặc thanh toán gia hạn. Khoản hoàn tiền và tranh chấp sẽ tự động thu hồi hoa hồng.
</Info>

## Cách hoạt động

Dodo Payments lưu trữ trang checkout trên domain riêng, vì vậy lượt giới thiệu từ affiliate được truyền vào giao dịch dưới dạng checkout metadata:

1. Khách truy cập nhấp vào liên kết affiliate và đến website của bạn, nơi script của Rekomi lưu thông tin giới thiệu trong trình duyệt của họ.
2. Họ đi đến checkout, và bạn đính kèm thông tin giới thiệu đó vào khoản thanh toán dưới dạng `rekomi_ref` metadata.
3. Dodo Payments xử lý khoản thanh toán và gửi một `payment.succeeded` webhook đã ký đến endpoint do Rekomi tạo.
4. Rekomi đối chiếu thông tin giới thiệu với affiliate, tính hoa hồng trên số tiền bán hàng trước thuế và ghi nhận khoản đó.

Các lần gia hạn gói đăng ký cũng được gửi theo cách tương tự, vì vậy hoa hồng định kỳ không cần thêm thao tác nào, đồng thời khoản hoàn tiền và tranh chấp cũng đi qua cùng endpoint.

## Điều kiện tiên quyết

Trước khi thiết lập tích hợp này, hãy đảm bảo bạn có:

1. Một [tài khoản Dodo Payments](https://app.dodopayments.com) ở live mode
2. Một [tài khoản Rekomi](https://app.rekomi.com/sign-up)
3. Một Dodo Payments API key đã bật **write access** (key chỉ có quyền đọc không thể tạo webhook)

## Bắt đầu

<Steps>
  <Step title="Create an API Key with Write Access">
    Trong dashboard Dodo Payments, đi đến **Developer → API Keys** và tạo một key (đặt tên là "Rekomi") với tùy chọn **Enable write access** được bật. Xem [hướng dẫn API key](/api-reference/introduction#api-key-management-and-authentication) để biết hướng dẫn chi tiết.

    <Warning>
      Bật write access cho key: key chỉ có quyền đọc sẽ vượt qua bước xác thực nhưng không thể tạo webhook endpoint, vì vậy kết nối sẽ bị lỗi giữa chừng.
    </Warning>
  </Step>

  <Step title="Paste the Key into Rekomi">
    Trong Rekomi, mở **Setup → Connect payment processor**, chọn Dodo Payments và dán key. Rekomi xác thực key theo thời gian thực, tạo webhook endpoint trong tài khoản của bạn và tự lấy signing secret.

    <Frame>
      <img src="https://mintcdn.com/dodopayments/ic2bWXoH5_Rw-GN5/images/integrations/rekomi/connect.png?fit=max&auto=format&n=ic2bWXoH5_Rw-GN5&q=85&s=2271768fc16cecec3196c8006e0c73ab" alt="Trang thiết lập Dodo Payments của Rekomi với một trường API key duy nhất và nút kết nối" style={{ maxHeight: '500px', width: 'auto' }} width="1280" height="690" data-path="images/integrations/rekomi/connect.png" />
    </Frame>

    <Info>
      Sau khi kết nối, key chỉ được dùng để quản lý webhook endpoint và thực hiện các lần kiểm tra tình trạng định kỳ. Doanh số của bạn được gửi qua signed webhook, không bao giờ thông qua API.
    </Info>
  </Step>

  <Step title="Install the Rekomi Script">
    Thêm Rekomi tracking script vào website marketing của bạn để ghi nhận các lượt nhấp vào liên kết affiliate. Đoạn snippet đã điền sẵn program ID nằm trong **Setup → Install** trên Rekomi.

    ```html theme={null}
    <script
      async
      src="https://api.rekomi.com/api/v1/r/loader.js"
      data-program-id="YOUR_PROGRAM_ID"
    ></script>
    ```
  </Step>

  <Step title="Pass the Referral into Checkout">
    Đính kèm thông tin giới thiệu đã ghi nhận vào mỗi khoản thanh toán dưới dạng `rekomi_ref` metadata. Xem các ví dụ triển khai bên dưới.
  </Step>

  <Step title="Done!">
    Doanh số, gia hạn, hoàn tiền và tranh chấp giờ đây sẽ tự động ghi nhận và thu hồi hoa hồng affiliate, còn Rekomi sẽ xử lý việc thanh toán cho các affiliate của bạn.
  </Step>
</Steps>

## Hướng dẫn triển khai

### Checkout Sessions qua API

Đọc thông tin giới thiệu ở frontend bằng `window.Rekomi.getReferral()`, gửi thông tin đó đến backend cùng với yêu cầu checkout và đặt thông tin vào `metadata`:

```typescript Node.js theme={null}
import DodoPayments from 'dodopayments';

const client = new DodoPayments();

export async function createCheckout(productId: string, rekomiRef?: string) {
  const session = await client.checkoutSessions.create({
    product_cart: [{ product_id: productId, quantity: 1 }],
    customer: {
      email: 'customer@example.com',
      name: 'John Doe',
    },
    return_url: 'https://yoursite.com/success',
    metadata: {
      ...(rekomiRef ? { rekomi_ref: rekomiRef } : {}),
    },
  });

  return session.checkout_url;
}
```

Trường `metadata.rekomi_ref` tương tự cũng hoạt động với các sản phẩm subscription, vì vậy khoản phí ban đầu và mọi lần gia hạn đều ghi nhận cho cùng một affiliate.

### Payments API

<Note>
  Ví dụ bên dưới sử dụng `POST /payments`, hiện đã **deprecated**. Tính năng này vẫn hoạt động với các tích hợp hiện có, nhưng các tích hợp mới nên sử dụng [Checkout Sessions](/developer-resources/checkout-session) (`POST /checkouts`) — `metadata` được truyền theo cùng cách.
</Note>

```typescript Node.js theme={null}
import DodoPayments from 'dodopayments';

const client = new DodoPayments();

export async function createPayment(productId: string, rekomiRef?: string) {
  const payment = await client.payments.create({
    billing: {
      city: 'New York',
      country: 'US',
      state: 'NY',
      street: '123 Main St',
      zipcode: '10001',
    },
    customer: {
      email: 'customer@example.com',
      name: 'John Doe',
    },
    product_cart: [{ product_id: productId, quantity: 1 }],
    payment_link: true,
    metadata: {
      ...(rekomiRef ? { rekomi_ref: rekomiRef } : {}),
    },
  });

  return payment;
}
```

### Static Payment Links

Thêm tham số truy vấn flat metadata vào liên kết (không dùng dạng bracket):

```javascript theme={null}
const ref = window.Rekomi?.getReferral?.();
let url = 'https://checkout.dodopayments.com/buy/YOUR_PRODUCT_ID';
if (ref) url += `?metadata_rekomi_ref=${encodeURIComponent(ref)}`;
// use url as the href on your Buy button
```

Dodo Payments đưa các tham số truy vấn `metadata_*` vào metadata của khoản thanh toán, nơi Rekomi đọc chúng.

## Những gì được theo dõi

| Sự kiện              | Điều xảy ra                                                                |
| -------------------- | -------------------------------------------------------------------------- |
| Thanh toán một lần   | Hoa hồng được ghi nhận trên số tiền bán hàng trước thuế                    |
| Gia hạn subscription | Hoa hồng định kỳ, mỗi khoản phí được gửi dưới dạng một payment event riêng |
| Hoàn tiền            | Hoa hồng tự động bị thu hồi, không bao giờ vượt quá số đã ghi nhận         |
| Tranh chấp           | Hoa hồng bị thu hồi ngay khi tranh chấp được mở                            |

<Tip>
  Hoa hồng được tính trên số tiền bán hàng trước thuế: Dodo Payments là một Merchant of Record và thu thuế, vì vậy affiliate của bạn nhận hoa hồng trên chính doanh số bán hàng, không bao giờ trên khoản thuế mà quốc gia của người mua tình cờ cộng thêm.
</Tip>

## Lưu ý quan trọng

* Rekomi đăng ký webhook endpoint với chính xác các event cần thiết. Tránh chỉnh sửa danh sách event của endpoint đó trong dashboard Dodo Payments; các lần kiểm tra tình trạng của Rekomi sẽ đánh dấu kết nối nếu có event bị xóa.
* Trial không phát sinh thanh toán cho đến khi kết thúc, vì vậy không có hoa hồng cho đến khoản phí thực tế đầu tiên.
* Ngắt kết nối trong Rekomi sẽ xóa webhook endpoint khỏi tài khoản Dodo Payments của bạn.

## Tài nguyên bổ sung

<CardGroup cols={2}>
  <Card title="Rekomi's Dodo Payments Guide" icon="book-open" href="https://rekomi.com/docs/brands/install/dodo">
    Hướng dẫn thiết lập đầy đủ, thông tin khắc phục sự cố và chi tiết bảo mật trong tài liệu của Rekomi.
  </Card>

  <Card title="Affiliates Feature Guide" icon="users" href="/features/affiliates">
    Tất cả tùy chọn tích hợp affiliate cho Dodo Payments.
  </Card>
</CardGroup>

<Info>
  Cần trợ giúp? Hãy liên hệ bộ phận hỗ trợ của Rekomi tại [support@rekomi.com](mailto:support@rekomi.com) hoặc bộ phận hỗ trợ của Dodo Payments tại [support@dodopayments.com](mailto:support@dodopayments.com) để được hỗ trợ về việc tích hợp.
</Info>