Radom hosted checkout

Radom hosted checkout is the easiest way to integrate crypto payments into your platform. The lifecycle of a hosted checkout integration works as follows:

1. Call Radom's API on your backend to create a hosted checkout session.
2. Redirect your user to the hosted checkout session URL
3. User checks out
4. User is redirected back to your platform
5. You receive a webhook message confirming the payment

Creating an API token​

In order to use the Radom hosted checkout go to the Developer API tokens page in the Radom Dashboard and generate an API token. Make sure to store this somewhere securely as it can only be viewed once after creation, lost API tokens cannot be recovered and a new one will need to be generated.

Creating a checkout session​

Creating a checkout session should be done on a secure back-end server, and is usually done when triggered by a request from your customer facing front-end application sending an order request to the back-end server when the customer is ready to checkout.

In the example below, a hosted checkout session is created using a product. Products can be used to better customize the hosted checkout session with a product image and name. Products can be created through the Product API or through the Products Page on the Radom Dashboard.

{
  "successUrl": "https://yourwebsite.com/on_payment_success",
  "cancelUrl": "https://yourwebsite.com",
  "gateway": {
    "managed": {
      "methods": [{
        "network": "SepoliaTestnet",
        "token": "0x5D684d37922dAf7Aa2013E65A22880a11C475e25"
      }]
    }
  },
  "lineItems": [{
    "productId": "ff20f359-f170-4b88-b59c-9ef4c7aa097b"
  }],
  "customizations": {
    "leftPanelColor": "linear-gradient(125deg, rgba(0,0,128,1) 0%, RGBA(196,22,196,1) 100%)",
    "primaryButtonColor": "#000000",
    "slantedEdge": true
  }
}

var axios = require("axios").default;

var options = {
  method: 'POST',
  url: 'https://api.radom.com/checkout_session',
  headers: {'Content-Type': 'application/json', 'Authorization': 'RADOM_API_TOKEN'},
  data: {
    "successUrl": "https://yourwebsite.com/on_payment_success",
    "cancelUrl": "https://yourwebsite.com",
    "gateway": {
      "managed": {
        "methods": [
          { "network": "SepoliaTestnet", "token": "0x5D684d37922dAf7Aa2013E65A22880a11C475e25" }
        ]
      }
    },
    "lineItems": [{
      "productId": "ff20f359-f170-4b88-b59c-9ef4c7aa097b"
    }],
    "customizations": {
      "leftPanelColor": "linear-gradient(125deg, rgba(0,0,128,1) 0%, RGBA(196,22,196,1) 100%)",
      "primaryButtonColor": "#000000",
      "slantedEdge": true
    }
  }
};

axios.request(options).then(function (response) {
  console.log(response.data);
}).catch(function (error) {
  console.error(error);
});

Detailed information about using hosted checkout session API can be found in the hosted checkout API Reference.

Using the create checkout session API response​

Once a call is made to the create checkout session API, the response payload will contain two fields:

1. checkoutSessionId
2. checkoutSessionUrl

The checkoutSessionId should be stored in order to match the customer with incoming webhook messages. This allows you to ship the product or service to the customer programmatically at the point in which a successful payment has been received. You can also view the webhook messages in the Developer Webhook page in the Radom Dashboard and trigger retries if needed.

The checkoutSessionUrl is the URL used to redirect the customer to the hosted checkout payment page.

{
  "checkoutSessionId": "<UUID>",
  "checkoutSessionUrl": "https://pay.radom.com/checkout/<UUID>"
}

Receiving webhook notifications​

Webhook messages are JSON objects which contain two fields:

1. eventType - determines the type of webhook event. For one-time checkouts, the type will be managedPayment. For subscription products, the type will be managedRecurringPayment.
2. eventData - contains an object keyed with the eventType that includes information about the event, such as the payment amount, network, and token.
3. radomData - information about associated radom payment entities at checkout, e.g. checkout session ID, payment link ID, payment session ID, etc.

For example:

{
  "eventType": "managedRecurringPayment",
  "eventData": {
    "managedRecurringPayment": {
      "paymentMethod": {
        "network": "SepoliaTestnet",
        "token": "0xa4fCE8264370437e718aE207805b4e6233638b9E"
      },
      "amount": "99.49005000000"
    }
  },
  "radomData": {
    "checkoutSession": {
      "checkoutSessionId": "<UUID>"
    }
  }
}

Checking out with arbitrary amounts and currencies​

You can also create hosted checkouts on the fly with arbitrary amounts and currencies. For example, if you wish to have your user checkout with $150 USD, you can simply create a hosted checkout session using 100 as the total and USD as the currency.

Once created, products can be attached within the list of line items passed in when creating a Checkout Session.

Below is an example of a Create Checkout Session API request body with a product attached:

{
  "successUrl": "https://yourwebsite.com/on_payment_success",
  "cancelUrl": "https://yourwebsite.com",
  "gateway": {
    "managed": {
      "methods": [{
        "network": "SepoliaTestnet",
        "token": "0x5D684d37922dAf7Aa2013E65A22880a11C475e25"
      }]
    }
  },
  "total": 150,
  "currency": "USD",
  "customizations": {
    "leftPanelColor": "linear-gradient(125deg, rgba(0,0,128,1) 0%, RGBA(196,22,196,1) 100%)",
    "primaryButtonColor": "#000000",
    "slantedEdge": true
  }
}

It is also possible to mix both products and line items in the same checkout session, this can be helpful for tracking inventory on a commonly purchased product and adding in line items that are specific to a customer checkout session.

See also​

Webhook messages
Supported payment methods
Integrated checkout
Testnet token faucet