Get started

Complete deposit flow

1. Set up an approved workspace and at least one active, approved receiving account before creating an order.
2. Your backend creates a dynamic or fixed deposit with an Idempotency-Key and receives a checkout_url.
3. PeerPay generates merchant_order_id, assigns an eligible masked receiving-account option, and starts the expiry timer.
4. You redirect the customer to hosted checkout. They choose the shown method, transfer outside PeerPay, and submit the provider reference.
5. PeerPay verifies the transaction ID or reference against the assigned receiving account, amount, currency, transaction age, and duplicate use through bank and wallet APIs.
6. Your backend consumes signed webhooks or polls the deposit and event timeline through a terminal result.
7. Your system credits its own wallet only after succeeded or manually_succeeded; PeerPay does not know your internal ledger.

PeerPay does not know whether you credited the customer wallet. It exposes deposit outcome, verification evidence, and webhook delivery state only.

Core withdrawal flow

1. Add receiving accounts and attach withdrawal agents in the dashboard. Automatic routing needs those agents to already have spendable float.
2. Your backend creates a withdrawal with a locked amount and an Idempotency-Key.
3. You redirect the customer to checkout_url so they can confirm the destination account. If you turned on Auto-Confirm Withdrawals, send the bank and account number on create instead; there is no redirect.
4. PeerPay assigns an eligible agent, or leaves the request in review for you to assign manually.
5. The agent sends the transfer and submits the transaction ID. PeerPay verifies it.
6. You receive withdrawal.succeeded, withdrawal.expired, or another signed event, and can also poll GET /v1/withdrawals/:id.

Do not treat create or checkout return as success. Debit your customer wallet only after withdrawal.succeeded.

Before you start

Read Accounts & Agents before the first deposit. It shows the receiving-account setup, the agent setup, and the allowance flow that decides whether checkout can open.

1. Request merchant access and get approved.
2. Complete your business profile in the dashboard.
3. Create an API key with deposits:create / deposits:read (and withdrawal scopes if needed).
4. Add at least one receiving account.
5. Add a public HTTPS webhook URL in Developer Controls. PeerPay tests it automatically; save the signing secret.

Approved merchants receive 150 successful-order credits (deposits + withdrawals). Failed, pending, expired, cancelled, and review-required orders do not consume credits. After the allowance, PeerPay reports your negotiated percentage (default 3%) without blocking transactions.

Browse guides

• Accounts & AgentsChoose receiving accounts or agents, then see when checkout can offer an account.
• AuthenticationAPI keys, PeerPay-Version, and idempotency keys.
• Accept PaymentsSet up accounts, create deposits, use checkout, and reconcile success.
• Hosted CheckoutRedirect customers to PeerPay-hosted checkout.
• WithdrawalsSet up accounts and agents, then create and confirm withdrawals.
• WebhooksRegister a URL, verify signatures, and debug deliveries.
• Errors & OpenAPIStable error envelopes and the OpenAPI contract.

Recommended integration path

1. Read Authentication.
2. Create a deposit via Accept Payments.
3. Understand Hosted Checkout.
4. Register a URL and verify signatures in Webhooks.
5. Follow Withdrawals for payout setup, confirmation, and status handling.
6. Handle Errors & OpenAPI.