Checkout to Payment

This tutorial provides step-by-step instructions to process a checkout, from creating the session to accepting payment.

Step 1: Create the checkout session

A Checkout session can be created for both logged-in customers and unauthenticated guests.

1

(Optional)Log in as a buyer

2

Create the checkout session

Use the checkoutCreate mutation to initiate the checkout instance. Store the checkout id and token from the response, as you'll need both to add line items and process this checkout.

Guest Checkout

If no authentication token is provided, the checkout will be created for an anonymous user. You can optionally pass the email argument to associate the checkout with an email address.

Request

mutation {
  checkoutCreate(
    input: { email: "buyer@example.com", lines: [] }
  ) {
    checkout {
      id
      token
    }
  }
}

---

Step 2: Add checkout lines

A CheckoutLine represents a given quantity of a product variant in the buyer's cart. When a buyer adds an item to their cart, it creates or updates a checkout line.

1

Add a checkout line

Adding a checkout line requires the following arguments:

Argument	Usage
checkoutId	The id of the checkout session.
lines.variantId	The id of the product variant.
lines.quantity	The number of units of the product variant.

The following mutation adds a single line to the checkout. Subsequent checkoutLinesAdd mutations for the same variantId increase the quantity of the same checkout line.

Request

mutation {
  checkoutLinesAdd(
    checkoutId: "Q2hlY2tvdXQ6NWEyZDQ5NTUtY2UwNS00YTZjLTkyNzEtNjdmMjY0ZWNlNDFl"
    lines: { quantity: 5, variantId: "UHJvZHVjdFZhcmlhbnQ6NTkz" }
  ) {
    checkout {
      lines {
        id
        quantity
        variant {
          name
        }
        totalPrice {
          net {
            baseAmount
            currency
          }
        }
      }
    }
    checkoutErrors {
      code
      field
      message
    }
  }
}

Show more ↓

2

(Optional)Add a note to a checkout line

3

(Optional)Update checkout line quantity

4

(Optional)Remove a checkout line

---

Step 3: Select shipping address and methods

When the checkout contains lines that require shipping (physical products), you must set the shipping methods for each seller order before you can complete the checkout.

1

(Optional)Query whether shipping is required

2

(Optional)Query current user address

3

Update the checkout shipping address

The shipping address can be inputted when creating the initial checkout session, or added later using the checkoutShippingAddressUpdate mutation.

The following mutation updates the shipping address in a checkout session:

Request

mutation {
  checkoutShippingAddressUpdate(
    checkoutId: "Q2hlY2tvdXQ6YWZlMzU4ZjctNTdkZC00NDU4LThiYTYtNWFjYTkzZDAxMTNj"
    shippingAddress: {
      firstName: "Martha"
      lastName: "Mack"
      streetAddress1: "227 Green Motorway"
      city: "South Robert"
      postalCode: "85357"
      countryArea: "AZ"
      country: US
    }
  ) {
    checkout {
      id
      shippingAddress {
        firstName
        lastName
        phone
        streetAddress1
        streetAddress2
        city
        postalCode
        countryArea
        country {
          country
          code
        }
      }
      quantity
      currency
      email
      isShippingRequired
      token
      created
      lastChange
    }
    checkoutErrors {
      field
      message
      code
      variants
    }
  }
}

Show more ↓

4

Query available shipping methods

The following query returns the available shipping methods that can be used for a given checkout. Because shipping is assigned per seller, the available rates are organized by seller.

Save the seller and value.id from the response, which you'll need to set shipping methods for the checkout:

Request

query {
  checkout(token: "afe358f7-57dd-4454-858a-5aca9dc0113c") {
    availableShippingMethodsBySeller {
      sellerName
      seller
      value {
        id
        name
        type
        price {
          baseAmount
          currency
        }
      }
    }
  }
}

5

Assign shipping methods by seller

Now that we know which lines require shipping, and what shipping methods are available to each, we can select shipping methods for each seller order using the checkoutSellerShippingMethodsBulkUpdate mutation.

This mutation requires the following arguments:

Argument	Usage
checkoutId	The id of the checkout session.
seller	The seller number. All checkout lines associated with this seller will be assigned this shipping method.
shippingMethodSelection	The id of the shipping method.

The following mutation pairs each seller with a shipping method:

Request

mutation {
  checkoutSellerShippingMethodsBulkUpdate(
    checkoutId: "Q2hlY2tvdXQ6YWZlMzU4ZjctNTdkZC00NDU0LTg1OGEtNWFjYTlkYzAxMTNj"
    sellerShippingMethods: [
      { seller: "1", shippingMethodSelection: "U2hpcHBpbmdNZXRob2Q6MTQ="}
      { seller: "9", shippingMethodSelection: "U2hpcHBpbmdNZXRob2Q6MTI="}
    ]
  ) {
    checkout {
      id
      token
      sellerShippingMethods
      totalPrice {
        net {
          baseAmount
          currency
        }
      }
    }
    checkoutErrors {
      message
      field
      code
    }
  }
}

Show more ↓

6

(Optional)Override shipping prices

Result

After assigning shipping methods to both seller orders, the totalPrice on the checkout is updated to include the shipping cost.

---

Step 4: Process payment

Depending on the selected payment gateway, you will either use a webform integrated with Nautical, or the payment gateway will direct you to an external payment page.

The payment gateway sends information about if the payment is successful, along with tokenized credit card payment information. This token is then used to run the checkoutPaymentCreate mutation.

1

Add billing address

The billing address can be inputted when creating the initial checkout session, or added later using the checkoutBillingAddressUpdate mutation.

The following mutation updates the billing address in a checkout session:

Request

mutation {
  checkoutBillingAddressUpdate(
    billingAddress: {
      firstName: "Martha"
      lastName: "Mack"
      streetAddress1: "227 Green Motorway"
      city: "South Robert"
      postalCode: "85357"
      countryArea: "AZ"
      country: US
    }
    checkoutId: "Q2hlY2tvdXQ6YWZlMzU4ZjctNTdkZC00NDU0LTg1OGEtNWFjYTlkYzAxMTNj"
  ) {
    checkout {
      id
      token
      billingAddress {
        firstName
        lastName
        phone
        streetAddress1
        streetAddress2
        city
        postalCode
        countryArea
        country {
          country
          code
        }
      }
    }
    checkoutErrors {
      field
      message
      code
      variants
    }
  }
}

Show more ↓

2

(Optional)Query checkout total

3

(Optional)Query available payment gateways

4

Choose payment method

How you process a payment depends on the selected payment gateway.

Assuming you are using an integrated app like Stripe or Braintree, you will first need to generate a payment intent client secret that you will use for the next step.

With Stripe for example, the payment intent is created when the customer gets to the Stripe checkout screen. See Accepting Payments with Stripe for more information.

Request

query {
  getClientSecret(
    gateway: "nautical.payments.stripe"
    paymentInformation: {
      checkoutId: "Q2hlY2tvdXQ6NWEyZDQ5NTUtY2UwNS00YTZjLTkyNzEtNjdmMjY0ZWNlNDFl"
      paymentMethodToken: "pm_1OUGADCp3bxKlBq1ycTryyF6"
      customerEmail: "buyer@example.com"
      customerId: "cus_PIruOzl2CNfhsq"
      amount: 205.68
      currency: "USD"
    }
  )

5

Create a payment

Creating a payment requires the following arguments:

Argument	Usage
checkoutId	The id of the target checkout session.
input.gateway	The id of the payment gateway, such as nautical.payments.stripe or nautical.payments.wire.
input.token	The id of the payment token from the gateway, generated with getClientSecret.
input.amount	The total amount for the payment.

The following mutation creates a payment against a checkout using the payment intent retrieved from the client:

Request

mutation {
  checkoutPaymentCreate(
    checkoutId: "Q2hlY2tvdXQ6YWZlMzU4ZjctNTdkZC00NDU0LTg1OGEtNWFjYTlkYzAxMTNj"
    input: {
      gateway: "nautical.payments.stripe"
      token: "pi_3OQCnNCp3bxKlBq11VSh6DnW"
      amount: 1663.50
    }
  ) {
    checkout {
      id
      token
    }
    payment {
      id
      chargeStatus
    }
    paymentErrors {
      field
      message
      code
    }
  }
}

Show more ↓

6

Complete the checkout

Completing a checkout requires the following arguments:

Argument	Usage
checkoutId	The id of the target checkout session.
volumeDiscount	The volume discount to apply. Leave as 0 if no volume discount applies.

Request

mutation {
  checkoutComplete(
    checkoutId: "Q2hlY2tvdXQ6YWZlMzU4ZjctNTdkZC00NDU0LTg1OGEtNWFjYTlkYzAxMTNj"
    volumeDiscount: 0
  ) {
    order {
      id
      status
      }
    checkoutErrors {
      field
      message
      code
      variants
    }
  }
}

Result

The checkoutComplete mutation finalizes a checkout and transforms it into an order. During this process, several validations are performed:

• The shipping and billing addresses provided are validated as required.
• The selected order lines are checked to ensure they are still in stock. It's possible that while the purchase is being made, another user may have already bought the last available item.
• The payment creation is verified for success.
• Any additional actions required by the payment service provider (PSP) are completed.

If all these conditions are met, the checkout is successfully converted into an order, and the customer receives a confirmation email.