> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.crisscross.money/core-concepts-merchant-location/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.crisscross.money/_mcp/server.

# Merchant Location

> Learn how merchant location data is integrated into CrissCross for enhanced payment processing and fraud prevention.

### Overview

Merchant location data is a crucial component in the CrissCross ecosystem, providing valuable insights for payment processing and fraud prevention. By understanding where transactions are initiated, merchants can better tailor their services and enhance security measures.

---

### Importance of Merchant Location

Merchant location forms part of the default environment variables that a merchant can configure in their system. During session initiation calls, merchants can pass through the `merchantLocation`. This information can be a determining factor in how payments are executed, especially in scenarios where the merchant operates in multiple locations.

#### Example Scenarios:

1. **Influencing Payment Methods**:
   * If the `merchantLocation` is set to Kenya, and the merchant has regulatory access to receive payment methods local to Kenya, then those payment options can be rendered during the checkout process. This ensures that customers have access to familiar and trusted payment methods, enhancing their overall experience.

2. **Transaction Execution Considerations**:
   * The `merchantLocation` can also be relevant when executing a transaction. For instance, if a customer is paying with a card issued in a different country than the merchant's location, additional security requirements may be appropriate. This could involve implementing extra verification steps, such as 3D Secure, to mitigate the risk of fraud.

---

### How to Use Merchant Location Data

1. **Integration with Rules Engine**:
   * Use location data as a condition in your payment rules to customize payment flows.
   * Example: Prioritize mobile money options for transactions initiated in regions where mobile payments are prevalent.

2. **Enhancing Customer Experience**:
   * Tailor offers and services based on the customer's location to improve engagement and satisfaction.

3. **Monitoring and Reporting**:
   * Use location data in reports to analyze transaction trends and optimize business strategies.

---

### Example Rule Using Location Data

```json maxLines=0
{
  "trigger": {
    "on": "determinePaymentOptions",
    "filter": {
      "paymentMethodCode": "mobileMoney"
    }
  },
  "rules": [
    {
      "condition": {
        "field": "customer.location.country",
        "operator": "IS ONE OF",
        "value": [
          "NG", // Nigeria
          "KE"  // Kenya
        ]
      },
      "action": {
        "type": "setPriority",
        "params": {
          "priority": 1
        }
      }
    }
  ],
  "defaultAction": {
    "type": "skip"
  },
  "workspaceId": "7f9f1882-a103-408d-ac96-46a7021e537a"
}
```

### Passing merchant location in API calls

If you need to pass a merchant operating location through to processing/rules, include it as a custom attribute when creating a checkout session using `paymentAttributes`:

```json
{
  "merchantId": "YOUR_MERCHANT_ID",
  "merchantReference": "ORDER12345",
  "amount": 15000,
  "currency": "ZAR",
  "integrationType": "hosted",
  "payerDetails": {
    "emailAddress": "customer@example.com",
    "location": "ZAF"
  },
  "paymentAttributes": {
    "merchantLocation": "ZAF"
  }
}
```

> Understanding and Utilizing Merchant Location Data