FAQ
Getting started
Is there a separate sandbox URL?
No. There's one base URL, https://api.aletaplanet.com, for both environments.
Your token tells us which environment you're using: at_test_… is sandbox and
at_live_… is production.
See environments.
How do I get production access?
Your account contact can enable it after business verification and program setup.
Until then, production calls return 403 production_not_enabled. Make sure
you've worked through the go-live
checklist first.
Cardholders and cards
Can I change a cardholder's type later?
No. The type is set when the cardholder is created and can't be changed later.
Why can't I issue a card?
The cardholder needs an approved KYC outcome, an address, and an identity document.
The identity document can only be set when the cardholder is created. If it's missing, you'll need to create a new cardholder record.
Can I get the full card number from the API?
Yes. POST /v1/cards/{card_id}/secrets takes a public key from you and returns
the card number and security code encrypted to it.
Only the holder of the matching private key can read them. If the key stays on the cardholder's device, your servers only relay ciphertext and stay out of PCI DSS cardholder-data scope. A server that decrypts the number is in scope. See displaying PAN and CVV securely.
Endpoints and errors
An endpoint in the spec returns 404. Why?
Routes are only available when the processor behind your program supports them.
For example, if your processor doesn't report transactions, GET /v1/transactions won't be available even though it's in the API spec.
See troubleshooting.
Is it safe to retry a failed request?
With an Idempotency-Key, yes.
Without one, retrying after a timeout could create a second card or a second debit. Send an idempotency key with every write.
See idempotency.
What are the rate limits?
Sandbox allows 100 requests per minute. Production starts at 1,000 requests per minute, with the final limit set during program setup.
Limits apply per client and are also tracked per organization.
See rate limits.
Webhooks
Should I poll instead?
No. Polling endpoints are rate-limited well below what you'd need for regular polling, and some state is only delivered through events.
Where do I register an endpoint?
In Cockpit, go to Developers → Webhooks. There's currently no API for registering an endpoint.
Can I receive the same event twice?
Yes. You should expect duplicate deliveries and deduplicate them using
event.id.
See idempotent event handling.
Do events arrive in order?
No. Events can arrive out of order.
Use created_at from the envelope and ignore anything older than the state you
already have.
See retries, backoff and ordering.
My endpoint stopped receiving events.
Twenty consecutive failed deliveries will disable the endpoint.
Re-enable it in Cockpit, then use the API to reconcile any missing state. Events aren't queued while the endpoint is disabled.
Security
Can I restrict access by IP?
Yes, per OAuth client, in Cockpit under Developers → OAuth clients. A call from
an address that isn't on the list is refused with 403 ip_not_allowed.
How do I report a vulnerability?
Email it@aletaplanet.com.
I leaked a credential.
Revoke it in Cockpit first, then let us know. Don't wait for a reply before revoking it.