Skip to content

Style the hosted payment page

Give the hosted payment page of a project its own logo, background and colours, and preview it before it goes live.

The hosted payment page is the checkout Ginger shows to the shopper when a merchant creates an order. Each project can give it its own logo, background image and colours. You set the style with the Boarding API. Merchants can also set it themselves in the Merchant portal.

What you can style

The style is stored on the project, in settings.hosted-payment-page, in two sets:

  • default: the style shoppers see.
  • preview: a draft you check on the preview page before you copy it to default.

You set the colours of the header, the order summary next to the form, the pay button, the link back to the webshop and the language selector, and can hide the header, for example when the page is shown in an app. The logo and the page background are images you upload. See settings.hosted-payment-page in Update a project for every field.

Colours are hexadecimal RGB values including the #, such as #0ade63. To go back to the default colour, set the field to an empty string or null.

The order of the payment methods on the page is set in payment_method_order, a list of payment method identifiers. The project's terms_and_conditions_url is shown on the page as a link to the merchant's terms.

Preview the page

Open the preview page of the project to see the preview style:

https://api.example.com/pay/preview/<merchant_id>/<project_id>/

Set the colours

Send the style in an update of the project. The update needs the required project fields trade_name, description, status and website_url. Send their current values, so the update doesn't change them.

curl https://api.example.com/v1/admin/merchants/$MERCHANT_ID/projects/$PROJECT_ID/ \
  --user "$API_KEY:" \
  --header "Content-Type: application/json" \
  --request PUT \
  --data '{
    "trade_name": "Acme Coffee",
    "description": "Acme Coffee webshop",
    "status": "active-production",
    "website_url": "https://www.example.com/",
    "settings": {
      "hosted-payment-page": {
        "preview": {
          "header_background_color": "#1d3557",
          "header_font_color": "#ffffff",
          "payment_button_background_color": "#e63946"
        }
      }
    }
  }'

See Update a project in the API reference for every style field.

Check the preview page. When it looks right, send the same values in default.

Upload a logo or background

Upload the image as the request body. The path says which image (logo or background) and which set (preview or default). The Content-Type must be image/png, image/jpeg or image/gif.

curl https://api.example.com/v1/admin/merchants/$MERCHANT_ID/projects/$PROJECT_ID/hpp-uploads/logo/preview/ \
  --user "$API_KEY:" \
  --header "Content-Type: image/png" \
  --request PUT \
  --data-binary @logo.png

Ginger answers 201 Created and stores the URL of the image in logo_image_url or background_image_url of that set. To remove an image, send a DELETE to the same path. See Upload a hosted payment page image and Delete a hosted payment page image in the API reference.

Next steps