> ## 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 với tích hợp Dodo Payments gốc. Một affiliate chia sẻ liên kết và Rekomi ghi nhận lượt nhấp. Khi khách truy cập đó mua hàng, Dodo Payments gửi giao dịch đến Rekomi, nơi ghi nhận hoa hồng cho đúng affiliate. Rekomi tính hoa hồng và thanh toán cho các affiliate thay bạn tại hơn 150 quốc gia, bao gồm cả biểu mẫu thuế.

Để kết nối, bạn dán một Dodo Payments API key có quyền ghi vào Rekomi. Rekomi xác thực key, tạo webhook endpoint trong tài khoản Dodo Payments của bạn và lấy signing secret của endpoint. Bạn không cần điền biểu mẫu webhook hay dán bất kỳ thông tin nào trở lại Dodo Payments.

<Info>
  Rekomi ghi nhận giao dịch cho một 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 paid subscription hoặc thanh toán gia hạn. Các 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 trang web của bạn, nơi script Rekomi lưu thông tin giới thiệu trong trình duyệt của họ.
2. Khi checkout, bạn đính kèm thông tin giới thiệu đó vào payment dưới dạng metadata `rekomi_ref`.
3. Dodo Payments xử lý payment và gửi webhook `payment.succeeded` đã 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 giao dịch.

Các lượt gia hạn subscription cũng được gửi theo cách tương tự, vì vậy hoa hồng định kỳ không cần thao tác bổ sung. Các khoản hoàn tiền và tranh chấp cũng được gử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, bạn cần:

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 **quyền ghi**, vì key chỉ đọc không thể tạo webhook

## Bắt đầu

<Steps>
  <Step title="Create an API Key with Write Access">
    <Warning>
      Bật quyền ghi cho key. Key chỉ đọc vẫn 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>

    Trong dashboard Dodo Payments, truy cập **Developer → API Keys** và nhấp **Add API Key**. Đặt tên cho key là `Rekomi` và giữ nguyên tùy chọn **Enable write access**. Để biết thêm chi tiết, xem [Authentication](/api-reference/introduction#authentication).
  </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, tạo webhook endpoint trong tài khoản của bạn và lấy signing secret của endpoint.

    <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, Rekomi chỉ sử dụng key để quản lý webhook endpoint và thực hiện các lần kiểm tra tình trạng định kỳ. Giao dịch của bạn được gửi qua webhook đã ký, không phải qua API.
    </Info>
  </Step>

  <Step title="Install the Rekomi Script">
    Thêm tracking script của Rekomi vào website marketing để ghi nhận lượt nhấp của affiliate. Rekomi hiển thị đoạn mã của bạn, với program ID đã được điền sẵn, tại **Setup → Install**.

    ```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 đã thu thập vào mỗi payment dưới dạng metadata `rekomi_ref`. [Implementation Guide](#implementation-guide) hướng dẫn cách thực hiện cho từng loại checkout.
  </Step>

  <Step title="Done">
    Các giao dịch, lượt gia hạn, khoản hoàn tiền và tranh chấp hiện sẽ tự động ghi nhận và thu hồi hoa hồng affiliate, đồng thời Rekomi thanh toán cho các affiliate của bạn.
  </Step>
</Steps>

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

### Checkout Sessions qua API

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

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

// Reads DODO_PAYMENTS_API_KEY from the environment and defaults to live mode.
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 trên các sản phẩm subscription, vì vậy khoản thu đầu tiên 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ùy chọn này vẫn hoạt động với các tích hợp hiện có. Các tích hợp mới nên sử dụng [Checkout Sessions](/developer-resources/checkout-session) (`POST /checkouts`), sử dụng `metadata` theo cùng cách.
</Note>

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

// Reads DODO_PAYMENTS_API_KEY from the environment and defaults to live mode.
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 thông tin giới thiệu vào liên kết dưới dạng query parameter phẳng `metadata_rekomi_ref`, không sử dụng dạng dấu ngoặc:

```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 thêm các query parameter `metadata_*` vào metadata của payment, nơi Rekomi đọc các parameter này.

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

Rekomi xử lý từng loại sự kiện bán hàng như sau:

| 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 thu được gửi dưới dạng một sự kiện payment riêng |
| Hoàn tiền | Hoa hồng tự động bị thu hồi, tối đa bằng số tiền đã ghi nhận |
| Tranh chấp | Hoa hồng bị thu hồi ngay khi tranh chấp được mở |

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

## Lưu ý quan trọng

* Rekomi đăng ký webhook endpoint với chính xác các sự kiện cần thiết. Không chỉnh sửa danh sách sự kiện 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ó sự kiện bị xóa.
* Bản dùng thử miễn phí không tạo payment cho đến khi thời gian dùng thử kết thúc, vì vậy chưa có hoa hồng cho đến khoản thu đầu tiên. [Bản dùng thử trả phí](/features/subscription#paid-trials) sẽ tính trước số tiền dùng thử.
* Việc 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>
  Nếu cần hỗ trợ về tích hợ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).
</Info>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.