The SDK can be configured in a few ways.

FieldOptional / RequiredDescription
gr4vyIdRequiredThe Gr4vy ID automatically sets the apiHost to api.<gr4vyId>.gr4vy.app for production and api.sandbox.<gr4vyId>.gr4vy.app and to embed.sandbox.<gr4vyId>.gr4vy.app for the sandbox environment.
tokenRequiredThe server-side generated JWT token which will be used to authenticate any of the API calls.
environmentOptional.sandbox, .production. Defaults to .production. When .sandbox is provided the URL will contain sandbox.GR4VY_ID.
amountRequiredThe amount to authorize or capture in the specified currency only.
currencyRequiredA valid, active, 3-character ISO 4217 currency code to authorize or capture the amount for.
countryRequiredA valid ISO 3166 country code.
buyerIdOptionalAn optional ID for a buyer. The transaction will automatically be associated with a buyer with that ID. If no buyer with this ID exists then it will be ignored.
buyerExternalIdentifierOptionalAn optional external ID for a Gr4vy buyer. The transaction will automatically be associated with a buyer with that external ID. If no buyer with this external ID exists then it will be ignored. This option is ignored if the buyerId is provided.
presentingViewControllerRequiredThe view controller that opens the payment sheet.
externalIdentifierOptionalAn optional external identifier that can be supplied. This will automatically be associated with any resource that opens the payment sheet and subsequently used to find a resource by that ID.
storeOptional'ask', true, false - Explicitly store the payment method or ask the buyer, this is used when a buyerId is provided.
displayOptionalall, addOnly, storedOnly, supportsTokenization - Filters the payment methods to show stored methods only, new payment methods only or methods that support tokenization.
intentOptionalauthorize, capture - Defines the intent of this API call. This determines the desired initial state of the transaction.
metadataOptionalAn optional dictionary of keys and values for transaction metadata. All values should be a string.
paymentSourceOptionalinstallment, recurring - Can be used to signal that Embed is used to capture the first transaction for a subscription or an installment. When used, store is implied to be true and display is implied to be supportsTokenization. This means that payment options that do not support tokenization are automatically hidden.
cartItemsOptionalAn optional array of cart item objects, each object must define a name, quantity, and unitAmount.
applePayMerchantIdOptionalThe Apple merchant ID to be used during Apple Pay transactions.
debugModeOptionaltrue, false. Defaults to false, this prints to the console.
themeOptionalTheme customization options. See Theming. The iOS SDK also contains an additional two properties within the colors object; headerBackground and headerText. These are used for the navigation background and foreground colors.
localeOptionalAn optional locale, consists of an ISO 639 Language Code followed by an optional ISO 3166 Country Code, e.g. en, en-gb or pt-br.
statementDescriptorOptionalAn optional object with information about the purchase to construct the statement information the buyer will see in their bank statement. Please note support for these fields varies across payment service providers and underlying banks, so Gr4vy can only ensure a best-effort approach for each supported platform. As an example, most platforms will only support a concatenation of the name and description fields, this is truncated to a length of 22 characters within embed. The object can contain name, description, phoneNumber, city and url properties, with string values. phoneNumber should be in E164 format. Gr4vy recommends avoiding characters outside the alphanumeric range and the dot (.) to ensure wide compatibility.
requireSecurityCodeOptionalAn optional boolean that forces security code to be prompted for stored card payments.
shippingDetailsIdOptionalAn optional unique identifier of a set of shipping details stored for the buyer.
merchantAccountIdOptionalAn optional merchant account ID.
onEventOptionalPlease see below for more details.

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.

The possible values for your ID are one of wpay, wpay1, wpay2, or wpay3. We will inform you in which instance your account has been set up.