The Rye Pay JavaScript script is a replacement for Stripe and allows vaulting user credit card details for further transactions. When a customer enters their credit card information, the script automatically gets an environment token used for vaulting credit card data.

The script itself does not provide any UI, it should be done by developers. Instead, the script encapsulates the steps necessary to transfer payment information to Spreedly, get the token, and submit the cart with the required data.

When the customer submits their payment information, the payment details are automatically sent to the Spreedly backend where they are securely vaulted.

Once the payment details are securely stored in Spreedly, the frontend script returns the vaulted session token, which can be used to make purchases on the Shopify gateway. This process ensures that sensitive payment information is never stored or transmitted by the merchant, and is instead handled securely by Spreedly.

npm package: @rye-api/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

Here is an example of how you can submit a cart via rye-pay:

1

Integrate rye-pay

Import RyePay from ‘@rye-api/rye-pay’ and create a new object for it.

import { RyePay, SubmitStoreResult, SubmitCartResult } from '@rye-api/rye-pay';

const ryePay = new RyePay();
2

Initialize rye-pay via Spreedly iFrames

In your front-end, you should have input objects which allow users to enter their spreedly number and cvv. The object IDs should be spreedly-number and spreedly-cvv respectively.

Initialize the RyePay object by passing in the spreedly-number and spreedly-cvv.

Feel free to play around with the other auxiliary methods that rye-pay offers. You can see additional documentation or explore the source code here.

const loadSpreedly = () => {
    ryePay.init({
      generateJWT: () => {
        // This function should return a JWT that's used for Rye authentication
        // See docs for more info: https://docs.rye.com/jwt-authentication
      },
      numberEl: 'spreedly-number',
      cvvEl: 'spreedly-cvv',
      environment: prod,
      enableLogging: true,
      onReady: () => {
        // Customize card number field and cvv field
        ryePay.setStyle(
          'number',
          'display:inline; width: 30%; border-radius: 3px; border: 1px solid #ccc;',
        );
        ryePay.setStyle(
          'cvv',
          'display: inline; width: 30%; border-radius: 3px; border: 1px solid #ccc;',
        );
      },
      onErrors: (errors: SpreedlyError[]) => {
        for (const { key, message, attribute } of errors) {
          console.log(`new error: ${key}-${message}-${attribute}`);
        }
      },
      onIFrameError: (err: FrameError) => {
        console.log(`iframeError: ${JSON.stringify(err)}`);
      },
      onCartSubmitted: (result: SubmitCartResult) => {
        console.log(`cart submitted: ${JSON.stringify(result)}`);
      },
      }
    });
  };

loadSpreedly();
3

Submit cart via rye-pay

Call ryePay.submit to submit your cart. It is important that you have set the cartId to be an existing cartId and your shopperIp.

const submit = () => {
  ryePay.submit({
    first_name: 'John',
    last_name: 'Doe',
    month: '04',
    year: '2025',
    cartId: 'cartId', // IMPORTANT! Make sure the cartId is valid
    address1: 'address1',
    address2: 'address2',
    zip: 'zip',
    city: 'city',
    country: 'country',
    state: 'state',
    selectedShippingOptions: [],
    shopperIp: 'xxx.xxx.x.x', // IMPORTANT! Make sure this is set correctly
  });
}

submit();

Could you clarify the precise distinctions between the following inquiries for Rye Pay versus Backend Only?

  • How are refunds handled in both cases? Who handles them?
  • How exactly does money move throughout both processes?
  • How is the actual order to the Shopify store placed?

The answer varies on how we setup your BE payments. We can do it either 1 of 2 ways:

  • Option 1: Rye pays on credit on behalf of the developer and does net 30 invoicing (up to a max $ amount).

  • Option 2: We vault the developer’s credit cards / payment methods.

  • How are refunds handled in both cases? Who handles them?

    • Refunds can be handled by you via our refund endpoint and you work with the shopper/buyer side to figure out how to thread the refund request back to the refund endpoint. Once the refund endpoint is hit, the payment method on file gets refunded.
  • How exactly does money move throughout both processes?

    • The difference here in option 1 and 2 is which payment method gets charged for the order, but basically, the shopper/buyer would purchase on the platform (merchant of record), you would send the order request to Rye, Rye places an order on the merchant side (option 1 or 2 payment method gets charged).
  • How is the actual order to the Shopify store placed?

    • The order would get placed with the option 1 or 2 payment method either via the Sync API or through the Sell Anything API checkout flow. The merchant would see all the other customer information that the developer sends in the request, but the payment method would be the one on file.