BETA: This endpoint is subject to change without notice.

Required permission: payments.write

Allocates one eligible Tap to Pay terminal for the account, mints a Softpay Cloud setup reference and one-use setup token, and returns the SDK-init context. The POS Backend hands setup_token to the POS App, which the Synapto POS SDK feeds to the Softpay app via the Android SETUP intent.

platform must be ANDROID; iOS pairing is a subsequent milestone.

Eligible terminals are those in UNPAIRED or PAIRING_FAILED state, plus the crash-recovery case of PAIRING with no persisted Cloud setup reference. If no eligible terminal exists (or the account has no Tap to Pay Rail, or the Softpay Merchant is not yet provisioned), the call fails with FAILED_PRECONDITION.

Idempotent via the idempotency-key header: a retry with the same key returns the cached response — success or failure — without allocating a second terminal, up to the service-default retention window (~96h). A same-key retry after a failure therefore replays that failure; the "retry" hint in any error message applies to a fresh request (new key or no key), not to a same-key repeat. Without an idempotency key, two rapid requests each allocate their own terminal.

publishable_key on the response is the SDK-init key for this account. Persist it alongside the account_id: the same key applies to every subsequent Tap to Pay operation for this account and is not re-delivered on publishable-key-authenticated endpoints.