Documentation

Copy page

Best Practices & Common Pitfalls

This page distills the most frequent integration issues we see — and how to avoid them. Read this before going to production.

---

1. Never use placeholder payment tokens

The sample customer creation payload in the documentation uses a placeholder paymentToken:

Code
"paymentToken": "00000000-000000-000000-000000000000"

This value works for sandbox testing but will fail in production. In production, every paymentToken must come from a live call to ZeroGateway.js. The token is generated when a real cardholder enters their card details into your hosted form.

What to do: Complete the tokenization setup before writing any server-side payment code. Your server should receive the token from your client-side form, not generate or hardcode it.

---

2. Use id, not customerVaultId, when charging via vault

See Customer Vault — id vs customerVaultId for a full explanation of why these fields are not interchangeable and which one to pass as card.vaultId.

---

3. Keep credentials server-side

The Strictly API issues two types of keys with different security requirements:

Key	Exposure	Risk if leaked
Tokenization key	Client-side (safe)	Limited to tokenizing cards
API key-hash + Basic auth	Server-side only	Full API access

Store credentials in environment variables on your server:

Code
STRICTLY_KEY_HASH=your_key_hash_here
STRICTLY_EMAIL=[email protected]
STRICTLY_PASSWORD=yourpassword

Rotate your key-hash immediately if it is ever exposed.

---

4. Always paginate list requests

All GET endpoints default to 10 records. If your integration fetches a list and processes the results, you will silently miss records once you have more than 10 in your account.

Always pass page and limit
GET /public/customer?page=1&limit=50

In batch jobs that need all records, loop until you receive fewer records than your limit:

Fetch all customers
async function fetchAllCustomers() {
  const allCustomers = [];
  let page = 1;
  const limit = 50;

  while (true) {
    const response = await fetch(
      `https://api.paywithzero.net/v1/public/customer?page=${page}&limit=${limit}`,
      { headers }
    );
    const { data } = await response.json();

    allCustomers.push(...data);

    if (data.length < limit) break; // Last page
    page++;
  }

  return allCustomers;
}

See Pagination & Filtering for full parameter details.

---

5. Use ISO 8601 for date range queries

Date filter parameters (startDay, endDay) require ISO 8601 format with millisecond precision. A common mistake is passing a plain date string:

Incorrect ❌
?startDay=2025-03-03

Correct ✅
?startDay=2025-03-03T05:00:00.000Z

Use the timezone parameter to avoid manual UTC conversion:

Code
?startDay=2025-03-03T00:00:00.000Z&endDay=2025-03-03T23:59:59.999Z&timezone=America/New_York

---

6. Do not retry declined transactions

A 400 response with a payment error code (e.g. 300 — Transaction rejected by gateway) is a definitive gateway response. Automatically retrying the same request will not succeed and may trigger fraud detection on the card.

Response	Safe to retry?
400 with payment error code	No — show the customer an error
500 or network timeout	Yes — use exponential backoff

Only retry requests that fail with server errors (5xx) or network issues. For payment declines, always prompt the customer to use a different card or contact their bank.

---

7. Confirm the correct tokenization key

A common setup issue: the tokenization form loads but the token request silently fails because the wrong key type is loaded.

• Go to Merchant Settings → Security Keys
• Copy from Tokenization Source (not from the API key section)
• The tokenization key and API key are different strings and are not interchangeable

See Authentication and Tokenization for details.

---

8. Handle the sendReceipt flag intentionally

Charge requests include a sendReceipt field. When true, the Strictly platform sends an email receipt to the customer's address.

• Set sendReceipt: false during testing to avoid emailing real customers from sandbox
• Set it based on your UX intent in production — some integrations manage their own receipt emails

---

Reference

• Tokenization — set up ZeroGateway.js correctly
• Customer Vault — vault IDs explained
• Pagination & Filtering — query parameters reference
• Error Handling — full error code reference
• Sandbox & Testing — test without real money