Developer docs

Accounts & Agents

Choose one setup before the first deposit. Checkout can offer a receiving account directly, or it can offer accounts that belong to an available agent. Mixing those setups after an agent is attached does not turn the agent rules off.

PeerPay does not hold the customer’s money. The customer pays the account shown at checkout. Your backend credits your own customer after the deposit succeeds.

Choose a Setup

The two ways a merchant can receive a deposit.
Setup	Use it when	Who must act	Checkout rule
Receiving accounts only	You operate the bank and wallet accounts yourself.	You add each account and approve it.	No availability switch and no agent allowance.
Agents	People on your team receive the transfers.	You invite them. Each agent turns availability on.	One switch covers every account on that agent.

Receiving accounts only

One or many accounts
You approve each account
No agent login

Agents

Main agent and sub-agents
Each agent turns availability on
Allowance is optional

Receiving Accounts Only

Use this when you operate the accounts yourself. Several accounts are normal: one CBE account, two Telebirr numbers, and another wallet can all be offered on the same checkout when each one is active and approved.

Direct account flow

1
Add receiving accounts
Open Workspace and add each bank or wallet account.
2
Approve them
A pending account is not offered. Leave approved accounts active.
3
Skip agents
Do not invite a withdrawal agent onto these accounts.
4
Create a deposit
Checkout lists each method that has an eligible account. The customer pays that account directly.

Direct routing continues only while that account owner has never had a withdrawal agent. Removing an agent does not put those accounts back on this path. Add a new account that has never had an agent, or invite an agent again and have them turn availability on.

Agents

A receiving account always has an owner record. That owner is not a person until you invite one. Several accounts can share one agent, and they then share that person’s availability, suspension, and allowance.

One merchant, one main agent, and one sub-agent

Merchant
Approves every new account. Tops up the main agent only.
- Main agent
  Availability on. Both accounts follow this one switch.
  - CBE, approved
  - Telebirr, approved
- Sub-agent
  Availability on. Funded by an allocation, not by your top-up.
  - Telebirr, approved

What each person does.
Person	Responsibility
Merchant	Approves accounts, invites the main agent, and tops up that main agent when allowance is on.
Main agent	The team lead. Some merchants call this a super-agent. Signs in, turns availability on, and allocates allowance to sub-agents.
Sub-agent	A member of that lead’s team. Turns their own availability on. Cannot be funded by a merchant top-up.

Open Agents and invite the main agent.
The agent accepts, signs in with the agent login, and turns availability on from Overview or Withdrawals. New agents start off.
Add the agent’s receiving accounts and approve them. Pending accounts are not offered.
Invite sub-agents from Agents, or let the main agent invite them from Team. Each sub-agent turns their own availability on.

Suspending a main agent also stops new checkout work for that team. Suspending one sub-agent stops only that sub-agent. Orders already assigned still complete. There is no third level of agents.

Allowance

Leave agent credit off when any approved, available account should be offered without a cap. Turn it on when you want to limit how much net verified volume an agent may process. The allowance is not the money in the bank account. You pay the agent outside PeerPay.

Two credits that are easy to mix up.
Credit	What it counts	Effect on checkout
Platform usage credit	150 succeeded deposit and withdrawal orders included at approval.	PeerPay’s processing allowance. Running out does not stop checkout.
Agent credit	Optional cap on an agent’s net verified volume. 1 credit is 1 ETB.	Spendable allowance must cover a new order or that agent is left out.

How a top-up is used

1
Top up the main agent
You record 10,000 ETB of allowance on the main agent. No bank money moves.
2
Allocate to a sub-agent
The main agent moves 2,500 ETB of that allowance to a sub-agent.
3
Reserve on checkout
An open checkout reserves its amount from spendable allowance before the customer pays.
4
Settle the verified payment
A succeeded deposit consumes the paid amount and releases the rest of the reservation.

Example split of a 10,000 ETB main-agent top-up

6,700 ETBSpendable. Still available for a new checkout on the main agent.
800 ETBReserved. Held by a checkout the customer has not finished.
2,500 ETBAllocated. Moved to a sub-agent. It is no longer spendable by the main agent.

Spendable allowance is what remains after allocations and open checkout reservations. On the allowance model current workspaces use, checkout offers the one receiving account designated for that agent. A workspace on the newer shared-allowance model can offer every approved account on that agent from the same allowance. A succeeded payment still settles when the allowance was too small. The shortage shows up as a negative allowance for you to adjust.

When Checkout Offers an Account

Gates checked at deposit creation.
Gate	Receiving accounts only	Agent accounts
Account is active and approved	Required	Required
Payment method and amount fit the account	Required	Required
Pending capacity is free	Required	Required
Availability switch	Not used	The agent must turn it on. You cannot flip it.
Suspension	Not used	The agent, and a sub-agent’s main agent, must stay unsuspended.
Allowance	Not used	Used only when agent credit is on. The current model offers the designated account. The newer model offers every approved account on that agent from one allowance.

GET /v1/capabilities lists the methods your workspace can advertise. The create response decides whether an account is free for that order. A 503 order_routing_unavailable response has no checkout URL. Fix the account, then create the deposit again. The failed response does not become a checkout. Error codes are listed in Errors & OpenAPI.

Failures to Expect

What to check when checkout does not open or the customer is not credited.
What you see	Likely cause	What to do
Create deposit returns 503	No eligible account. Often the agent has not turned availability on.	The agent opens Overview or Withdrawals and turns availability on. Then create a new deposit.
503 after you removed the agent	Those accounts stay out of direct routing.	Invite an agent again, or add new accounts that have never had an agent.
One payment method fails	No active approved account supports that method or amount.	Approve an account for the method, or widen its limits.
An available agent still gets 503	Allowance is used up, or credit is on and the designated account is not the one you expect.	Top up the main agent, or allocate to the sub-agent. Confirm the designated account is active.
A burst of checkouts starts failing	Pending capacity is full, or open checkouts have reserved the allowance.	Wait for those checkouts to finish, raise the pending limit, or add allowance.
“This bank is currently unavailable.”	That account lost availability or allowance after checkout opened.	The customer chooses another listed bank.
A sub-agent never receives deposits	A merchant top-up funds the main agent only, or the sub-agent is still unavailable.	The main agent allocates allowance. The sub-agent turns availability on.
The customer paid, but your user is not credited	PeerPay verified the bank payment. Your backend has not applied it.	Credit your customer once from the signed webhook or from the deposit, using the PeerPay deposit id.