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.
Prerequisites
Complete this section to create resources and gather your website ID, organization ID, and secret API key. These resources and details are required to complete this guide using your Rebilly sandbox environment.
To complete this guide, an active gateway is required. If you are testing in the sandbox environment, a test payment gateway called TestProcessor
is already configured. For more information, see set up a payment gateway.
When you first log in to Rebilly, you create an organization as part of the setup process. A default website is created when a new organization is created. For more information, see Organizations and websites.
- Log in or sign up to Rebilly.
- 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 1: 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.
How to use the interactive example
- Enter your organization ID:
- Beneath the Environment field, click
{{server}}
. - Beneath the URL, click Show nested variables, then click Edit.
- In the Value field, enter your organization ID and click Save.
- Beneath the Environment field, click
- Enter your secret API key:
- Click Security.
- In the API key field, click
{{SecretApiKey}}
, then click Set value. - In the Value field, enter your secret Rebilly sandbox API key and click Save. For more information, see Prerequisites.
- Enter a customer ID:
- In the URL field beneath the Environment field, click
{{id}}
. - Click Set value.
- In the Value field, enter a customer ID.
Example:cus_01HDP7FFX2PGDVH1995EA4QY95
.
- In the URL field beneath the Environment field, click
- Enter your website ID:
- Click Body.
- In the
websiteId
, enter your website ID. - Optionally, change the customer details.
- Click Send.
Theid
value from this response is used as thecustomerId
value when creating the order in Step 2. ThewebsiteId
value is also used in Step 2.
Step 2: 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 using the customerId
value you created in the previous step.
How to use the interactive example
- Enter your organization ID:
- Beneath the Environment field, click
{{server}}
. - Beneath the URL, click Show nested variables, then click Edit.
- In the Value field, enter your organization ID and click Save.
- Beneath the Environment field, click
- Enter your secret API key:
- Click Security.
- In the API key field, click
{{SecretApiKey}}
, then click Set value. - In the Value field, enter your secret Rebilly sandbox API key and click Save. For more information, see Prerequisites.
- Enter the deposit details:
- Click Body.
- In the
customerId
field, enter theid
value from the previous response in Step 1. - In the
websiteId
field, enter your website ID. - 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, in the_links
field, under"rel": "deposit"
, thehref
field contains the deposit URL. The value is used to redirect the customer to the deposit form in Step 3.
Step 3: Redirect the customer to the deposit URL to complete the deposit
Redirect the customer to the deposit URL that you created in Step 2. After completing the deposit form, the hosted payment form is displayed to complete the deposit.