Create a hosted checkout deposit

Before calling the API, your workspace needs an active receiving account, an API key with the required scope, and an active return origin matching return_url.

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.

Request

POST https://checkoutapi.verify.et/v1/deposits

{
  "merchant_customer_id": "customer_42",
  "currency": "ETB",
  "return_url": "https://shop.example.com/payments/return"
}

{
  "merchant_customer_id": "customer_42",
  "amount": "250.00",
  "currency": "ETB",
  "payment_method": "telebirr",
  "return_url": "https://shop.example.com/payments/return"
}

Amounts may be sent as JSON strings or numbers and are returned as normalized strings. ETB is the current currency. Provider and amount limits are enforced by the response options and hosted checkout.

Response

A successful creation returns 201 with the deposit, a public checkout URL, its expiry, and the accounts available for this deposit.

{
  "data": {
    "id": "dep_example",
    "merchant_order_id": "order_1042",
    "merchant_customer_id": "customer_42",
    "status": "awaiting_transfer",
    "verification_status": "not_started",
    "notification_status": "not_ready",
    "amount": "250.00",
    "currency": "ETB",
    "checkout_url": "https://checkout.verify.et/c/example_token",
    "support_reference": "VC-1042",
    "payment_options": [
      {
        "payment_method": "telebirr",
        "institution_code": "telebirr",
        "institution_name": "Telebirr",
        "masked_identifier": "09••••1234",
        "min_amount": "1.00",
        "max_amount": "30000.00"
      }
    ],
    "metadata": {},
    "created_at": "2026-08-21T10:00:00.000Z",
    "expires_at": "2026-08-21T11:00:00.000Z"
  },
  "meta": {
    "requestId": "req_example",
    "apiVersion": "2026-06-01"
  }
}

Persist data.id, then redirect the customer's browser to data.checkout_url. The link expires 60 minutes after creation.

Recommended production flow

Use signed webhooks for prompt change notifications and the deposits API for the authoritative current state:

Create checkout
      ↓
Save deposit ID
      ↓
Customer completes payment
      ↓
Signed webhook informs merchant backend
      ↓
Merchant fetches deposit by ID when confirmation is needed
      ↓
Merchant fulfills only when current status is succeeded

The webhook tells your backend that something changed; it is not a replacement for storing the deposit ID or retrieving the current deposit. Webhooks are delivered at least once and may be delayed, retried, duplicated, or arrive out of order. Verify the webhook signature over the raw body, deduplicate by event ID, then use GET /v1/deposits/{depositId} whenever you need to confirm the latest state.

Only succeeded authorizes fulfillment. Treat review_required as pending an operational decision, and never fulfill failed, expired, or cancelled. Apply fulfillment exactly once using the Verify Checkout deposit ID as the idempotency key in your own system.

Retrieve and reconcile

• GET /v1/deposits/{depositId} — retrieve the current authoritative state.
• GET /v1/deposits — list deposits using the documented filters and pagination.
• GET /v1/deposits/{depositId}/events — inspect the deposit event timeline.

Use signed webhooks for prompt automation and polling as a recovery path. The public API does not require you to build a manual checkout or accept payment references in your own frontend.

Error envelope

{
  "data": null,
  "error": {
    "code": "return_url_not_allowed",
    "message": "The return URL is not allowed"
  },
  "meta": { "requestId": "req_example" }
}

Branch on the stable error.code, show your own customer-safe message, and log meta.requestId. See the generated API reference for every field, filter, status, and error.