Skip to main content
Version: 3.x

Stripe

Stripe plugin uses custom payment flow to process customer transactions.

note

Saleor uses Stripe API in version 2020-08-27

Creating payment in Saleor​

To create a payment properly, you need to follow the steps described in Creating a checkout session and Selecting a shipping method.

The next step is to choose Stripe as a payment gateway that we want to use to process checkout. For the Stripe payment gateway, we need to provide: checkoutId, and input with gateway and amount.

note

Description of the checkoutPaymentCreate mutation can be found here.

mutation {
  checkoutPaymentCreate(
    checkoutId: "Q2hlY2tvdXQ6MWZiMmM1OGUtN2JhMy00YmY5LWI2ZDItNWY2ZWJiN2U3ZWJj"
    input: { gateway: "saleor.payments.stripe", amount: 45.61 }
  ) {
    payment {
      id
      chargeStatus
    }
    errors {
      field
      message
    }
  }
}

Completing the checkout​

After we create a payment object for the Stripe payment gateway, we can call the checkoutComplete mutation. The first call of checkoutComplete for checkout creates Stripe payment intent object.

Optionaly, checkoutComplete can accept additional parameters for Stripe as fields in paymentData input:

note

paymentData.payment_method_type - accepts all standard payment method types which use standard PaymentIntent flow to process a payment. For more details check Stripe docs.

mutation {
 checkoutComplete(
   checkoutId: "Q2hlY2tvdXQ6YjBhYTUzMWItYjc3NS00MzM3LTkxNzEtYTgzOTYwYThjMmVk"
 ) {
   order {
     id
     userEmail
     created
   }
   confirmationNeeded
   confirmationData
   errors {
     field
     message
     code
   }
 }
}

As a result, we get details required to finalize a payment.

{
  "data": {
    "checkoutComplete": {
      "order": null,
      "confirmationNeeded": true,
      "confirmationData": "{\"client_secret\": \"pi_1J2Yh3H1Vac4G4dbfuBvQhTe_secret_DkwP8jcdenirqazGpjPvSaPtV\", \"id\": \"pi_1J2Yh3H1Vac4G4dbfuBvQhTe\"}",
      "checkoutErrors": []
    }
  }
}

client_secret is required to process a customer payment. Steps required to finalize a payment transaction are described in Stripe documentation.

Finalizing a payment​

When the customer finalizes a payment, Stripe sends a webhook notification with all details related to this payment. Saleor asynchronously receives the notification and completes checkout process.

On client-side, when stripe.confirmCardPayment doesn't return an error as described here,
client-side can call checkoutComplete one more time. Saleor confirms that the payment has success status and returns an order object.

mutation {
 checkoutComplete(
   checkoutId: "Q2hlY2tvdXQ6YjBhYTUzMWItYjc3NS00MzM3LTkxNzEtYTgzOTYwYThjMmVk"
 ) {
   order {
     id
     userEmail
     created
   }
   confirmationNeeded
   confirmationData
   errors {
     field
     message
     code
   }
 }
}

As a result we get order object.

{
  "data": {
    "checkoutComplete": {
      "order": {
        "id": "T3JkZXI6MjI0Mw==",
        "userEmail": "m...@saleor.io",
        "created": "2021-06-04T09:24:44.552881+00:00"
      },
      "confirmationNeeded": false,
      "confirmationData": "{}",
      "checkoutErrors": []
    }
  }
}

Saving card in Stripe for future payments​

Saleor 3.0 (deprecated)​

Use paymentData.setup_future_usage to store payment method for future payments with checkoutComplete

mutation {
  checkoutComplete(
    checkoutId: "ID"
    storeSource: true
    paymentData: "{\"setup_future_usage\": \"off_session\"}"
  ) {
    order {
      id
      userEmail
      created
    }
    confirmationNeeded
    confirmationData
    errors {
      field
      message
      code
    }
  }
}

Saleor 3.1+​

Use input.storePaymentMethod to store payment method for future payments with checkoutPaymentCreate. Metadata in input.metadata will be stored with the payment

mutation {
  checkoutPaymentCreate(
    checkoutId: "ID"
    input: {
      gateway: "saleor.payments.stripe"
      token: "tokencc_bh_s3bjkh_24smq8_6c6zhq_w4v6b9_8vz"
      amount: 33.33
      storePaymentMethod: OFF_SESSION
      metadata: [
        {
          key: "key"
          value: "value"
        }
      ]
    }
  ) {
    payment {
      id
      chargeStatus
    }
    errors {
      field
      message
    }
  }
}

Using stored payment method​

Use paymentData.payment_method_id and paymentData.off_session to use stored payment method. You can retrieve

mutation {
  checkoutComplete(
    checkoutId: "ID"
    storeSource: true
    paymentData: "{\"payment_method_id\": \"pm_id\", \"off_session\": false}"
  ) {
    order {
      id
      userEmail
      created
    }
    confirmationNeeded
    confirmationData
    errors {
      field
      message
      code
    }
  }
}

Stripe webhooks​

By activating a plugin, Saleor automatically subscribes the following Stripe webhook events:

  • payment_intent.succeeded
  • payment_intent.processing
  • payment_intent.payment_failed
  • payment_intent.amount_capturable_updated
  • payment_intent.canceled
  • charge.refunded