Overview
Rye makes it easy to take payments and sell products from multiple merchants with a single API. This section covers the different ways to set up payments with Rye, and explains the lifecycle of a Rye order.
Making payments
There are two ways to set up payments with Rye.
Backend ordering
Backend ordering involves you collecting payments yourself and only using Rye to place orders for products. This is the faster way to get started with Rye if you already have a payments solution in place, such as Stripe.
Note: The developer—and not Rye—will be the merchant of record for orders placed using backend ordering.
By default, the workflow for backend ordering looks like this:
- You create a Rye cart and add products to it.
- You retrieve the final cost of the cart from Rye.
- You charge the customer using your own payment processor.
- You submit the order to Rye, passing a tokenized credit card Rye will use to settle the order with the merchant(s) involved in the transaction.
- NOTE: The card you provide Rye here should not be the customer’s card, as you have already charged them. You should provide Rye a company card here to avoid double charging the customer.
- Rye places the order with the merchant(s) and handles the shipping and fulfillment.
We also offer a net 30 invoicing option for larger accounts. You can opt in to this by contacting us.
You can place your first order from your backend by following our backend ordering guide.
Rye Pay
Rye handles both payments and ordering when you use the Rye Pay library. When using Rye Pay, customers will enter their credit card information into a secure form inside their web browser and Rye will charge them directly when the cart is submitted.
You can place your first order using Rye Pay by following our tutorial.
Order placement
A single Rye cart can contain products from multiple different merchants. When you submit an order, Rye will transparently handle routing payments and placing orders with the appropriate merchants. More detailed information about how order placement works can be found here.
We also have sequence diagrams available which show the exact data flow for certain order placement scenarios. Note that in practice the data flow can be more complicated than what is shown in these diagrams in cases where multiple merchants are involved. Nonetheless, these diagrams should give you a good idea of how the process generally works.
Order returns
For products purchased using the Sync API, shoppers can request a refund directly with the merchant. Once the merchant accepts the refund request, Rye will automatically process the refund with no further action on the part of the developer.
Refunds for orders using the Sell Anything API are more involved. Read more about returning Sell Anything API orders here.
Checkout / order lifecycle
Submitting a cart is an asynchronous operation. The successful execution of a submitCart mutation should not be interpreted as the order succeeding; it is possible for errors to occur after the cart is submitted during order placement and payment capture. After submitting a cart, developers should take care to monitor the status of the order and step in to handle errors as they occur.
You can find detailed instructions on how to handle the checkout lifecycle here.