These docs are intended for a developer audience.
Hosted deposit API integration
This topic describes how to integrate a Rebilly hosted deposit form into your website, or checkout flow, using the Rebilly API.
The interactive steps in this guide are configured with sample data using a mock server. To use the steps in your own environment, replace the sample data with your own data.
Step 1: Optional: Get a secret API key and website ID
Complete this step to use your own API key and website ID in the steps in this guide. The interactive elements in this guide are configured with sample data in the Rebilly sandbox environment. Skip this step to use the sample data in interactive examples in this guide.
- An active gateway is required to complete a payment using a Rebilly hosted deposit. If you would like to complete a payment flow, see set up a payment gateway.
- If you are testing in the sandbox environment, a test payment gateway called
TestProcessor
is already configured.
- Obtain your organization ID and website ID:
- In the left navigation bar, click Settings .
- In the Management section, click My organization & websites.
- In the Organization details section, note the ID value.
- In the Website section, note the ID value. For more information, see Organizations and websites.
- Obtain your secret API key:
- In the left navigation bar, click Automations .
- In the Development section, click API keys.
- Optionally, if you have not created a secret key:
- In top right of the screen, click Add API.
- In the API key type section, select Secret, then complete the form and click Save API key.
- Go back to the API Keys page.
- Select a secret key and copy the Key value.
Step 2: Upsert a customer
This step creates or updates (upserts) a customer with a specified ID.
This operation prevents duplicate customers. If the customer already has an identifier within your system, that customer is updated. If the customer does not have an identifier, a new customer is created.
For detailed information about this API operation, see Upsert a customer.
Interactive example
This example creates a customer with a specified ID.
- Click Security, then in the REB-APIKEY field, enter any alphanumeric value. Alternatively, use your own API key. For more information, see Step 1.
- Optionally, if you are using your own data, click Body, then enter your own
websiteId
value. - Click Parameters, then in the
id
field, enter any value. - Click Send.
The id
value from this response is used as the customerId
value when creating the deposit request in Step 3. The websiteId
value is also used in Step 3.
Step 3: Create a deposit request
This step creates a deposit request using the customer that you created, and website ID that you obtained, in the previous step. When the customer opens the URL included in the response, a Rebilly hosted deposit form is displayed to complete the deposit.
In the response, in the _links
field, under "rel": "deposit"
, the href
field contains the deposit URL.
For detailed information about this API operation, see Create a deposit request.
Interactive example
This example creates a deposit request.
- Click Security, then in the REB-APIKEY field, enter any numeric value. Alternatively, use your own API key. For more information, see Step 1.
- Click Body, and enter the following:
- In the
websiteId
field, enter thewebsiteId
value from the Step 2. Or, use your own website ID. - In the
customerId
field, enter theid
value from the Step 2 response.
- In the
- Optionally, to present fixed amounts in the deposit request:
- In the
amounts
field, enter the array of amounts that you want to present in the deposit request. For example,[100, 200, 300]
. - In the
customAmount
field, enternull
value to disable the custom amount option. Specifyminimum
,maximum
, andmultipleOf
to enable the custom amount option.
- In the
- Optionally, to apply a specific strategy for the request use the
strategyId
field. To learn more about deposit strategies, see Deposit strategies. - Optionally, to apply a deposit amount limit, in the
amountLimits
field, specifyminimum
andmaximum
amount values. Limits overrideamounts
andcustomAmount
values. - Click Send.
- In the response, expand the
_links
field, then under"rel": "deposit"
, thehref
value is the deposit URL.
The below example uses a mock documentation server by default, and does not generate a deposit form URL. Use your own API key against the sandbox to generate a deposit URL.
Step 4: Redirect the customer to the deposit URL to complete the deposit
Redirect the customer to the deposit URL that you created in Step 3. After completing the deposit form, the hosted payment form is displayed to complete the deposit.