gmichokostas / tipsi-stripe

React Native Stripe binding for iOS/Andriod platforms

tipsi-stripe

React Native Stripe binding for iOS/Andriod 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'

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" }
    }
}

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).

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
})

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.
• 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.
• 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.

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'
  }
}

Apple Pay (iOS only)

deviceSupportsApplePay() -> Promise

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

paymentRequestWithApplePay(items, [options]) -> Promise

Launch the Apple Pay view to 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.

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 to accept payment.

options

An object with the following keys:

• price String - Price of the item.
• currency String - Three-letter ISO currency code representing the currency paid out to the bank account.

Example

const options = {
  price: '80.00',
  currency: 'USD',
  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.
• 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.

theme (iOS only)

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',
}

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 (Required) - 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)

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.
• onValueChange 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

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.

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.