@gigster/module-loopback-stripe

loopback-stripe

Role	Name	Email	Slack
Product Owner	Ryan Borker	[e-mail]	[@borker]
Maintainer	Sameep Sheth	[e-mail]	[@sameepsheth]
Contributor	Mark Miyashita	[e-mail]	[@mark]

Overview

This module Generates models and their helpers to communicate and perform operations related to stripe such as creating customers, charges and managing payment sources. The models has a set amount of remote methods implemented to perform these actions. Stripe module is used to process order payments. Payment can be associated to an order, a basket, a service, or some transaction. We can apply Coupons to the transaction as well. To set it up, we can first associate a credit card to a user.

Features

Presently, The following features are implemented.

• Create a customer in stripe.
• Create/Manage the stripe payment sources (Cards) of an user.
• Set default payment source (Card) of an user.
• List all the active payment sources (Cards) of an user.
• Achieve a stripe charge. You can also use coupons If required (Check the transactions/checkout remote method for an example).
• Get a History of charges.
• Create coupons and apply them in a transaction.

Note:

Store your stripe public and private tokens inside a .env file. It should look something like this.

STRIPE_PUBLIC_KEY=pk_test_xxx
STRIPE_PRIVATE_KEY=sk_test_yyy

Login

Login to get an authentication token.

Example Request:
  curl localhost:3000/api/users/login \
    -d email="[e-mail]" \
    -d password="1234"

Example Response:
  {
    "id":"xyz3vefrnjv397gh38v7h37fhv73h4v34f34",
    "email":"[e-mail]",
    ...,
    ...
  }

  Use the above value inside the id property as auth_token/user_token for the subsequent requests.

Stripe token

The client will have to provide the stripe token obtained from the stripe js script. This token is required to identify the local customer/user in stripe and also create/update payment sources / cards. Learn more about creating stripe tokens here https://stripe.com/docs/stripe-js . This token is used in the endpoints like adding a card, checkout a product.

Usage

1.)
  * Name: addCard
  * Overview: Add a new payment source to an existing user.
  * Url: /users/:id/cards
  * Type: POST

  Description:
    Call this method when you want to add a new card to the user. Internally It creates a stripe user and associates the payment source with it.

  Example Request:
   curl localhost:3000/api/users/1/cards?auth_token={user_token} \
   	 -d token="tok_visa"

  Request parameters:
    * token:
      - Description: Token from stripe.js, Stripe token
      - ParameterType: body
      - DataType: string
      - required: true
    * id:
      - Description: id of the user
      - ParameterType: path
      - DataType: number
      - required: true

  Example Response:
  200
  {
    "message": "Card added Successfully!"
  }

2.)
  * Name: listCards
  * Overview: List the cards of an user.
  * Url: /users/:id/cards
  * Type: GET

  Description:
    This method lists all the cards that are added by the user. To change the default card, You can use this method to get the card id which is supplied to the setDefaultCard method.

 Example Request:
 	 curl localhost:3000/api/users/1/cards?auth_token={user_token}

  Request parameters:
    * id:
      - Description: id of the user
      - ParameterType: path
      - DataType: number
      - required: true

  Example Response:
  200
  {
  "object": "list",
  "url": "/v1/customers/cus_Br3BtfcB8xdneK/sources",
  "has_more": false,
  "data": [
    {
      "id": "card_1BTNNTJW39IQVtC9tl3R2q2H",
      "object": "card",
      "address_city": null,
      "address_country": null,
      "address_line1": null,
      "address_line1_check": null,
      "address_line2": null,
      "address_state": null,
      "address_zip": null,
      "address_zip_check": null,
      "brand": "Visa",
      "country": "US",
      "customer": "cus_Br3BtfcB8xdneK",
      "cvc_check": null,
      "dynamic_last4": null,
      "exp_month": 8,
      "exp_year": 2018,
      "fingerprint": "K23TqmI2Bj0NLcbN",
      "funding": "credit",
      "last4": "4242",
      "metadata": {
      },
      "name": null,
      "tokenization_method": null
    },
    {...},
    {...}
  ]
}

3.)
  * Name: setDefaultCard
  * Overview: Set default card for an user.
  * Url: /:id/cards/:stripeCardId/set-default
  * Type: post

  Description:
    This method takes in one of the card id of the user to set as the default card to be used in all the transactions.This method is called when you have to change the default card.

  Example Request:
 	  curl localhost:3000/api/users/1/cards/card_123asd/set-default?auth_token={user_token}

  Request parameters:
    * id:
      - Description: id of the user
      - ParameterType: path
      - DataType: number
      - required: true
    * stripeCardId:
      - Description: The stripeCardId
      - ParameterType: path
      - DataType: string
      - required: true

Example Response:
  200
  {
    "message": "Default Card set Successfully!"
  }

4.)
  * Name: listTransactions
  * Overview: List all the transactions of a particular user
  * Url: /transactions/:id/list
  * Type: GET

  Example Request:
    curl localhost:3000/api/transactions/1/list?auth_token={user_token}

  Request parameters:
  * id:
    - Description: id of the user
    - ParameterType: path
    - DataType: number
    - required: true

  Example Response:
    {
      "transactions": [
        {
          "id": 1,
          "transactableId":1,
          "transactableType":"Product",
          "stripeChargeId":"ch_v123ef24f",
          "amount":1000,
          "createdAt":"2018-04-05T01:00:00.345"
        },
        ...,
        ...
      ]
    }

5.)
  * Name: list All Transactions
  * Overview: List all transactions of every user
  * Url: /transactions
  * Type: GET

  Description:
    Admin user gets all user transactions. Regular user can only read her transactions in the above method.

  Example Request:
    curl localhost:3000/api/transactions?auth_token={user_token}

  Example Response:
    {
      "transactions": [
        {
          "id": 1,
          "transactableId":1,
          "transactableType":"Product",
          "stripeChargeId":"ch_v123ef24f",
          "amount":1000,
          "createdAt":"2018-04-05T01:00:00.345"
        },
        ...,
        ...
      ]
    }

6.)
  * Name: checkout
  * Overview: Charge user and create a record
  * Url: /transactions/checkout
  * Type: POST

  Description:
    Use this method to charge the customer and associate the charge to a transaction. A transaction could be an order or a basket or a service. You can specify that as a transactableType to this method.
    This method optionally takes credit card information. You can pass it as a stripe token. (https://stripe.com/docs/stripe-js)

  Example Request:
    curl localhost:3000/api/transactions/checkout?auth_token={user_token} \
      -d transactableId=1 \
      -d transactableAmount=2500 \
      -d couponName="50OFF" \
      -d token="tok_amex"

  Request parameters:
    * transactableId:
      - Description: id of the record in transactable model.
      - ParameterType: body
      - DataType: number
      - required: true
    * transactableAmount:
      - Description: amount in cents
      - ParameterType: body
      - DataType: number
      - required: true
    * couponName:
      - Description: coupon name if applicable to the transaction.
      - ParameterType: body
      - DataType: string
      - required: false
    * token:
      - Description: Token from stripe.js, This is passed if the transaction is for the first time.
      - ParameterType: body
      - DataType: string
      - required: true

  Example Response:
    200
    {
      "message": "Transaction succeeded"
    }

7.)
  * Name: create coupon
  * Overview: Creates a new coupon code.
  * Url: /coupons
  * Type: POST

  Description:
    Admins can use this method to create coupons and also specify their usage limits, validity period and other options.

  Example Request:
    curl localhost:3000/api/coupons?auth_token={user_token} \
      -d name="50OFF" \
      -d amountOff=50 \
      -d currency="USD" \
      -d duration="six" \
      -d durationInMonths=6 \
      -d maxRedemptions=50 \
      -d percentOff=50 \
      -d redeemBy="2018-04-28T06:01:08.277Z" \
      -d timesRedeemed=0

  Example Response:
    200
    {
      "name": "50OFF",
      "amountOff": 50,
      "createdAt": "2017-11-29T06:01:08.277Z",
      "currency": "USD",
      "duration": "six",
      "durationInMonths": 6,
      "maxRedemptions": 50,
      "percentOff": 50,
      "redeemBy": "2018-04-28T06:01:08.277Z",
      "timesRedeemed": 0,
      "id": 0
    }

  Request parameters:
    * name:
      - Description: The name of the coupon.
      - ParameterType: body
      - DataType: string
      - required: true
    * amountOff:
      - Description: The amount off.
      - ParameterType: body
      - DataType: number
      - required: true
    * currency:
      - Description: Name of the currency
      - ParameterType: body
      - DataType: string
      - required: true
    * duration:
      - Description: Duration of the coupon.
      - ParameterType: body
      - DataType: string
    * durationInMonths:
      - Description: Duration in months
      - ParameterType: body
      - DataType: number
      - required: true
    * maxRedemptions:
      - Description: Maximum number of times this coupon can be applied
      - ParameterType: body
      - DataType: number
      - required: true
    * percentOff:
      - Description: The percentage that is reduced from the actual price of the transactable item
      - ParameterType: body
      - DataType: number
      - required: true
    * redeemBy:
      - Description: The date before which this coupon should be redeemed
      - ParameterType: body
      - DataType: date
    * timesRedeemed:
      - Description: Number of times this coupon is already redeemed (0 if this is a new coupon).
      - ParameterType: body
      - DataType: number

Tests

Module tests are defined using a test/scenarios.yaml file. This file defines the set of example gigs that we generate as part of integration testing. To run all tests, run yarn test at the root of this module.

Each scenario is generated in test/scenario/<name> which you can then cd into and run the actual app. For a scenario called default, this is done via:

cd test/scenario/default
yarn install

# Run tests.
yarn test

# Start the app.
yarn start