Make your first deposit

This guide follows the same order as the dashboard. You will need a receiving account that your business controls and a backend where secrets can be stored.

Verify Checkout API AI Agent Skill

Give Your Coding Agent the Integration Playbook

Install the skill, then ask a compatible AI coding agent to add Verify Checkout to your app, site, or bot. It gets the API workflow, security boundaries, and integration guidance in one place.

npx skills add https://github.com/negusnati/verify-checkout --skill verify-checkoutCopy

View on GitHubOpen in Skills

Review generated changes and keep your API key on the server—the skill guides the integration but never replaces your security review.

1. 01
   Monthly Starter credits

   Sign in with Telegram

   Continue with Telegram. A new workspace receives monthly Starter verification credits; creating a checkout does not consume a credit.

2. 02
   Required

   Complete Business Details

   Add your business name and upload the logo shown on checkout. PNG, JPEG, and WebP images up to 7 MB are accepted. Phone, website, and support URL are useful to customers, but do not block setup.

3. 03
   Available immediately

   Add a receiving account

   Choose a supported provider and enter an account owned by your business. New receiving accounts are active as soon as they are created.

4. 04
   Copy once

   Create an API key

   Create a key with the deposit permissions you need. Copy the vchk_… secret immediately—the dashboard cannot reveal it again.

   VERIFY_CHECKOUT_API_KEY=vchk_replace_with_your_secret

5. 05
   Required

   Register the return domain

   Add and activate the exact origin that will receive the customer after checkout, such as https://shop.example.com. The scheme, host, and port of every return_url must match. HTTP is accepted only for loopback development.

6. 06
   Server-side

   Create a deposit

   Use a fresh idempotency key for this logical deposit. Omit amount to let the customer enter it, or send an ETB amount for a fixed checkout.

   cURL

   TypeScript

   curl --request POST 'https://checkoutapi.verify.et/v1/deposits' \
     --header "Authorization: Bearer $VERIFY_CHECKOUT_API_KEY" \
     --header 'Content-Type: application/json' \
     --header 'VerifyCheckout-Version: 2026-06-01' \
     --header 'Idempotency-Key: order_1042_deposit' \
     --data '{
       "merchant_customer_id": "customer_42",
       "amount": "250.00",
       "currency": "ETB",
       "return_url": "https://shop.example.com/payments/return"
     }'

   const response = await fetch("https://checkoutapi.verify.et/v1/deposits", {
     method: "POST",
     headers: {
       Authorization: `Bearer ${process.env.VERIFY_CHECKOUT_API_KEY}`,
       "Content-Type": "application/json",
       "VerifyCheckout-Version": "2026-06-01",
       "Idempotency-Key": "order_1042_deposit",
     },
     body: JSON.stringify({
       merchant_customer_id: "customer_42",
       amount: "250.00",
       currency: "ETB",
       return_url: "https://shop.example.com/payments/return",
     }),
   });
   
   if (!response.ok) throw new Error(`Deposit creation failed: ${response.status}`);
   const result = await response.json();

7. 07
   60-minute link

   Send the customer to checkout

   Read data.checkout_url from the 201 response and redirect the customer's browser to it. Store data.id in your system before redirecting.

   window.location.assign(result.data.checkout_url);

8. 08
   Webhook recommended

   Reconcile the result

   Poll GET /v1/deposits/{depositId} until the deposit reaches a terminal state. For production automation, add a signed webhook and keep polling as a recovery path. A webhook tells your backend that the deposit changed; the deposits API returns its authoritative current state. Credit your customer exactly once, keyed by the Verify Checkout deposit ID, and only when that state is succeeded.

Next, read Create a deposit for every request shape and Reconciliation before crediting customer balances.