## Overview

Customer intelligence is a suite of tools that allow you to build detailed profiles for your customers. By attaching customer data to your transactions, you gain valuable insights, reduce fraud risk, and create more personalized experiences.

Reservepay's intelligence engine automatically correlates information across your account. Whether you provide a Customer ID, an email address, or a mobile phone number, we'll correctly identify and link the data to the same customer profile.

## Managing contacts

Contacts are the core of customer intelligence in Reservepay. You can create, retrieve, update, and remove contacts using our API. Contacts support both payments and payouts, making it easy to manage the full lifecycle of your customer interactions.

### Creating a contact

To create a new contact, use the `merchants/add-contact` endpoint. You must provide either an email address or a mobile number. You can also provide your own `external_id` to use as a Customer ID from your system.

```ts
await fetch('https://api.reservepay.com/merchants/add-contact', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Api-Version': '2025-04-01',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    contact_email: 'customer@example.com',
    contact_name: 'John Doe',
    external_id: 'cust_987654' // Your own Customer ID
  })
})
```

## Linking transactions to contacts

When initiating a payment or a payout, you can link the transaction to a contact. Our system will automatically correlate the information even if you only provide an email or mobile number.

### Payments

When initiating a payment flow, you can link the transaction to an existing contact by providing the `customer_id` (either our `ctc_` ID or your `external_id`), `customer_email`, or `customer_mobile`.

```ts
await fetch('https://api.reservepay.com/merchants/initiate-payment-flow', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Api-Version': '2025-04-01',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: '10000',
    currency: 'THB',
    customer_email: 'customer@example.com', // We'll automatically correlate this to the right contact
    payment_session_id: 'sess_1234567890',
    capture: true,
    return_url: 'https://example.com/return'
  })
})
```

### Payouts

You can also send payouts to your contacts. Use the `merchants/send-payout-to-contact` endpoint to send funds to a contact's primary bank account or via PromptPay using their mobile number or national ID.

## Managing bank accounts for contacts

To send a payout to a contact's bank account, you can first link one or more bank accounts to the contact using the `merchants/link-bank-account` endpoint.

Once a bank account is linked, you can:

- **Set a primary account**: Use `merchants/set-primary-contact-bank-account` to specify which account should receive payouts by default.
- **Find accounts**: Use `merchants/find-bank-account` to retrieve details of a specific bank account.
- **Unlink accounts**: Use `merchants/unlink-bank-account` to remove a bank account from a contact's profile.

## Saving cards for future use

You can securely save customer cards for future payments. This is useful for implementing one-click checkouts or subscription billing.

### Tokenizing a card

First, tokenize the card details using the `sdk/tokenize-card` endpoint. Set `usage: 'MULTIPLE'` to create a reusable token.

### Saving the card to a contact

Use the `merchants/save-card` endpoint to convert the token into a saved card associated with a contact.

```ts
await fetch('https://api.reservepay.com/merchants/save-card', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Api-Version': '2025-04-01',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    token: 'tok_1234567890',
    contact_id: 'ctc_1234567890',
    default: true
  })
})
```

## Insights and analytics

By consistently linking payments to contacts, you can unlock powerful insights through our dashboard and API. You can see:

- **Customer lifetime value (CLV):** Total amount spent by a customer.
- **Purchase frequency:** How often a customer makes a purchase.
- **Preferred payment methods:** Which payment methods a customer uses most frequently.