Summary
Heartland gift cards are transferred into iPaaS.com as Gift Card records, each carrying its own activity history as child Gift Card Activity records. Gift cards are handled by two separate collections rather than one combined Add/Update collection: Add Heartland Gift Card TO iPaaS.com creates the iPaaS.com record the first time a card is seen, and Update Heartland Gift Card TO iPaaS.com refreshes a card that is already linked. Each parent has its own child activity collection.
The split matters, because the two collections behave very differently. The Add collection populates the whole record from Heartland — number, balance, type, expiration date, status, and a description derived from the card's activity. The Update collection deliberately refreshes only Balance and Status from Heartland and writes every other mapped field back from the record's own current iPaaS.com value, so the details established at creation are not replaced on each subsequent transfer. If you change one of those preservation mappings, you change which system owns that field for the rest of the card's life.
Gift cards are inbound-only in practice. Two opposite-direction collections exist in the integration template, but both ship disabled and neither transfers records — see Disabled Outbound Gift Card Collections.
ID Format
Manual Sync ID Format
On the iPaaS.com Manual Sync page, enter the Heartland gift card number — for example, TB112. The integration retrieves that gift card from Heartland by its number and transfers it together with its activity.
External ID Format
After a successful transfer, the Heartland gift card number is saved as the external-id link between the two systems (for example, TB112). That link is what later transfers use to locate the existing iPaaS.com Gift Card record.
Whether an incoming gift card is created or updated is determined by whether it is already linked by an external id, not by which event triggered the transfer. A card with no external-id link is routed to the Add collection; a card that already has one is routed to the Update collection.
Note that Heartland stores gift card numbers with non-alphanumeric characters removed. A card entered as 1234-5678 is stored in Heartland as 12345678, and the number transferred to iPaaS.com — and therefore the external id — reflects Heartland's stored form. Use the stored form when entering a number on the Manual Sync page.
Deleted Record Support
Deleting a gift card is not supported in this direction. The integration creates and updates iPaaS.com Gift Card records only — removing a gift card in Heartland does not delete or deactivate the linked iPaaS.com Gift Card record, and no delete operation is available for gift cards in this integration.
A gift card that has been fully spent is reflected through its status rather than through deletion: when the balance reaches zero the status mapping resolves to Redeemed, and when the card has expired it resolves to Expired. Gift cards that should be removed entirely must be managed directly in iPaaS.com.
Custom Field Support
This integration does not map any gift card custom fields by default. Neither the gift card collections nor the gift card activity collections include a custom-field mapping in the shipped template.
iPaaS.com does support custom fields on both the Gift Card record and the Gift Card Activity record, so you can add custom-field mappings if you need to carry additional Heartland values. If you do, note two things:
A matching iPaaS.com subscription custom field must exist on the Gift Card or Gift Card Activity collection before the value is stored.
A Heartland custom field must be created in Heartland before it becomes visible on the Heartland website and available to mappings.
If you add custom fields to the Add collection, add the corresponding preservation mappings to the Update collection as well. See Unmapped Field Overwrite Risk.
Mapping Collection Status
Status: Enabled. All four inbound collections — both parents and both children — are enabled. The two opposite-direction collections ship disabled.
Trigger Events: Gift card creation, gift card update, and gift card polling are all supported. Automatic transfers run on a schedule through polling; Heartland's webhook format is not compatible with iPaaS.com instant webhooks, so gift cards arrive through polling rather than instant push notifications. Polling does not run until the subscription is configured and enabled. Individual gift cards can also be transferred at any time from the Manual Sync page.
Transaction-driven transfers: A gift card is also transferred automatically as a prerequisite of a transaction transfer, when the transaction pays with a gift card or when a ticket line item issues one. See Integration Flow.
Duplicate or Conflicting Mappings
Four collections operate on Heartland gift card data in the inbound direction, and they do not compete with one another:
Add Heartland Gift Card TO iPaaS.com handles gift cards that are not yet linked to an iPaaS.com record.
Update Heartland Gift Card TO iPaaS.com handles gift cards that are already linked.
Add Heartland Gift Card Activity TO iPaaS.com is a child of the Add collection and runs only within it.
Update Heartland Gift Card Additional Activity TO iPaaS.com is a child of the Update collection and runs only within it.
Because routing between Add and Update is decided by the external-id link, exactly one parent collection processes any given transfer. There is no configuration choice to make between them, and no scenario in which both run against the same card in the same transfer.
The two opposite-direction collections would otherwise conflict with these, since they write gift card data back to Heartland. They ship disabled specifically so that Heartland remains the single source of truth for gift card balances.
Collision Handling
This integration does not use iPaaS.com collision handling for gift cards. Whether an incoming gift card is created or updated is determined solely by whether it is already linked by an external id; there is no collision recovery step to configure.
Supported Child Collections
Each parent collection has exactly one child, and the two children are not interchangeable:
Add Heartland Gift Card Activity TO iPaaS.com is the child of Add Heartland Gift Card TO iPaaS.com. It runs when a gift card is created in iPaaS.com for the first time, and it brings over the activity history the card already carries in Heartland. This is the card's opening history.
Update Heartland Gift Card Additional Activity TO iPaaS.com is the child of Update Heartland Gift Card TO iPaaS.com. It runs when a gift card that already exists in iPaaS.com is transferred again, and it carries the additional activity recorded against the card since it was created. This is the ongoing history.
Both children map the same four values and share the same lookup translation. What distinguishes them is which parent they belong to and therefore when they run — one populates history at creation, the other appends history on update. Neither child has a schedule, webhook, or Manual Sync entry of its own; each runs only as part of its parent's transfer.
System Caveats
Heartland Caveats
Heartland requires both a Number and a Balance to create a gift card. A card lacking either will not exist in Heartland to be transferred.
Heartland stores gift card numbers with non-alphanumeric characters removed. A card entered as 1234-5678 is stored as 12345678, and that stored form is what transfers to iPaaS.com and becomes the external id.
Heartland is the authoritative source for gift card balances. Gift card balances cannot be fully integrated bidirectionally with other platforms, which is why the outbound direction ships disabled.
Heartland activity history is not a balance ledger. Heartland adjustment activity is not guaranteed to be complete or in order, and a correct balance should never be reconstructed by summing activity records. Some balance changes — a gift card redeemed on a sales order or a ticket, for example — do not always produce a corresponding adjustment activity in Heartland. Treat the activity transferred through these collections as a record of what Heartland reports, and treat the Balance field as the authoritative figure.
Heartland records a reason on each gift card activity. Reasons that have no entry in the lookup translation are not converted, so the resulting activity record has no activity type.
iPaaS.com Caveats
The iPaaS.com Gift Card record requires a Number, Type, Status, and Balance. Both parent collections keep all four populated.
The Number is accepted only when the Gift Card record is created. iPaaS.com ignores an incoming number on update, so a change to a gift card number in Heartland never propagates to an already-linked iPaaS.com record. This also means the preservation mapping on the Update collection cannot be defeated by accident — but it equally means you cannot correct a number through a transfer. Correct it directly in iPaaS.com.
The originating system is likewise accepted only on create and is ignored on update, for the same reason.
iPaaS.com documents the accepted gift card status values as Active, Expired, Void, and Redeemed. The status formula resolves to Active, Expired, or Redeemed, all of which are accepted. Void is never produced by this integration.
iPaaS.com documents the accepted gift card type values as "Giftcard" and "Store Credit". The shipped Add collection supplies the static value "Gift Card". Confirm in a staging environment that the shipped value is accepted for your subscription before relying on it in production, and set the static value to a documented type if it is not.
iPaaS.com documents the accepted gift card activity type values as Issue, Redeem, Void, Reinstate, and Adjust. The shipped lookup translation produces Issue, Void, and Adjust; Redeem and Reinstate are available but not used by the shipped entries.
On update, activity is only ever added — never modified. iPaaS.com does not support updating an existing gift card activity record by its id; an update that references an existing activity is treated as a new activity instead. Repeatedly transferring a gift card whose activity has already been carried across can therefore produce duplicate activity records in iPaaS.com. Validate this behavior against your polling schedule in staging.
Updating an existing iPaaS.com Gift Card record replaces the whole record. Any writable field the collection does not supply is cleared. See Unmapped Field Overwrite Risk.
Integration-Specific Caveats
Transfers are additive and update-in-place: an incoming gift card never removes an existing iPaaS.com Gift Card record.
The Add and Update collections are genuinely separate collections with different mappings, not two names for one behavior. Configuration changes made to one do not apply to the other. If you add a field to the Add collection, add a matching mapping to the Update collection or that field will be cleared the next time the card is updated.
The Update collection's preservation mappings are a deliberate design choice, not a platform default. Changing one of them from a preservation formula to a Heartland source hands ownership of that field to Heartland permanently.
A gift card is transferred as a prerequisite of a transaction only when the integration can recover a card number from the payment or line item description. When no number can be recovered, or the card cannot be retrieved from Heartland, no gift card transfer is attempted and the transaction continues.
Setup Requirements
Heartland Configuration
Ensure each gift card has a Number and a Balance, both of which Heartland requires to create the card.
Review the gift card activity reasons your business actually uses in Heartland, so you can confirm each has a lookup translation entry.
Create any Heartland custom fields you intend to map before configuring the mappings, so they are available for selection.
iPaaS.com Configuration
Confirm the Number, Balance, Type, and Status mappings resolve on the Add collection — all four are required for the iPaaS.com Gift Card record to be created.
Review the Gift Card Activity lookup translation and add an entry for every Heartland reason your business uses. Reasons with no entry produce an activity record with no activity type.
Review the Update collection's preservation mappings and decide, field by field, whether Heartland or iPaaS.com should own that value.
Add preservation mappings to the Update collection for any writable gift card field you populate in iPaaS.com outside this integration. See Unmapped Field Overwrite Risk.
Enable the subscription so polling can run, or use Manual Sync to transfer a specific gift card on demand.
Authentication & Security
Heartland uses OAuth 2.0 to obtain an access token, which authorizes the Heartland API requests made during a transfer. Credentials are configured on the Heartland subscription — see the Heartland Installation Instructions.
Integration Flow
Scheduled polling:
On its polling schedule, the integration requests the current set of gift cards from Heartland.
For each gift card returned, it retrieves the full Heartland gift card record together with its activity.
Each record is dispatched to iPaaS.com. A card with no external-id link is created through Add Heartland Gift Card TO iPaaS.com, and its activity history is attached through Add Heartland Gift Card Activity TO iPaaS.com.
A card that is already linked by its Heartland gift card number is updated through Update Heartland Gift Card TO iPaaS.com, and its additional activity is attached through Update Heartland Gift Card Additional Activity TO iPaaS.com.
Manual Sync:
A Heartland gift card number is entered on the iPaaS.com Manual Sync page.
The integration retrieves that single gift card from Heartland and dispatches it through the same create-or-update path, including its activity.
Gift card paid on a transaction:
While preparing a transaction for transfer, the integration inspects each of the transaction's payments.
When a payment is a gift card payment, the integration recovers the gift card number from the payment description and retrieves that gift card from Heartland.
When the gift card is found and has a number, it is dispatched to iPaaS.com as a gift card update before the transaction itself is transferred, so the transaction lands against a gift card whose balance is current.
When no number can be recovered from the description, or the card cannot be retrieved, no gift card transfer is attempted and processing of the transaction continues.
Gift card issued on a ticket:
When the transaction being transferred is a Ticket, the integration inspects each of its line items.
When a line item is associated with a gift card, the integration recovers the gift card number from the line item description and retrieves that gift card from Heartland.
When the gift card is found and has a number, it is dispatched to iPaaS.com as a gift card update before the transaction itself is transferred.
As above, when no number can be recovered or the card cannot be retrieved, no gift card transfer is attempted and processing of the transaction continues.
Both transaction-driven paths dispatch the gift card as an update request. As with every other path, the external-id link ultimately determines whether the card is created or updated in iPaaS.com, so a card seen for the first time through a transaction is still created correctly.
Mappings
Add Heartland Gift Card TO iPaaS.com
Mapping Filter
This mapping collection does not have a mapping filter applied. All records routed to it are processed without additional filtering conditions.
Description: Creates the iPaaS.com Gift Card record from a Heartland gift card that is not yet linked, populating the full record from Heartland and saving the Heartland gift card number as the external-id link. That number is the durable match key; it is not a configurable mapping row.
Mapping Type | Source Field (Heartland) | Destination Field (iPaaS.com) | Description |
Field | Number | Number | Required. Stores the Heartland gift card number in the iPaaS.com Number field. This value is also saved as the external-id link between the two systems. iPaaS.com will not create a gift card without a number. Heartland stores gift card numbers with non-alphanumeric characters removed (for example, 1234-5678 is stored as 12345678), so the number transferred reflects Heartland's stored value. |
Field | Balance | Balance | Required. Stores the gift card's current balance from Heartland in the iPaaS.com Balance field. iPaaS.com will not create a gift card without a balance, and Heartland requires a balance to create the card. |
Static | "Gift Card" | Type | Required. Sets the iPaaS.com gift card Type to the fixed value "Gift Card", identifying the record as a gift card. iPaaS.com documents "Giftcard" and "Store Credit" as its accepted type values; confirm in staging that the shipped value is accepted for your subscription. |
Dynamic Formula |
| Status | Required. Derives the gift card's status and stores it in the iPaaS.com Status field: Redeemed when the balance is 0, Expired when the card has expired, and Active otherwise. All three values are accepted by iPaaS.com. |
Field | ExpiresAt | ExpirationDate | Optional. Stores the gift card's expiration date from Heartland in the iPaaS.com ExpirationDate field. |
Dynamic Formula |
| Description | Optional. Builds the gift card Description from the card's activity history. When the card has one or more activity records, the Description is set from the reason recorded on the card's first activity; when the card has no activity, the Description is left empty. |
Dynamic Formula |
| Originating_SystemId | Optional. Sets the originating system on the iPaaS.com gift card so the record is attributed to the correct source system. This value is applied automatically by the integration and does not require configuration. iPaaS.com accepts it only when the record is created. |
Add Heartland Gift Card Activity TO iPaaS.com
This collection is a child of Add Heartland Gift Card TO iPaaS.com. It does not run on its own and has no schedule, webhook, or Manual Sync entry of its own.
Mapping Filter
This mapping collection does not have a mapping filter applied. All records routed to it are processed without additional filtering conditions.
Description: Attaches the gift card's existing Heartland activity history to the iPaaS.com Gift Card record created by the parent collection. Each activity record describes one transaction against the card. The association to the parent gift card is supplied by the parent transfer and is not a subscriber mapping.
Mapping Type | Source Field (Heartland) | Destination Field (iPaaS.com) | Description |
Lookup Translation | ReasonName | ActivityType | Recommended. Translates the reason recorded on the Heartland gift card activity into the iPaaS.com ActivityType through the Gift Card Activity lookup translation, so each activity record identifies the kind of transaction that occurred. See Gift Card Activity Lookup Translation for the value pairs. A Heartland reason with no entry in the translation is not converted. |
Field | CreatedAt | Timestamp | Recommended. Stores the date and time the activity was created in Heartland in the iPaaS.com Timestamp field, recording when the activity occurred. |
Field | DeltaBalance | Amount | Recommended. Stores the amount of the balance change from the Heartland activity in the iPaaS.com Amount field, recording how much the gift card balance changed for this activity. |
Field | LocalCreatedAt | Location | Optional. Stores the Heartland LocalCreatedAt value from the activity in the iPaaS.com Location field. |
Update Heartland Gift Card TO iPaaS.com
Mapping Filter
This mapping collection does not have a mapping filter applied. All records routed to it are processed without additional filtering conditions.
Description: Updates an iPaaS.com Gift Card record that is already linked to a Heartland gift card. Only Balance and Status are refreshed from Heartland; every other mapped field is written back from the record's own current iPaaS.com value so it is not replaced. Each of those preservation mappings uses a Dynamic Formula sourced from DestinationValue.[FieldName], which reads the current iPaaS.com value for the field and writes it back unchanged. To hand a preserved field to Heartland instead, change its mapping to draw from a Heartland source.
Mapping Type | Source Field (Heartland) | Destination Field (iPaaS.com) | Description |
Field | Balance | Balance | Required. Updates the iPaaS.com Balance field with the gift card's current balance from Heartland. This is the primary value refreshed by this collection and the reason the update runs. |
Dynamic Formula |
| Status | Required. Derives the gift card's status from the Heartland balance and expiration and stores it in the iPaaS.com Status field. Refreshed alongside Balance so the status stays consistent with the current balance. |
Dynamic Formula |
| Number | Preserves the existing iPaaS.com gift card number rather than replacing it, keeping the number — which is also the external-id link — stable. Note that iPaaS.com ignores an incoming number on update in any case, so this mapping is a safeguard rather than the mechanism that keeps the number stable. |
Dynamic Formula |
| Type | Preserves the existing iPaaS.com gift card Type rather than replacing it. The iPaaS.com record requires a type, so preserving it here keeps that required value populated. |
Dynamic Formula |
| Description | Preserves the existing iPaaS.com Description rather than replacing it, so the description established when the card was created is retained instead of being rebuilt from the latest activity. |
Dynamic Formula |
| ExpirationDate | Preserves the existing iPaaS.com expiration date rather than replacing it. Change this mapping to the Heartland ExpiresAt field if expiration changes in Heartland should propagate. |
Dynamic Formula |
| Originating_SystemId | Preserves the existing iPaaS.com originating system so the record stays attributed to the source system it was created under. iPaaS.com ignores an incoming originating system on update, so this mapping is a safeguard rather than the mechanism that keeps the value stable. |
Update Heartland Gift Card Additional Activity TO iPaaS.com
This collection is a child of Update Heartland Gift Card TO iPaaS.com. It does not run on its own and has no schedule, webhook, or Manual Sync entry of its own. It is a distinct collection from Add Heartland Gift Card Activity TO iPaaS.com: where that collection brings over a card's history when the card is first created in iPaaS.com, this one carries the additional activity recorded against a card that already exists there.
Mapping Filter
This mapping collection does not have a mapping filter applied. All records routed to it are processed without additional filtering conditions.
Description: Attaches additional Heartland gift card activity to the iPaaS.com Gift Card record updated by the parent collection. The mappings are identical to those of the Add-side activity collection; only the parent and the timing differ.
Mapping Type | Source Field (Heartland) | Destination Field (iPaaS.com) | Description |
Lookup Translation | ReasonName | ActivityType | Recommended. Translates the reason recorded on the Heartland gift card activity into the iPaaS.com ActivityType through the Gift Card Activity lookup translation, so each additional activity record identifies the kind of transaction that occurred. See Gift Card Activity Lookup Translation for the value pairs. A Heartland reason with no entry in the translation is not converted. |
Field | CreatedAt | Timestamp | Recommended. Stores the date and time the activity was created in Heartland in the iPaaS.com Timestamp field, recording when the activity occurred. |
Field | DeltaBalance | Amount | Recommended. Stores the amount of the balance change from the Heartland activity in the iPaaS.com Amount field, recording how much the gift card balance changed for this activity. |
Field | LocalCreatedAt | Location | Optional. Stores the Heartland LocalCreatedAt value from the activity in the iPaaS.com Location field. |
Gift Card Activity Lookup Translation
Both child activity collections use the same Gift Card Activity lookup translation to convert the Heartland activity ReasonName into the iPaaS.com ActivityType. The shipped translation contains the following value pairs:
Source Value (Heartland ReasonName) | Destination Value (iPaaS.com ActivityType) |
Employee | Issue |
Gift | Issue |
Promotion | Issue |
Expiration | Void |
Correction | Adjust |
A Heartland reason that does not appear in this table is not converted, and the resulting iPaaS.com activity record has no activity type. Review the reasons your business actually uses in Heartland and add an entry for each one that is missing. iPaaS.com also accepts the activity types Redeem and Reinstate, which no shipped entry produces; add entries mapping to those values if your Heartland reasons warrant them.
Unmapped Field Overwrite Risk
Updating an iPaaS.com Gift Card record replaces the whole record. Every writable field the collection does not supply is overwritten with an empty value. This is the reason the Update collection carries five preservation mappings — but those five do not cover every writable field on the record.
The iPaaS.com Gift Card record exposes the following writable values: Number, Description, Type, Status, Balance, OriginalAmount, PurchaseDate, CustomerId, TransactionId, ReceivingCustomer, ReceivingCustomerEmail, ExpirationDate, Originating_SystemId, activity records, custom fields, and external ids.
Update Heartland Gift Card TO iPaaS.com maps Number, Description, Type, Status, Balance, ExpirationDate, and Originating_SystemId. The following writable fields are not mapped and will be cleared on every update:
OriginalAmount
PurchaseDate
CustomerId
TransactionId
ReceivingCustomer
ReceivingCustomerEmail
Any custom field on the Gift Card record
The same fields are also unmapped on Add Heartland Gift Card TO iPaaS.com, but there the consequence is only that they start out empty on a newly created record, since there is no prior value to lose.
The remedy is the same technique the collection already uses for its five preserved fields: for each field you want to keep, add a Dynamic Formula mapping to the Update collection whose source is DestinationValue.[FieldName] — for example, DestinationValue.OriginalAmount, DestinationValue.PurchaseDate, DestinationValue.CustomerId, DestinationValue.TransactionId, DestinationValue.ReceivingCustomer, and DestinationValue.ReceivingCustomerEmail. Each reads the record's current iPaaS.com value and writes it back unchanged.
This matters most if you populate any of these fields in iPaaS.com outside this integration — linking a gift card to a customer or a transaction, for instance, or recording who received the card. Without a preservation mapping, that association is lost the first time Heartland reports a balance change.
Two fields are exempt because iPaaS.com ignores them on update: the Number and the Originating_SystemId are accepted only when the record is created. Even without their preservation mappings they would not be cleared. The practical consequence is the reverse of an overwrite risk — a gift card number that changes in Heartland can never be pushed to an already-linked iPaaS.com record, and must be corrected in iPaaS.com directly.
Activity records are never cleared, only added. An update does not remove existing iPaaS.com activity. However, iPaaS.com does not support modifying an existing activity record by its id, and an update that references one is treated as a new activity instead — so repeated transfers can accumulate duplicate activity rather than lose it.
Disabled Outbound Gift Card Collections
Two collections exist for the opposite direction, writing gift card data from iPaaS.com into Heartland:
(DISABLED) Add Heartland Gift Card FROM iPaaS.com
(DISABLED) Update Heartland Gift Card FROM iPaaS.com
Neither transfers any records. Gift cards are inbound-only in practice — Heartland to iPaaS.com. These two collections are retained as non-functional templates for completeness alongside the inbound collections, and they should be left as shipped.
They are disabled for a substantive reason, not an oversight. Heartland does not support setting or maintaining gift card balances from an outside system. The only reliable way to change a Heartland gift card balance is through Heartland's own adjustment activity, and the behavior that would let an outbound transfer set a balance directly is undocumented and may be removed by Heartland at any time. Heartland is therefore the source of truth for all gift card information, and gift card data should flow only from Heartland to iPaaS.com.
How the disabled state is recorded. The (DISABLED) prefix on the collection name is the only place this state is recorded. There is no separate active or enabled flag on these collections that you can inspect or toggle in the mapping list — the name is the record. Do not remove the prefix, and do not assume a collection without the prefix behaves the same way as one with it.
What enforces it. Each collection carries a mapping filter that throws an error and then returns false, so no record can reach the mappings under any circumstance. Both collections carry the identical filter:
throw new Exception("Disable gift card webhooks from iPaaS to Heartland. Gift card transfers to Heartland are not currently supported!");
return false;//This mapping colletion is intentionally disabled
//Heartland does not support setting card balances in this manner
//This mapping is for development purposes only!Every record routed to either collection hits the throw on the first line and is rejected with the message "Disable gift card webhooks from iPaaS to Heartland. Gift card transfers to Heartland are not currently supported!" The return false on the following line is never reached, and would reject the record in any case. The comments below it are inert.
What a subscriber should expect. If a gift card is somehow routed to either collection, the transfer fails with that message and it appears in the iPaaS.com Dashboard error logs. This is expected behavior, not a fault to troubleshoot — the message is the collection announcing that it is intentionally switched off. No Heartland gift card is created or changed. The correct response is to stop routing gift cards outbound, not to modify the filter.
The mappings configured on these collections are template defaults that never execute. For reference, the Add collection would set the Heartland Number, Balance, ReasonId, and ExpiresAt; the Update collection would set Balance, Number, and ExpiresAt. Both use the formula (Status == "Void" ? 0 : Balance) for the balance, writing 0 when the iPaaS.com card status is "Void" and otherwise the iPaaS.com balance.
Error Handling
Missing gift card number: the Number is required in iPaaS.com. When Heartland does not supply a number, or the Number mapping does not resolve, the iPaaS.com Gift Card record is not created. Confirm the card has a number in Heartland and that the mapping resolves before retrying.
Missing balance: the Balance is required in iPaaS.com, and Heartland requires a balance to create the card. A gift card without a balance will not be created in iPaaS.com.
Status formula returns no value: the Status is required in iPaaS.com. If the status formula is edited and can return no value for some cards, those transfers fail. Confirm the formula returns one of Active, Expired, Redeemed, or Void for every input.
Type not accepted: the Type is required in iPaaS.com and is validated against a fixed list of accepted values. If the static type value is rejected, the gift card is not created. Set the static value to an accepted type and re-transfer.
Activity type not translated: when a Heartland activity carries a reason that has no entry in the Gift Card Activity lookup translation, the reason is not converted and the activity record has no activity type. The gift card transfer itself is not blocked. Add the missing reason to the lookup translation and re-transfer to populate it.
Gift card not found: when a Manual Sync is run for a gift card number that does not exist in Heartland, or the card cannot be retrieved, the transfer fails and no iPaaS.com record is created or updated. Confirm the number is correct, in Heartland's stored form with non-alphanumeric characters removed, and that the card is still present in Heartland.
Gift card skipped during a transaction transfer: when a transaction pays with a gift card but no card number can be recovered from the payment or line item description, or the card cannot be retrieved from Heartland, no gift card transfer is attempted. The transaction continues without error, so the gift card may be absent or out of date in iPaaS.com. Transfer the card through Manual Sync if it is needed.
Heartland API unavailable: when Heartland is temporarily unreachable at the time of a transfer, the transfer fails, including any child activity. The error appears in the iPaaS.com Dashboard error logs, and the record can be retried through a new polling cycle or Manual Sync.
Outbound transfer rejected: an attempt to transfer a gift card from iPaaS.com to Heartland fails with the message "Disable gift card webhooks from iPaaS to Heartland. Gift card transfers to Heartland are not currently supported!". This is the expected result of the intentionally disabled outbound collections and requires no remediation.
Testing & Validation
Test Scenarios
New gift card created — create a gift card in Heartland with a number and a balance, transfer it, and confirm an iPaaS.com Gift Card record is created with the matching number, balance, and a Type of "Gift Card", linked by the Heartland gift card number.
Activity history attached on create — transfer a Heartland gift card that already has activity, and confirm the child activity records are created against the new iPaaS.com gift card with the correct timestamp, amount, location, and activity type.
Balance refreshed on update — change the balance of a linked gift card in Heartland, transfer it again, and confirm the iPaaS.com Balance is updated and no duplicate gift card is created.
Preserved fields survive an update — note the Description, Type, ExpirationDate, and Originating_SystemId on a linked iPaaS.com gift card, transfer the card again, and confirm all four are unchanged.
Unmapped fields are cleared on update — populate OriginalAmount, PurchaseDate, CustomerId, or ReceivingCustomer on a linked iPaaS.com gift card, transfer the card again, and confirm the value is cleared. This is the expected behavior without a preservation mapping.
Preservation remedy works — add a Dynamic Formula mapping sourced from DestinationValue.CustomerId to the Update collection, repeat the previous scenario, and confirm the value now survives the update.
Number does not propagate on update — change a gift card number in Heartland on a card that is already linked, transfer it again, and confirm the iPaaS.com Number is unchanged. iPaaS.com accepts the number only when the record is created.
Originating system does not propagate on update — confirm the same for Originating_SystemId.
Status derives correctly — transfer three gift cards: one with a positive balance, one with a zero balance, and one that has expired. Confirm the iPaaS.com statuses resolve to Active, Redeemed, and Expired respectively.
Description built from activity — transfer a new gift card that has at least one activity and confirm the Description is populated from the reason on its first activity. Transfer a new gift card with no activity and confirm the Description is left empty.
Additional activity appended on update — record a new activity against a linked gift card in Heartland, transfer the card again, and confirm the new activity appears in iPaaS.com through the Update-side child collection alongside the activity already present.
Duplicate activity check — transfer the same linked gift card twice with no new Heartland activity in between, and confirm whether any activity record is duplicated in iPaaS.com. iPaaS.com adds rather than modifies activity on update, so validate this against your polling frequency.
Untranslated activity reason — record a Heartland activity with a reason that has no lookup translation entry, transfer the card, and confirm the gift card still transfers while that activity record has no activity type.
Non-alphanumeric card number — create a Heartland gift card with a number containing a hyphen, transfer it, and confirm the iPaaS.com number and external id both reflect Heartland's stored form with the hyphen removed.
Gift card paid on a transaction — pay a Heartland transaction with a gift card and transfer the transaction. Confirm the gift card is transferred to iPaaS.com ahead of the transaction and its balance is current.
Gift card issued on a ticket — issue a gift card on a Heartland ticket line item and transfer the ticket. Confirm the gift card is transferred to iPaaS.com.
Manual Sync by number — enter a known Heartland gift card number on the Manual Sync page and confirm that specific gift card and its activity transfer.
Polling — with the subscription enabled, create a gift card in Heartland and confirm it arrives in iPaaS.com on the next polling cycle without manual intervention.
Outbound collections are inert — confirm that no gift card is written from iPaaS.com to Heartland, and that any attempt fails with the disabled-collection message rather than creating a Heartland gift card.
Validation Checklist
Every transferred gift card has a Number, Balance, Type, and Status populated in iPaaS.com.
Each transferred gift card is linked by the Heartland gift card number, and re-transfers update rather than duplicate.
The Status resolves to Active, Redeemed, or Expired consistently with the card's balance and expiration.
On update, Balance and Status change while Description, Type, ExpirationDate, and Originating_SystemId remain as they were.
Every writable gift card field your business relies on is either refreshed from Heartland or protected by a DestinationValue preservation mapping on the Update collection.
Activity records are attached to the correct parent gift card with the expected timestamp, location, amount, and activity type.
Every Heartland gift card activity reason in use has an entry in the Gift Card Activity lookup translation.
Activity counts in iPaaS.com are reviewed after repeated transfers to confirm activity is not accumulating unexpectedly.
Balances in iPaaS.com match Heartland, and are read from the Balance field rather than reconstructed from activity records.
The two outbound collections remain disabled and retain their
(DISABLED)name prefix.
Additional Notes
Gift cards use separate Add and Update collections rather than a single combined collection. The two have deliberately different mappings, so review and configure both — a change to one does not carry over to the other.
Heartland is the source of truth for gift card balances. Editing a balance directly in iPaaS.com will be overwritten on the next transfer of that gift card.
Do not reconstruct a gift card balance by summing its activity records. Heartland activity is not guaranteed to be complete or in order, and some balance changes produce no activity record at all. The Balance field is authoritative.
The Update collection's use of DestinationValue is intentional and is the pattern to follow when you need to protect an additional field. Change a preservation mapping to a Heartland source only when you specifically want Heartland to own that field going forward.
Because gift cards arrive by polling rather than instant webhooks, allow for the polling interval when validating a change made in Heartland.
Reprocess failed records after correcting a mapping or data issue to confirm the transfer succeeds.
Related Documents
Setup & Reference