Create a hosted payment form

One of the fastest way to integrate Rebilly payments into your website is using our hosted payment forms. Our hosted payment form uses our FramePay solution to safely and securely capture payment information from your customers.


In this guide, we'll interact with the API to complete a transaction in 3 steps:

  1. upsert a customer
  2. create a transaction
  3. complete the transaction using the hosted payment form

This guide will take about 10 minutes.

To do this, you should have already gone through the getting ready prerequisites.

Upsert customer

First, we will upsert the customer. It is a best practice to upsert the customer. In the case of a duplicate customer ID, the customer record will be updated.

You'll need:

  • Your websiteId
  • Your organizationId
  • Your secret API key - Note: this will be pre populated if you are logged into the Rebilly app in the sandbox environment.

Go to the upsert a customer with a predefined ID API, and use the "Try it" console to create your customer.

Try it console


Only a few pieces of information are required at this point. In this example, we are using Redocly as our organization, and our customer is Benjamin Franklin.

Replace "" with your own website ID.

  "websiteId": "",
  "primaryAddress": {
    "firstName": "Benjamin",
    "lastName": "Franklin"


In the parameters tab, add your customerId and the organizationId.

upsert customer parameters

Before you click send, be sure that your target is set to the correct environment. The target is set as the sandbox server by default.

Click send to submit your request.


We created our customer. Now, let's inspect that API response.

The customer has an id, and that should match what we supplied in the path parameter of the PUT request to upsert the customer.

Create transaction

Next, we'll create a pending transaction that will be completed using the hosted payment form in the last step.

You'll need:

  • Your websiteId
  • Your organizationId
  • The customerId you created in the first step

Go to the create a transaction API and use the "Try it" console to create a transaction.


Enter your websiteId and customerId.

You can create the transaction for any amount, and any currency that is supported by your TestProcessor. For this example, we'll use $30 USD as our amount and currency.

Under the payment instruction, instead of supplying a payment instrument or token, we will supply the method(s) of payment we would like to accept using the hosted payment form. This can be any payment method that is supported by an active gateway in your Rebilly settings. For this example, we will use a payment-card.

Enter a billing address for your customer, Benjamin Franklin.

The requestId can be any string of values, but it must be unique for each transaction created. If you create multiple transactions, enter a unique requestId for each request.

The notificationURL and redirectURL are important for supporting offsite payments. For this example, we will leave the default URLs,

  "websiteId": "",
  "customerId": "benjaminfranklin",
  "currency": "USD",
  "amount": 30,
  "paymentInstruction": {
    "methods": ["payment-card"]
  "billingAddress": {
    "firstName": "Benjamin",
    "lastName": "Franklin",
    "organization": null,
    "address": "123 Main St.",
    "address2": null,
    "city": "Boston",
    "region": "MA",
    "country": "US",
    "postalCode": "02101"
  "requestId": "1234",
  "notificationUrl": "",
  "redirectUrl": "",
  "isProcessedOutside": false,
  "type": "sale"


Under the parameters tab, enter your Organization-Id.

Then, click send.


You have created a transaction with an unknown result and a waiting-approval status.

Scroll to near the bottom of the response, locate the _links. In this section, you will find the approval URL. This link will be used to complete the payment.

approval URL

The link will look like this:

This is an expired link

Copy this URL to your clipboard.

Complete the transaction

Now, we will complete the payment using the hosted payment form.

You'll need:

  • The approval URL generated in the previous step.
  • A test card (provided below). However, you may test other types of cards and outcomes using any of our test cards

Paste the approvalURL into a new browser window or tab.

You'll enter:

  • First and last name: Benjamin Franklin
  • Email:
  • A test card: 4111 1111 1111 1111 with any future expiration and any 3 digit cvv.

Submit the form and your transaction is complete!

Check the customer record in the Rebilly app, and you will see all of the steps recorded in the customer timeline.

customer timeline