rye-pay

This package contains the Rye payment client required to perform checkout using Rye Cart-API. The package relays on Spreedly iFrame which takes care of handling secure payment data (credit card number and cvv).

Table of Contents

1. Install
2. Usage
   • Preparing a payment form
   • RyePay initialization and cart submission
   • Handle submission result
   • Other methods
3. Related documentation

Install

Install with npm:

npm i @rye-com/rye-pay

Install with yarn:

yarn add @rye-com/rye-pay

Usage

Preparing a payment form

Developers are responsible for creating a form that collects user credit card data. It is up to a developer how to style and layout the form. In order to be PCI Complaint a developer should not use any input fields to collect a credit card number and cvv. Instead, they should provide two HTML elements with id attribute where the number and cvv Spreedly iFrame fields should be rendered.

RyePay initialization and cart submission

1import { RyePay } from '@rye-com/rye-pay';
2
3const ryePay = new RyePay();
4ryePay.init(initParams);
5//...
6ryePay.submit(submitParams);

Initialization parameters

initParams is an object with the following fields:

apiKey: string ^required

Developer's key to access Rye API.

numberEl: string ^required

Id of the HTML element where the number iFrame field should be rendered.

cvvEl: string ^required

Id of the HTML element where the CVV iFrame field should be rendered.

onReady: () => void

Triggered when the iFrame is initialized and ready for configuration. setStyle and other UI function calls should be made within this event listener. This event will only fire after init() has been called.

onCartSubmitted(result: SubmitCartResult)

Triggered when the cart submission is completed and an attempt to make a payment and create orders is made.

onErrors: (errors) => void

Triggered when a payment method is not successfully tokenized. A description of the errors object can be found here

onIFrameError: (error) => void

Triggered when a javascript error occurs within the iFrame. This is useful for debugging runtime issues. error includes keys msg, url, line, col

onFieldChanged: (name, type, activeEl, inputProperties) => void

Triggered when an input event occurs in either iFrame field. This is useful to provide real-time feedback to the user. A description of params can be found here

onValidate: (inputProperties) => void

Triggered when validation of the iFrame is requested. This event will only fire after validate() has been called. A description of input properties can be found here

enableLogging: boolean

Indicates whether to log to the console the crucial steps of the script execution. Helpful for debugging.

Submit parameters

As soon as the user filled the payment form and the cart is ready to be submitted, the developer should call ryePay.submit(submitParams). To handle the result the developer should provide onCartSubmitted callback in the init method. This method will submit the cart, make a payment transaction using specified credit card data and create an order per each store in the cart.

submitParams is an object with the following fields:

cartId: string ^required

cart identifier

first_name: string ^required

user's first name. Should match the name on the credit card.

last_name: string ^required

user's last name. Should match the last name on the credit card.

month: string ^required

credit card expiration month

year: string ^required

credit card expiration year

address1: string ^required

billing address.

address2: string

additional billing address

city: string ^required

billing city

state: string ^required

billing state/province

country: string ^required

billing country

zip: string ^required

billing zip/postal code

selectedShippingOptions: SelectedShippingOption[]

an array of objects that represent selected shipping option per store

1export interface SelectedShippingOption {
2  store: string;
3  shippingId: string;
4}

Handle submission result

onCartSubmitted callback takes an argument of SubmitCartResult type that provides detail information about the cart submission status.

1interface SubmitCartResult {
2  // Cart identifier
3  id: string;
4  // Submission result per each store in the cart
5  stores: SubmitStoreResult[];
6}
7
8interface SubmitStoreResult {
9  // Store information
10  store: Store;
11  // Submission status for this store
12  status: SubmitStoreStatus;
13  // Identifier of the request to track order status
14  requestId?: string;
15}
16
17type Store = AmazonStore | ShopifyStore;
18
19interface AmazonStore {
20  store: string;
21  cartLines: AmazonCartLine[];
22}
23
24interface ShopifyStore {
25  store: string;
26  cartLines: ShopifyCartLine[];
27}
28
29export interface AmazonCartLine {
30  quantity: number;
31  product: {
32    id: string;
33  };
34}
35
36export interface ShopifyCartLine {
37  quantity: number;
38  variant: {
39    id: string;
40  };
41}
42
43enum SubmitStoreStatus {
44  // Submission completed without any issues
45  COMPLETED = 'COMPLETED',
46  // Payment issues occurred during the submission
47  PAYMENT_FAILED = 'PAYMENT_FAILED',
48  // Other issues occurred during the submission
49  FAILED = 'FAILED',
50}

Other methods

Methods described below are a direct mapping to the Spreedly object. A detailed description can be found here

reload()

validate()

setFieldType(field, type)

setLabel(field, label)

setTitle(field, title)

setNumberFormat(format)

setPlaceholder(field, placeholder)

setStyle(field, css)

transferFocus(field)

toggleAutoComplete()

Related documentation

Spreedly iFrame api reference