README.md

tipsi-stripe

React Native Stripe binding for iOS/Android platforms

Requirements

iOS

• Xcode 8+
• iOS 10+
• CocoaPods 1.1.1+

Android

• SDK 17+

Compatibility

This package is now built for React Native 0.40 or greater! If you need to support React Native < 0.40, you should install this package @1.4.0.

Installation

Run npm install --save tipsi-stripe to add the package to your app's dependencies.

iOS

react-native cli

Run react-native link tipsi-stripe so your project is linked against your Xcode project and all CocoaPods dependencies are installed.

CocoaPods

1. Setup your Podfile like the included example/ios/Podfile then run pod install.
2. Open your project in Xcode workspace.
3. Drag the following folder into your project:

• node_modules/tipsi-stripe/ios/TPSStripe/

Manual

1. Open your project in Xcode, right click on Libraries and click Add Files to "Your Project Name".
2. Look under node_modules/tipsi-stripe/ios and add TPSStripe.xcodeproj.
3. Add libTPSStripe.a to Build Phases -> Link Binary With Libraries.
4. Click on TPSStripe.xcodeproj in Libraries and go the Build Settings tab. Double click the text to the right of Header Search Paths and verify that it has $(SRCROOT)/../../react-native/React as well as ${SRCROOT}/../../../ios/Pods/Headers/Public - if they aren't, then add them. This is so Xcode is able to find the headers that the TPSStripe source files are referring to by pointing to the header files installed within the react-native node_modules directory.
5. Whenever you want to use it within React code now you can:

• import stripe from 'tipsi-stripe'

Running Apple Pay in a Real Device

In order to run Apple Pay on an Apple device (as opposed to a simulator), there's an extra step you need to complete in XCode. Without completing this step, Apple Pay will say that it is not supported - even if Apple Pay is set up correctly on the device.

Navigate to the Capabilities tab in your XCode project and turn Apple Pay on. Then, add your Apple Pay Merchant ID to the 'Merchant IDs' section by clicking the '+' icon. Finally, make sure that the checkbox next to your merchant ID is blue and checked off.

Android

react-native cli

Run react-native link tipsi-stripe so your project is linked against your Android project

Manual

In your android/app/build.gradle add:

...
dependencies {
  ...
+ compile project(':tipsi-stripe')
}

In your android/settings.gradle add:

...
+include ':tipsi-stripe'
+project(':tipsi-stripe').projectDir = new File(rootProject.projectDir, '../node_modules/tipsi-stripe/android')

In your android/build.gradle add:

...
allprojects {
  repositories {
    ...
+   maven { url "https://jitpack.io" }
  }
}

In your android/app/src/main/java/com/%YOUR_APP_NAME%/MainApplication.java add:

...
+ import com.gettipsi.stripe.StripeReactPackage;
...
protected List<ReactPackage> getPackages() {
  return Arrays.<ReactPackage>asList(
-   new MainReactPackage()
+   new MainReactPackage(),
+   new StripeReactPackage()
  );
}

Ensure that you have Google Play Services installed:

For Genymotion you can follow these instructions. For a physical device you need to search on Google for 'Google Play Services'. There will be a link that takes you to the Play Store and from there you will see a button to update it (do not search within the Play Store).

Android Pay

For using Android Pay in your android/app/src/main/AndroidManifest.xml add:

<application
...     
+  <meta-data
+    android:name="com.google.android.gms.wallet.api.enabled"
+    android:value="true" />
...
</application>

More information about Android Pay deployment and testing.

Usage

Let's require tipsi-stripe module:

import stripe from 'tipsi-stripe'

And initialize it with your Stripe credentials that you can get from dashboard. If you want to use Apple Pay you must provide your Merchant ID.

stripe.init({
  publishableKey: 'PUBLISHABLE_KEY',
  merchantId: 'MERCHANT_ID', // Optional
  androidPayMode: 'test', // Optional, android only, 'production' by default
})

androidPayMode String (Android only) - Corresponds to WALLET_ENVIRONMENT. Can be one of: test|production.

Token

A token object returned from submitting payment details (via paymentRequestWithApplePay, paymentRequestWithCardForm and createTokenWithCard) to the Stripe API.

token

An object with the following keys:

• tokenId String - The value of the token. You can store this value on your server and use it to make charges and customers.
• created Number - When the token was created.
• livemode Number - Whether or not this token was created in livemode. Will be 1 if you used your Live Publishable Key, and 0 if you used your Test Publishable Key.
• card Object - The credit card details object that were used to create the token.
• bankAccount Object - The external (bank) account details object that were used to create the token.
• extra Object (iOS only)- An additional information that method can provide.

card

An object with the following keys:

• cardId String - The Stripe ID for the card.
• brand String - The card’s brand. Can be one of: JCB|American Express|Visa|Discover|Diners Club|MasterCard|Unknown.
• funding String (iOS only) - The card’s funding. Can be one of: debit|credit|prepaid|unknown.
• last4 String - The last 4 digits of the card.
• dynamicLast4 String (iOS only) - For cards made with Apple Pay, this refers to the last 4 digits of the Device Account Number for the tokenized card.
• isApplePayCard Bool (iOS only) - Whether or not the card originated from Apple Pay.
• expMonth Number - The card’s expiration month. 1-indexed (i.e. 1 == January)
• expYear Number - The card’s expiration year.
• country String - Two-letter ISO code representing the issuing country of the card.
• currency String - This is only applicable when tokenizing debit cards to issue payouts to managed accounts. The card can then be used as a transfer destination for funds in this currency.
• name String - The cardholder’s name.
• addressLine1 String - The cardholder’s first address line.
• addressLine2 String - The cardholder’s second address line.
• addressCity String - The cardholder’s city.
• addressState String - The cardholder’s state.
• addressCountry String - The cardholder’s country.
• addressZip String - The cardholder’s zip code.

bankAccount

An object with the following keys:

• routingNumber String - The routing number of this account.
• accountNumber String - The account number for this BankAccount.
• countryCode String - The two-letter country code that this account was created in.
• currency String - The currency of this account.
• accountHolderName String - The account holder's name.
• accountHolderType String - the bank account type. Can be one of: company|individual.
• fingerprint String - The account fingerprint.
• bankName String - The name of bank.
• last4 String - The last four digits of the account number.

Example

{
  tokenId: 'tok_19GCAQI5NuVQgnjeKNE32K0p',
  created: 1479236426,
  livemode: 0,
  card: {
    cardId: 'card_19GCAQI5NuVQgnjeRZizG4U3',
    brand: 'Visa',
    funding: 'credit',
    last4: '4242',
    expMonth: 4,
    expYear: 2024,
    country: 'US',
    name: 'Eugene Grissom',
    addressLine1: 'Green Street',
    addressLine2: '3380',
    addressCity: 'Nashville',
    addressState: 'Tennessee',
    addressCountry: 'US',
    addressZip: '37211',
  },
  bankAccount: {
    bankName: 'STRIPE TEST BANK',
    accountHolderType: 'company',
    last4: '6789',
    accountHolderName: 'Test holder name',
    currency: 'usd',
    fingerprint: 'afghsajhaartkjasd',
    countryCode: 'US',
    accountNumber: '424542424',
    routingNumber: '110000000',
  },
}

Apple Pay (iOS only)

openApplePaySetup()

Opens the user interface to set up credit cards for Apple Pay.

deviceSupportsApplePay() -> Promise

Returns whether the user can make Apple Pay payments. User may not be able to make payments for a variety of reasons. For example, this functionality may not be supported by their hardware, or it may be restricted by parental controls. Returns true if the device supports making payments; otherwise, false.

NOTE: iOS Simulator always return true

canMakeApplePayPayments([options]) -> Promise

Returns whether the user can make Apple Pay payments with specified options. If there are no configured payment cards, this method always returns false. Return true if the user can make Apple Pay payments through any of the specified networks; otherwise, false.

NOTE: iOS Simulator always return true

options

An object with the following keys:

• networks [String] (Array of String) - Indicates whether the user can make Apple Pay payments through the specified network. Available networks: american_express|discover|master_card|visa. If option does not specify we pass all available networks under the hood.

paymentRequestWithApplePay(items, [options]) -> Promise

Launch the Apple Pay view to accept payment.

items

An array of object with the following keys:

• label String - A short, localized description of the item.
• amount String - The summary item’s amount.

NOTE: The final item should represent your company; it'll be prepended with the word "Pay" (i.e. "Pay Tipsi, Inc $50")

options

An object with the following keys:

• requiredBillingAddressFields String - A bit field of billing address fields that you need in order to process the transaction. Can be one of: all|name|email|phone|postal_address or not specify to disable.
• requiredShippingAddressFields String - A bit field of shipping address fields that you need in order to process the transaction. Can be one of: all|name|email|phone|postal_address or not specify to disable.
• shippingMethods Array - An array of shippingMethod objects that describe the supported shipping methods.
• currencyCode String - The three-letter ISO 4217 currency code.

shippingMethod

An object with the following keys:

• id String - A unique identifier for the shipping method, used by the app.
• label String - A short, localized description of the shipping method.
• detail String - A user-readable description of the shipping method.
• amount String - The shipping method’s amount.

completeApplePayRequest()/cancelApplePayRequest() -> Promise

After requiredBillingAddressFields you should complete the operation by calling completeApplePayRequest or cancel if an error occurred.

Extra info

Token's extra field

extra

An object with the following keys:

• shippingMethod Object - Selected shippingMethod object.
• billingContact Object - The user's billing contact object.
• shippingContact Object - The user's shipping contact object.

contact

An object with the following keys:

• name String - The contact’s name.
• phoneNumber String - The contact’s phone number.
• emailAddress String - The contact’s email address.
• street String - The street name in a postal address.
• city String - The city name in a postal address.
• state String - The state name in a postal address.
• country String - The country name in a postal address.
• ISOCountryCode String - The ISO country code for the country in a postal address.
• postalCode String - The postal code in a postal address.
• supplementarySubLocality String - The contact’s sublocality.

Example

const items = [{
  label: 'Whisky',
  amount: '50.00',
}, {
  label: 'Tipsi, Inc',
  amount: '50.00',
}]

const shippingMethods = [{
  id: 'fedex',
  label: 'FedEX',
  detail: 'Test @ 10',
  amount: '10.00',
}]

const options = {
  requiredBillingAddressFields: 'all',
  requiredShippingAddressFields: 'all',
  shippingMethods,
}

const token = await stripe.paymentRequestWithApplePay(items, options)

// Client specific code
// api.sendTokenToBackend(token)

// You should complete the operation by calling
stripe.completeApplePayRequest()

// Or cancel if an error occurred
// stripe.cancelApplePayRequest()

Android Pay (Android only)

(Under active development)

deviceSupportsAndroidPay() -> Promise

Indicates whether or not the device supports Android Pay. Returns a Boolean value.

paymentRequestWithAndroidPay(options) -> Promise

Launch the Android Pay view to accept payment.

options

An object with the following keys:

• total_price String - Price of the item.
• currency_code String - Three-letter ISO currency code representing the currency paid out to the bank account.
• shipping_address_required Boolean (Optional) - Is shipping address menu required. Default true.
• line_items Array - Array of purchased items. Each item contains:
  • currency_code String - Currency code string.
  • description String - Short description that will shown to user.
  • total_price String - Total order price.
  • unit_price String - Price per unit.
  • quantity String - Number of items.

Example

const options = {
  total_price: '80.00',
  currency_code: 'USD',
  shipping_address_required: false,
  line_items: [{
    currency_code: 'USD',
    description: 'Whisky',
    total_price: '50.00',
    unit_price: '50.00',
    quantity: '1',
  }, {
    currency_code: 'USD',
    description: 'Vine',
    total_price: '30.00',
    unit_price: '30.00',
    quantity: '1',
  }],
}

const token = await stripe.paymentRequestWithAndroidPay(options)

// Client specific code
// api.sendTokenToBackend(token)

Request with Card Form

paymentRequestWithCardForm(options) -> Promise

Launch Add Card view to to accept payment.

options (iOS only)

An object with the following keys:

• requiredBillingAddressFields String - The billing address fields the user must fill out when prompted for their payment details. Can be one of: full|zip or not specify to disable.
• prefilledInformation Object - You can set this property to pre-fill any information you’ve already collected from your user.
• managedAccountCurrency String - Required to be able to add the card to an account (in all other cases, this parameter is not used). More info.
• smsAutofillDisabled Bool - When entering their payment information, users who have a saved card with Stripe will be prompted to autofill it by entering an SMS code. Set this property to true to disable this feature.
• theme Object - Can be used to visually style Stripe-provided UI.

prefilledInformation

An object with the following keys:

• email String - The user’s email address.
• phone String - The user’s phone number.
• billingAddress Object - The user’s billing address. When set, the add card form will be filled with this address.

billingAddress

An object with the following keys:

• name String - The user’s full name (e.g. "Jane Doe").
• line1 String - The first line of the user’s street address (e.g. "123 Fake St").
• line2 String - The apartment, floor number, etc of the user’s street address (e.g. "Apartment 1A").
• city String - The city in which the user resides (e.g. "San Francisco").
• state String - The state in which the user resides (e.g. "CA").
• postalCode String - The postal code in which the user resides (e.g. "90210").
• country String - The ISO country code of the address (e.g. "US").
• phone String - The phone number of the address (e.g. "8885551212").
• email String - The email of the address (e.g. "jane@doe.com").

theme

An object with the following keys:

• primaryBackgroundColor String - The primary background color of the theme.
• secondaryBackgroundColor String - The secondary background color of this theme.
• primaryForegroundColor String - The primary foreground color of this theme. This will be used as the text color for any important labels in a view with this theme (such as the text color for a text field that the user needs to fill out).
• secondaryForegroundColor String - The secondary foreground color of this theme. This will be used as the text color for any supplementary labels in a view with this theme (such as the placeholder color for a text field that the user needs to fill out).
• accentColor String - The accent color of this theme - it will be used for any buttons and other elements on a view that are important to highlight.
• errorColor String - The error color of this theme - it will be used for rendering any error messages or view.

Example

const options = {
  smsAutofillDisabled: true,
  requiredBillingAddressFields: 'full',
  prefilledInformation: {
    billingAddress: {
      name: 'Gunilla Haugeh',
      line1: 'Canary Place',
      line2: '3',
      city: 'Macon',
      state: 'Georgia',
      country: 'US',
      postalCode: '31217',
    },
  },
}

const token = await stripe.paymentRequestWithCardForm(options)

// Client specific code
// api.sendTokenToBackend(token)

Request with card params object

createTokenWithCard(params) -> Promise

Creates token based on passed card params.

params

An object with the following keys:

• number String (Required) - The card’s number.
• expMonth Number (Required) - The card’s expiration month.
• expYear Number (Required) - The card’s expiration year.
• cvc String - The card’s security code, found on the back.
• name String - The cardholder’s name.
• addressLine1 String - The first line of the billing address.
• addressLine2 String - The second line of the billing address.
• addressCity String - City of the billing address.
• addressState String - State of the billing address.
• addressZip String - Zip code of the billing address.
• addressCountry String - Country for the billing address.
• brand String (Android only) - Brand of this card. Can be one of: JCB|American Express|Visa|Discover|Diners Club|MasterCard|Unknown.
• last4 String (Android only) - last 4 digits of the card.
• fingerprint String (Android only) - The card fingerprint.
• funding String (Android only) - The funding type of the card. Can be one of: debit|credit|prepaid|unknown.
• country String (Android only) - ISO country code of the card itself.
• currency String - Three-letter ISO currency code representing the currency paid out to the bank account. This is only applicable when tokenizing debit cards to issue payouts to managed accounts. You should not set it otherwise. The card can then be used as a transfer destination for funds in this currency.

Example

const params = {
  // mandatory
  number: '4242424242424242',
  expMonth: 11,
  expYear: 17,
  cvc: '223',
  // optional
  name: 'Test User',
  currency: 'usd',
  addressLine1: '123 Test Street',
  addressLine2: 'Apt. 5',
  addressCity: 'Test City',
  addressState: 'Test State',
  addressCountry: 'Test Country',
  addressZip: '55555',
}

const token = await stripe.createTokenWithCard(params)

// Client specific code
// api.sendTokenToBackend(token)

Request with external (bank) account params object (Android only at the moment)

createTokenWithBankAccount(params) -> Promise

Creates token based on external (bank) params.

params

An object with the following keys:

• accountNumber String (Required) - The account number for this BankAccount.
• countryCode String (Required) - The two-letter country code that this account was created in.
• currency String (Required) - The currency of this account.
• routingNumber String - The routing number of this account.
• accountHolderName String - The account holder's name.
• accountHolderType String - the bank account type. Can be one of: company|individual.

Example

const params = {
  // mandatory
  accountNumber: '000123456789',
  countryCode: 'us',
  currency: 'usd',
  // optional
  routingNumber: '110000000', // 9 digits
  accountHolderName: 'Test holder name',
  accountHolderType: 'company', // "company" or "individual"
}

const token = await stripe.createTokenWithBankAccount(params)

// Client specific code
// api.sendTokenToBackend(token)

PaymentCardTextField component

A text field component specialized for collecting credit/debit card information. It manages multiple text fields under the hood to collect this information. It’s designed to fit on a single line.

Props

• styles Object - Accepts all View styles, also support color param.
• cursorColor String (IOS only) - The cursor color for the field.
• textErrorColor String (IOS only) - The text color to be used when the user has entered invalid information, such as an invalid card number.
• placeholderColor String (IOS only)- The text placeholder color used in each child field.
• numberPlaceholder String - The placeholder for the card number field.
• expirationPlaceholder String - The placeholder for the expiration field.
• cvcPlaceholder String - The placeholder for the cvc field.
• disabled Bool (IOS only) - Enable/disable selecting or editing the field. Useful when submitting card details to Stripe.
• enabled Bool (Android only) - Enable/disable selecting or editing the field. Useful when submitting card details to Stripe.
• onChange Func - This function will be called each input change.
• onParamsChange Func - This function will be called each input change, it takes two argumants:
  • valid Bool - Whether or not the form currently contains a valid card number, expiration date, and CVC.
  • params Object - Contains entered card params: number, expMonth, expYear and cvc.

Initial params

To set inital params you can use <instance>.setParams(params) method which is available via ref. For example, if you’re using another library to scan your user’s credit card with a camera, you can assemble that data into an object and set this property to that object to prefill the fields you’ve collected.

You can also access to valid and params info via <instance>.valid and <instance>.params respectively.

Example

import React, { Component } from 'react'
import { StyleSheet } from 'react-native'
import { PaymentCardTextField } from 'tipsi-stripe'

const styles = StyleSheet.create({
  field: {
    width: 300,
    color: '#449aeb',
    borderColor: '#000',
    borderWidth: 1,
    borderRadius: 5,
  }
})

class FieldExample extends Component {
  handleFieldParamsChange = (valid, params) => {
    console.log(`
      Valid: ${valid}
      Number: ${params.number || '-'}
      Month: ${params.expMonth || '-'}
      Year: ${params.expYear || '-'}
      CVC: ${params.cvc || '-'}
    `)
  }

  render() {
    return (
      <PaymentCardTextField
        style={styles.field}
        cursorColor={...}
        textErrorColor={...}
        placeholderColor={...}
        numberPlaceholder={...}
        expirationPlaceholder={...}
        cvcPlaceholder={...}
        disabled={false}
        onParamsChange={this.handleFieldParamsChange}
      />
    )
  }
}

Tests

Local CI

To run example app e2e tests for all platforms you can use npm run ci command. Before run this command you need to specify PUBLISHABLE_KEY and MERCHANT_ID environment variables:

PUBLISHABLE_KEY=<...> MERCHANT_ID=<...> npm run ci

Manual

1. Go to example folder cd example
2. Install CocoaPods dependencies (iOS only) pod install --project-directory=ios
3. Install npm dependencies npm install
4. Configure project before build PUBLISHABLE_KEY=<...> MERCHANT_ID=<...> npm run configure
5. Build project:

• npm run build:ios - for iOS
• npm run build:android - for Android
• npm run build - for both iOS and Android

6. Open Appium in other tab npm run appium
7. Run tests:

• npm run test:ios - for iOS
• npm run test:android - for Android
• npm run test - for both iOS and Android

Troubleshooting

Tests

You might encounter the following error while trying to run tests:

An unknown server-side error occurred while processing the command. Original error: Command \'/bin/bash Scripts/bootstrap.sh -d\' exited with code 1

You can fix it by installing Carthage:

brew install carthage

use_frameworks! issue

If you are using CocoaPods and use_frameworks! enabled in your Podfile you might get the following error:

fatal error: 'Stripe/Stripe.h' file not found

To solve this problem please be sure that Stripe.framework is added to Link Binary with Libraries section of Build Phases in TPSStripe.xcodeproj. If problem still persist, please try to clean your build folder and rebuild again.

Android

• Using higher than ours version of Google Play Services in your project might encourage an error: NoClassDefFoundError: com.google.android.gms.wallet.MaskedWalletRequest

We have fixed this issue, but if you somehow facing this bug again - please, create an issue or a pull request and we will take another look.

jest

To make jest work with tipsi-stripe, you should change transformIgnorePatterns in package.json file. Please refer to here

"jest": {
  "preset": "react-native",
  "transformIgnorePatterns": [
    "node_modules/(?!(jest-)?react-native|tipsi-stripe)"
  ]
}

Example

To see more of the tipsi-stripe in action, you can check out the source in example folder.

License

tipsi-stripe is available under the MIT license. See the LICENSE file for more info.