Deposit requests

A deposit request is a customer request to deposit funds into their account. Customers make deposits using deposit forms.

To integrate a deposit form into your website, see Integrate a deposit form, Integrate an express deposit form, or Integrate a cashier form.

A deposit request contains the following:

• Customer: Customer who is making the deposit.
• Amount and currency: Requested deposit amount and currency. The deposit form displays amounts that are determined by a deposit amount strategy, or amounts that are specified when the deposit request is created.
• Transactions: Deposit transactions created when the customer initiates or retries payment. A deposit request can reference multiple deposit transactions. For example, declined attempts followed by a successful retry. At most one deposit transaction is approved.
• Custom properties: Optional fields collected from the customer in the deposit form. Custom properties are rendered in deposit forms. For more information, see Custom property sets.
• Custom fields: Optional metadata specified when the deposit request is created. Custom fields are not displayed in the deposit form. Custom field values are copied to each deposit transaction when matching custom fields exist on both the deposit request and transaction. Custom fields match when they have the same name and type. For more information, see the customFields field in the deposit request schema.
• Redirect URL: URL to redirect the customer to when the deposit request is completed. If not specified, the default value is the website URL.
• Notification URL: URL where a server-to-server POST notification is sent when the deposit transaction result is finalized.

This section describes the lifecycle of a deposit request.

The following are all deposit request status types.

This section describes the lifecycle for a deposit request that is completed.

1. A deposit request is created using the Create a deposit request API operation and assigned the created status.
2. The customer visits the deposit form. The deposit request transitions to pending.
3. The customer selects an amount and payment method, and initiates a deposit transaction. The deposit request transitions to initiated.
4. The deposit transaction is approved, and the deposit request transitions to completed.

This section describes the lifecycle for a deposit request where the payment gateway declines a deposit transaction and the customer retries.

1. A deposit request is created and assigned the created status.
2. The customer visits the deposit form. The deposit request transitions to pending.
3. The customer initiates a deposit transaction. The deposit request transitions to initiated.
4. The deposit transaction is declined. The deposit request transitions to attempted.
5. The customer retries with a different payment method or amount. Rebilly creates another deposit transaction, and the deposit request transitions to initiated.
6. The deposit transaction is approved, and the deposit request transitions to completed.

This section describes the lifecycle for a deposit request that expires.

1. A deposit request is created and assigned the created status.
2. The customer does not visit the deposit form, or visits but does not complete an approved deposit transaction.
3. The expiration time is reached, and the deposit request transitions to expired.

Deposit amount strategies determine which amounts are displayed to the customer in a deposit form. Use strategies to configure amounts based on currency, customer segmentation, or prior deposit behavior.

A deposit amount strategy contains the following:

• Amounts: Configuration for how amounts are calculated, including a base amount and increments. The calculator can be absolute or percent. Optionally, the base amount adjusts to the customer's last deposit amount.
• Custom amount: Optional restrictions for custom amounts that a customer can enter, including minimum, maximum, and increment values. If this value is null, custom amounts are prohibited.
• Filter: An optional filter that determines if the strategy applies to a deposit request based on its properties, such as currency.
• Priority: A non-negative integer that determines which deposit amount strategy is applied when more than one matches. The deposit amount strategy with the highest priority value is applied. If the strategyId property is specified when a deposit request is created, the specified deposit amount strategy is applied and all other deposit amount strategies are ignored.

Available operations:

• Create a deposit amount strategy
• Retrieve deposit amount strategies
• Retrieve a deposit amount strategy
• Update a deposit amount strategy
• Delete a deposit amount strategy

Custom property sets extend the deposit form with additional customer-facing fields. Use custom property sets to collect information from the customer during the deposit request process. The collected information is stored on the deposit request.

Available operations:

• Create a custom deposit property set
• Retrieve custom deposit property sets
• Retrieve a custom deposit property set
• Upsert a custom deposit property set
• Delete a custom deposit property set

Transaction webhooks are sent to webhook subscribers when the result of a deposit transaction is finalized. For more information, see Webhook configuration.

Customer timeline messages also record deposit request status changes. Examples of timeline message types are deposit-request-created, deposit-request-started, deposit-request-completed, and deposit-request-expired. These types align with the deposit request lifecycle described in this topic. For more information, see Retrieve customer timeline messages.

• Integrate a deposit form
• Integrate an express deposit form
• Integrate a cashier form
• Deposits API operations