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

import { RyePay } from '@rye-com/rye-pay';

const ryePay = new RyePay();
ryePay.init(initParams);
//...
ryePay.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

export interface SelectedShippingOption {
  store: string;
  shippingId: string;
}

Handle submission result

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

interface SubmitCartResult {
  // Cart identifier
  id: string;
  // Submission result per each store in the cart
  stores: SubmitStoreResult[];
}

interface SubmitStoreResult {
  // Store information
  store: Store;
  // Submission status for this store
  status: SubmitStoreStatus;
  // Identifier of the request to track order status
  requestId?: string;
}

type Store = AmazonStore | ShopifyStore;

interface AmazonStore {
  store: string;
  cartLines: AmazonCartLine[];
}

interface ShopifyStore {
  store: string;
  cartLines: ShopifyCartLine[];
}

export interface AmazonCartLine {
  quantity: number;
  product: {
    id: string;
  };
}

export interface ShopifyCartLine {
  quantity: number;
  variant: {
    id: string;
  };
}

enum SubmitStoreStatus {
  // Submission completed without any issues
  COMPLETED = 'COMPLETED',
  // Payment issues occurred during the submission
  PAYMENT_FAILED = 'PAYMENT_FAILED',
  // Other issues occurred during the submission
  FAILED = 'FAILED',
}

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