eGift API

The eGift API is the EPI wrapper over the eGiftSolutions stored-value + loyalty network. Integrate over a clean REST surface — JSON endpoints under https://www.egift.online/api/egift/v1/*, Bearer-key auth.

A “Terminal Type” (assigned during certification by eGiftSolutions support) identifies your integration on every request. The 15-digit Terminal ID is a composite: MID(7) + LID(4) + TID(4) — e.g. 000123400010001 = merchant 0001234, location 0001, terminal 0001.

Card numbers are digits only. Strip whitespace and hyphens before sending — the API rejects formatted PANs with a 400. The official SDK handles this for you.

1. Get your API key from the merchant portal — starts with egw_ followed by 32 hex characters.
2. Call POST /api/egift/v1/balance when a customer enters a gift card code.
3. Call POST /api/egift/v1/redeem at order placement. If cancelled later, call POST /api/egift/v1/void.

For reload / top-up flows (coffee shops, loyalty), use POST /api/egift/v1/add-value.

Every request needs an Authorization: Bearer egw_<your-key>header. Each merchant has one key (plus optionally anegw_test_*sandbox key); the key resolves server-side to the merchant’s 15-digit gateway credentials (MID + LID + TID). Keys are minted and revoked from the ISO360 staff panel.

Reference table of every transaction code defined by the spec. The Future Use column marks ops that are reserved in the spec but not yet enabled in production by eGiftSolutions — they round-trip but may decline.

Every endpoint that accepts a card accepts either cardNumber (key-entered) OR raw track1 / track2 from an MSR. Pass exactly one set. The spec ignores Track 3 entirely and prefers Track 2 when both are provided. Set track2FormatCode = 1 (or any non-zero) when sending raw swipe data; 0 means terminal-formatted.

Gift-card track data is not PCI-scoped — these are merchant-issued stored-value SVCs, not real interchange credentials. TLS is sufficient.

Returns dollar and point balance for any of the merchant’s eGiftSolutions cards. No transaction is recorded — informational only (Result Code 501).

Deducts transaction amount, or remaining balance, whichever is smaller, from stored card balance. Returns the balance left. You can adjust a tip on the fly (aka Counter Tip or Tip in Transaction) by putting the primary amount in amountCents and the tip in tipCents.

Pass an Idempotency-Key header. Without one, a network flake on retry can deduct twice. See Idempotency.

Adds transaction amount to stored card balance. If card is already active, transaction is possible — otherwise, perform an Activation (code 005) first.

Add Value transactions may NOT be voided. The spec recommends reversing an Add Value with a Redeem against the same card for the same amount, since real cash / credit was exchanged for stored balance.

Reverses a specific transaction. Internally flags the transaction voided so it cannot be voided more than once. The original Transaction ID is required — pass it as transactionId.

You may NOT void Add Value (003) or Activation (005) transactions. To reverse an Activation, deactivate the card (007); to reverse an Add Value, redeem the same amount back.

Like Add Value but also creates a new card record in the database. Only valid on a card that has never been activated — if the card already exists, the gateway declines with code 013 (Card Already Active) and you should switch to Add Value (003).

Changes card status to inactive, zeroes the balance. Use this when reversing an Activation — the spec’s recommended way to “void” the activation since 005 is un-voidable.

Changes card status to inactive but does NOT zero the balance. The remaining balance is returned in Amount 2 so the cashier can issue a cash / credit refund to the customer. Card stays deactivated.

Like Deactivate (006) but also creates a new card record in the database and transfers the old card’s balance to it. Used when issuing a replacement card.

Functionally identical to Add Value / Activation, but records the load as Store Credit. Add Value / Activation assume cash or credit was tendered into the business; Store Credit assumes goods came back in exchange for merchandise credit. Affects reporting only — also used for promotional / donation loads where no money is taken in.

Modifies a specific previous redemption — updates the tip and total. Requires the original Transaction ID (transactionId) plus the new tip. Restaurant flow: tip card on the receipt at end of meal, then the POS posts a tip adjust before close-of-day.

Like Reissue (008), but the receiving card already exists on the gateway. Pass the existing source card, an already-activated destination card, and optionally an amount — the gateway debits the source by that amount and credits the destination the same. Returns the new balances on both sides.

Common use cases

• Partial gift to a recipient. Customer wants to send $10 of their $25 balance to a friend. Activate a fresh pool card at $0, then transfer with amountCents: 1000. Source ends at $15, recipient card at $10.
• Full balance move (damaged stripe replacement).A card’s mag stripe is damaged. Key-enter the bad card as the source, swipe the replacement as the destination, and omit amountCents to move the entire balance off the old card in one call.

Modifies a specific card to update its expiration date to the default or specified value. Future implementation — round-trips today but the upstream gateway may not enforce the change yet.

Returns the card’s transaction history for a specific date range as a JSON array. Used primarily to print a card-history receipt.

Issue a new card to a recipient. Charges the buyer’s credit card on the merchant’s Cygma processing MID and emails a PDF gift card to the recipient. Under the hood: payment leg → Activate (005) on a freshly-minted card number.

Adds transaction amount to stored card point total. Loyalty implementation only. Pass the point amount as a plain integerpoints field.

Deducts transaction amount from stored point total. Loyalty implementation only. Decline 101 (Insufficient Funds) applies to points the same as dollars — the wrapper sets balance to zero and returns a partial-redemption hint, leaving the terminal to split-pay if you support that flow.

Returns point total only. Loyalty implementation only — does NOT return the dollar balance. Use code 001 if you need both (it returns dollar balance and the upstream gateway includes a separate point line in the Text field on loyalty-enabled accounts).

Loyalty equivalent of card Activation (005) — creates a new loyalty-enabled card and seeds it with a starting point balance. Future Use per the spec: round-trips today, may decline at the upstream gateway until enabled for your merchant.

Reverse a point redemption — restores points to the card balance. Future Use per the spec; behaves like a Void (004) over loyalty points. The original Transaction ID identifies the redemption being refunded.

Move the entire point balance from one card to another (both must already exist). Future Use per the spec.

Reverse an Add Points (020) or Redeem Points (021) transaction — flags it voided so it cannot be voided more than once. Pass the original transaction ID as transactionId. Future Use.

Loyalty equivalent of Card History (200) — returns point movements over a date range as a JSON array. Future Use.

Cashier sign-in with or without a PIN. Records the cashier as the active operator on the terminal so subsequent transactions attribute to them in reporting. The session is tied to the Terminal ID; sign-out (302) or sign-on (010) by another cashier ends it.

Future Use per the spec. The upstream gateway accepts the request and returns Result 501 (informational) — full session tracking depends on a per-merchant enable flag at eGiftSolutions.

End the active cashier session. reasonCode is required. Used for shift-management reporting — at end-of-shift the POS issues a sign-out before close-of-day.

Future Use per the spec.

Rotate a cashier’s PIN. Both old and new PIN are required. Used by self-service password rotation built into POS systems.

Future Use per the spec.

Open a terminal-level sessionwith the gateway. Distinct from Sign in (301), which scopes to a cashier — Sign-On scopes to the device itself. Some terminal-based integrations issue Sign-On at boot and Sign-Off at shutdown to bracket their activity for the gateway’s session log.

Future Use per the spec.

Close the active terminal session. Pair with Sign-On (010). Useful for terminals that want explicit session boundaries for reconciliation.

Future Use per the spec.

Returned as the declineCode on a failed request. For successful transactions it is 000 — every non-zero code means the gateway rejected the request. Match these against your error UI.

The top-level outcome of the request. Drives the high-level branch on your side — success, decline, info, void.

The API maps the gateway result + decline code into a familiar HTTP envelope. The original decline code is preserved on the response body so you can branch on it directly.

The G1 Message Formats Companion is the source of truth for which fields each transaction overrides. Most of the 26 input fields stay identical across every transaction — only a handful of fields (Transaction Code, Amount 1, Amount 2, Text) actually vary by op. The table below captures every override verbatim from the companion. A blank cell (“—”) means the field carries its default treatment from §9 of the spec.

Per-transaction overrides

* = Future Use per the spec. Cells marked “—” mean the field carries its default treatment from §9 of the spec (no per-transaction override). Sign On notes “Reserved code for future trans” in Amount 1, History packs the from/to date range into Text RS-delimited (see the History section above), and Customer Svc packs a request type code in Text (1=Help, 2=Paper, 4=Cards).

Every monetary endpoint (redeem, void, add-value, activate, tip-adjust, all loyalty operations) accepts an Idempotency-Key header. First call processes normally; retries within 24h return the cached response without re-hitting the gateway. Use <orderRef>-<operation>as the key so retries across multiple ops don’t collide.

Ask your ISO360 rep for a test key. egw_test_<32-hex>keys route to a deterministic stub — no gateway calls, no real balances move. Card-number suffix drives the outcome; loyalty calls return synthesized point balances with the same deterministic suffix rules (last 4 digits × 10 = point balance).

A tiny universal client at https://www.egift.online/egift-sdk.js — works in browsers AND Node ≥18.

TypeScript types at https://www.egift.online/egift-sdk.d.ts.

Paste your API key, pick an endpoint, and call the live API. Request goes from this page to the same URL your cart will use — what you see here is what your integration will do.

curl -X POST https://www.egift.online/api/egift/v1/balance \
  -H "Authorization: Bearer egw_..." \
  -H "Content-Type: application/json" \
  -d '{
  "cardNumber": ""
}'

⚠️ Uses YOUR live API key against the production gateway. Use a test card from your pool or an egw_test_* key.