Creating checkout sessions

Before using Secure Fields in the web checkout, create a checkout session.

Install a server-side SDK

Use the package manager in the preferred programming language to install the server-side SDK. Token generation can only be done server side and doing this client side is not recommended as it exposes the API key to customers.

dotnet add package Gr4vy

go get github.com/gr4vy/gr4vy-go

# Please check for the latest version
implementation 'com.gr4vy:sdk:1.0.0'

composer require "gr4vy/gr4vy-php"

pip install gr4vy

npm install @gr4vy/sdk
# or: yarn add @gr4vy/sdk

Please always check and install the latest release of the preferred SDK.

Initialize the SDK client

Next, initialize the SDK with the ID of the instance and the private key.

using Gr4vy;
using Gr4vy.Models.Components;
using System.Collections.Generic;

// Loaded the key from a file, env variable, 
// or anywhere else
var privateKey = "..."; 

var sdk = new Gr4vySDK(
    id: "example",
    server: SDKConfig.Server.Sandbox,
    bearerAuthSource: Auth.WithToken(privateKey),
    merchantAccountId: "default"
);

package main

import (
	"context"
	gr4vy "github.com/gr4vy/gr4vy-go"
	"github.com/gr4vy/gr4vy-go/models/operations"
	"log"
	"os"
)

func main() {
	ctx := context.Background()

	privateKey := "...." // Private key loaded from disk or env var
	withToken := gr4vy.WithToken(privateKey, []JWTScope{ReadAll, WriteAll}, 60)

	s := gr4vy.New(
		gr4vy.WithID("example"),
		gr4vy.WithServer(gr4vy.ServerSandbox),
		gr4vy.WithSecuritySource(withToken),
		gr4vy.WithMerchantAccountID("default"),
	)
}

package hello.world;

import com.gr4vy.sdk.BearerSecuritySource;
import com.gr4vy.sdk.Gr4vy;
import com.gr4vy.sdk.Gr4vy.AvailableServers;
import com.gr4vy.sdk.models.components.AccountUpdaterJobCreate;
import com.gr4vy.sdk.models.errors.*;
import com.gr4vy.sdk.models.operations.ListTransactionsRequest;
import java.lang.Exception;
import java.util.List;

public class Application {

    public static void main(String[] args) throws Exception {

        String privateKey = "-----BEGIN PRIVATE KEY-----\n...."; // a valid private key

        Gr4vy sdk = Gr4vy.builder()
                .id("example")
                .server(AvailableServers.SANDBOX)
                .merchantAccountId("default")
                .securitySource(new BearerSecuritySource.Builder(privateKey).build())
            .build();
    }
}

declare(strict_types=1);

require 'vendor/autoload.php';

use Gr4vy;
use Gr4vy\Auth;

// Loaded the key from a file, env variable, 
// or anywhere else
$privateKey = "..."; 

$sdk = Gr4vy\SDK::builder()
    ->setId('example')
    ->setServer('sandbox')
    ->setSecuritySource(Auth::withToken($privateKey))
    ->setMerchantAccountId('default')
    ->build();

from gr4vy import Gr4vy, auth
import os

client = Gr4vy(
    id="example",
    server="production",
    merchant_account_id="default",
    bearer_auth=auth.with_token(open("./private_key.pem").read())
)

import fs from "fs";
import { Gr4vy, withToken } from "@gr4vy/sdk";

const gr4vy = new Gr4vy({
    server: "sandbox",
    id: "example",
    bearerAuth: withToken({
      privateKey: fs.readFileSync("private_key.pem", "utf8"),
    }),
});

The instance ID is the unique identifier for the deployment of the system and is included in every API call. Together with the environment (sandbox or production) it is used to connect to the right APIs, as well as dashboard.

Generate a Checkout Session

The final step is to create a new checkout session for use by Secure Fields. Checkout sessions can also store cart_items, metadata, buyer, and airline data, removing the need to pass these values on the transaction request.

using Gr4vy;
using Gr4vy.Models.Components;
using NodaTime;
using System;
using System.Collections.Generic;

var sdk = new Gr4vySDK(
    merchantAccountId: "default",
    bearerAuth: "<YOUR_BEARER_TOKEN_HERE>"
);

var checkoutSession = await sdk.CheckoutSessions.CreateAsync(checkoutSessionCreate: new CheckoutSessionCreate() {
    CartItems = new List<CartItem>() {
        new CartItem() {
            Name = "GoPro HD",
            Quantity = 2,
            UnitAmount = 1299,
            DiscountAmount = 0,
            TaxAmount = 0,
            ExternalIdentifier = "goprohd",
            Sku = "GPHD1078",
            ProductUrl = "https://example.com/catalog/go-pro-hd",
            ImageUrl = "https://example.com/images/go-pro-hd.jpg",
            Categories = new List<string>() {
                "camera",
                "travel",
                "gear",
            },
            ProductType = "physical",
            SellerCountry = "GB",
        },
        new CartItem() {
            Name = "GoPro HD",
            Quantity = 2,
            UnitAmount = 1299,
            DiscountAmount = 0,
            TaxAmount = 0,
            ExternalIdentifier = "goprohd",
            Sku = "GPHD1078",
            ProductUrl = "https://example.com/catalog/go-pro-hd",
            ImageUrl = "https://example.com/images/go-pro-hd.jpg",
            Categories = new List<string>() {
                "camera",
                "travel",
                "gear",
            },
            ProductType = "physical",
            SellerCountry = "GB",
        },
        new CartItem() {
            Name = "GoPro HD",
            Quantity = 2,
            UnitAmount = 1299,
            DiscountAmount = 0,
            TaxAmount = 0,
            ExternalIdentifier = "goprohd",
            Sku = "GPHD1078",
            ProductUrl = "https://example.com/catalog/go-pro-hd",
            ImageUrl = "https://example.com/images/go-pro-hd.jpg",
            Categories = new List<string>() {
                "camera",
                "travel",
                "gear",
            },
            ProductType = "physical",
            SellerCountry = "US",
        },
    },
    Metadata = new Dictionary<string, string>() {
        { "cohort", "cohort-a" },
        { "order_id", "order-12345" },
    },
    Buyer = new GuestBuyer() {
        DisplayName = "John Doe",
        ExternalIdentifier = "buyer-12345",
        BillingDetails = new BillingDetails() {
            FirstName = "John",
            LastName = "Doe",
            EmailAddress = "john@example.com",
            PhoneNumber = "+1234567890",
            Address = new Address() {
                City = "San Jose",
                Country = "US",
                PostalCode = "94560",
                State = "California",
                StateCode = "US-CA",
                HouseNumberOrName = "10",
                Line1 = "Stafford Appartments",
                Line2 = "29th Street",
                Organization = "Gr4vy",
            },
            TaxId = new TaxId() {
                Value = "12345678931",
                Kind = "ar.cuit",
            },
        },
        ShippingDetails = new ShippingDetailsCreate() {
            FirstName = "John",
            LastName = "Doe",
            EmailAddress = "john@example.com",
            PhoneNumber = "+1234567890",
            Address = new Address() {
                City = "San Jose",
                Country = "US",
                PostalCode = "94560",
                State = "California",
                StateCode = "US-CA",
                HouseNumberOrName = "10",
                Line1 = "Stafford Appartments",
                Line2 = "29th Street",
                Organization = "Gr4vy",
            },
        },
    },
});

// handle response

package main

import(
	"context"
	gr4vygo "github.com/gr4vy/gr4vy-go"
	"os"
	"github.com/gr4vy/gr4vy-go/models/components"
	"github.com/gr4vy/gr4vy-go/types"
	"log"
)

func main() {
    ctx := context.Background()

    s := gr4vygo.New(
        gr4vygo.WithMerchantAccountID("default"),
        gr4vygo.WithSecurity(os.Getenv("GR4VY_BEARER_AUTH")),
    )

    checkoutSession, err := s.CheckoutSessions.Create(ctx, &components.CheckoutSessionCreate{
        CartItems: []components.CartItem{
            components.CartItem{
                Name: "GoPro HD",
                Quantity: 2,
                UnitAmount: 1299,
                DiscountAmount: gr4vygo.Int64(0),
                TaxAmount: gr4vygo.Int64(0),
                ExternalIdentifier: gr4vygo.String("goprohd"),
                Sku: gr4vygo.String("GPHD1078"),
                ProductURL: gr4vygo.String("https://example.com/catalog/go-pro-hd"),
                ImageURL: gr4vygo.String("https://example.com/images/go-pro-hd.jpg"),
                Categories: []string{
                    "camera",
                    "travel",
                    "gear",
                },
                ProductType: components.ProductTypePhysical.ToPointer(),
                SellerCountry: gr4vygo.String("US"),
            },
            components.CartItem{
                Name: "GoPro HD",
                Quantity: 2,
                UnitAmount: 1299,
                DiscountAmount: gr4vygo.Int64(0),
                TaxAmount: gr4vygo.Int64(0),
                ExternalIdentifier: gr4vygo.String("goprohd"),
                Sku: gr4vygo.String("GPHD1078"),
                ProductURL: gr4vygo.String("https://example.com/catalog/go-pro-hd"),
                ImageURL: gr4vygo.String("https://example.com/images/go-pro-hd.jpg"),
                Categories: []string{
                    "camera",
                    "travel",
                    "gear",
                },
                ProductType: components.ProductTypePhysical.ToPointer(),
                SellerCountry: gr4vygo.String("US"),
            },
        },
        Metadata: map[string]string{
            "cohort": "cohort-a",
            "order_id": "order-12345",
        },
        Buyer: nil,
    })
    if err != nil {
        log.Fatal(err)
    }
    if checkoutSession != nil {
        // handle response
    }
}

package hello.world;

import com.gr4vy.sdk.Gr4vy;
import com.gr4vy.sdk.models.components.*;
import com.gr4vy.sdk.models.errors.*;
import com.gr4vy.sdk.models.operations.CreateCheckoutSessionResponse;
import java.lang.Exception;
import java.time.LocalDate;
import java.time.OffsetDateTime;
import java.util.List;
import java.util.Map;
import org.openapitools.jackson.nullable.JsonNullable;

public class Application {

    public static void main(String[] args) throws Exception {

        Gr4vy sdk = Gr4vy.builder()
                .merchantAccountId("default")
                .bearerAuth("<YOUR_BEARER_TOKEN_HERE>")
            .build();

        CreateCheckoutSessionResponse res = sdk.checkoutSessions().create()
                .checkoutSessionCreate(CheckoutSessionCreate.builder()
                    .cartItems(List.of(
                        CartItem.builder()
                            .name("GoPro HD")
                            .quantity(2L)
                            .unitAmount(1299L)
                            .discountAmount(0L)
                            .taxAmount(0L)
                            .externalIdentifier("goprohd")
                            .sku("GPHD1078")
                            .productUrl("https://example.com/catalog/go-pro-hd")
                            .imageUrl("https://example.com/images/go-pro-hd.jpg")
                            .categories(List.of(
                                "camera",
                                "travel",
                                "gear"))
                            .productType(ProductType.PHYSICAL)
                            .sellerCountry("US")
                            .build(),
                        CartItem.builder()
                            .name("GoPro HD")
                            .quantity(2L)
                            .unitAmount(1299L)
                            .discountAmount(0L)
                            .taxAmount(0L)
                            .externalIdentifier("goprohd")
                            .sku("GPHD1078")
                            .productUrl("https://example.com/catalog/go-pro-hd")
                            .imageUrl("https://example.com/images/go-pro-hd.jpg")
                            .categories(List.of(
                                "camera",
                                "travel",
                                "gear"))
                            .productType(ProductType.PHYSICAL)
                            .sellerCountry("US")
                            .build()))
                    .metadata(Map.ofEntries(
                        Map.entry("cohort", "cohort-a"),
                        Map.entry("order_id", "order-12345")))
                    .buyer(JsonNullable.of(null))
                    .build())
                .call();

        if (res.checkoutSession().isPresent()) {
            // handle response
        }
    }
}

declare(strict_types=1);

require 'vendor/autoload.php';

use Brick\DateTime\LocalDate;
use Gr4vy;
use Gr4vy\Utils;

$sdk = Gr4vy\SDK::builder()
    ->setMerchantAccountId('default')
    ->setSecurity(
        '<YOUR_BEARER_TOKEN_HERE>'
    )
    ->build();

$checkoutSessionCreate = new Gr4vy\CheckoutSessionCreate(
    cartItems: [
        new Gr4vy\CartItem(
            name: 'GoPro HD',
            quantity: 2,
            unitAmount: 1299,
            discountAmount: 0,
            taxAmount: 0,
            externalIdentifier: 'goprohd',
            sku: 'GPHD1078',
            productUrl: 'https://example.com/catalog/go-pro-hd',
            imageUrl: 'https://example.com/images/go-pro-hd.jpg',
            categories: [
                'camera',
                'travel',
                'gear',
            ],
            productType: 'physical',
            sellerCountry: 'US',
        ),
        new Gr4vy\CartItem(
            name: 'GoPro HD',
            quantity: 2,
            unitAmount: 1299,
            discountAmount: 0,
            taxAmount: 0,
            externalIdentifier: 'goprohd',
            sku: 'GPHD1078',
            productUrl: 'https://example.com/catalog/go-pro-hd',
            imageUrl: 'https://example.com/images/go-pro-hd.jpg',
            categories: [
                'camera',
                'travel',
                'gear',
            ],
            productType: 'physical',
            sellerCountry: 'US',
        ),
    ],
    metadata: [
        'cohort' => 'cohort-a',
        'order_id' => 'order-12345',
    ],
    buyer: new Gr4vy\GuestBuyer(
        displayName: 'John Doe',
        externalIdentifier: 'buyer-12345',
        billingDetails: new Gr4vy\BillingDetails(
            firstName: 'John',
            lastName: 'Doe',
            emailAddress: 'john@example.com',
            phoneNumber: '+1234567890',
            address: new Gr4vy\Address(
                city: 'San Jose',
                country: 'US',
                postalCode: '94560',
                state: 'California',
                stateCode: 'US-CA',
                houseNumberOrName: '10',
                line1: 'Stafford Appartments',
                line2: '29th Street',
                organization: 'Gr4vy',
            ),
            taxId: new Gr4vy\TaxId(
                value: '12345678931',
                kind: 'my.frp',
            ),
        ),
        shippingDetails: new Gr4vy\ShippingDetailsCreate(
            firstName: 'John',
            lastName: 'Doe',
            emailAddress: 'john@example.com',
            phoneNumber: '+1234567890',
            address: null,
        ),
    ),
);

$response = $sdk->checkoutSessions->create(
    checkoutSessionCreate: $checkoutSessionCreate
);

if ($response->checkoutSession !== null) {
    // handle response
}

from datetime import date
from gr4vy import Gr4vy, models
from gr4vy.utils import parse_datetime
import os

with Gr4vy(
    merchant_account_id="default",
    bearer_auth=os.getenv("GR4VY_BEARER_AUTH", ""),
) as g_client:

    checkout_session = g_client.checkout_sessions.create(checkout_session_create=models.CheckoutSessionCreate(
        cart_items=[
            models.CartItem(
                name="GoPro HD",
                quantity=2,
                unit_amount=1299,
                discount_amount=0,
                tax_amount=0,
                external_identifier="goprohd",
                sku="GPHD1078",
                product_url="https://example.com/catalog/go-pro-hd",
                image_url="https://example.com/images/go-pro-hd.jpg",
                categories=[
                    "camera",
                    "travel",
                    "gear",
                ],
                product_type="physical",
                seller_country="GB",
            ),
            models.CartItem(
                name="GoPro HD",
                quantity=2,
                unit_amount=1299,
                discount_amount=0,
                tax_amount=0,
                external_identifier="goprohd",
                sku="GPHD1078",
                product_url="https://example.com/catalog/go-pro-hd",
                image_url="https://example.com/images/go-pro-hd.jpg",
                categories=[
                    "camera",
                    "travel",
                    "gear",
                ],
                product_type="physical",
                seller_country="GB",
            ),
            models.CartItem(
                name="GoPro HD",
                quantity=2,
                unit_amount=1299,
                discount_amount=0,
                tax_amount=0,
                external_identifier="goprohd",
                sku="GPHD1078",
                product_url="https://example.com/catalog/go-pro-hd",
                image_url="https://example.com/images/go-pro-hd.jpg",
                categories=[
                    "camera",
                    "travel",
                    "gear",
                ],
                product_type="physical",
                seller_country="GB",
            ),
        ],
        metadata={
            "cohort": "cohort-a",
            "order_id": "order-12345",
        },
        buyer=models.GuestBuyer(
            display_name="John Doe",
            external_identifier="buyer-12345",
            billing_details=models.BillingDetails(
                first_name="John",
                last_name="Doe",
                email_address="john@example.com",
                phone_number="+1234567890",
                address=models.Address(
                    city="San Jose",
                    country="US",
                    postal_code="94560",
                    state="California",
                    state_code="US-CA",
                    house_number_or_name="10",
                    line1="Stafford Appartments",
                    line2="29th Street",
                    organization="Gr4vy",
                ),
                tax_id=models.TaxID(
                    value="12345678931",
                    kind="ar.cuit",
                ),
            ),
            shipping_details=models.ShippingDetailsCreate(
                first_name="John",
                last_name="Doe",
                email_address="john@example.com",
                phone_number="+1234567890",
                address=models.Address(
                    city="San Jose",
                    country="US",
                    postal_code="94560",
                    state="California",
                    state_code="US-CA",
                    house_number_or_name="10",
                    line1="Stafford Appartments",
                    line2="29th Street",
                    organization="Gr4vy",
                ),
            ),
        ),
    ))

    # Handle response
    print(checkout_session)

import { Gr4vy } from '@gr4vy/sdk'

const gr4vy = new Gr4vy({
    gr4vyId: 'your-gr4vy-id',
    privateKey: 'your-private-key',
    environment: 'sandbox',
})

async function createCheckoutSession() {
    const checkoutSession = await gr4vy.checkoutSessions.create({
        amount: 1000,
        currency: 'USD',
        country: 'US',
        cartItems: [
            {
                name: 'GoPro HD',
                quantity: 2,
                unitAmount: 1299,
                discountAmount: 0,
                taxAmount: 0,
                externalIdentifier: 'goprohd',
                sku: 'GPHD1078',
                productUrl: 'https://example.com/catalog/go-pro-hd',
                imageUrl: 'https://example.com/images/go-pro-hd.jpg',
                categories: ['camera', 'travel', 'gear'],
                productType: 'physical',
                sellerCountry: 'GB',
            },
            {
                name: 'GoPro HD',
                quantity: 2,
                unitAmount: 1299,
                discountAmount: 0,
                taxAmount: 0,
                externalIdentifier: 'goprohd',
                sku: 'GPHD1078',
                productUrl: 'https://example.com/catalog/go-pro-hd',
                imageUrl: 'https://example.com/images/go-pro-hd.jpg',
                categories: ['camera', 'travel', 'gear'],
                productType: 'physical',
                sellerCountry: 'GB',
            },
            {
                name: 'GoPro HD',
                quantity: 2,
                unitAmount: 1299,
                discountAmount: 0,
                taxAmount: 0,
                externalIdentifier: 'goprohd',
                sku: 'GPHD1078',
                productUrl: 'https://example.com/catalog/go-pro-hd',
                imageUrl: 'https://example.com/images/go-pro-hd.jpg',
                categories: ['camera', 'travel', 'gear'],
                productType: 'physical',
                sellerCountry: 'US',
            },
        ],
        metadata: {
            cohort: 'cohort-a',
            order_id: 'order-12345',
        },
        buyer: {
            displayName: 'John Doe',
            externalIdentifier: 'buyer-12345',
            billingDetails: {
                firstName: 'John',
                lastName: 'Doe',
                emailAddress: 'john@example.com',
                phoneNumber: '+1234567890',
                address: {
                    city: 'San Jose',
                    country: 'US',
                    postalCode: '94560',
                    state: 'California',
                    stateCode: 'US-CA',
                    houseNumberOrName: '10',
                    line1: 'Stafford Appartments',
                    line2: '29th Street',
                    organization: 'Gr4vy',
                },
                taxId: {
                    value: '12345678931',
                    kind: 'ar.cuit',
                },
            },
            shippingDetails: {
                firstName: 'John',
                lastName: 'Doe',
                emailAddress: 'john@example.com',
                phoneNumber: '+1234567890',
                address: {
                    city: 'San Jose',
                    country: 'US',
                    postalCode: '94560',
                    state: 'California',
                    stateCode: 'US-CA',
                    houseNumberOrName: '10',
                    line1: 'Stafford Appartments',
                    line2: '29th Street',
                    organization: 'Gr4vy',
                },
            },
        },
    })
    console.log(checkoutSession)
}

createCheckoutSession()

The id of this session can now be passed to the checkout page, where it can be used by Secure Fields.

How session values reach the transaction

When you create a transaction with the checkout session, Gr4vy copies the session’s cart_items, metadata, buyer, and airline values into the transaction. Which value wins when both the session and the transaction request set the same field depends on how the transaction uses the session.

How the transaction uses the session	Which value wins
As the payment method (`"method": "checkout-session"`), as with Secure Fields	The value in the transaction request. The session’s value fills in only fields that the request leaves out.
Pinned in the token with the `checkout_session_id` claim	The value on the session. It replaces the value in the transaction request.

Gr4vy replaces each field as a whole and never merges the two values. For example, if both set cart_items, the transaction gets one list of cart items, not both lists combined. A transaction that charges a stored payment method by its id, without a checkout session, doesn’t get any of these values. Send them on the transaction request instead.

Summary

In this step:

Installed the SDK
Created a new checkout session.
Passed the id of this session to the front-end app, where it is used by Secure Fields.

Get started

Integration guides

Best Practices

Resources

Features

Other

Creating checkout sessions

Install a server-side SDK

Initialize the SDK client

Generate a Checkout Session

How session values reach the transaction

Summary

​Install a server-side SDK

​Initialize the SDK client

​Generate a Checkout Session

​How session values reach the transaction

​Summary

Install a server-side SDK

Initialize the SDK client

Generate a Checkout Session

How session values reach the transaction

Summary