@gigster/module-loopback-stripe
v1.1.11
Published
Role | Name | Email | Slack ---- | ---- | ----- | ----- *Product Owner* | Ryan Borker | [[email protected]](mailto:[email protected]) | [@borker] *Maintainer* | Sameep Sheth | [[email protected]](mailto:[email protected]) | [@sameepsheth] *Contri
Downloads
40
Readme
loopback-stripe
Role | Name | Email | Slack ---- | ---- | ----- | ----- Product Owner | Ryan Borker | [email protected] | [@borker] Maintainer | Sameep Sheth | [email protected] | [@sameepsheth] Contributor | Mark Miyashita | [email protected] | [@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="[email protected]" \
-d password="1234"
Example Response:
{
"id":"xyz3vefrnjv397gh38v7h37fhv73h4v34f34",
"email":"[email protected]",
...,
...
}
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