Transfer authorization

By default every transfer created with POST /api/payments waits for a manager or legal representative to approve it in the app. Transfer authorization adds a second path for high-volume integrations:

1. An approver enrols one of your webhook endpoints in the app, with a limit per transfer and a limit per 24 hours.
2. When you create a transfer that fits inside those limits and pays a trusted payee, it is not shown to your approvers. Instead your endpoint receives a payment.authorization_requested webhook carrying a one-time nonce.
3. Your system checks the transfer against its own ledger, signs the transfer's fields with the endpoint's signing secret, and calls POST /api/payments/:id/authorize. The transfer then executes exactly like one approved in the app.

Anything outside the limits goes to your approvers, the same as before. Nothing is rejected. That includes an untrusted payee, a transfer over either limit and a suspended authorizer, and it also covers a wrong or stale signature and a challenge that gets no answer within one hour.

Enrolment happens only in the app: Settings → Developer → Transfer approval. The member needs permission to approve payments and to manage webhook endpoints, and confirms with their two-factor step. The API can never enrol, change limits or resume.

• Approving endpoint: one of your active webhook endpoints. While it is enrolled, its URL cannot change, its signing secret is hidden in the app and cannot be regenerated through the API.
• Currency, limit per transfer and limit per 24 hours: both limits are required.
• Signing secret lifetime: 90 days from enrolment or the last rotation. Approvers are reminded 14, 7 and 1 days before. When it expires, transfer authorization suspends itself and transfers go to your approvers.

To rotate the secret, an approver chooses Rotate secret on the same page and confirms with their two-factor step. The new secret is shown once and the 90 days start again. For the next 24 hours, authorizations signed with either the new or the previous secret are accepted, so you can deploy the new one without failing transfers. Webhooks are signed with the new secret straight away. A secret that has already expired gets no overlap, and rotating again within the 24 hours retires the oldest secret at once. After a rotation following an expiry, an approver resumes transfer authorization.

Any approver can suspend transfer authorization with one click in the app, or from the Suspend link in every alert email. No two-factor step is needed to suspend. Resuming needs one. It also suspends itself after five invalid signatures in a row, and when the endpoint is disabled or deleted.

A transfer is sent to your endpoint only when all of these hold, checked when the transfer is created and again when you authorize it:

A payee becomes trusted automatically once a transfer an approver approved in the app has settled to those exact bank details. Approvers can also mark payees as trusted from the Beneficiaries list, or your integration can ask them to (below). Trust follows the bank details: editing a payee's account number lapses it.

Body: external_account_ids, a list of up to 100 of your beneficiaries' bank account ids. Requires the beneficiaries:request_trust scope. The member who created the key must be allowed to create transfers. Limited to 10 requests per minute per key.

201 returns the request with status pending. Nothing is trusted yet: your approvers get one task for the whole batch and approve it in the app with a second factor. An id your workspace does not have returns 422 with param external_account_ids. A leaked key can ask, but only a person can approve.

Poll GET /api/payee_trust_requests/:id (with beneficiaries:request_trust or beneficiaries:read) for status: approved or declined. It becomes cancelled when an approver tries to approve after every requested account was deleted; deleting accounts alone does not change it. Approval trusts the bank details as they are at that moment.

Send your own id for the transfer as client_reference (a string of at most 128 characters) when you create it. It is unique per workspace: creating a second transfer with the same reference returns 409 duplicate_client_reference with the existing transfer's payment_id, so a retried create never makes a second transfer.

client_reference is part of the signed string. Only sign transfers whose client_reference your system issued. That check is what makes a leaked API key useless: a transfer an attacker creates is one your ledger has never seen.

payment.authorization_requested is delivered only to the enrolled endpoint, signed like every other webhook (X-Manza-Signature). You cannot subscribe to it through events. It is delivered at most three times (the first attempt and two retries) within the hour the challenge stays open.

GET /api/payments/:id shows the open challenge as authorization with its id, status and expires_at. The nonce only ever appears in the webhook.

Join these fields with | and compute a lowercase hex HMAC-SHA256 with the endpoint's signing secret:

manza.transfer-authorization.v1|<payment id>|<nonce>|<amount>|<currency>|<source account id>|<payee>|<client_reference>

• amount is the decimal string the API returns (for example 2500.0).
• payee is ext:<external_account_id> for a beneficiary's bank account, or own:<destination_account_id> for one of your own accounts.
• client_reference is empty when the transfer has none.

Build the string from your own ledger's values, not from signature_input in the webhook. signature_input is there so you can compare and debug. The fixed prefix means a webhook signature can never be replayed as an authorization.

Body: authorization_id (from the webhook) and signature. Requires the transfers:authorize scope on a different API key from the one that created the transfer: the creating key is always refused with 403 same_key_forbidden, even when it holds both scopes. Use one key to create and another, kept with your signing code, to authorize. Limited to 10 requests per minute per key.

A valid signature returns 200 with the transfer, now executing. A retried call with the same valid signature returns the same 200 and executes nothing twice. If the first call failed before the transfer started executing, the retry checks the challenge again, so it can return authorization_expired, authorization_stale or state_error instead. A wrong signature on an authorized challenge returns 422 invalid_signature and does not count toward the five attempts. On an open challenge, an invalid signature returns 422 invalid_signature; after five on one challenge the transfer goes to your approvers.

Body: authorization_id and an optional reason. No signature is needed. The transfer is deleted and 200 returns the challenge with status declined. Repeating the call returns the same answer. Same scope and creating-key rule as authorize.

• Keep the signing secret and the authorizing API key on the system that holds your ledger, apart from the key that creates transfers.
• Sign only transfers whose client_reference you issued and whose amount, currency and payee match your record.
• Approvers are alerted about every transfer your endpoint approves, on the cadence they choose: every transfer, above an amount with a daily digest, or the daily digest only. Each alert carries a Suspend link.