Skip to main content

Stripe to iPaaS.com Customer Mapping Documentation

How the Stripe integration brings Stripe customers TO iPaaS.com with their billing and shipping addresses, links each one to an existing iPaaS.com customer by its link, its iPaaS.com id or its email, and creates a customer only when there is none.

Contents

Summary

iPaaS.com customers can be transferred from Stripe customers through Stripe webhooks, a scheduled poll, Manual Sync, and automatically before a Stripe-made sale is created. Each Stripe customer arrives with its billing and shipping addresses. A Stripe customer is linked to the iPaaS.com customer it was created for, or else to the one iPaaS.com customer with the same email; only when there is none is a new iPaaS.com customer created. An iPaaS.com customer that already exists keeps the names, company, comment and email your systems gave it. Stripe metadata on the customer arrives as custom fields, and many more of the Stripe customer's values are available to map (see Custom Field Support).

ID Format

Manual Sync ID Format

Enter the Stripe customer id (it starts cus_) on the iPaaS.com Manual Sync page, for example cus_VeA0XhxuSFno8y.

External ID Format

iPaaS.com saves the Stripe customer id as the external ID on its own external-ID record, which is how later updates find the same customer. A new iPaaS.com customer's CustomerNumber is STRIPE- followed by its Stripe customer id, for example STRIPE-cus_VeA0XhxuSFno8y, so you can tell where it came from.

Each address is linked by the customer's external ID, a vertical bar, then billing or shipping, for example cus_VeA0XhxuSFno8y|billing.

Deleted Record Support

Not supported. A customer deleted in Stripe is not transferred, and the iPaaS.com customer is kept.

Custom Field Support

The collection writes the Stripe Customer ID custom field (the Stripe customer id, it starts cus_), which must exist on iPaaS.com customers before the first transfer.

A Stripe customer also offers these values, which you can map to further custom fields you add with + Add Custom Field in the mapping editor:

  • Phone, Currency and CreatedAt.

  • IndividualName: the person's name on the Stripe customer.

  • Balance (in the currency's smallest unit: 1250 is 12.50 USD; a negative balance is a credit), TaxExempt (none, exempt or reverse), InvoicePrefix, NextInvoiceSequence and PreferredLocales (for example "en, fr-CA").

  • TaxIdData: the customer's tax IDs as type:value pairs separated by semicolons, for example "eu_vat:DE123456789".

  • DefaultSource (the id of the default payment source) and TestClock (Stripe test mode only).

  • InvoiceSettings_Footer, InvoiceSettings_DefaultPaymentMethod, InvoiceSettings_RenderingOptions_AmountTaxDisplay and InvoiceSettings_RenderingOptions_Template.

  • Tax_IpAddress and CashBalance_Settings_ReconciliationMode.

  • Read only: Delinquent (true when the customer's latest Stripe invoice is past due or failed), Livemode (false for a test-mode customer), Object, CustomerAccount, and the customer's discount: Discount_Id, Discount_Coupon, Discount_PromotionCode, Discount_Start and Discount_End.

  • On the shipping address, read only: Carrier and TrackingNumber.

Stripe metadata on the customer is offered to mappings as custom fields under the metadata's own names, 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. Names that start with ipaas_ belong to the integration and are left out.

Mapping Collection Status

  • Status: Enabled.

  • Trigger Events: customer.created and customer.updated, turned on under the subscription's Inbound Data Flows. A scheduled iPaaS.com Event with the scope customer.poll catches anything a webhook missed, and Manual Sync is available by Stripe customer id. A Stripe-made sale also brings its customer in first when needed, whether or not these events are on, as long as this collection is turned on. The address child collection transfers with the customer.

Duplicate or Conflicting Mappings

  • Add/Update Stripe Customer FROM iPaaS.com writes the same customers the other way. Changes made in iPaaS.com go to Stripe through that collection, and changes made in Stripe come back through this one. Decide which system owns each field before turning both on.

Customer Matching

The collection has no Collision Handling Method: the integration matches automatically, in this order.

  • The link: a Stripe customer already linked to an iPaaS.com customer updates that customer.

  • The iPaaS.com id: a Stripe customer this integration created carries its iPaaS.com customer's id, and is linked to it.

  • The email: otherwise the Stripe customer is linked to the one iPaaS.com customer with the same email.

  • A new customer: when no iPaaS.com customer has the email, a new one is created.

  • Refusal: when the email belongs to an iPaaS.com customer already linked to a different Stripe customer, or to several iPaaS.com customers, nothing is transferred and the error list shows STRP-BIZL-1009. Merge the Stripe customers or give one its own email; if several iPaaS.com customers share the email, merge them in iPaaS.com first.

Unmapped Field Overwrite Risk

An update replaces the whole record, so a field these collections don't map can be cleared when the customer transfers again. The template keeps the customer's own CustomerNumber, EmailAddress, FirstName, LastName, Company and Comment, and the address's FirstName, LastName, Company and Address3, with formulas that return the value already there. The address's Type is kept the same way (return DestinationValue != null ? (object)DestinationValue.Type : null;), so every field Stripe doesn't own is kept. Keep every mapping: a field whose mapping is removed is written empty on the next update (removing Address1 blanks the street).

Supported Child Collections

  • Add/Update Stripe Customer Address TO iPaaS.com (Customer Address): the Stripe customer's billing address and shipping address.

System Caveats

Stripe Caveats

  • One name field: Stripe keeps a single name, so a two-part name is split into first and last name (the last word is the last name).

  • Two addresses: Stripe keeps one billing address and one shipping address per customer.

  • Name and phone on the billing address: Stripe keeps a name and phone on the shipping address only. The billing address arrives with the customer's individual name (else its name), and with the billing phone the integration kept on the Stripe customer when it sent one FROM iPaaS.com (else the customer's phone).

  • Customers with no phone in Stripe: a Stripe customer with no phone, for example one last sent FROM iPaaS.com by an earlier version of the integration, which didn't send the billing phone, brings a blank billing address phone TO iPaaS.com when it is changed in Stripe. Send such customers FROM iPaaS.com once (Manual Sync) so their phone is written to Stripe; a phone already blanked this way has to be entered again in iPaaS.com.

  • Country: Stripe stores a two-letter country code (for example US).

  • 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

  • Email required: iPaaS.com requires an email on every customer and allows one customer per email, so a Stripe customer with no email isn't brought in.

  • A name or company: iPaaS.com needs at least one of a first name, a last name or a company on every customer.

  • Child collections move with the customer: don't add the address 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 customer.created and customer.updated 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.

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

  • Custom field: Stripe Customer ID on iPaaS.com customers.

Integration Flow

  1. A Stripe webhook, the customer.poll Event, a Manual Sync, or a Stripe-made sale whose customer isn't in iPaaS.com yet names a Stripe customer.

  2. The integration reads the customer from Stripe. A deleted customer transfers nothing.

  3. It finds the iPaaS.com customer to update (see Customer Matching). When the email belongs to another linked customer, or to several, it stops with STRP-BIZL-1009.

  4. The customer passes the collection's filter and is mapped through Add/Update Stripe Customer TO iPaaS.com, and its billing and shipping addresses through Add/Update Stripe Customer Address TO iPaaS.com.

  5. iPaaS.com updates the linked customer, or creates one with the number STRIPE- and the Stripe customer id.

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.

Add/Update Stripe Customer TO iPaaS.com

iPaaS.com data type: Customer

Mapping Filter

// Stripe customers with an email and a name or company. iPaaS.com links and matches customers by email, and refuses a customer
// with neither a name nor a company, so those are skipped instead of failing. Their sales still arrive: iPaaS.com sets the
// customer whose email matches the sale's, when there is one.
return !string.IsNullOrEmpty(Email) && (!string.IsNullOrEmpty(Name) || !string.IsNullOrEmpty(Company));

Filter Description: only Stripe customers with an email (Email) and a name (Name) or company (Company) are processed: iPaaS.com requires an email, refuses a customer with neither a name nor a company, and customers are linked and matched by email. A customer without them is skipped with no error; its sales still arrive, and iPaaS.com sets the customer whose email matches. To bring them in anyway, remove the name condition from the filter and give the LastName mapping a fallback, for example ... : (!string.IsNullOrEmpty(LastName) ? LastName : Email).

Description: creates or updates the iPaaS.com customer for each Stripe customer, keeping the values an existing customer already has.

Mapping Type

Source Field (Stripe)

Destination Field (iPaaS.com)

Description

Dynamic Formula

return DestinationValue != null ? DestinationValue.Comment : Description;

Comment

Optional. A new customer gets the Stripe customer's description; an existing customer keeps its own comment.

Dynamic Formula

return DestinationValue != null && !string.IsNullOrEmpty(DestinationValue.Company) ? DestinationValue.Company : Company;

Company

Recommended. iPaaS.com needs a first name, a last name or a company. A customer that has a company keeps it; otherwise the Stripe customer's business name is used.

Dynamic Formula

return DestinationValue != null && !string.IsNullOrEmpty(DestinationValue.CustomerNumber) ? DestinationValue.CustomerNumber : CustomerNumber;

CustomerNumber

Required. An existing customer keeps its number; a new one gets STRIPE- followed by its Stripe customer id.

Dynamic Formula

return DestinationValue != null && !string.IsNullOrEmpty(DestinationValue.EmailAddress) ? DestinationValue.EmailAddress : Email;

EmailAddress

Required. iPaaS.com requires an email and allows one customer per email. A linked customer keeps its own email (how customers are matched); a new customer gets the Stripe email.

Dynamic Formula

return DestinationValue != null && !string.IsNullOrEmpty(DestinationValue.FirstName) ? DestinationValue.FirstName : FirstName;

FirstName

Recommended. A customer that has a first name keeps it; otherwise the Stripe name without its last word.

Dynamic Formula

return DestinationValue != null && !string.IsNullOrEmpty(DestinationValue.LastName) ? DestinationValue.LastName : LastName;

LastName

Recommended. A customer that has a last name keeps it; otherwise the last word of the Stripe name.

Field

Id

Stripe Customer ID

Recommended. The Stripe customer id (it starts cus_). Keep this mapping: Add/Update Stripe Customer FROM iPaaS.com sends only customers whose Stripe Customer ID has a value.

Add/Update Stripe Customer Address TO iPaaS.com

iPaaS.com data type: Customer Address

Description: writes the Stripe customer's billing address and shipping address onto the iPaaS.com customer. An existing address keeps its company, third line and names.

Mapping Type

Source Field (Stripe)

Destination Field (iPaaS.com)

Description

Field

Line1

Address1

Recommended. Street address, line 1. Keep this mapping: removing it blanks the street on every customer update.

Field

Line2

Address2

Optional. Street address, line 2.

Dynamic Formula

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

Address3

Optional. Stripe has no third address line, so an existing address keeps its own.

Field

City

City

Recommended. City.

Dynamic Formula

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

Company

Optional. Stripe keeps no company on an address, so an existing address keeps its own.

Field

Country

Country

Recommended. The two-letter country code Stripe stores (for example US).

Dynamic Formula

return DestinationValue != null && !string.IsNullOrEmpty(DestinationValue.FirstName) ? DestinationValue.FirstName : (Name == null ? null : (Name.Trim().LastIndexOf(' ') > 0 ? Name.Trim().Substring(0, Name.Trim().LastIndexOf(' ')) : Name.Trim()));

FirstName

Recommended. An address with a first name keeps it; a new address takes the name on the Stripe address without its last word (a one-word name is used whole).

Field

IsPrimaryBilling

IsPrimaryBilling

Recommended. True for the Stripe customer's billing address.

Field

IsPrimaryShipping

IsPrimaryShipping

Recommended. True for the Stripe customer's shipping address.

Dynamic Formula

The LastName formula, shown in full after this table

LastName

Recommended. An address with a last name keeps it; a new address takes the last word of the name on the Stripe address (blank for a one-word name).

Field

Phone

PhoneNumber

Optional. The shipping address's phone as Stripe has it. For the billing address, the billing phone the integration kept on the Stripe customer, else the customer's phone.

Field

PostalCode

PostalCode

Recommended. Postal or ZIP code.

Field

State

Region

Recommended. State, province or region, as Stripe stores it.

Dynamic Formula

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

Type

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

LastName formula:

return DestinationValue != null && !string.IsNullOrEmpty(DestinationValue.LastName) ? DestinationValue.LastName : (Name == null || Name.Trim().LastIndexOf(' ') < 0 ? null : Name.Trim().Substring(Name.Trim().LastIndexOf(' ') + 1));

Error Handling

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

  • STRP-BIZL-1009: "Stripe customer … has the email …, which iPaaS.com customer … already has, linked to Stripe customer …" Two Stripe customers share an email that one iPaaS.com customer already holds. Nothing is transferred. Resolution: merge the Stripe customers in Stripe, or give this one its own email, then run a Manual Sync with its Stripe customer id.

  • STRP-BIZL-1009: "Stripe customer …: … iPaaS.com customers have the email …, so it can't be matched to one." Several iPaaS.com customers share the email. Resolution: merge them in iPaaS.com, then resync.

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

  • STRP-EXTN-1003 (Stripe rate limit) and STRP-EXTN-1002 (Stripe temporarily unavailable). 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.

A Stripe customer with no email, or one deleted in Stripe, transfers nothing and is not an error.

Testing and Validation

Test Scenarios

  1. Create a Stripe customer in test mode with an email no iPaaS.com customer has, a name and a billing address. Confirm a new iPaaS.com customer arrives with the number STRIPE- and its Stripe id, Stripe Customer ID, the names split into first and last, and the billing address.

  2. Create a Stripe customer with the email of an existing, unlinked iPaaS.com customer. Confirm that customer is linked and keeps its own names, company and email; no new customer is created.

  3. Change the Stripe customer's shipping address. Confirm the iPaaS.com shipping address is updated and its company and third line are kept.

  4. Create a second Stripe customer with the same email as the first. Confirm nothing is transferred and the error list shows STRP-BIZL-1009.

  5. Run a Manual Sync with the Stripe customer id. Confirm the same customer is updated.

Validation Checklist

  • The Stripe Customer ID custom field exists.

  • customer.created and customer.updated are on under Inbound Data Flows, and the customer.poll Event is scheduled.

  • The Address1 mapping and the formulas that keep existing values are in place.

Additional Notes

  • Initial load: Stripe customers created before the integration was set up are not brought in automatically; use Manual Sync for any you need.

  • Payment methods: no full card or bank number reaches iPaaS.com. For formulas, the customer offers its saved payment sources with their brand and last 4 digits, and its subscriptions, tax IDs, invoice settings, Stripe Tax details, cash balance and invoice credit balance.

Related Documents

Related Mapping Documentation

Did this answer your question?