Skip to main content

Stripe to iPaaS.com Invoice Mapping Documentation

How the Stripe integration writes the pay link, Stripe status, amount paid and payments of the invoices it issued back TO iPaaS.com onto their transactions, and marks a transaction Complete when its invoice is paid in full.

Contents

Summary

iPaaS.com transactions can be updated from the Stripe invoices this integration issued for them, through an automatic write-back after each send, Stripe webhooks, a scheduled poll and Manual Sync. The integration writes back the invoice id, the pay link, the invoice's Stripe status, the amount paid and anything you must act on, and adds the invoice's payments, refunds and disputes as payment lines. When the invoice is paid in full, the transaction becomes Complete; its own amounts, customer and lines stay as your systems set them.

This collection only updates transactions that already exist in iPaaS.com, the ones sent to Stripe through Add/Update Stripe Invoice FROM iPaaS.com (see iPaaS.com to Stripe Invoice Mapping Documentation). Sales that Stripe made on its own arrive through Add/Update Stripe Sale TO iPaaS.com (see Stripe to iPaaS.com Sale Mapping Documentation).

ID Format

Manual Sync ID Format

Enter the Stripe invoice id (it starts in_) on the iPaaS.com Manual Sync page, for example in_1Ucu7H5scPVYZfHF6vmLQCY7. The id of a payment, charge, refund or dispute on the invoice (it starts pi_, ch_, py_, re_ or du_) also finds it.

External ID Format

iPaaS.com saves the Stripe invoice id as the external ID on its own external-ID record. The Stripe invoice carries the iPaaS.com transaction id in its metadata, which is how the integration finds the transaction to update. A re-issued invoice (one voided and issued again after the transaction changed) updates the same transaction, and its invoice number adds -R1, -R2 and so on to the transaction number.

Each payment line is linked by the invoice's external ID, a vertical bar, then the Stripe payment, refund or dispute id (it starts pi_, re_ or du_). A reversal (a refund that failed, a dispute won) adds -reversal to the id.

Deleted Record Support

Not supported in this direction. An invoice voided in Stripe sets Stripe Invoice Status to Void and clears the Stripe Pay Link; nothing is deleted in iPaaS.com. To take an invoice out of use from iPaaS.com, delete the transaction there: Delete Stripe Invoice FROM iPaaS.com voids its open invoice (see iPaaS.com to Stripe Invoice Mapping Documentation).

Custom Field Support

The collections write these iPaaS.com custom fields, which must exist before the first transfer:

Custom field

On

Value

Stripe Invoice ID

Transaction

The Stripe invoice issued for the transaction (it starts in_).

Stripe Pay Link

Transaction

The Stripe page where the customer pays the invoice.

Stripe Invoice Status

Transaction

The invoice's state in Stripe (see Status Write-Back under Mappings).

Stripe Amount Paid

Transaction

The money Stripe received, less refunds and money held by disputes.

Stripe Message

Transaction

Anything you must act on in Stripe; blank when there is nothing.

Stripe Payment ID

Transaction Payment

The Stripe payment, refund or dispute id.

Stripe Fee

Transaction Payment

Stripe's processing fee, or the dispute fee.

An invoice also offers these Stripe values, which you can map to further custom fields you add with + Add Custom Field in the mapping editor: StripeCustomerId (it starts cus_), Currency, DueDate, InvoicePdf, CreatedAt and PaidAt.

Stripe metadata: each metadata key on the Stripe invoice arrives as a custom field of the Stripe record, so a Dynamic Formula can read one with var f = CustomFields == null ? null : CustomFields.FirstOrDefault(x => x.Key == "your key"); return f == null ? null : f.Value; and map it to any iPaaS.com field or custom field. More Stripe values: every other value Stripe holds for the invoice is offered too, for example the amount due, amounts paid in and outside Stripe, starting and ending balances, credit notes, the collection method, finalized, voided and next-attempt times, the receipt number, tax and discount amounts (Taxes, Discounts), the customer's tax ids, Stripe's own custom fields, and, under Details, Stripe's settings for the invoice as name and value pairs (for example payment_settings.payment_method_types). Lines and payments offer the same: each line's period, price, tax and discount amounts and metadata; each payment's charge, card brand, funding and country (never the card number, expiry or fingerprint), receipt, failure reason, refund and dispute details. Stripe's payment secrets (client secrets) are never brought into iPaaS.com.

Mapping Collection Status

  • Status: Enabled.

  • Trigger Events: after each send FROM iPaaS.com that issues, re-issues, voids or closes a Stripe invoice, the integration queues this collection for it (scope invoice.pay_link_updated), with no setup. The Stripe events you turn on under the subscription's Inbound Data Flows bring later changes: invoice.finalized, invoice.paid, invoice.payment_succeeded, invoice.voided, invoice.marked_uncollectible, invoice.updated, payment_intent.succeeded, payment_intent.processing, payment_intent.payment_failed, charge.refunded, refund.created, refund.updated, refund.failed, charge.dispute.created, charge.dispute.updated, charge.dispute.closed, charge.dispute.funds_withdrawn and charge.dispute.funds_reinstated. A scheduled iPaaS.com Event with the scope invoice.poll catches anything a webhook missed, and Manual Sync is available by Stripe invoice id. The payment child collection transfers with the invoice.

Duplicate or Conflicting Mappings

  • Add/Update Stripe Sale TO iPaaS.com also brings Stripe transactions into iPaaS.com. The two collections are separated by Kind: this collection takes Invoice (the invoices this integration issued), that one takes Sale. Keep both filters' Kind conditions as they are, so each Stripe record reaches exactly one collection.

  • Add/Update Stripe Invoice FROM iPaaS.com sends the same transactions to Stripe. This collection writes only the Stripe fields, the status when the invoice is paid, and the payment lines, so the two don't overwrite each other's values.

Record Matching

The collection has no Collision Handling Method. It never creates a transaction: the invoice's metadata names the iPaaS.com transaction it was issued for, and that transaction is updated. Each payment line is matched by its Stripe id, so a payment is never added twice.

Unmapped Field Overwrite Risk

An update replaces the whole record, so the template maps every transaction field it can with a formula that returns the value already on the transaction (CompanyId, CustomerId, EmailAddress, ParentId, the amounts, TotalQty, TransactionNumber, Type, SystemId, TransactionCreatedDateTime and TransactionUpdatedDateTime), so no transaction field is cleared by the write-back. Keep those mappings: without one, an update clears that field (without SystemId iPaaS.com refuses the update).

Supported Child Collections

  • Add/Update Stripe Invoice Payment TO iPaaS.com (Transaction Payment): the invoice's payments, and a payment line for each refund, dispute and reversal.

System Caveats

Stripe Caveats

  • Pay link lifetime: Stripe's documentation says invoice links expire 30 days after the due date (30 days after the invoice is issued when there is no due date, and never later than 120 days) (Stripe Hosted Invoice Page, read 2026-11-20).

  • Payments that settle later: a bank debit arrives as Pending, then becomes Paid or Failed.

  • Rate limiting: when Stripe asks the integration to slow down, the transfer is rescheduled automatically and resumes after the wait. No action is needed.

iPaaS.com Caveats

  • The transaction must exist: this collection updates the transaction the invoice was issued for, and never creates one.

  • Payment Method: every payment line needs a Payment Method that exists in iPaaS.com, named in the Method mapping of Add/Update Stripe Invoice Payment TO iPaaS.com.

  • Payment status is text: iPaaS.com stores a payment line's status as text, so Stripe's status words are saved as they are.

  • Child collections move with the invoice: don't add the payment collection as a collection of its own. A record sent on its own is refused.

Setup Requirements

Stripe Configuration

iPaaS.com Configuration

  • Webhooks: turn on the Stripe events you want under the subscription's Inbound Data Flows. The integration creates and maintains this subscription's Stripe webhook endpoint for you; turning the last event off removes it. Payments and refunds made in Stripe reach iPaaS.com only through these events or the poll.

  • Poll: a scheduled iPaaS.com Event with the scope invoice.poll, for example every 15 minutes.

  • Custom fields: the seven custom fields listed under Custom Field Support.

  • Payment Method: replace the placeholder value described under Mappings before the first transfer.

Integration Flow

  1. A send FROM iPaaS.com queues the write-back, or a Stripe webhook, the invoice.poll Event or a Manual Sync names a Stripe record.

  2. The integration reads the invoice from Stripe, with its payments and each payment's charge, refunds and disputes.

  3. It confirms the invoice was issued by this subscription: its metadata names an iPaaS.com transaction. An invoice issued by another subscription, or one replaced by a re-issued invoice, transfers nothing and logs no error.

  4. It works out the invoice's Stripe status, the amount paid and any message you must act on.

  5. The invoice passes the collection's filter (it must be an Invoice) and is mapped through Update Stripe Invoice TO iPaaS.com, and its payments through Add/Update Stripe Invoice Payment TO iPaaS.com.

  6. iPaaS.com updates the transaction: the Stripe fields, the status when the invoice is paid in full, and a payment line for each new payment, refund, dispute or reversal. A line already posted never changes its amount.

Mappings

Single-line formulas in the tables are shown without the one-line explanatory comment the template puts above them; the logic is the same.

Update Stripe Invoice TO iPaaS.com

iPaaS.com data type: Transaction

Mapping Filter

// Leave as is: only the Stripe invoices this subscription issued update a transaction here.
return Kind == "Invoice";

Filter Description: only invoices this integration issued are processed (Kind is Invoice); sales Stripe made (Kind is Sale) are left to Add/Update Stripe Sale TO iPaaS.com. A record that fails the filter is skipped with no error. Leave the filter as it is.

Description: updates the transaction an invoice was issued for with the invoice's Stripe fields and, when it is paid in full, its status, while keeping every value your systems own.

Mapping Type

Source Field (Stripe)

Destination Field (iPaaS.com)

Description

Dynamic Formula

return DestinationValue != null ? DestinationValue.CompanyId : null;

CompanyId

Recommended. Keeps the transaction's company. Leave this mapping in place: an update replaces the whole record.

Dynamic Formula

return DestinationValue != null ? DestinationValue.CustomerId : null;

CustomerId

Recommended. Keeps the transaction's customer.

Dynamic Formula

return DestinationValue != null ? DestinationValue.DiscountAmount : 0;

DiscountAmount

Recommended. Keeps the transaction's discount: Stripe's copy of the invoice never changes the amounts on the iPaaS.com record.

Dynamic Formula

return DestinationValue != null ? DestinationValue.EmailAddress : CustomerEmail;

EmailAddress

Recommended. Keeps the transaction's email; without this mapping the email is cleared on the next invoice update.

Dynamic Formula

return DestinationValue != null ? (object)DestinationValue.ParentId : null;

ParentId

Recommended. Keeps the transaction's parent.

Dynamic Formula

return DestinationValue != null ? DestinationValue.ShippingAmount : 0;

ShippingAmount

Recommended. Keeps the transaction's shipping.

Dynamic Formula

if (DestinationValue == null) return null; if (DestinationValue.Status == "Cancelled") return DestinationValue.Status; if (Status == "Paid") return "Complete"; return DestinationValue.Status;

Status

Required. Paid in full in Stripe becomes Complete; a Cancelled transaction stays Cancelled; otherwise the transaction keeps its own status. Change "Complete" if your systems use another status for a paid order.

Field

AmountPaid

Stripe Amount Paid

Recommended. The money Stripe received for the invoice, less refunds and money held by disputes.

Field

StripeInvoiceId

Stripe Invoice ID

Recommended. The Stripe invoice issued for the transaction (it starts in_). When the transaction is sent FROM iPaaS.com again, the integration finds its invoice by this id first, so keep the mapping.

Field

Status

Stripe Invoice Status

Recommended. The invoice's state in Stripe (see Status Write-Back below).

Field

Message

Stripe Message

Recommended. Anything you must act on in Stripe, for example "Cancelled in iPaaS.com but paid in Stripe: refund it in Stripe if needed"; blank when there is nothing.

Field

PayLink

Stripe Pay Link

Recommended. The Stripe page where the customer pays, for your own emails or portal. Written when the invoice is issued or re-issued, and cleared when it is voided or paid.

Dynamic Formula

return DestinationValue != null ? DestinationValue.Subtotal : Total;

Subtotal

Recommended. Keeps the transaction's subtotal.

Dynamic Formula

return DestinationValue != null ? (object)DestinationValue.SystemId : SpaceportSystemId;

SystemId

Required. Keeps the system the transaction belongs to. Without it iPaaS.com refuses every invoice update with VALD-1023.

Dynamic Formula

return DestinationValue != null ? DestinationValue.TaxAmount : 0;

TaxAmount

Recommended. Keeps the transaction's tax.

Dynamic Formula

return DestinationValue != null ? DestinationValue.Total : Total;

Total

Recommended. Keeps the transaction's total. What was paid in Stripe is in Stripe Amount Paid and the payment lines.

Dynamic Formula

return DestinationValue != null ? DestinationValue.TotalQty : 0;

TotalQty

Optional. Keeps the transaction's item count.

Dynamic Formula

return DestinationValue != null ? DestinationValue.TransactionNumber : TransactionNumber;

TransactionNumber

Required. Keeps the transaction's number. The Stripe invoice carries the same number; a re-issued invoice adds -R1, -R2 and so on.

Dynamic Formula

return DestinationValue != null ? DestinationValue.Type : "Invoice";

Type

Required. Keeps the transaction's type.

Dynamic Formula

return DestinationValue != null ? (object)DestinationValue.TransactionCreatedDateTime : null;

TransactionCreatedDateTime

Optional. Keeps the value your systems set: Stripe has no TransactionCreatedDateTime, and an update replaces the whole record.

Dynamic Formula

return DestinationValue != null ? (object)DestinationValue.TransactionUpdatedDateTime : null;

TransactionUpdatedDateTime

Optional. Keeps the value your systems set: Stripe has no TransactionUpdatedDateTime, and an update replaces the whole record.

Status Write-Back: the Stripe Invoice Status values are Draft, Open, PartiallyPaid, Paid, PartiallyRefunded, Refunded, PaidWithCredit (Stripe closed the invoice for less with a credit note), Disputed (a dispute is open or was lost), Void and Uncollectible. Only a paid-in-full invoice changes the transaction's own Status.

Add/Update Stripe Invoice Payment TO iPaaS.com

iPaaS.com data type: Transaction Payment

Description: writes the invoice's payments onto the transaction, and a payment line for each refund, dispute and reversal that happens later. A line's amount never changes once it is posted.

Mapping Type

Source Field (Stripe)

Destination Field (iPaaS.com)

Description

Field

Amount

Amount

Required. Positive for a payment and for money given back to you (a refund that failed, a dispute won), negative for a refund and a dispute. Keep this mapping: without it a new payment line is written as 0.00.

Field

Description

Description

Recommended. A short description of the line, for example the Stripe payment id with the card brand and last four digits.

Static

"REPLACE with your iPaaS.com card Payment Method name"

Method

Required. The name of a Payment Method configured in iPaaS.com.

Field

Status

Status

Recommended. The line's state in Stripe's words (see the values below).

Field

StripeFee

Stripe Fee

Optional. What Stripe charged for this line (its processing fee, or the dispute fee); blank until Stripe has settled it.

Field

StripePaymentId

Stripe Payment ID

Recommended. Stripe's id for the line: the payment (it starts pi_), refund (re_) or dispute (du_).

Placeholder value — replace during implementation: the Method value "REPLACE with your iPaaS.com card Payment Method name". Change it to the name of the Payment Method you use for Stripe payments, exactly as configured in iPaaS.com (for example Credit Card). This must be done before the first transfer; until it is, iPaaS.com refuses the invoice's payments (see Error Handling).

Payment statuses: a payment is Paid, Pending (a bank debit not settled yet), Failed (a bank debit that failed after Pending) or Authorized (not captured yet). A refund is Refunded or Pending. A dispute is Disputed, Won or Lost. Money given back is RefundReversed or Reinstated. To use your own status names, change the Status mapping to a Lookup Translation that covers every value; a value with no translation row is saved with an empty status.

Only the card brand and last four digits reach iPaaS.com; no field can hold a card number.

Error Handling

Errors appear in iPaaS.com Dashboard / Integration Monitoring / Error Logs. Every Stripe error code is described in Stripe Error Messages.

  • "VALD-1036 - Value (REPLACE with your iPaaS.com card Payment Method name) provided for Payment Method is not valid." The Method mapping still holds the template value, or names a Payment Method that doesn't exist in iPaaS.com (the message names the value sent). Resolution: change the mapping to your Payment Method, then run a Manual Sync with the Stripe invoice id.

  • STRP-INTL-1003: "Stripe invoice … couldn't be written back onto the iPaaS.com transaction." The write-back after a send couldn't be queued. The send itself succeeded. Resolution: nothing in most cases; the invoice's webhook or the next poll writes it back, or send the transaction FROM iPaaS.com again.

  • STRP-BIZL-1011: "This record moves with its transaction or customer, never on its own." The payment collection was added as a collection of its own. Resolution: remove that collection.

  • STRP-EXTN-1003 (Stripe rate limit) and STRP-EXTN-1002 (Stripe temporarily unavailable). Stripe limited the number of calls or didn't answer. Resolution: nothing; the transfer is retried. Lower Concurrent Connections if the rate limit appears often.

  • STRP-AUTH-1002 (Secret Key refused) and STRP-AUTZ-1001 (restricted key lacks a permission). Resolution: create the key again in Stripe, or add the permission the message names, and update Secret Key.

An invoice that isn't one this subscription issued (see Integration Flow, step 3) transfers nothing and is not an error.

Testing and Validation

Test Scenarios

  1. Send a test transaction FROM iPaaS.com so its Stripe invoice is issued. Confirm Stripe Invoice ID, Stripe Pay Link and Stripe Invoice Status (Open) appear on the transaction without waiting for an event.

  2. Pay the invoice in Stripe test mode. Confirm a Paid payment line with its Stripe Fee, Stripe Amount Paid equal to the total, Stripe Invoice Status Paid, the transaction's Status Complete, and the pay link cleared.

  3. Refund part of the payment in Stripe. Confirm a negative Refunded payment line, Stripe Invoice Status PartiallyRefunded, and the transaction's amounts unchanged.

  4. Void an open invoice in Stripe. Confirm Stripe Invoice Status Void, the pay link cleared, and a warning in Stripe Message.

  5. Run a Manual Sync with the Stripe invoice id. Confirm the same transaction is updated and no payment line is added twice.

Validation Checklist

  • The payment Method names a Payment Method that exists in iPaaS.com.

  • The seven custom fields exist.

  • The invoice.poll Event is scheduled, and the Stripe events you want are on under Inbound Data Flows.

  • The formulas that keep the transaction's own values are in place.

Additional Notes

Related Documents

Related Mapping Documentation

Did this answer your question?