Before you add the SDK to your iOS app you will need to create a client token that can be used to authenticate the transaction.

​
Install a server-side SDK

Use the package manager in your preferred programming language to install our server-side SDK. Token generation can only be done server side and we do not recommend doing this client side as it will expose your API key to your customers.

npm install @gr4vy/node --save
# or: yarn add @gr4vy/node

Please install the latest release of your preferred SDK.

​
Initialize the SDK client

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

const fs = require("fs");
const { Client } = require("@gr4vy/node");
// or: import { Client } from "@gr4vy/node";

const key = String(fs.readFileSync("./private_key.pem"));

const client = new Client({
  gr4vyId: "[GR4VY_ID]",
  privateKey: key,
  environment: "sandbox",
});

The Gr4vy ID is the unique identifier for your instance. Together with the environment (sandbox or production) it is used to connect to the right APIs.

This assumes the key you created in the previous step is kept in a file called private_key.pem that is kept in the same folder next to the code. You could store this key in an environment variable or a secure vault.

​
Generate a token

The final step is to create a new token for frontend authentication. The SDK comes with a helper function for exactly that purpose. It requires an amount and currency for the transaction to be created and additionally accepts either the ID of a buyer or your external identifier for a buyer to link the transaction to.

const response = await client.newCheckoutSession();
const token = await client.getEmbedToken({
  amount: 1299,
  currency: "AUD",
  checkoutSessionId: response.body.id,
  buyerExternalIdentifier: "user-12345",
  metadata: { key: "value" },
  cartItems: [
    {
      name: "Joust Duffle Bag",
      quantity: 1,
      unitAmount: 9000,
      taxAmount: 0,
      categories: ["Gear", "Bags", "Test"],
    },
  ],
});

This token can now be served to the frontend where it will be used by our SDK.

If you would prefer to generate the client token without using a server-side SDK, then please read our guide on manually generating a JWT.

Data Pinning

We recommend pinning metadata and cart_items in the token to prevent the values being manipulated during a frontend client session. Alternatively, these can be stored in a Checkout session.

​
Checkout sessions

An optional ID for a checkout session can be used to help identify multiple transaction attempts. This is useful to identify if one or more failed/declined transactions eventually result in a successful transaction.

Checkout sessions can store cart_items and metadata. This removes the need to pin them or pass as a parameter to Embed.

const response = await this.newCheckoutSession({
  cartItems: [
    {
      name: "Joust Duffle Bag",
      quantity: 1,
      unitAmount: 9000,
      taxAmount: 0,
      categories: ["Gear", "Bags", "Test"],
    },
  ],
  metadata: { key: "value" },
});

const token = await client.getEmbedToken({
  amount: 1299,
  currency: "AUD",
  checkoutSessionId: response.body.id,
  buyerExternalIdentifier: "user-12345",
});

Checkout session expiry

Checkout sessions expire after 1 hour. Updating a checkout session will not extend the time.

​
Loading token in iOS

The token needs to be shared with your iOS application via your own API. We recommend you create a token per checkout and only use a token for a short amount of time.

​
Summary

In this step you:

  • Created a signed JWT token using a server-side SDK.
  • Shared the JWT with your iOS application