Overview

Stripe is a third-party credit card payment provider that, combined with the Stripe Payment service, enables you to capture a customer's payment. Prior to using the service, you need to create a Standalone Stripe account and configure Stripe using Stripe Connect.

When you are ready to charge a credit card, you need to:

  • Authorize the Stripe account.
  • Use the publishable key to create the credit card token.
  • Use the token in the payment capture request.


API Reference

/{tenant}/payments

/{tenant}/payments

post

Authorize or capture the payment for a given credit card token based on merchant settings in site. Capture a payment for the authorized transaction.

/{tenant}/connect

/{tenant}/connect

post

Generate the redirect URL to navigate to Stripe.

put

Update the Stripe connection. Used to toggle between live mode and test mode.

/callback

/callback

get

Process the callback from Stripe.


Stripe Connect

Stripe Connect is used to configure Stripe as your payment provider for Hybris YaaS. If you activate Stripe Connect, you will link your merchant Stripe account to YaaS in a single click of a button. Enabling Stripe Connect also gives you the ability to use features such as the Stripe Relay that is available in the Stripe Relay In-App & Social Sales package. For more information on Stripe Connect, see the Stripe documentation.

Before you can activate Stripe Connect, you need to create a fully-configured and valid standalone Stripe account. This means you need a live Stripe account on the Stripe website. If your account is not in live mode, you will be requested to activate your account by providing the necessary information on the Account application page.

To activate Stripe Connect, complete the following:

  1. In Builder, select your project and click Commerce Settings > Payment Settings > select a site.
  2. On the Payment Details page, click the ACTIVATE STRIPE CONNECT button. You will be redirected to the Stripe website.
  3. A) If you already have a Stripe account and are logged in, select the Stripe account you want to link to that site and click Connect my Stripe account. B) If you do not have a Stripe account, fill out the form and click Authorize access to this account.

    A Stripe account can only be connected to one site. If you have multiple sites, you will need to have multiple Stripe accounts.

    You will be redirected back to the Payment Details page on Builder and you will see that Stripe Connect is CONNECTED and in live mode. Live mode means that it will capture the payment with valid credit cards. To test or validate the payment process, you must set the Stripe setting in Builder to test mode. For more information on how to toggle between live and test mode, see the Live and Test Mode tutorial.

If you have set up Stripe with the previous configuration using the private and public keys, you have the option to leave the configuration as is or to update to Stripe Connect. You need to update your configuration to Stripe Connect if you want to use the Stripe Relay.


Live and Test Mode

This feature lets you toggle between live mode and test mode. Live mode completes a payment capture with a credit card. You will use live mode when you are ready to start charging your customers' credit cards. Test mode lets you test the Stripe Payment configuration by using a valid/test credit card without charging it to complete a checkout. When you initially configure Stripe Connect, it is set to live mode by default. You can use the liveMode attribute to toggle between live mode (true) and test mode (false). If you have the previous Stripe configuration (with the private and public keys), the live/test mode feature is not available. For more information about testing Stripe, see the Testing documentation.

You must switch to test mode if you do not want to "go live" immediately.

The setting for the live/test mode in the Stripe Payment service does not mimic the live/test mode setting for your Stripe account. For testing purposes, you can set the Stripe Payment service to test mode, while the Stripe account is set to live mode. This allows you to create an order successfully without charging a valid credit card.

When changing the current mode, the Stripe Payment service makes a call to Stripe. The service uses the refresh_token to send the new liveMode value to Stripe. Stripe then returns a corresponding access_token. This access token is needed to perform the payment capture. If you are in live mode, a live mode access token is used, and if you are in test mode, a test mode access token is used.


Deferred Payment

After Stripe is configured, you can decide whether to capture the payment at the initial checkout (when an order is created), or at a later time (when the order has shipped). To accomplish this, you need to configure the captureMode attribute in the Site service. This attribute determines:

  • ORDER_CREATE: Captures the payment when the order is created (this is the default).
  • ORDER_SHIP: Captures the payment when the order is shipped. This requires that the credit card was authorized when it went through the payment capture process the first time.

Payment capture process for a deferred payment

The following is how a payment is captured when you choose to complete the payment capture after the order has been shipped:

  1. The shopper checks out their cart and goes through the initial payment capture. See the Payment Capture tutorial. Instead of returning true for the captured attribute, it returns false, which means the payment status is pending.
  2. The payment information is sent to the Order service before the Order ID is created. The order status is set to confirmed.
  3. Once the order has shipped, the same payment endpoint is called again. If successful, the captured attribute is set to true and a payment status of success is sent to the Order service. The payment is now captured.

    The Stripe Payment service returns an error message if:

    • You try to charge an amount greater than what was initially authorized.
    • The credit card is no longer valid.


Test Mode

Because a Stripe Connect account cannot be created on the fly, this cannot be shown as an interactive tutorial.

When you initially configure Stripe Connect, it is set to live mode by default. This means you can start charging credit cards for any created orders. If you want to test your Stripe Payment configuration, you need to set the liveMode attribute to test mode (false). In test mode you can successfully create an order by using a valid credit card (but not charging it), or a credit card number meant for testing purposes found on the Stripe Testing page.

The following tutorial shows how you can set your Stripe Payment setting to test mode.

Request

  • Method: PUT
  • Request URL: https://api.beta.yaas.io/hybris/payment-stripe/v1/{tenant}/connect
  • Example:

      ```
        {
            "siteCode": "canada",
             "paymentProviderId": "stripe",
             "liveMode": false
        }
      ```
    

Response

  • Status Code: HTTP/1.1 204


Payment Capture

Because a Stripe Connect account cannot be created on the fly, this cannot be shown as an interactive tutorial.

To complete a payment capture, you must complete these two steps:

  1. Create a token for a specific credit card.
  2. Capture the payment through Stripe using the token.

Create a token

When the customer enters their credit card information, the application or web page uses the publishable key (publicKey) to call the Stripe API to get a token. This token holds all the information pertaining to that specific credit card. To create a token, refer to the Stripe documentation.

Capture the payment

The Stripe Payment service uses the token, the total amount, and the access token (OAuth2) to call the Stripe API and charge the total amount to that specific credit card.

Request

  • Method: POST
  • Request URL: https://api.beta.yaas.io/hybris/payment-stripe/v1/{tenant}/payments
  • Example: The amount, currency, and token are the mandatory attributes needed to charge a specific credit card.

If this is the second payment capture attempt made for a deferred payment, the customAttributes contains the transactionID when the credit card was authorized during the initial checkout.

{
    "amount": 55.55,
    "currency": "CAD",
    "siteCode": "canada",
    "customAttributes":
        {
            "token" : "visa123abc0001"
        }
}

Response

  • Status code: 200
  • Example: The captured attribute is false if you have set up the payment capture to be executed once the order has shipped. For more information, see the Deferred Payment page.
    {
      "paidAmount": 55.55,
      "currency": "CAD",
      "transactionId":"0000A123",
      "paymentMethod": "VISA",
      "captured":true
    }
    


Error Codes

For more information about error codes, see the API Reference.


Glossary

TermDescription
live accountThe account used in the application when you deploy the site.
orderOnce a customer has finished shopping and the items in the cart are checked out and processed.
payment captureWhen the service makes a call to the third-party payment provider and charges the cost of the order to the customer's payment card.
privateKeyMandatory attribute used when configuring the Stripe Payment service in the Site service. The value of this key is the secret key you received from Stripe. Also known as secret key.
publicKeyAn optional attribute to configure in the Site service. The value of this key is the publishable key you received from Stripe. If you prefer, you can store this key in another location. See publishable key.
publishable keyThis key is provided by Stripe when you create a Stripe account. This key creates the token needed to capture a payment. Also known as publicKey.
secret keyThis key is provided by Stripe and is used to charge the credit card. You must keep the contents of this key secure. Also known as privateKey.
StripeA third-party credit card payment provider.
Stripe accountThe account you need to create in order to use the Stripe API and Stripe Payment service.
test accountThe account used to test the application. Any actions made on this account do not affect any credit cards or bank accounts.
tokenThe value needed to complete a payment capture. This token is generated by using the publishable key and the Stripe API.


  • Send feedback

    If you find any information that is unclear or incorrect, please let us know so that we can improve the Dev Portal content.

  • Get Help

    Use our private help channel. Receive updates over email and contact our specialists directly.

  • hybris Experts

    If you need more information about this topic, visit hybris Experts to post your own question and interact with our community and experts.