Skip to main content
In no particular order, here are some useful recommendations when integrating the API, Embed, or Secure Fields.

​
Associate transactions with a buyer

A Buyer allows transactions to be linked with customers as well as send buyer-specific information such as name, email, address and tax ID, etc. See Buyers for further details.

​
Set a unique reference ID for each transaction

A unique transaction reference ID helps link transactions to orders (see step 2). A unique reference ID can either be set as an external identifier or metadata on the transaction. This is available when using Embed, Secure Fields, or the API directly. Embed is sometimes displayed at checkout before an order is created by the system. After all, creating an order every time a customer loads a checkout page is not desired. An onBeforeTransaction callback in Embed has been introduced that can be used to set the externalIdentifier or metadata right before a transaction is created. This allows a unique reference ID to be created just-in-time before a transaction is created by Embed.
Update the external identifier
embed.setup({
  onBeforeTransaction: async () => {
    // Merchant could make a call to a server here to get an order ID.
    // let { orderId } = await client.getOrder()
    return { 
      externalIdentifier: orderId,
    }
  }
})
Metadata can be updated in a similar way. In the case that the metadata has been pinned, the JWT token also needs to be updated because the metadata may be pinned in the token.
Update the metadata
embed.setup({
  onBeforeTransaction: async ({ metadata }) => {
    // Merchant could make a call to a server here to get an order ID.
    // let { orderId, newToken } = client.getOrder()
    return { 
      token: newToken,
      metadata: {
        ...metadata,
        orderId: orderId
      }
    }
  }
})

​
Use webhooks to listen for transaction updates

It is recommended to listen for updates to transactions by using webhooks. As a unique reference ID has been set (see preceding section), this can be used to listen to webhook events, which notify of a transaction completing, failing, or being declined. Please reach out to the team to set up the webhook URL.
It is highly recommended to use webhooks and not exclusively rely on any in-browser events like Embed’s transactionCreated event or onComplete callback. Because browsers are an unreliable environment this message between Embed and the system could get lost for many reasons, and so listening to webhook updates is generally considered the only fully reliable option when dealing with transaction updates.

​
Use idempotent requests

Sometimes transactions fail, either because of bad input or because of some kind of network or other system error. In the case of an error where the response was not received by the buyer’s browser (or the system), a transaction can be retried using a special header. 
curl -i -X POST "https://api.{gr4vyId}.gr4vy.app/transactions" \
 -H "Authorization: Bearer {jwtToken}" \
 -H "Idempotency-Key: bffa9ce6-7a8a-449c-889a-65bd2ee86903" \
 -d "{...}"
The Idempotency-Key header is used to uniquely identify a transaction when retrying the same transaction after a network error or some kind of timeout. The second request is matched using this key against the original request, and rather than creating a new transaction the original response is returned. See Idempotent Requests for further details.
If Embed is being used then idempotent requests are already in use.

​
Transaction request information

Some payment methods require specific ‘non-standard’ information to process. For example, some Buy Now Pay Later (BNPL) methods require cart items to successfully process payments. Therefore to future-proof the integration, integrating as much information in the transaction request as possible is recommended. This allows new additional methods of payment to be added without having to update the integration. Here are a few examples of optional request information to include.
  • buyer information
  • cart_items
  • shipping information
  • connection_options (where applicable)
  • payment_source
  • is_subsequent_payment
  • merchant_initiated