> ## Documentation Index > Fetch the complete documentation index at: https://docs.stablepayfi.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create a customer deposit > Create a deposit session and hosted checkout link using the 10-digit customer ID from the merchant system. If the customer does not exist, it is automatically created within the current merchant. `external_customer_id` must be exactly 10 digits, and `allow_multiple_deposits` is required. Creation requests must also include `Idempotency-Key`. ## OpenAPI ````yaml /en/api/customer-deposits.openapi.json post /api/v1/customer-deposits openapi: 3.1.0 info: title: StablePay Customer Deposits API version: '2026-10-13' summary: API for creating and retrieving customer deposit sessions. description: >- OpenAPI specification for StablePay customer deposits. Notes: - Base URL: https://api.stablepay.co - Authentication: Bearer API Key + `X-StablePay-Timestamp` + `X-StablePay-Nonce` + `X-StablePay-Signature` - Signature payload: `{timestamp}.{nonce}.{requestBody}` - Signature algorithm: HMAC-SHA256, lowercase hex - For GET requests, `requestBody` is an empty string - StablePay automatically identifies or creates customers within the current merchant using `external_customer_id` - Merchant identity is injected by the authentication gateway; do not pass `merchant_id` in request parameters servers: - url: https://api.stablepay.co description: Production security: - bearerAuth: [] stablepayTimestamp: [] stablepayNonce: [] stablepaySignature: [] tags: - name: Customer Deposits description: Create and retrieve customer deposit sessions and hosted checkout links. paths: /api/v1/customer-deposits: post: tags: - Customer Deposits summary: Create a customer deposit description: >- Create a deposit session and hosted checkout link using the 10-digit customer ID from the merchant system. If the customer does not exist, it is automatically created within the current merchant. `external_customer_id` must be exactly 10 digits, and `allow_multiple_deposits` is required. Creation requests must also include `Idempotency-Key`. operationId: createCustomerDeposit parameters: - $ref: '#/components/parameters/XStablePayTimestamp' - $ref: '#/components/parameters/XStablePayNonce' - $ref: '#/components/parameters/XStablePaySignature' - name: Idempotency-Key in: header required: true description: >- Request idempotency key scoped to the merchant, up to 128 characters. schema: type: string minLength: 1 maxLength: 128 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateCustomerDepositRequest' example: external_customer_id: '1234567890' customer_name: Example Customer customer_email: customer@example.com allow_multiple_deposits: true description: Account top-up success_url: https://merchant.example/deposit/success cancel_url: https://merchant.example/deposit/cancel metadata: reference: CRM-10001 responses: '200': description: >- Idempotent replay. Returns the same deposit session that was already created. content: application/json: schema: $ref: '#/components/schemas/CustomerDepositSession' '201': description: Successfully created for the first time. content: application/json: schema: $ref: '#/components/schemas/CustomerDepositSession' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '409': $ref: '#/components/responses/Conflict' '500': $ref: '#/components/responses/InternalError' components: parameters: XStablePayTimestamp: name: X-StablePay-Timestamp in: header required: true description: Unix timestamp in seconds. Must be within 5 minutes of the server time. schema: type: string example: '1791878400' XStablePayNonce: name: X-StablePay-Nonce in: header required: true description: >- Random string for replay protection, 16–64 characters. A new UUID is recommended for each request. schema: type: string minLength: 16 maxLength: 64 example: 550e8400-e29b-41d4-a716-446655440000 XStablePaySignature: name: X-StablePay-Signature in: header required: true description: >- Compute HMAC-SHA256 over `{timestamp}.{nonce}.{requestBody}` using the merchant API Secret and encode the result as lowercase hex. For GET requests, `requestBody` is an empty string. schema: type: string example: a1b2c3d4e5f6... schemas: CreateCustomerDepositRequest: type: object required: - external_customer_id - allow_multiple_deposits properties: external_customer_id: type: string pattern: ^[0-9]{10}$ description: Customer ID in the merchant system. Must be exactly 10 digits. customer_name: type: string maxLength: 255 description: >- Customer name. Saved when the customer is first created; existing customer details are not overwritten. customer_email: type: string format: email maxLength: 255 description: >- Customer email address. Saved when the customer is first created; existing customer details are not overwritten. customer_phone: type: string maxLength: 50 description: >- Customer phone number. Saved when the customer is first created; existing customer details are not overwritten. expires_at: type: integer format: int64 description: >- Expiration time in Unix seconds. Must be in the future. Omit for a link that never expires; the response returns null. allow_multiple_deposits: type: boolean description: Whether multiple deposits are allowed using the same deposit link. description: type: string maxLength: 500 description: Description of the deposit session. success_url: type: string format: uri maxLength: 1024 description: >- Redirect URL after successful payment. Must be an absolute HTTPS URL. cancel_url: type: string format: uri maxLength: 1024 description: >- Redirect URL after the customer cancels payment. Must be an absolute HTTPS URL. metadata: type: object maxProperties: 50 propertyNames: minLength: 1 maxLength: 64 additionalProperties: type: string maxLength: 500 description: >- Merchant-defined metadata. Up to 50 entries, with keys of 1–64 characters and values of up to 500 characters. additionalProperties: false CustomerDepositSession: type: object required: - deposit_session_id - customer_id - status - allow_multiple_deposits - expires_at - url - metadata - created properties: deposit_session_id: type: string description: Deposit session ID. customer_id: type: string description: StablePay customer ID. status: type: string enum: - active - closed - expired description: Deposit session status. allow_multiple_deposits: type: boolean description: Whether multiple deposits are allowed using the same link. expires_at: type: - integer - 'null' format: int64 description: >- Expiration time in Unix seconds. Always null when the link never expires. url: type: string format: uri description: Hosted checkout URL. metadata: type: object additionalProperties: type: string description: Merchant-defined metadata. created: type: integer format: int64 description: Creation time in Unix seconds. ErrorResponse: type: object required: - code - message - errorCode - data description: Error response. properties: code: type: integer description: HTTP status code. message: type: string description: Error message. errorCode: type: string description: Stable business error code. data: type: 'null' description: Always null in error responses. responses: BadRequest: description: Invalid request parameters. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Unauthorized: description: Authentication failed. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Conflict: description: Idempotency key conflict. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' InternalError: description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API Key description: Bearer API Key, for example `Bearer sk_live_xxx`. stablepayTimestamp: type: apiKey in: header name: X-StablePay-Timestamp description: Unix timestamp in seconds. Must be within 5 minutes of the server time. stablepayNonce: type: apiKey in: header name: X-StablePay-Nonce description: Random string for replay protection, 16–64 characters. stablepaySignature: type: apiKey in: header name: X-StablePay-Signature description: >- HMAC-SHA256 signature computed using the merchant API Secret, encoded as lowercase hex. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.