Create a wallet

post

https://app-dev.paykeeper.com/api/public/escrow/wallets

Opens a wallet from a preset. Create one per pool of money you
account for separately, such as a waterfall. The response carries the
wallet's paymentReference and funding instructions, ready to hand to
payers. When the preset gives wallets their own account numbers
(fundingAccount: DEDICATED), the new wallet's number is in those
instructions and is the wallet's for good.

Wallets are created from presets only; a request that carries a
policy is refused.

Status	`code`	When
400	`missing_field`	`preset` or `label` is missing.
400	`unsupported_currency`	`currency` is not `USD`.
400	`invalid_field`	A field is the wrong type or too long, or `metadata` breaks its limits.
400	`invalid_body`	The body is not a JSON object.
400	`invalid_idempotency_key`	The `Idempotency-Key` is longer than 255 characters, is not printable ASCII, or was sent twice.
403	`policy_composition_not_permitted`	The request carries a `policy`.
409	`external_id_already_exists`	You already have a wallet, or another object, with this `externalId`. Nothing is created.
409	`idempotency_key_in_use`	A request with this `Idempotency-Key` is still running. Send it again after `Retry-After` seconds.
422	`preset_not_available`	The preset is not in your catalogue.
422	`idempotency_key_reused`	This `Idempotency-Key` was already used for a different request. Use a new key.
503	`virtual_account_unavailable`	The preset gives wallets their own account numbers and none is free right now. Nothing is created; PayKeeper is alerted. Try again later.
503	`upstream_busy`	PayKeeper's banking provider asked it to slow down. Send it again after `Retry-After` seconds, with the same `Idempotency-Key`.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

preset

string

required

length ≤ 60

A preset name from GET /wallet-presets.

label

string

required

length between 1 and 200

The wallet's name, shown wherever the wallet appears.

description

string

length ≤ 2000

Defaults to the label.

externalId

string

length ≤ 200

Your id for the wallet, unique within your organization.

metadata

object

Your own string tags, returned as you sent them. At most 20 keys; keys up to 40 characters; values up to 500.

currency

string

enum

Optional; USD is the only currency in this version.

Allowed:

Headers

Idempotency-Key

string

length between 1 and 255

Optional here, and just as safe to send: a key you generate for this request (a UUID is best) and send again only to retry it, with the same body. Up to 255 printable ASCII characters. See Retries in the introduction.

Responses

201The wallet, open and ready to fund.

400The request is malformed. param names the field. invalid_actor_headers means the request carried x-user-* headers that do not name a valid user; this API does not use them, so leave them out.

401missing_credentials: no HTTP Basic credentials were sent. invalid_credentials: the organization id or access key secret is wrong or revoked.

403The request is well formed but not allowed, or PayKeeper has not set the API up for your organization yet (public_api_not_enabled, on every path).

409The request conflicts with something that already exists.

422The request is valid but cannot be carried out as it stands.

503PayKeeper could not finish safely just now. No money moved, and sending the request again with the same Idempotency-Key is safe; wait Retry-After seconds when the response has it.