# Handling Cards

To ensure **PCI DSS compliance**, all developers integrating with our platform **must not send raw card information
directly to us**. Instead, they must first utilize **Heartland’s API** to tokenize card data. Our platform uses
Heartland as the secure handler of sensitive payment data through simple tokenization flow of card data.
This happens the first time you add a card(payment method) to the VYAFAC system.

## Workflow Overview

1. **Tokenize the Card via Heartland**
2. **Send the tokenized card to our API endpoint**
3. **We create a customer object linked with the payment method**
4. **Use the customer object for all future payment operations**


## Step 1: Tokenize Card Using Heartland API

Before interacting with our system, send the raw card details to Heartland to get a secure token.

**Endpoint (Heartland):**


```http
POST https://cert.api2.heartlandportico.com/Hps.Exchange.PosGateway.Hpf.v1/api/token
```


```http
POST https://api.heartlandportico.com/SecureSubmit.v1/api/token
```

**Note:** The `cert` API endpoint is intended for testing purposes only. Use the second endpoint for production environments.

### Authorization

Merchants must obtain their Heartland public key from the Developer Settings in their VYAFAC account.
In test mode, a test key is provided for use with test card data; in live mode, the key corresponds to their live
account.

When sending requests to Heartland, this key must be passed as a query parameter named `api_key`.
This is how Heartland handles authorization for tokenization requests.


```http
Authorization Query Param: api_key=<YOUR_HEARTLAND_PUBLIC_API_KEY>
```

**Request Body Example:**


```json
{
  "card": {
    "number": "4111111111111111",
    "cvn": "567",
    "exp_month": "12",
    "exp_year": "2030"
  },
  "object": "token",
  "token_type": "supt"
}
```

**Response Example:**


```json
{
    "object": "token",
    "token_value": "supt_SnucH7r2TJDywIGbdr6pmpze", // The single use token you will send to VYAFAC.
    "token_type": "supt",
    "token_expire": "2025-05-05T07:07:13.6842464Z",
    "card": {
        "number": "************1111"
    }
}
```

## Step 2: Send Token to Our API

Once you receive the token from Heartland, send it to our API to create a customer
or a payment method for a specific customer. You may get more information for those APIs
in their respective documentation section.

This is how a card object must be structured:


```json5
{
  "card": {
    // The token you got from the heartland API
    "token": "supt_SnucH7r2TJDywIGbdr6pmpze",
    "last_four": "1111",
    "exp_month": "12",
    "exp_year": "2030"
  }
}
```

Whenever a card object is referenced in any future API calls, always use the Heartland token.

For example, when creating a customer or adding a payment method, the card is processed once
and replaced with secure identifiers. After that, simply reference entities using their API
IDs—such as `cus_st7udftsdy8ofys8` for a customer or `pm_fg8di73tef98s7diuftuos` for a payment
method.

This ensures compliance, security, and seamless integration.