Pocket Money - Relay API (0.1.0-draft)

A transfer moves money out of an account. A deposit is money coming in.

An accepted internal (Pocket-to-Pocket) move creates one txn_ ID:

• For the source account, it is a transfer.
• For the destination account, it is a deposit.
• Both account-relative views exist immediately with status set to pending.
• Each view remains visible to callers authorized to read its account.

Transactions form the unified activity feed. When a transfer or deposit object exists, the feed points to it. A pending movement has not posted to either balance:

• At acceptance, the source amount moves from available to reserved.
• The source settled amount remains unchanged.
• Every destination balance amount remains unchanged.
• At settlement, both views become settled together.
• The source reservation posts out, and the destination settled and available amounts are credited.

Clients create transfers, not deposits. Pocket creates deposits for incoming Automated Clearing House (ACH) payments, the destination side of internal transfers and Pocket-funded advances or rewards.

Card refunds appear in the activity feed as deposits, but do not have deposit objects.

Authorization is based on the account hierarchy associated with the API key. A key may act only on its associated account and that account's complete owned sub-account hierarchy.

Each bearer API key is associated with one account:

Authorization: Bearer <api_key>

• Every request requires the key. A missing or invalid key returns 401 unauthorized.
• Within its capability scopes, the key applies to its associated account and that account's complete owned sub-account hierarchy.
• There are no per-account grants, delegated accounts, or key-specific subtrees.

An account outside that hierarchy, or a resource belonging to it, returns 404 as if it did not exist. 403 is reserved for actions the key may not perform on an account in the hierarchy.

API keys also carry capability scopes. Each operation states its required scopes at the start of its description and in x-required-scopes for tooling. The key needs every listed scope.

Scopes control what a key may do. Its account hierarchy controls which accounts it may act on.

• A scope never grants access outside the associated account hierarchy.
• A missing scope returns 403 for a resource in that hierarchy.
• An account outside the hierarchy returns 404.

Broad scopes satisfy granular requirements:

• read satisfies any *:read requirement.
• write satisfies any *:write or *:read requirement.
• A granular *:write scope includes the corresponding *:read operations and the reads needed to perform and inspect that write. For example, transfers:write permits the source balance details returned while creating a transfer.
• A new high-risk capability may require an explicit granular scope even when a key has write.

Available scopes:

Transfers are authorized from the source:

• source.account_id must be the account associated with the API key or one of its sub-accounts.
• The destination only needs to be valid for the method.
• transfers:write applies across every eligible account in that hierarchy, subject to account state and method-specific requirements.

Sending money to an account does not grant read access or any other access to it.

A business may keep a roster of customers it pays. A member is a reference to a Pocket customer account, not delegated access to that account.

• Changing or removing the roster reference never changes the customer account.
• Rostered customer accounts do not appear in the business's account, balance, transaction, or instrument lists.
• Direct reads return 404 unless the account is in the hierarchy associated with the API key.

An external payment instrument (epi_…) is a verified outside destination for money leaving Pocket, such as a bank account.

• It is not a Pocket account.
• It does not hold a Pocket balance.
• It is not used for Pocket-to-Pocket transfers.
• It is private to its owning account.

A business can create, list, remove, and use instruments only for accounts in the hierarchy associated with the API key. A roster relationship does not change that rule.

Money-movement field visibility:

• memo is the payment note and may be visible to both sides.
• reference and metadata are visible only from the account-owner side on which they were set.

A counterparty does not see your reference or metadata. A key that owns both sides can read both account-relative views.

An account is a money-holding party identified by a prefixed id (biz_… or cus_…).

• All accounts are customer-owned.
• Whether Pocket or the API provisioned an account has no public significance.
• A customer's portfolio is its principal account plus its complete owned sub-account hierarchy, recursively.
• Money operations reference accounts by id.

The optional reference is an opaque, non-unique external reference. Use the reference filter on list accounts or list balances to find matches; a filter may return more than one.

A wrong-prefix ID for an operation returns 400.

Amounts are decimal strings in major units of the currency. For example, "100.00" means 100 USD. USD supports at most two decimal places.

• Amounts are always JSON strings, never JSON numbers.
• Write amounts must be greater than zero.
• A USD write uses an unsigned decimal with 1–16 integer digits and at most two fractional digits.
• Commas, whitespace, scientific notation, and unnecessary leading zeros are not accepted.
• The maximum USD write amount is "9999999999999999.99".
• Valid examples include "1", "1.0", "1.00", "0.01", and "2500.50".
• Decimal-equivalent forms such as "1", "1.0", and "1.00" produce the same idempotency request fingerprint.

Pocket rejects an amount outside this boundary with 400 invalid_request; param identifies the actual request field, such as amount, source_amount, or items[n].amount. No resource is created or changed, and the idempotency_key is not bound.

A USD-to-PKR Inter Bank Funds Transfer (IBFT) can use an explicit quote or accept the current price as part of transfer creation.

• A quote is source-fixed in v1: the caller supplies the gross USD source amount.
• The destination currency is supplied explicitly and must match the destination instrument.
• Creating a quote does not reserve the source account's USD or change any customer balance.
• Each fee is already rounded in its currency.
• net_source_amount equals source_amount minus the sum of source-currency fees.
• The gross source amount must exceed the total source-currency fees. Otherwise Pocket returns 400 invalid_request, with param identifying the submitted source-amount field.
• rate is destination-currency units per one source-currency unit.
• destination_amount equals net_source_amount multiplied by rate, rounded half-even to the destination currency's precision. PKR supports two decimal places.
• On an accepted IBFT Transfer, amount equals fx.source_amount, and currency equals fx.source_currency (USD in v1).
• fx.destination_amount is the PKR amount delivered to the destination instrument.
• FX fees are included within the gross source amount. They are not added on top of the Transfer's amount.

Display and reconcile the amounts, fees and rate returned on the quote and transfer. Do not recompute them.

JSON request-body limits:

• Most operations: 1 MiB (1,048,576 bytes).
• POST /v1/batches: 10 MiB (10,485,760 bytes).

The limit applies to the UTF-8-encoded JSON body, including JSON syntax and whitespace but excluding HTTP headers. Pocket enforces it even when Content-Length is absent.

An oversized body returns 413 Payload Too Large with code payload_too_large. The error has no field-specific param.

An oversized request creates or changes nothing and does not bind its idempotency key. OpenAPI 3.0 cannot express these whole-body limits. A request can satisfy every field limit and still exceed the body limit.

All timestamps are strings in RFC 3339 / ISO 8601 format.

• Responses use UTC with a Z suffix, e.g. 2026-07-31T09:00:00Z.
• Requests accept any valid instant, including numeric offsets. For example, 2026-07-31T14:00:00+05:00 and 2026-07-31T09:00:00Z are the same instant.

A caller-supplied idempotency_key is required for:

• Resource-creating POST requests for accounts, transfers, FX quotes, batches, instruments, funding rules, and webhook endpoints.
• Webhook secret rotation.

PATCH requests accept a key optionally. Without one, retrying after a lost response may apply an update more than once.

Use a non-blank random value of 1–255 characters, such as a universally unique identifier (UUID). Mint it once per logical operation and reuse it only when retrying that operation.

All operations that accept an idempotency key share one namespace per associated account and environment.

The namespace spans:

• Resource families and endpoints.
• Transfer methods.
• Every account in the associated account hierarchy.
• Optional idempotent PATCH requests.
• Webhook secret rotation.

The namespace is not scoped by source account, endpoint, resource family or API credential. Keys associated with the same account share it, including after credential rotation. Sandbox and production use separate namespaces.

Each key identifies one logical operation during the retention window. Reusing it elsewhere in the same namespace with a different request fingerprint returns 409.

The fingerprint covers:

• The HTTP method.
• The canonical path.
• A canonical hash of the request body.

Metadata key order does not affect the hash. Amounts are compared as decimals, so "10.4" and "10.40" are equivalent.

A key is bound by the first request that succeeds with a 2xx response. The binding lasts at least 24 hours.

• An identical replay returns the original status code and the object's current representation. Fields may have changed since creation.
• The same key with a different fingerprint returns 409.
• A duplicate received while the original request is still running returns 409 until the original completes.

A failed request that creates or updates nothing leaves an unbound key available. This includes resource-state 409 responses. Retry the unchanged operation with the same key.

Quote creation and transfer creation are separate logical operations and use separate keys. For an IBFT transfer request:

• If a Transfer is created, its key is bound. An identical replay returns that Transfer even though its quote is now accepted.
• If no Transfer is created, its key remains unbound and the unchanged request may reuse it.
• Replacing an expired, canceled, or already accepted quote changes the financial instruction. Submit the changed request with a new key.

A 409 means one of the following:

• The key is bound to a different request fingerprint.
• The original request is still in flight.
• The resource is in a conflicting state.

When retrying after an error:

• After 409 idempotency_conflict, never change the request while reusing the key. Retry an unchanged in-flight duplicate, or retrieve existing_id when one is returned.
• After a resource-state 409 that created no object, the key remains unbound. Retry the unchanged request with the same key. Mint a new key if the financial instruction changes.
• After a 5xx response or timeout, keep the same key until you receive a definitive response.

After the retention window expires, a key may be treated as new and can create a second object.

idempotency_key is not returned on objects and is not a business identifier. To store a pay-run, invoice, employee, or other external ID, use the filterable reference field.

One-time values are never replayed. A webhook secret appears only in the original successful create or rotate response.

If that response is lost, the same idempotency_key will not recover the secret. Rotate with a new key to get a fresh one.

Lists return { data, has_more, next_cursor }. Ordering varies by endpoint. A valid next_cursor continues the first page's ordering.

• Pass next_cursor back as cursor, together with limit.
• Treat the cursor as opaque; do not parse it.
• Re-supply the same filters on every page.
• A cursor/filter mismatch returns 400.
• An expired or invalid cursor returns 400.

After a cursor error, restart from the first page.

Query filters accept one value unless stated otherwise. The money-movement method filter accepts a comma-separated list, for example method=ach,wire. Each endpoint accepts only the methods it can return. An unsupported method returns 400 with code invalid_request and param=method.

Any endpoint may return 429 with code rate_limited and a Retry-After header when you exceed the rate limit. Its value is a non-negative base-10 integer giving the number of seconds to wait after receiving the response. Pocket does not use the HTTP-date form.

For example, Retry-After: 30 means wait at least 30 seconds before retrying.

Error responses use one JSON shape:

{
  "code": "invalid_request",
  "message": "destination.account_id has an unexpected prefix",
  "param": "destination.account_id",
  "request_id": "req_01jj0m9w2k3n5p7q9r1s3t5v7w"
}

• code is the stable, machine-readable reason. Preserve unknown codes and fall back to the HTTP status.
• message explains the error to a human. Do not branch on its wording.
• param identifies the request field involved, when applicable; otherwise it is absent or null.
• request_id identifies the request. Include it when contacting Pocket support.

Common HTTP statuses:

Reads can be retried after transient server failures. After a timeout or 500 on a money-writing request, retry only with the same idempotency_key; see Idempotency above.

When webhook delivery is enabled, every request carries a Pocket-Signature header. Use it to verify that the request came from Pocket and was not altered in transit.

Verify the signature before acting on the payload.

Treat the event as a hint, not the source of truth. Fetch the resource named by subject to read its current state. Retrieving the event returns its immutable notification envelope, not the current subject state.

The header is a comma-separated list of fields:

Pocket-Signature: t=1690794000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

• t: the Unix timestamp (seconds) when we signed the request.
• v1: a hex-encoded HMAC using the SHA-256 hash function. There may be more than one v1 value (space- or comma-separated) during secret rotation; a request is valid if any matches.

The signing secret is returned when you create a webhook endpoint or call rotate_secret. It is shown only in those responses, so store it.

To verify a request:

1. Read the raw request body as bytes. Do not parse and re-serialize it first: any reformatting changes the bytes and breaks the signature.
2. Extract t and the v1 value(s) from the Pocket-Signature header.
3. Build the signed payload by concatenating t, a literal ., and the raw body: signed_payload = t + "." + raw_body.
4. Compute HMAC-SHA256(signed_payload, secret) and hex-encode it.
5. Constant-time compare your result against each v1. If none match, reject the request.
6. Reject if t is outside your tolerance for the current time (we recommend 5 minutes) to guard against replay.

During rotate_secret, Pocket signs with both secrets for a grace period. Verify against both until you have switched to the new secret.

1. Add the employee to the member roster

Supply the identifiers you know. This example uses email and phone:

POST /v1/accounts/{biz_account_id}/members

{
  "email": "employee@example.com",
  "phone": "+12025550123",
  "metadata": {
    "employee_id": "EMP-1042"
  }
}

The response returns the roster relationship and its customer_id.

• A newly created roster relationship returns 201 Created and its relative URL in the Location header.
• An existing or restored roster relationship returns 200 OK.
• An existing Pocket customer is linked immediately.
• If no customer matches, an email or phone can create a customer whose member status is onboarding_required.

2. Wait until the employee can be paid

Retrieve the member using the returned customer_id:

GET /v1/accounts/{biz_account_id}/members/{customer_id}

Include the employee in payroll when capabilities.can_receive_transfers is true.

1. Submit the payroll transfers

Give each employee a unique item_id for this batch. Use the employee's customer_id as the destination account ID.

POST /v1/batches

{
  "idempotency_key": "a15e4ae4-52f3-460c-9c1c-5f6b7b90cc44",
  "source": { "account_id": "biz_..." },
  "recipient_policy": "payable_members",
  "reference": "payroll-2026-07",
  "items": [
    {
      "item_id": "line-001",
      "destination": { "account_id": "cus_..." },
      "amount": "100.00",
      "currency": "USD",
      "reference": "EMP-1042"
    },
    {
      "item_id": "line-002",
      "destination": { "account_id": "cus_..." },
      "amount": "120.00",
      "currency": "USD",
      "reference": "EMP-1089"
    }
  ]
}

The 202 response returns the batch and its batch_... ID.

2. Track the batch

GET /v1/batches/{batch_id}

When every transfer settles, status becomes completed and item_counts.settled equals item_counts.total.

3. Reconcile each employee

GET /v1/batches/{batch_id}/items

Match each result to the submitted line by item_id. Its transfer_id is the resulting txn_... ID.

Send money to a Pocket customer or another Pocket account:

POST /v1/transfers/internal

{
  "idempotency_key": "d9f80740-7f8e-4f16-b5cc-4fd5bf7d3b21",
  "source": { "account_id": "biz_..." },
  "destination": { "account_id": "cus_..." },
  "amount": "100.00",
  "currency": "USD",
  "reference": "payrun-2026-07"
}

Read the business's balances and activity. Use parent_id to limit balances to the direct sub-accounts of one business account.

GET /v1/balances
GET /v1/balances?parent_id=biz_...
GET /v1/transactions?account_id=biz_...

1. Create the child account

POST /v1/accounts

{
  "idempotency_key": "7a4409dc-5612-41d9-8e5d-e2fbfb657f83",
  "parent_id": "biz_...",
  "name": "Payroll operations",
  "reference": "payroll-operations"
}

The returned child account is active and can be used as a funding-rule destination.

2. Preview the matching criteria

POST /v1/accounts/{parent_account_id}/funding_rules/preview

{
  "criteria": [
    { "field": "sender_name", "operator": "contains", "value": "ACME PAYROLL" }
  ]
}

Use the preview results to confirm the criteria match the intended settled deposits.

3. Create the funding rule

POST /v1/accounts/{parent_account_id}/funding_rules

{
  "idempotency_key": "c20d05c2-40c6-48f6-b2b7-a1aaac33370c",
  "destination_account_id": "biz_...",
  "criteria": [
    { "field": "sender_name", "operator": "contains", "value": "ACME PAYROLL" }
  ]
}

The rule begins enabled. When a matching deposit into the parent account settles, its full amount moves to the child account as an internal transfer.

4. View transfers created by the rule

GET /v1/transfers?funding_rule_id={funding_rule_id}

Withdraw from a business-owned balance to that account's own external instrument.

1. Register the external bank instrument

POST /v1/accounts/{biz_account_id}/instruments

{
  "idempotency_key": "b57ba9a4-0f17-4c5d-99cd-e1467069270e",
  "type": "bank_account",
  "currency": "USD",
  "bank_account": {
    "holder_name": "Example Business LLC",
    "account_number": "000123456789",
    "routing_number": "021000021",
    "country": "US"
  }
}

2. Check the review status

If a newly registered instrument is in_review, poll it while that status remains:

GET /v1/instruments/{instrument_id}

Proceed only when the instrument is approved. declined is terminal; correct the bank details and register a new instrument.

3. Create the withdrawal

Use the method-specific endpoint. For ACH:

POST /v1/transfers/ach

{
  "idempotency_key": "15dfe9e2-04e2-4e9a-b448-2d71c46c2219",
  "source": { "account_id": "biz_..." },
  "destination": { "instrument_id": "epi_..." },
  "amount": "500.00",
  "currency": "USD",
  "memo": "PAYROLL"
}

Use POST /v1/transfers/wire instead for a wire withdrawal. ACH and wire have different memo limits; see the endpoint request schemas.

To withdraw USD converted to PKR, see Withdraw USD as PKR.

Convert USD and withdraw the resolved PKR amount through Pocket's instant IBFT route to the source account's own approved Pakistani bank instrument. V1 does not expose the standard PKR cash-out route and does not promise a delivery time.

1. Find a supported bank

GET /v1/banks?country=PK&method=ibft

Use the returned code when registering the bank account.

2. Register the PKR instrument

POST /v1/accounts/{biz_account_id}/instruments

{
  "idempotency_key": "0b57ba9a-4f17-4c5d-99cd-e14670692710",
  "type": "bank_account",
  "currency": "PKR",
  "bank_account": {
    "country": "PK",
    "bank_code": "hbl",
    "account_number": "PK16HABB1234567890123456"
  }
}

account_number may be a supported local account number or Pakistani International Bank Account Number (IBAN). If the instrument is in_review, poll it while that status remains. Proceed only when it is approved. If it is declined, correct the bank details and register a new instrument.

3. Request a quote

POST /v1/fx_quotes

{
  "idempotency_key": "9f1c2a34-6a3d-4e0b-9c7e-2f8b1d5a7e21",
  "source": { "account_id": "biz_..." },
  "destination": { "instrument_id": "epi_..." },
  "method": "ibft",
  "source_amount": "1000.00",
  "source_currency": "USD",
  "destination_currency": "PKR"
}

The response fixes the rate, fees and PKR amount until expires_at, while the quote remains open. The quote cannot be accepted at or after expires_at. Creating it does not reserve USD.

4. Create the transfer

POST /v1/transfers/ibft

{
  "idempotency_key": "b2e6d1f0-3c44-4d55-8f66-77a889900abc",
  "source": { "account_id": "biz_..." },
  "destination": { "instrument_id": "epi_..." },
  "amount": "1000.00",
  "currency": "USD",
  "destination_currency": "PKR",
  "pricing": {
    "mode": "quote",
    "quote_id": "fxq_..."
  },
  "reference": "cashout-1042"
}

To skip the separate quote request, use pricing.mode=current. Pocket then creates and accepts an equivalent quote as part of transfer creation. If the request fails, neither the quote nor the transfer is created. Add minimum_destination_amount when the transfer must not proceed below a particular PKR amount.

5. Track the withdrawal

Poll GET /v1/transfers/{transfer_id} until the transfer is terminal. amount is the gross USD debit; fx contains the fee, rate and PKR amount to reconcile. A failed transfer releases the full USD reservation and is not automatically retried.

Money-movement activity across the account hierarchy associated with the API key. It includes transfers, deposits and the transaction entry for each account-relative view. Pending entries are visible before they post to a balance.

Use the transaction ID to fetch the transfer or deposit object when one exists.

Move money out of the account associated with the API key or one of its sub-accounts.

An internal transfer pays another Pocket account. ach and wire withdraw USD to the source account's own approved external instrument. ibft converts USD and withdraws PKR through Pocket's instant route to the source account's own approved Pakistani bank instrument. V1 does not expose the standard PKR cash-out route or promise a delivery time. Each method has its own write endpoint.

Money arriving in an account.

Deposits are created for you, never by you:

• An incoming ACH or other supported rail.
• The destination view of an accepted internal transfer.
• A Pocket-funded advance or reward.

A pending internal deposit is visible but does not affect the destination balance until settlement. Card refunds are feed-only transactions, not deposit objects.

Price a cross-currency transfer before creating it.

V1 quotes are source-fixed USD-to-PKR quotes for method=ibft. A quote binds its source account, destination instrument, method, currencies, gross source amount, fees, rate, and resolved destination amount.

Lifecycle

• open: available for one transfer to accept before expires_at.
• accepted: linked permanently to the transfer in transfer_id.
• expired: not accepted before expires_at.
• canceled: withdrawn by Pocket before acceptance.

expires_at is exclusive: the quote cannot be accepted at or after that instant.

Terminal states do not change. An accepted quote never expires and is never reusable. Pocket may cancel an open quote, but while it remains open its quoted pricing is honored until expires_at. Acceptance can still fail because funds, authorization, limits, account state, or instrument approval changed.

Creating a quote does not reserve customer funds or affect balances. Multiple open quotes may coexist, subject to rate and capacity limits; creating one does not cancel another.

Submit independent internal transfers from one source account in a single request.