Skip to content
Last updated

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):

POST https://cert.api2.heartlandportico.com/Hps.Exchange.PosGateway.Hpf.v1/api/token
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.

Authorization Query Param: api_key=<YOUR_HEARTLAND_PUBLIC_API_KEY>

Request Body Example:

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

Response Example:

{
    "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:

{
  "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.

Previous page
Next page