Create payment method setup

POST/v1/payments/methods:setup

Idempotency-Key requiredAccepts bearer

Start saving a card with the card provider — a SetupIntent for the hosted card fields

The first half of saving a card. With the card provider stripe (aikonic.payment-methods.card-provider) the server creates a card setup for off-session use on the tenant's own customer at the card provider (one customer per tenant, created on first use) and answers provider STRIPE, setupRef (the setup id), clientSecret (the setup's client secret, handed to the card provider's browser library only; never logged or audited) and publishableKey. The console mounts the card provider's hosted card fields with them, confirms the card in the browser (3-D Secure included) and then saves it with POST /v1/payments/methods, kind CARD, token the confirmed payment-method id; the card number never reaches Apiq. With the harness card provider (DEV and SANDBOX only) the answer is provider HARNESS, publishableKey null, and the console keeps the harness test tokens (tok_harness_success, tok_harness_decline). kind is CARD (UPI needs no setup). Each call starts a new setup; an unused one simply expires (expiresAt when the provider states it). Human session only; Owner only, as the saved methods (403 PERMISSION_DENIED details.reason OWNER_ONLY). Idempotency-Key required: a replay answers the original setup. A card provider that cannot be reached is 502 UPSTREAM_UNAVAILABLE (retryable). Audited (payments.method_setup_started, never the client secret).

Headers

Idempotency-KeystringRequired
Mandatory on mutations: **48h TTL**; replay with same body-hash returns the original response with Idempotency-Replayed true; same key + different body is 409 IDEMPOTENCY_CONFLICT; in-flight duplicate…Show more
Mandatory on mutations: **48h TTL**; replay with same body-hash returns the original response with Idempotency-Replayed true; same key + different body is 409 IDEMPOTENCY_CONFLICT; in-flight duplicate is 409 IDEMPOTENCY_IN_PROGRESS.

Request bodyPaymentMethodSetupRequest

kindstringRequired
- CARD

Responses

201The setup to hand to the card provider's hosted fieldsPaymentMethodSetup
400VALIDATION — kind missing or not CARDApiErrorResponse
401
UNAUTHENTICATED — missing or expired token.Show more
UNAUTHENTICATED — missing or expired token. Declared on every operation because `security` is declared globally at the document root: every route is authenticated, so every route can answer 401.
ApiErrorResponse
403ApiErrorResponse
405
VALIDATION — the public edge serves GET, POST, PUT, PATCH and DELETE only; any other method is refused before the platform sees it (details.reason METHOD_NOT_ALLOWED, details.source edge).Show more
VALIDATION — the public edge serves GET, POST, PUT, PATCH and DELETE only; any other method is refused before the platform sees it (details.reason METHOD_NOT_ALLOWED, details.source edge). Not retryable as sent.
ApiErrorResponse
409IDEMPOTENCY_CONFLICT | IDEMPOTENCY_IN_PROGRESS — the only 409s of a mutation with no domain conflictApiErrorResponse
413
VALIDATION — the request body is larger than the surface's limit.Show more
VALIDATION — the request body is larger than the surface's limit. Not retryable as sent: shrink the body. Declared on every operation that takes a request body. details carries exactly one key, maxBodyBytes (integer): the limit that applies to this surface, in bytes.
ApiErrorResponse
414
VALIDATION — the request URI (path and query string) is longer than 8 KiB; the public edge refuses it before the platform sees it (details.reason URI_TOO_LONG, details.source edge).Show more
VALIDATION — the request URI (path and query string) is longer than 8 KiB; the public edge refuses it before the platform sees it (details.reason URI_TOO_LONG, details.source edge). Not retryable as sent: send long input in the body of a POST.
ApiErrorResponse
415
VALIDATION — a request body that is not JSON (application/json or application/*+json; a form body only on the OAuth token routes).Show more
VALIDATION — a request body that is not JSON (application/json or application/*+json; a form body only on the OAuth token routes). The public edge refuses it before the platform sees it (details.reason UNSUPPORTED_MEDIA_TYPE, details.source edge). Not retryable as sent: send Content-Type application/json. Declared on every operation that takes a JSON request body.
ApiErrorResponse
500INTERNAL — a bug, and traceId is the support handle.ApiErrorResponse
501
NOT_IMPLEMENTED PAYMENT_METHODS_UNAVAILABLE — saved payment methods are off on this deployment (aikonic.payment-methods.enabled, off by default, on at DEV and SANDBOX).Show more
NOT_IMPLEMENTED PAYMENT_METHODS_UNAVAILABLE — saved payment methods are off on this deployment (aikonic.payment-methods.enabled, off by default, on at DEV and SANDBOX). Not retryable.
ApiErrorResponse
502Retryable; details.psp names the provider.ApiErrorResponse

Errors you should handle

Branch on code and honour retryable — never on the HTTP status alone.

400	VALIDATION Only a card is set up first; save a UPI method directly with its VPA.	not retryable
401	UNAUTHENTICATED The bearer token is expired. Re-authenticate and retry.	not retryable
403	PERMISSION_DENIED Reading wallets needs the finance:read permission.	not retryable
405	VALIDATION This method is not served.	not retryable
409	IDEMPOTENCY_CONFLICT Idempotency-Key 7f0c33d1-9a1e-4d2c-9f77-1c0f2b3a4d55 was used with a different body; never executed	not retryable
409	IDEMPOTENCY_IN_PROGRESS A request with this Idempotency-Key is still executing	retryable
413	VALIDATION The request body is larger than this API accepts (262144 bytes).	not retryable
414	VALIDATION The request URI is longer than 8 KiB.	not retryable
415	VALIDATION Send application/json.	not retryable
500	INTERNAL An unexpected error occurred. Quote the traceId to support.	retryable
501	NOT_IMPLEMENTED Saved payment methods are not available on this deployment.	not retryable
502	UPSTREAM_UNAVAILABLE The payment provider is not answering right now. Try again in a minute.	retryable