Pocket Money - Relay API (0.6.0)

Specification 0.6.0 uses the existing /v1 paths. This is the Sandbox release candidate; it does not establish what is deployed to production.

Use a key issued in the environment you are calling. Do not use a production key or production funds for Sandbox tests. Paths and JSON examples below are relative to the selected API base URL. Replace example IDs with resources in that environment. Use a new idempotency key for each new operation, and reuse that key when retrying the same operation.

For example, read Sandbox Accounts with an environment-specific bearer key:

curl 'https://api.relay.sandbox.pocketmoney.global/v1/accounts' \
  -H "Authorization: Bearer $RELAY_SANDBOX_API_KEY"

The release contains 23 public operations across the seven resource families above. New Accounts, internal Transfers and Batches use USD. An Account's owner, currency, default designation and lifecycle status cannot be changed through these endpoints. Account updates change the label, reference and metadata.

Operations require appropriate permissions and eligible Customers and Accounts. Payments also require sufficient funds. Customer-to-Customer payments may have a limit on the total sent in the previous 30 days. This includes pending and settled payments. The limit can vary by Customer. Batch acceptance confirms submission; check each item's status to confirm payment.

Send the API key as a bearer token:

Authorization: Bearer eak_v1_...

Every request runs as the Customer attached to that key. A source account_id must belong to it. Direct retrieval of another Customer's resource returns 404 as if it did not exist. List-filter error behaviour is described on each operation. Recipient, Account-create and Batch operations require an active, unblocked business Customer. Pending, suspended, closed, blocked or non-business Customers cannot use those business-only operations.

The key must also contain every scope named by the operation. The V1 scopes are accounts:read, accounts:write, balances:read, recipients:read, recipients:write, transactions:read, transfers:read, transfers:write, deposits:read, batches:read and batches:write. Broad read grants every read scope; broad write grants every read and write scope. Each granular write scope also grants its matching read scope (for example, accounts:write includes accounts:read, but not balances:read). Batch creation needs both batches:write and transfers:write; listing Batch Transfers needs both batches:read and transfers:read.

Keys authenticate API requests, not Relay browser sessions. Current key validity, ownership, scopes and applicable business eligibility are checked on retries too: an idempotency key is not an authorization bypass.

An accepted internal transfer creates one txn_… ID. The source Account sees a Transfer and the receiving Account sees a Deposit. Addressing another Customer credits its immutable default Account. Addressing another Account owned by the same Customer creates an Account transfer with one debit and one credit view.

Accepted outbound money moves from available to reserved. At settlement it leaves the source balance and is credited to the destination balance. A failed or voided movement remains visible and the reservation is released.

Amounts are decimal strings in major currency units. New payments must be positive USD amounts with at most two decimal places and no more than 9999999999999999.99 per payment. JSON numbers, commas, whitespace, scientific notation and negative values are rejected. Monetary amounts returned in balance and activity views follow the response schemas; a zero balance is valid.

Send the request key in the Idempotency-Key HTTP header, not in JSON. Create Account, Recipient, Transfer and Batch require it. Account PATCH, Recipient PUT and Recipient DELETE accept it optionally; omitting it does not provide saved-response protection. Keep the same key and input for retries of one operation. Do not generate a new key merely because the connection timed out.

Keys apply to a Customer and operation, even if the Customer uses another API key. For transfers, changing between destination.customer_id and destination.account_id while reusing the same key within 24 hours returns 409 Conflict. For updates and removals, using the same key for a different resource also returns 409 Conflict.

After a request succeeds, matching retries within 24 hours return the original response:

Replay does not reapply an edit, restore a removed Recipient or send money again. Use GET for current state. It is not proof of settlement.

Concurrent matching requests wait for the first transaction to finish. If it commits, they replay its response; being in flight alone is not a conflict. A changed, valid request under an unexpired idempotency key returns 409 with details.code: idempotency_conflict and details.param: Idempotency-Key, without an existing_id. Each operation defines how it normalizes input before comparing it. Request validation still runs, so invalid input can return 400 instead. Authentication, authorization and maintenance checks also apply to retries.

Replay does not extend the 24-hour window. At or after expiry, the same key can identify new work, including another payment. Save resource IDs separately and reconcile uncertain outcomes before resubmitting. Use a new key for each new intent, not for a retry of an uncertain one.

List operations use opaque cursors. Pass next_cursor back as cursor with the same filters and ordering. Do not parse or construct cursors. Stop when has_more is false. An invalid or mismatched cursor returns 400; restart from the first page. Pagination is not a frozen snapshot of resources that continue changing.

Errors use { code, message, details }. The outer code describes the HTTP error class; details.code, when present, is Pocket's machine-readable reason. Do not branch on message text. Details may be null for transport/authentication failures. Preserve unknown reason codes, and record details.request_id when provided for support.

During maintenance, 503 can instead have details: { "maintenance": true, "retry_after_seconds": 60 }, without a Pocket reason or request ID. Maintenance headers (X-Pocket-Maintenance, Retry-After) may be present; authentication can reject the request before those headers are attached. The body remains the maintenance indicator.

201 Created for a Transfer means it was accepted, not settled. 202 Accepted for a Batch means the Batch was saved for asynchronous execution, not that its items succeeded. GET returns current progress; replaying POST returns the original acceptance response. A terminal Batch can be completed, partially_completed or failed; reconcile each item, not just the Batch status.

If a response is lost, retry the same request with the same key within 24 hours. Once you have the resource ID, reconcile using GET and, for a Batch, its items and resulting Transfers. Retain each item's item_id and Transaction ID, and use terminal movement status to determine the payment outcome.

If the replay window has elapsed, or the outcome remains uncertain, do not blindly resubmit with the old or a new key: either can create another payment. Reconcile saved IDs and activity first, and contact Pocket when an outcome cannot be established. A reference is a reconciliation label, not a uniqueness constraint. Do not assume a failed HTTP request proves no money movement was accepted.

A payroll integration uses an API key for one active, unblocked business Customer. That Customer owns the Recipient roster and the source Accounts, and submits each Batch. Employees are destination Customers, not Accounts or Recipient IDs. Adding a Recipient does not create a Customer.

The normal flow is:

1. Add each employee as a Recipient using an existing Customer ID or an exact supported identity lookup. Store both the Recipient ID and its destination Customer ID.
2. Select the source Account and check that Account's available USD balance.
3. Submit a Batch with either the Customer in source.customer_id to use its default Account, or a chosen Account in source.account_id. The resolved source Account is fixed when the Batch is accepted.
4. Save the returned Batch ID and reconcile its items and resulting Transfers. Acceptance is asynchronous; it does not reserve the Batch total or guarantee that every item will be paid.

Recipient reads require recipients:read; Recipient writes require recipients:write. Submitting a Batch requires both batches:write and transfers:write. Reading Batches and their items requires batches:read; listing a Batch's Transfers also requires transfers:read. Scopes and Customer eligibility are checked again on retries.

Use the public /v1 endpoints for this integration. The Relay console's CSV preview/execute workflow and its operator permissions are a separate API surface; a public Batch submission queues execution directly.

Add each employee to the authenticated business Customer's recipient roster. The Recipient has its own rcp_… ID for roster management. Its linked customer_id is the destination to use in a Batch; never send the Recipient ID as a payment destination.

POST /v1/customers/cus_01j8ma3wv3mepwabfxxs0yc395/recipients
Authorization: Bearer eak_v1_...
Idempotency-Key: add-employee-1042
Content-Type: application/json

{
  "customer_id": "cus_01jm0defbbct46vh2ev5dkkhej",
  "label": "Taylor Reed",
  "reference": "EMP-1042",
  "metadata": {"department": "Operations"}
}

Supply a nonblank label and at least one of customer_id, paytag, email, or phone. If several identifiers are supplied, all must resolve uniquely to the same existing, active, unblocked Customer other than the source Customer. Unresolved, conflicting or unavailable matches return the same privacy-preserving 404 with details.code: recipient_not_found. This operation does not create pending Recipients or onboard employees. Existing pending records remain readable, have customer_id: null, and cannot be used as Batch destinations.

A new Recipient returns 201 Created and a relative Location. An existing non-removed Recipient returns 200 OK without applying the submitted label, reference or metadata. A new request to re-add a removed Customer restores the same Recipient ID with the submitted fields and returns 200 OK.

Creation requires Idempotency-Key. An unchanged retry within 24 hours returns the saved original response, status and Location where present, even after later edits or removal. It does not restore or update the Recipient. Use GET for current state, especially capabilities.can_receive_transfers: a replay's capability value is a saved snapshot. The current capability checks roster and Customer eligibility, not wallet readiness, source funds, limits or the final payment outcome. Batch acceptance and execution perform further checks.

PUT replaces all four mutable fields: label, reference, status and metadata. Supply reference: null to clear it and metadata: {} to clear metadata; status may be active or inactive. DELETE soft-removes the Recipient and returns 204 No Content. Removed records remain readable but are excluded from unfiltered lists.

PUT and DELETE accept an optional Idempotency-Key. Use one to make a retry return the original response without reapplying an old edit or deleting a subsequently restored Recipient. Keys are scoped by business Customer and operation for 24 hours, not by API-key credential or Recipient ID. Changing the target or normalized input under an unexpired idempotency key returns 409 with details.code: idempotency_conflict. Use a new key for a new operation.

Each Account holds USD and has its own Account ID. Accounts belong to the Customer attached to your API key. A Customer can have more than one Account in the same currency. Use GET /v1/accounts (accounts:read) to discover them and GET /v1/accounts/{account_id} to read an Account's label, reference and metadata.

An eligible business Customer can create an additional, non-default Account with POST /v1/accounts (accounts:write). Pocket creates the default Account; this API cannot change ownership, currency, default selection or lifecycle status. Account creation requires an active default Account and its payment setup. Supplied labels must be unique within the Customer. References are not unique.

PATCH /v1/accounts/{account_id} updates supplied label, reference or metadata fields. Omitted fields remain unchanged, null clears a label or reference, and {} replaces metadata with an empty object. At least one field is required. Creation requires Idempotency-Key; updates support it optionally. Within 24 hours, matching keyed retries return the original Account response without reapplying the operation. Read the Account to see later changes.

GET /v1/balances requires balances:read and returns one page of Account balances, not one aggregated balance per currency:

{
  "data": [
    {
      "account_id": "acc_01j8ma3wv3mepwabfxxs0yc395",
      "currency": "USD",
      "reference": null,
      "available": "2500.00",
      "settled": "2500.00",
      "reserved": "0.00",
      "as_of": "2026-07-31T09:15:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Accounts with no ledger activity are included with zero amounts. settled is the posted balance; reserved is the amount held for pending outbound movements; available = settled - reserved. Pending incoming money is not spendable and does not increase these balances before settlement. Amounts are decimal strings; do not depend on a fixed number of trailing zeroes.

Account and balance lists accept currency=USD, status, an exact reference, limit (1–100, default 25) and an opaque cursor. They are ordered newest Account first, by creation time and Account ID. Keep the same filters and follow next_cursor while has_more is true. For one current balance, use GET /v1/accounts/{account_id}/balance with balances:read.

Use /v1/transactions for the combined activity feed, /v1/transfers for outbound movements and /v1/deposits for inbound movements. Every returned account_id identifies the exact Account-relative view. A transfer between two of your Accounts appears twice in the combined feed: one outbound view and one inbound view sharing the same transaction ID. Another Customer's private balances and activity are not accessible with your key.

Submit one asynchronous Batch from the authenticated business Customer to its employee Customers:

POST /v1/batches
Authorization: Bearer eak_v1_...
Idempotency-Key: a15e4ae4-52f3-460c-9c1c-5f6b7b90cc44
Content-Type: application/json

{
  "source": {
    "account_id": "acc_01j8ma3wv3mepwabfxxs0yc395"
  },
  "recipient_policy": "recipients_only",
  "items": [
    {
      "item_id": "line-001",
      "destination": {
        "customer_id": "cus_01jm0defbbct46vh2ev5dkkhej"
      },
      "amount": "100.00",
      "currency": "USD",
      "reference": "EMP-1042"
    }
  ],
  "reference": "northwind-payroll-2026-07"
}

Use a new key for each pay run and keep the same key and input for retries of that submission. Send 1–4,096 items, each with a unique, case-sensitive, nonblank item_id of at most 255 characters. Amounts are positive USD decimal strings with at most two decimal places. Every destination must be another Customer; Batch items do not accept Account destinations.

recipients_only checks the entire request before acceptance: each destination must be an active eligible roster member. Pocket also checks that the destination can receive the payment. can_receive_transfers: true does not guarantee that the recipient can receive this payment. A failed pre-check returns 400, details.code: recipient_policy_failed, and details.failures entries containing item_id, an indexed param, and a privacy-preserving failure code. No Batch is created. Omitting the policy selects any_customer, which skips the roster pre-check and checks destination eligibility and payability when each item first executes.

Success returns 202 Accepted, a Batch body, and Location: /v1/batches/{batch_id}. Acceptance does not reserve the whole Batch amount. Each item checks the pinned source Account's available balance and applicable transfer rules when it runs; processing order is not guaranteed. The roster policy is not checked again after acceptance. There is no public cancel endpoint for an accepted Batch.

An unchanged retry within 24 hours returns the saved initial 202 response and Location, without resubmitting items or refreshing counts. GET the Batch for progress. A changed request under the same unexpired idempotency key returns 409 with details.code: idempotency_conflict; it does not include an existing Batch ID. Retries do not extend the 24-hour window. After expiry the key can create another Batch.

Use GET /v1/batches/{batch_id}/items to reconcile every submitted item_id. A pending item, or an internal_error item with transfer_id: null, is not proof that no payment started. The Transfer list contains only linked, visible Transfers, so an empty list is not proof that the Batch did nothing. If a submission result is lost, retry within the replay window using the same input and key. For an older uncertain result, locate the Batch by its saved ID or list/filter by your reference and creation time, then reconcile its items and source activity before submitting anything again. References are not unique and item_id only identifies a line within one Batch. Escalate an unresolved payment outcome for reconciliation; do not automatically copy ambiguous lines into a new Batch.

Create an internal transfer from the authenticated Customer to another Pocket Customer using a key with transfers:write:

POST /v1/transfers/internal
Authorization: Bearer eak_v1_...
Idempotency-Key: d9f80740-7f8e-4f16-b5cc-4fd5bf7d3b21
Content-Type: application/json

{
  "source": {
    "account_id": "acc_01j8ma3wv3mepwabfxxs0yc395"
  },
  "destination": {
    "customer_id": "cus_01jm0defbbct46vh2ev5dkkhej"
  },
  "amount": "100.00",
  "currency": "USD",
  "reference": "payrun-2026-07",
  "memo": "July salary"
}

Supply exactly one source selector and one destination selector. source.customer_id may instead identify the Customer attached to the API key, in which case Pocket uses its immutable default Account. An explicit source Account must belong to that Customer. A Customer destination must be a different Customer; it receives into its default Account. Its private Account ID, balance and unrelated activity are never exposed to the sender. The destination uses a Customer ID, not a Recipient relationship ID.

To move money between your own Accounts, set destination.account_id to another owned Account instead. It must differ from the resolved source Account. You cannot select another Customer's Account directly.

amount is a positive decimal string in USD, with at most two decimal places. reference (up to 255 characters) and memo (up to 100) are optional strings, not null. The reference is private to your Customer and is not a uniqueness constraint. The destination Customer can see the memo.

Both destination types require the Idempotency-Key header. Matching retries within 24 hours return the original response. Keep the same key and body when retrying a payment. Changing between destination.customer_id and destination.account_id with the same key returns 409 Conflict, as does changing the amount. Retries return the original 201, Location, status and timestamps. Reusing an expired key can create another transfer.

201 Created means the payment was accepted. While pending, the source amount is reserved and its available balance decreases; the destination is not yet credited. Settlement posts the source debit and destination credit. Failure or voiding releases the reservation without a destination credit. Use GET /v1/transfers/{transfer_id} with transfers:read to observe current state. For an owned-Account move, the transaction feed contains both Account views.

Transfers between your own Accounts are not subject to the 30-day sending limit. A Customer-to-Customer payment that exceeds this limit returns 429. Insufficient funds return 402. Both responses reject the new payment. If a response is lost, retry with the same key within its 24-hour window. After expiry, reconcile known transaction IDs and references before deciding whether to send again; a reference alone does not prevent duplicates.

Directly addressable funds containers owned by the authenticated Customer.

Read current ledger-derived funds by Account.

Recipients are business-owned roster resources identified by rcp_…. A pending Recipient has no matched Customer. A linked Recipient returns the Customer cus_… ID that Transfers and Batch items use as their destination.

Recipient resources belong to the authenticated business Customer. An authenticated individual Customer returns 403. Another Customer returns 404 when used as business_customer_id.

• A Recipient id manages the roster resource; it is never a payment destination.
• A linked Recipient's customer_id is the Customer destination for Transfers and Batch items. It is null while the Recipient is pending.
• Adding a Recipient resolves one or more exact identifiers to an existing Customer. An incomplete or conflicting match creates nothing.
• A Recipient never grants access to or changes a linked Customer.
• The business supplies the recipient label. Pocket does not return the Customer's profile name, email, phone, government identity, KYC state, or onboarding reason.
• Raw email and phone inputs are sensitive. Pocket never returns them or includes them in errors, logs, traces, metadata, events, or webhook subjects.

Pocket normalizes identity inputs before matching:

• customer_id: exact Pocket cus_… ID.
• paytag: surrounding whitespace and one optional leading @ removed, then normalized with Pocket's paytag case rules.
• phone: E.164 international phone-number format.
• email: surrounding whitespace trimmed, then compared case-insensitively after Pocket's email normalization.

Supply at least one identifier. When several are supplied, every value must resolve uniquely to the same Customer. A malformed identifier returns 400 with param naming the field. Conflicting matches, ambiguity, blocks, and unavailable targets return the same generic 404 recipient_not_found and create nothing.

Account-relative money movement visible to the authenticated Customer. Both transaction endpoints require transactions:read. Each (id, account_id) pair identifies one view: outbound (kind: transfer) or inbound (kind: deposit). A transfer between two owned Accounts produces two views with the same txn_… ID. A transfer to another Customer exposes only your own Account's view and the counterparty Customer ID, not their Account ID or balance.

GET /v1/transactions supports account_id, kind, repeated method values, status, amount_min, amount_max, exact reference, creation and settlement time ranges, order, limit and cursor. Amount and time bounds are inclusive; settlement-time filters exclude entries without a settlement timestamp. Lists default to 25 items, newest first; the maximum page size is 100. Use order=asc for oldest first. Keep the same filters and order when following next_cursor. An Account filter must refer to an owned Account.

The account_id filter is optional. If supplied, it must identify an existing Account you own; otherwise the API returns 404. A malformed Account ID returns 400. An owned Account with no matching activity returns an empty page.

GET /v1/transactions/{transaction_id} returns current state. If the transaction touches two of your Accounts, supply ?account_id=acc_… to select one view; omitting it returns 400. An inaccessible transaction, or a transaction that does not touch the selected Account, returns 404.

Accepted internal movements appear as pending before settlement. Their source and destination views share the terminal status: settled, failed or voided. Use the corresponding Transfer or Deposit endpoint for its resource view. Card activity is feed-only and has no Transfer or Deposit resource. Verification microdeposits and zero-net Account activity are excluded.

Money leaving one of the authenticated Customer's Accounts. V1 creates internal transfers to another owned Account or another Pocket Customer. Transfer reads also expose supported outbound activity already processed by Pocket; this does not enable ACH, wire, onchain or IBFT creation through Relay. Card spends appear only in the transaction feed.

Reads require transfers:read; internal transfer creation requires transfers:write. Creation is not restricted to business Customers by this operation, but the source credential, Customer and Accounts must be eligible. Customer-to-Customer transfers may have a 30-day sending limit. Transfers between your own Accounts are not subject to this limit.

GET /v1/transfers accepts repeated method values, source_account_id, destination_id, status, amount and timestamp bounds, exact reference, order, limit and cursor. A destination filter can identify an owned Account, a counterparty Customer, or an external instrument visible on a transfer. Unowned Account filters return 404; an unmatched Customer or instrument filter returns an empty page. Historical transfers without an instrument ID cannot match that instrument filter. Page size defaults to 25 (maximum 100), newest first. Retain filters and order when following the returned cursor.

GET /v1/transfers/{transfer_id} returns the current outbound view, including its exact source Account, status and transition timestamps. For an internal movement, the same transaction ID identifies the destination's Deposit view. For an owned-Account transfer, both views are accessible to the same Customer. Otherwise, the destination Customer's private activity remains hidden.

Creation requires Idempotency-Key and returns 201 with a relative Location. For 24 hours, an unchanged retry replays the saved initial response; it does not refresh status or send money again. A changed request using an unexpired idempotency key returns 409. Reads return current state. A created, pending transfer is accepted, not settled. Preserve its ID and poll the read endpoint to reconcile the outcome.

The Transfer response does not expose method-specific details or FX data.

Money arriving in an Account owned by the authenticated Customer. Both Deposit endpoints require deposits:read. Deposits are read-only: Pocket creates them from incoming payments and the destination side of an internal transfer. Card refunds are transaction-feed entries, not Deposit resources.

GET /v1/deposits accepts repeated method values, account_id, status, amount and timestamp bounds, exact reference, order, limit and cursor. Page size defaults to 25 (maximum 100), newest first. Amount and time bounds are inclusive; settlement-time filters exclude entries without a settlement time. An Account filter must identify an owned Account. Keep the same filters and order when following next_cursor.

GET /v1/deposits/{deposit_id} returns the current inbound view. The top-level account_id and destination.account_id identify the same Account. source can be null when the external sender has no visible Pocket resource. For an internal payment from another Customer, their Customer ID and memo can be visible, but their private reference is not. Moving money between your own Accounts preserves your reference in both views.

An accepted internal transfer creates a pending Deposit with the same txn_… ID as the source Transfer. It does not increase destination funds before settlement. Failure or voiding leaves the Deposit visible with the terminal status and no destination credit. Fetching a Deposit outside your Customer's visible inbound activity returns 404.

The response reports the Account's USD movement amount and common movement fields. It does not expose method-specific details, original foreign amounts or fee breakdowns.

An asynchronous group of internal transfers from one authenticated business Customer to destination Customers. Every item has its own status and may fail without changing the result of another item.

The public API supports USD Batch submission, retrieval, Batch listing, item listing and listing the Transfers created by a Batch. POST accepts and queues the work in one operation; it is not the Relay console's CSV preview/execute workflow. It does not reserve funds, guarantee settlement, guarantee execution order, or offer cancellation.

Use Batch counts and item states to track progress. pending means every item is still pending, not necessarily that processing has not started. processing means some items have finished and others remain pending. Terminal states are completed (all settled), partially_completed (some settled), or failed (none settled). An individual item is pending, settled, failed or voided.

Lists return data, has_more and next_cursor; the final cursor is null. The default limit is 25 and the maximum is 100. Batch lists default to newest first and accept order=asc; item lists always use (created_at ASC, item_id ASC), and Transfer lists use (created_at ASC, id ASC). Repeat the same filters when using a cursor; the page size may change. Results are current views, not a frozen multi-page snapshot. When reconciling items whose status may have changed, start again from the first page using the same filters.

Send an Idempotency-Key header. Matching retries within 24 hours return the original response. Reads return current state.

Pocket retries each batch payment using the same idempotency key. If its outcome remains unknown after 24 hours, Pocket stops automatic retries to avoid duplicate payments.

Keep the Batch ID and your submitted item IDs. An item_id only identifies a payment within its Batch. Check uncertain payment outcomes before submitting a replacement Batch; reusing an item_id in a new Batch can pay the recipient again.