Withdrawals

Before you call the API

These are fulfillment prerequisites. The create call may still return a created withdrawal before the workspace is ready, but PeerPay cannot route it automatically until an eligible agent and account exist:

1. Add at least one approved receiving account in Workspace (https://peerpayment.org/dashboard/workspace). This is the account your agent will send from.
2. Invite a withdrawal agent from the same Workspace page (https://peerpayment.org/dashboard/workspace). The agent signs in, accepts the invite, then waits for you to attach a receiving account.
3. Attach each accepted agent to one active, approved receiving account. Automatic routing only considers attached agents.
4. Give those accounts withdrawal float. Succeeded deposits increase spendable capacity; succeeded withdrawals and recorded drains reduce it. An agent with too little remaining float is skipped.
5. Create an API key with withdrawal scopes and register a webhook URL in Developer Controls (https://peerpayment.org/dashboard/developers).

Dashboard home: https://peerpayment.org. Open live requests later at Withdrawals (https://peerpayment.org/dashboard/withdrawals).

How a withdrawal moves

1. Your backend creates the request with a locked amount and receives checkout_url.
2. You redirect the customer to that URL. They must confirm the destination account themselves. Creating the request is not enough. (With Auto-Confirm Withdrawals on, the create call confirms the destination and there is no redirect.)
3. After confirmation, PeerPay picks an eligible attached agent automatically, or leaves the request in review for you to assign manually.
4. The selected agent copies the customer-confirmed account and amount, sends the transfer from their attached receiving account, then pastes the transaction ID on the withdrawal.
5. PeerPay verifies that transaction. When it matches, you get withdrawal.succeeded. Eligible pre-transfer orders get withdrawal.expired at the deadline. Active verification can finish after the deadline and emits withdrawal.failed if its result is negative.

1. Create the withdrawal

POST /v1/withdrawals
Authorization: Bearer $PEERPAY_API_KEY
PeerPay-Version: 2026-06-01
Idempotency-Key: withdrawal_order_556621
Content-Type: application/json

Required: merchant_customer_id, amount (decimal string only). Optional: destination, return_url, metadata, legacy merchant_withdrawal_id. currency defaults to ETB.

Prefill a destination if you already know it. The customer can still change it on checkout. With Auto-Confirm Withdrawals on, destination.bank and destination.account_number are required and are used as the confirmed destination:

{
  "merchant_customer_id": "cust_sara_hailu",
  "amount": "250.00",
  "currency": "ETB",
  "destination": {
    "bank": "telebirr",
    "account_number": "0933445566"
  },
  "return_url": "https://app.habeshagames.et/withdrawals/return",
  "metadata": {}
}

Or omit destination and let the customer enter it on checkout (only when Auto-Confirm Withdrawals is off):

{
  "merchant_customer_id": "cust_sara_hailu",
  "amount": "250.00",
  "currency": "ETB",
  "return_url": "https://app.habeshagames.et/withdrawals/return"
}

curl -X POST "https://api.peerpayment.org/v1/withdrawals" \
  -H "Authorization: Bearer $PEERPAY_API_KEY" \
  -H "PeerPay-Version: 2026-06-01" \
  -H "Idempotency-Key: withdrawal_order_556621" \
  -H "Content-Type: application/json" \
  --data '{
    "merchant_customer_id": "cust_sara_hailu",
    "amount": "250.00",
    "currency": "ETB",
    "destination": {
      "bank": "telebirr",
      "account_number": "0933445566"
    },
    "return_url": "https://app.habeshagames.et/withdrawals/return",
    "metadata": {}
  }'

What you get back

201 on create, 200 on idempotent replay. Redirect to checkout_url from the first response or the same-key replay. Status at this point is created. With Auto-Confirm Withdrawals on, the response is different; see Auto-Confirm Withdrawals.

A new request and idempotency key that reuse an existing merchant_withdrawal_id return 200 with the existing resource but no new checkout_url. Persist the original URL; this duplicate lookup does not reissue it.

{
  "data": {
    "id": "wd_3p8r1xs6",
    "merchant_withdrawal_id": "pp_wd_3p8r1xs6a1b2c3d4e5f678901234",
    "merchant_customer_id": "cust_sara_hailu",
    "status": "created",
    "verification_status": "not_started",
    "notification_status": "not_ready",
    "amount": "250.00",
    "currency": "ETB",
    "destination": {
      "bank": "telebirr",
      "masked_account_number": "****5566"
    },
    "checkout_url": "https://checkout.peerpayment.org/w/ptk_wr5n8vj2",
    "support_reference": "PP-WD-556621",
    "metadata": {},
    "created_at": "2026-06-19T15:05:00Z",
    "expires_at": "2026-06-19T16:05:00Z"
  },
  "meta": {
    "requestId": "req_9f3a2c1b",
    "apiVersion": "2026-06-01"
  }
}

• id — PeerPay withdrawal ID. Use this for wallet hold, capture, and release idempotency.
• merchant_withdrawal_id — PeerPay generates pp_wd_… when omitted; store the returned value.
• checkout_url — https://checkout.peerpayment.org/w/{public_token}
• destination.masked_account_number when a destination was provided.
• expires_at is 60 minutes from creation. After that the customer cannot confirm and the request expires.

2. Send the customer to checkout

Redirect the customer to the checkout_url PeerPay returned. That page is where they confirm which account should receive the money. Do not skip this step, even if you already sent a destination in the create call. The only exception is a workspace with Auto-Confirm Withdrawals turned on, described next.

• The amount is locked. Checkout cannot change it.
• The customer must submit a bank and account number. Prefill is only a starting value.
• The hosted page submits confirmation to POST /checkout-api/w/{token}/confirm:

{
  "destination": {
    "bank": "telebirr",
    "account_number": "0933445566"
  }
}

Until that confirm succeeds, the withdrawal stays created and no agent is assigned. If the customer never opens or never confirms the page before expiry, the request becomes expired.

Auto-Confirm Withdrawals

Auto-Confirm Withdrawals is an optional workspace setting, off by default. Turn it on when your own site already collects and verifies the customer's bank and account number. While it is on, the withdrawal skips the confirm step on the hosted checkout page: the create call confirms the destination you send and PeerPay starts agent assignment straight away.

Where to turn it on or off:

1. Sign in to the merchant dashboard as a workspace owner or administrator.
2. In the sidebar, under Operations, open Routing (https://peerpayment.org/dashboard/routing).
3. Find the Withdrawal Routing card. The Auto-Confirm Withdrawals switch is at the top of the card, above the routing mode settings.
4. Flip the switch. It saves immediately; there is no separate Save button. The text under the label shows whether it is On or Off.

While it is on:

• destination.bank and destination.account_number are required on POST /v1/withdrawals. A request without them fails with 422 validation_failed and no withdrawal is created, because there is no hosted page to complete it.
• The 201 response has status assigned, or review_required when no agent is eligible or routing is manual. It has no checkout_url. Do not redirect the customer.
• Webhooks are the same as after a hosted confirmation: withdrawal.created, withdrawal.customer_confirmed, then withdrawal.assigned or withdrawal.review_required.
• Because the customer never visits checkout, return_url navigation does not happen. Show your own confirmation screen.
• Agent assignment, verification, expiry, and the wallet flow below are unchanged.

{
  "data": {
    "id": "wd_3p8r1xs6",
    "merchant_withdrawal_id": "pp_wd_3p8r1xs6a1b2c3d4e5f678901234",
    "merchant_customer_id": "cust_sara_hailu",
    "status": "assigned",
    "verification_status": "not_started",
    "notification_status": "pending",
    "amount": "250.00",
    "currency": "ETB",
    "destination": {
      "bank": "telebirr",
      "masked_account_number": "****5566"
    },
    "assigned_agent": {
      "id": "agt_04",
      "display_name": "Agent Bole 02"
    },
    "support_reference": "PP-WD-556621",
    "metadata": {},
    "created_at": "2026-06-19T15:05:00Z",
    "customer_confirmed_at": "2026-06-19T15:05:00Z",
    "assigned_at": "2026-06-19T15:05:00Z",
    "expires_at": "2026-06-19T16:05:00Z"
  },
  "meta": {
    "requestId": "req_9f3a2c1b",
    "apiVersion": "2026-06-01"
  }
}

Turning it off restores the default flow for new requests: the destination is only a prefill hint and the customer confirms on checkout_url.

3. Agent assignment

Confirmation is the trigger, whether it comes from hosted checkout or from Auto-Confirm Withdrawals. PeerPay then chooses between agents that already exist in your workspace.

• Automatic: PeerPay selects an active agent attached to an approved receiving account with enough spendable float, preferring the agent who has waited longest.
• Review / manual: If no agent qualifies, routing is manual-only, or the policy is disabled, the request becomes review_required. Assign an agent from Withdrawals.
• There is no public API parameter for choosing an agent. Manual assignment is an operator action on the existing request; do not create a second withdrawal or ask the customer to confirm again.
• Deposits into those receiving accounts are what create float. If agents have no recent succeeded deposits and you have not recorded capacity, automatic assignment will keep landing in review.
• You can reassign only before the agent submits a transaction reference.

4. Agent sends and verifies

The assigned agent works from the withdrawal detail page. They copy the customer-confirmed destination and locked amount, send that transfer from the attached receiving account, then paste the transaction ID into the withdrawal verification form. This is a dashboard/agent action, not a second public /v1/withdrawals request.

• PeerPay checks that the transaction is unused, matches the exact amount, happened after customer confirmation, and landed on the confirmed destination.
• A good match becomes succeeded and emits withdrawal.succeeded.
• A mismatch, duplicate, or provider problem usually becomes review_required (or remains retryable while verification is pending) so the agent can correct and resubmit the reference.

5. Listen for the outcome

Prefer signed webhooks. Poll GET /v1/withdrawals/:id only as a reconciliation fallback. Webhook delivery is at least once and may arrive out of order, so deduplicate by PeerPay-Event-Id and store the greatest sequence processed for each withdrawal.

{
  "id": "evt_4d8e2a71",
  "type": "withdrawal.succeeded",
  "api_version": "2026-06-01",
  "sequence": 6,
  "created_at": "2026-06-19T15:18:40Z",
  "data": {
    "object": {
      "id": "wd_3p8r1xs6",
      "merchant_withdrawal_id": "pp_wd_3p8r1xs6a1b2c3d4e5f678901234",
      "merchant_customer_id": "cust_sara_hailu",
      "status": "succeeded",
      "verification_status": "succeeded",
      "amount": "250.00",
      "currency": "ETB",
      "destination": {
        "bank": "telebirr",
        "masked_account_number": "****5566"
      },
      "assigned_agent": {
        "id": "agt_04",
        "display_name": "Agent Bole 02"
      },
      "assignment_method": "automatic",
      "metadata": {},
      "created_at": "2026-06-19T15:05:00Z",
      "customer_confirmed_at": "2026-06-19T15:07:12Z",
      "assigned_at": "2026-06-19T15:07:13Z",
      "succeeded_at": "2026-06-19T15:18:39Z",
      "expires_at": "2026-06-19T16:05:00Z"
    }
  }
}

Use a reversible wallet hold when you create the request. Then apply exactly one of these actions:

• withdrawal.succeeded — verified and complete. Capture the existing hold exactly once, keyed by data.object.id.
• withdrawal.expired — the eligible pre-transfer request reached its deadline. Release the hold exactly once.
• withdrawal.failed — unsuccessful terminal outcome after the deadline. Release the hold exactly once.
• withdrawal.cancelled — a workspace administrator cancelled before transfer submission. Release the hold exactly once. The normal verification path uses review_required for bad or ambiguous references, so treat that event as an operator queue, not as a successful payout.
• withdrawal.verification_failed — the latest verification attempt was negative or could not be completed. It is non-terminal before the deadline; use decision_code and keep the wallet hold unchanged while evidence is corrected.
• withdrawal.review_required — not finished. Someone in your workspace still has to assign an agent or correct the transfer evidence.

{
  "id": "evt_wd_verify_failed_01",
  "type": "withdrawal.verification_failed",
  "api_version": "2026-06-01",
  "sequence": 6,
  "created_at": "2026-06-19T15:15:20Z",
  "data": {
    "object": {
      "id": "wd_3p8r1xs6",
      "merchant_withdrawal_id": "pp_wd_3p8r1xs6a1b2c3d4e5f678901234",
      "merchant_customer_id": "cust_sara_hailu",
      "status": "transfer_submitted",
      "verification_status": "amount_mismatch",
      "amount": "250.00",
      "currency": "ETB",
      "verification": {
        "provider": "bank",
        "status": "amount_mismatch",
        "verified": false,
        "provider_request_id": "req_verify_01",
        "verification_attempt_id": "wva_01",
        "decision_code": "amount_mismatch"
      },
      "created_at": "2026-06-19T15:05:00Z",
      "expires_at": "2026-06-19T16:05:00Z"
    }
  }
}

A configured withdrawal return_url must match an active workspace return domain by scheme, hostname, and explicit port; path and query do not participate in allowlisting. After destination confirmation —not payout success—checkout returns with peerpay_withdrawal_id, merchant_withdrawal_id, and checkout_status=customer_confirmed. These values are informational; use signed webhooks for transfer outcomes.

The API field notification_status reports delivery of the latest withdrawal event: pending, delivered, retrying, exhausted, or disabled. It does not mean your application has processed the wallet change.

See the full envelope and signature rules in Webhooks.

Recommended Wallet Flow

1. When POST /v1/withdrawals succeeds, create one reversible hold for the exact amount. Key it by the PeerPay withdrawal id, not by a browser session.
2. Keep the hold unchanged for every non-terminal event, including withdrawal.verification_failed, withdrawal.review_required, and withdrawal.review_resolved.
3. Capture the hold only for a signature-verified withdrawal.succeeded event or an authenticated read that returns status=succeeded.
4. Release the hold only for a signature-verified withdrawal.failed, withdrawal.expired, or withdrawal.cancelled event, or the matching authenticated terminal status.

Make hold creation, capture, and release idempotent by withdrawal ID. Make webhook ingestion idempotent by event ID. These are separate guards and you need both.

Copyable Webhook Handler

Verify the signature against the raw body, enqueue the event once, and return 2xx within 10 seconds. Perform wallet changes in a worker transaction.

// Keep the raw request body. Parsing it before verification breaks the HMAC.
export async function receivePeerPayWebhook(request) {
  const rawBody = await request.text();
  const eventId = request.headers.get("PeerPay-Event-Id") ?? "";
  const timestamp = request.headers.get("PeerPay-Timestamp") ?? "";
  const signatureHeader = request.headers.get("PeerPay-Signature") ?? "";

  if (!verifyPeerPaySignature({
    secret: process.env.PEERPAY_WEBHOOK_SECRET,
    eventId,
    timestamp,
    rawBody,
    signatureHeader,
  })) {
    return new Response("Invalid signature", { status: 401 });
  }

  // Enqueue once by eventId, then acknowledge quickly. The queue worker below
  // performs wallet changes outside the webhook request.
  await enqueueWebhookOnce({ eventId, rawBody });
  return new Response(null, { status: 204 });
}

const releaseEvents = new Set([
  "withdrawal.failed",
  "withdrawal.expired",
  "withdrawal.cancelled",
]);

export async function processPeerPayWithdrawalEvent(event) {
  const withdrawal = event.data.object;

  await db.transaction(async (tx) => {
    // Insert has a unique constraint on event.id. A duplicate delivery exits.
    const inserted = await recordWebhookEventOnce(tx, event.id);
    if (!inserted) return;

    if (event.type === "withdrawal.succeeded") {
      await captureWithdrawalHoldOnce(tx, withdrawal.id);
      return;
    }

    if (releaseEvents.has(event.type)) {
      await releaseWithdrawalHoldOnce(tx, withdrawal.id);
      return;
    }

    // created, assigned, verification_pending, verification_failed,
    // review_required, and review_resolved never move customer funds.
    await updateWithdrawalProgress(tx, withdrawal.id, {
      status: withdrawal.status,
      verificationStatus: withdrawal.verification_status,
      decisionCode: withdrawal.verification?.decision_code ?? null,
      sequence: event.sequence,
    });
  });
}

The persistence helper names are illustrative. Back them with unique constraints on webhook event ID and withdrawal hold ID in your own database.

Status map

Webhook events

Edge cases that confuse first integrations

• Create does not assign an agent. Assignment starts only after checkout confirmation, unless Auto-Confirm Withdrawals is on.
• Prefill is not confirmation. A destination in POST /v1/withdrawals is a hint. The customer still has to confirm, unless Auto-Confirm Withdrawals is on.
• No eligible agent becomes review, not failure. Check attachments, account approval, and spendable float, then assign manually.
• Return URL is browser navigation only. Do not treat the customer coming back as proof the withdrawal succeeded.
• Expiry is state-aware. Eligible pre-transfer orders expire after 1 hour. Active verification is allowed to finish; a negative result at or after the deadline becomes failed.
• Do not capture on created or assigned. Keep the hold until withdrawal.succeeded, or poll until status is succeeded.

Get, list, and event timeline

GET /v1/withdrawals/:id and GET /v1/withdrawals support filters: status, merchant_withdrawal_id, merchant_customer_id, created_from, created_to, cursor, limit (default 25, max 100).

curl "https://api.peerpayment.org/v1/withdrawals/wd_3p8r1xs6" \
  -H "Authorization: Bearer $PEERPAY_API_KEY" \
  -H "PeerPay-Version: 2026-06-01"

{
  "data": [ /* Withdrawal[] */ ],
  "meta": {
    "requestId": "req_9f3a2c1b",
    "apiVersion": "2026-06-01",
    "pagination": {
      "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTA2LTE5VDE1OjA1OjAwLjAwMFoiLCJpZCI6IndkXzNwOHIxeHM2In0",
      "hasMore": true,
      "limit": 25
    }
  }
}

GET /v1/withdrawals/:id/events is an ordered audit timeline. It is not the webhook payload shape.

GET /v1/withdrawals/wd_3p8r1xs6/events
PeerPay-Version: 2026-06-01