ampr docs

Drivers

Drivers and their saved payment methods, for the CPO's own app (card entry happens with the payment provider's client SDK, never through Ampr)

GET /drivers List drivers

Parameters

Name In Type Required Description
external_ref query string Return only the driver with this external reference.
per_page query integer
after query string Cursor. Pass the previous page's `pagination.next_cursor`.

Responses

200 Driver list

PropertyTypeRequiredDescription
dataarray<Driver>required
PropertyTypeRequiredDescription
idstringrequired
external_refstringnullablerequiredThe CPO's own user id for this driver. Null when none was supplied or after erasure.
statusenum
  • active
  • erased
required
default_payment_method_idstringnullablerequired
token_idsarray<string>requiredTokens (RFID or app credentials) linked to this driver.
created_atstringformat: date-timerequired
paginationCursorPaginationrequired
PropertyTypeRequiredDescription
per_pageintegerrequired
has_morebooleanrequired
next_cursorstringnullablerequiredPass as `after` to fetch the next page; null on the last page.

400 Invalid request parameters application/problem+json

PropertyTypeRequiredDescription
typestringformat: urirequired
titlestringrequired
statusintegerrequired
detailstringnullable
instancestringnullable
codestringStable machine-readable problem code, present on problems a client is expected to branch on (for example `org_payments_not_ready`, `driver_erased`, `token_already_linked`, `payment_method_not_active`, `idempotency_key_required`, `idempotency_key_reused`, `provider_unavailable`, `publishable_key_not_configured`).

401 Missing or invalid API key application/problem+json

PropertyTypeRequiredDescription
typestringformat: urirequired
titlestringrequired
statusintegerrequired
detailstringnullable
instancestringnullable
codestringStable machine-readable problem code, present on problems a client is expected to branch on (for example `org_payments_not_ready`, `driver_erased`, `token_already_linked`, `payment_method_not_active`, `idempotency_key_required`, `idempotency_key_reused`, `provider_unavailable`, `publishable_key_not_configured`).

Request example

curl -X GET "https://api.ampr.dev/v1/drivers" \
  -H "Authorization: Bearer $AMPR_API_KEY"
Note
This endpoint requires an API key. Send it as a Bearer token in the Authorization header.

POST /drivers Create a driver (idempotent)

Creates a driver and its payment-provider Customer on the organization's connected account. Operator role or higher. **Idempotency.** With an `external_ref`, the call is idempotent on `(organization, external_ref)`: the first call returns `201`, repeats return `200` with the same driver. Without an `external_ref` an `Idempotency-Key` header is required (`400` otherwise); the same key with the same body returns the same driver, and the same key with a different body returns `422` and never the stored driver. `email` and `name`, when supplied, are forwarded to the payment provider only (for provider-sent receipts); Ampr does not store them. Returns `409` (`org_payments_not_ready`) when the organization has no charges-enabled connected account; nothing is stored and no Customer is created in that case.

Parameters

Name In Type Required Description
Idempotency-Key header string 1 to 255 printable ASCII characters, no spaces. Scoped to your organization. Required by `POST /drivers` when no `external_ref` is sent.

Request body

PropertyTypeRequiredDescription
external_refstringThe CPO's own user id for this driver. Unique per organization.
emailstringForwarded to the payment provider only.
namestringForwarded to the payment provider only.

Responses

200 An existing driver (same `external_ref`, or the same Idempotency-Key and body)

PropertyTypeRequiredDescription
dataDriverrequiredA driver of the organization (the CPO's end customer). Ampr stores no name, email or card number, and the payment provider's Customer id is not exposed.
PropertyTypeRequiredDescription
idstringrequired
external_refstringnullablerequiredThe CPO's own user id for this driver. Null when none was supplied or after erasure.
statusenum
  • active
  • erased
required
default_payment_method_idstringnullablerequired
token_idsarray<string>requiredTokens (RFID or app credentials) linked to this driver.
created_atstringformat: date-timerequired

201 Driver created

PropertyTypeRequiredDescription
dataDriverrequiredA driver of the organization (the CPO's end customer). Ampr stores no name, email or card number, and the payment provider's Customer id is not exposed.
PropertyTypeRequiredDescription
idstringrequired
external_refstringnullablerequiredThe CPO's own user id for this driver. Null when none was supplied or after erasure.
statusenum
  • active
  • erased
required
default_payment_method_idstringnullablerequired
token_idsarray<string>requiredTokens (RFID or app credentials) linked to this driver.
created_atstringformat: date-timerequired

400 Invalid request parameters application/problem+json

PropertyTypeRequiredDescription
typestringformat: urirequired
titlestringrequired
statusintegerrequired
detailstringnullable
instancestringnullable
codestringStable machine-readable problem code, present on problems a client is expected to branch on (for example `org_payments_not_ready`, `driver_erased`, `token_already_linked`, `payment_method_not_active`, `idempotency_key_required`, `idempotency_key_reused`, `provider_unavailable`, `publishable_key_not_configured`).

401 Missing or invalid API key application/problem+json

PropertyTypeRequiredDescription
typestringformat: urirequired
titlestringrequired
statusintegerrequired
detailstringnullable
instancestringnullable
codestringStable machine-readable problem code, present on problems a client is expected to branch on (for example `org_payments_not_ready`, `driver_erased`, `token_already_linked`, `payment_method_not_active`, `idempotency_key_required`, `idempotency_key_reused`, `provider_unavailable`, `publishable_key_not_configured`).

403 Authenticated but not authorized for this action (insufficient role) application/problem+json

PropertyTypeRequiredDescription
typestringformat: urirequired
titlestringrequired
statusintegerrequired
detailstringnullable
instancestringnullable
codestringStable machine-readable problem code, present on problems a client is expected to branch on (for example `org_payments_not_ready`, `driver_erased`, `token_already_linked`, `payment_method_not_active`, `idempotency_key_required`, `idempotency_key_reused`, `provider_unavailable`, `publishable_key_not_configured`).

409 Resource conflict (e.g., duplicate serial, active session) application/problem+json

PropertyTypeRequiredDescription
typestringformat: urirequired
titlestringrequired
statusintegerrequired
detailstringnullable
instancestringnullable
codestringStable machine-readable problem code, present on problems a client is expected to branch on (for example `org_payments_not_ready`, `driver_erased`, `token_already_linked`, `payment_method_not_active`, `idempotency_key_required`, `idempotency_key_reused`, `provider_unavailable`, `publishable_key_not_configured`).

422 Request understood but cannot be processed (e.g., invalid state) application/problem+json

PropertyTypeRequiredDescription
typestringformat: urirequired
titlestringrequired
statusintegerrequired
detailstringnullable
instancestringnullable
codestringStable machine-readable problem code, present on problems a client is expected to branch on (for example `org_payments_not_ready`, `driver_erased`, `token_already_linked`, `payment_method_not_active`, `idempotency_key_required`, `idempotency_key_reused`, `provider_unavailable`, `publishable_key_not_configured`).

502 The payment provider did not complete the request (`provider_unavailable`); safe to retry with the same Idempotency-Key application/problem+json

PropertyTypeRequiredDescription
typestringformat: urirequired
titlestringrequired
statusintegerrequired
detailstringnullable
instancestringnullable
codestringStable machine-readable problem code, present on problems a client is expected to branch on (for example `org_payments_not_ready`, `driver_erased`, `token_already_linked`, `payment_method_not_active`, `idempotency_key_required`, `idempotency_key_reused`, `provider_unavailable`, `publishable_key_not_configured`).

Request example

curl -X POST "https://api.ampr.dev/v1/drivers" \
  -H "Authorization: Bearer $AMPR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_ref": "string",
    "email": "string",
    "name": "string"
  }'
Note
This endpoint requires an API key. Send it as a Bearer token in the Authorization header.

GET /drivers/{driver_id} Get a driver

A driver of another organization is indistinguishable from a nonexistent one (`404`).

Parameters

Name In Type Required Description
driver_id path string required

Responses

200 Driver detail

PropertyTypeRequiredDescription
dataDriverrequiredA driver of the organization (the CPO's end customer). Ampr stores no name, email or card number, and the payment provider's Customer id is not exposed.
PropertyTypeRequiredDescription
idstringrequired
external_refstringnullablerequiredThe CPO's own user id for this driver. Null when none was supplied or after erasure.
statusenum
  • active
  • erased
required
default_payment_method_idstringnullablerequired
token_idsarray<string>requiredTokens (RFID or app credentials) linked to this driver.
created_atstringformat: date-timerequired

401 Missing or invalid API key application/problem+json

PropertyTypeRequiredDescription
typestringformat: urirequired
titlestringrequired
statusintegerrequired
detailstringnullable
instancestringnullable
codestringStable machine-readable problem code, present on problems a client is expected to branch on (for example `org_payments_not_ready`, `driver_erased`, `token_already_linked`, `payment_method_not_active`, `idempotency_key_required`, `idempotency_key_reused`, `provider_unavailable`, `publishable_key_not_configured`).

404 Resource not found application/problem+json

PropertyTypeRequiredDescription
typestringformat: urirequired
titlestringrequired
statusintegerrequired
detailstringnullable
instancestringnullable
codestringStable machine-readable problem code, present on problems a client is expected to branch on (for example `org_payments_not_ready`, `driver_erased`, `token_already_linked`, `payment_method_not_active`, `idempotency_key_required`, `idempotency_key_reused`, `provider_unavailable`, `publishable_key_not_configured`).

Request example

curl -X GET "https://api.ampr.dev/v1/drivers/drv_example" \
  -H "Authorization: Bearer $AMPR_API_KEY"
Note
This endpoint requires an API key. Send it as a Bearer token in the Authorization header.

POST /drivers/{driver_id}/payment-methods/setup-intent Create a SetupIntent so the CPO app can save the driver's card

Creates a payment-provider SetupIntent (for later off-session use) on the organization's connected account, bound to the driver's Customer. Operator role or higher. Pass the returned `client_secret` and `stripe_account` to the provider's client SDK (for example Stripe.js `confirmSetup`, initialised with `stripeAccount`); card data goes to the provider and never to Ampr. The `client_secret` is a bearer credential: the response is `Cache-Control: no-store`, and Ampr never stores or logs it. The `Idempotency-Key` header is required: a retry with the same key returns the same SetupIntent (and `client_secret`), fetched again from the provider under the same provider idempotency key, for at least 24 hours. Once the driver completes card entry, the card appears in `GET .../payment-methods` (listen for the `payment_method.attached` webhook event, or poll). Errors: `400` `idempotency_key_required` (no `Idempotency-Key`) or `idempotency_key_invalid`; `409` `driver_erased` or `org_payments_not_ready`; `503` `publishable_key_not_configured` when the deployment has no provider publishable key (nothing is created); `502` `provider_unavailable`.

Parameters

Name In Type Required Description
driver_id path string required
Idempotency-Key header string required 1 to 255 printable ASCII characters, no spaces. Scoped to your organization and to the driver. Retry with the SAME key to get the same SetupIntent back (inside the provider's idempotency window, at least 24 hours); a new key creates a new SetupIntent.

Responses

201 SetupIntent created

PropertyTypeRequiredDescription
dataDriverSetupIntentrequired
PropertyTypeRequiredDescription
setup_intent_idstringrequired
client_secretstringrequiredBearer credential for the payment provider's client SDK. Never stored or logged by Ampr, and the response is sent with `Cache-Control: no-store`.
stripe_accountstringrequiredThe organization's connected account id. Initialise the client SDK with it.
publishable_keystringrequiredThe payment provider's publishable (not secret) key for the client SDK.

400 Invalid request parameters application/problem+json

PropertyTypeRequiredDescription
typestringformat: urirequired
titlestringrequired
statusintegerrequired
detailstringnullable
instancestringnullable
codestringStable machine-readable problem code, present on problems a client is expected to branch on (for example `org_payments_not_ready`, `driver_erased`, `token_already_linked`, `payment_method_not_active`, `idempotency_key_required`, `idempotency_key_reused`, `provider_unavailable`, `publishable_key_not_configured`).

401 Missing or invalid API key application/problem+json

PropertyTypeRequiredDescription
typestringformat: urirequired
titlestringrequired
statusintegerrequired
detailstringnullable
instancestringnullable
codestringStable machine-readable problem code, present on problems a client is expected to branch on (for example `org_payments_not_ready`, `driver_erased`, `token_already_linked`, `payment_method_not_active`, `idempotency_key_required`, `idempotency_key_reused`, `provider_unavailable`, `publishable_key_not_configured`).

403 Authenticated but not authorized for this action (insufficient role) application/problem+json

PropertyTypeRequiredDescription
typestringformat: urirequired
titlestringrequired
statusintegerrequired
detailstringnullable
instancestringnullable
codestringStable machine-readable problem code, present on problems a client is expected to branch on (for example `org_payments_not_ready`, `driver_erased`, `token_already_linked`, `payment_method_not_active`, `idempotency_key_required`, `idempotency_key_reused`, `provider_unavailable`, `publishable_key_not_configured`).

404 Resource not found application/problem+json

PropertyTypeRequiredDescription
typestringformat: urirequired
titlestringrequired
statusintegerrequired
detailstringnullable
instancestringnullable
codestringStable machine-readable problem code, present on problems a client is expected to branch on (for example `org_payments_not_ready`, `driver_erased`, `token_already_linked`, `payment_method_not_active`, `idempotency_key_required`, `idempotency_key_reused`, `provider_unavailable`, `publishable_key_not_configured`).

409 Resource conflict (e.g., duplicate serial, active session) application/problem+json

PropertyTypeRequiredDescription
typestringformat: urirequired
titlestringrequired
statusintegerrequired
detailstringnullable
instancestringnullable
codestringStable machine-readable problem code, present on problems a client is expected to branch on (for example `org_payments_not_ready`, `driver_erased`, `token_already_linked`, `payment_method_not_active`, `idempotency_key_required`, `idempotency_key_reused`, `provider_unavailable`, `publishable_key_not_configured`).

502 The payment provider did not complete the request (`provider_unavailable`); safe to retry with the same Idempotency-Key application/problem+json

PropertyTypeRequiredDescription
typestringformat: urirequired
titlestringrequired
statusintegerrequired
detailstringnullable
instancestringnullable
codestringStable machine-readable problem code, present on problems a client is expected to branch on (for example `org_payments_not_ready`, `driver_erased`, `token_already_linked`, `payment_method_not_active`, `idempotency_key_required`, `idempotency_key_reused`, `provider_unavailable`, `publishable_key_not_configured`).

503 A required deployment setting is missing (for example `publishable_key_not_configured`); nothing was created application/problem+json

PropertyTypeRequiredDescription
typestringformat: urirequired
titlestringrequired
statusintegerrequired
detailstringnullable
instancestringnullable
codestringStable machine-readable problem code, present on problems a client is expected to branch on (for example `org_payments_not_ready`, `driver_erased`, `token_already_linked`, `payment_method_not_active`, `idempotency_key_required`, `idempotency_key_reused`, `provider_unavailable`, `publishable_key_not_configured`).

Request example

curl -X POST "https://api.ampr.dev/v1/drivers/drv_example/payment-methods/setup-intent" \
  -H "Authorization: Bearer $AMPR_API_KEY"
Note
This endpoint requires an API key. Send it as a Bearer token in the Authorization header.

GET /drivers/{driver_id}/payment-methods List a driver's saved payment methods

Display metadata only (brand, last four digits, expiry month and year, funding, country). No card number, no provider secret.

Parameters

Name In Type Required Description
driver_id path string required
include_inactive query boolean Also return detached or expired methods.

Responses

200 Payment methods, newest first

PropertyTypeRequiredDescription
dataarray<DriverPaymentMethod>required
PropertyTypeRequiredDescription
idstringrequired
brandstringnullablerequired
last4stringnullablerequired
exp_monthintegernullablerequired
exp_yearintegernullablerequired
fundingstringnullablerequired
countrystringnullablerequired
is_defaultbooleanrequired
statusenum
  • active
  • detached
  • expired
required
created_atstringformat: date-timerequired
paginationPaginationrequired
PropertyTypeRequiredDescription
totalintegerrequired
pageintegerrequired
per_pageintegerrequired
has_morebooleanrequired

401 Missing or invalid API key application/problem+json

PropertyTypeRequiredDescription
typestringformat: urirequired
titlestringrequired
statusintegerrequired
detailstringnullable
instancestringnullable
codestringStable machine-readable problem code, present on problems a client is expected to branch on (for example `org_payments_not_ready`, `driver_erased`, `token_already_linked`, `payment_method_not_active`, `idempotency_key_required`, `idempotency_key_reused`, `provider_unavailable`, `publishable_key_not_configured`).

404 Resource not found application/problem+json

PropertyTypeRequiredDescription
typestringformat: urirequired
titlestringrequired
statusintegerrequired
detailstringnullable
instancestringnullable
codestringStable machine-readable problem code, present on problems a client is expected to branch on (for example `org_payments_not_ready`, `driver_erased`, `token_already_linked`, `payment_method_not_active`, `idempotency_key_required`, `idempotency_key_reused`, `provider_unavailable`, `publishable_key_not_configured`).

Request example

curl -X GET "https://api.ampr.dev/v1/drivers/drv_example/payment-methods" \
  -H "Authorization: Bearer $AMPR_API_KEY"
Note
This endpoint requires an API key. Send it as a Bearer token in the Authorization header.

PUT /drivers/{driver_id}/payment-methods/{payment_method_id}/default Make a saved payment method the driver's default

Exactly one active default exists per driver. Operator role or higher. A detached or expired method returns `409` (`payment_method_not_active`).

Parameters

Name In Type Required Description
driver_id path string required
payment_method_id path string required

Responses

200 The new default

PropertyTypeRequiredDescription
dataDriverPaymentMethodrequiredA saved card, as display metadata only. Never a card number, CVC, full expiry or provider secret.
PropertyTypeRequiredDescription
idstringrequired
brandstringnullablerequired
last4stringnullablerequired
exp_monthintegernullablerequired
exp_yearintegernullablerequired
fundingstringnullablerequired
countrystringnullablerequired
is_defaultbooleanrequired
statusenum
  • active
  • detached
  • expired
required
created_atstringformat: date-timerequired

401 Missing or invalid API key application/problem+json

PropertyTypeRequiredDescription
typestringformat: urirequired
titlestringrequired
statusintegerrequired
detailstringnullable
instancestringnullable
codestringStable machine-readable problem code, present on problems a client is expected to branch on (for example `org_payments_not_ready`, `driver_erased`, `token_already_linked`, `payment_method_not_active`, `idempotency_key_required`, `idempotency_key_reused`, `provider_unavailable`, `publishable_key_not_configured`).

403 Authenticated but not authorized for this action (insufficient role) application/problem+json

PropertyTypeRequiredDescription
typestringformat: urirequired
titlestringrequired
statusintegerrequired
detailstringnullable
instancestringnullable
codestringStable machine-readable problem code, present on problems a client is expected to branch on (for example `org_payments_not_ready`, `driver_erased`, `token_already_linked`, `payment_method_not_active`, `idempotency_key_required`, `idempotency_key_reused`, `provider_unavailable`, `publishable_key_not_configured`).

404 Resource not found application/problem+json

PropertyTypeRequiredDescription
typestringformat: urirequired
titlestringrequired
statusintegerrequired
detailstringnullable
instancestringnullable
codestringStable machine-readable problem code, present on problems a client is expected to branch on (for example `org_payments_not_ready`, `driver_erased`, `token_already_linked`, `payment_method_not_active`, `idempotency_key_required`, `idempotency_key_reused`, `provider_unavailable`, `publishable_key_not_configured`).

409 Resource conflict (e.g., duplicate serial, active session) application/problem+json

PropertyTypeRequiredDescription
typestringformat: urirequired
titlestringrequired
statusintegerrequired
detailstringnullable
instancestringnullable
codestringStable machine-readable problem code, present on problems a client is expected to branch on (for example `org_payments_not_ready`, `driver_erased`, `token_already_linked`, `payment_method_not_active`, `idempotency_key_required`, `idempotency_key_reused`, `provider_unavailable`, `publishable_key_not_configured`).

Request example

curl -X PUT "https://api.ampr.dev/v1/drivers/drv_example/payment-methods/dpm_example/default" \
  -H "Authorization: Bearer $AMPR_API_KEY"
Note
This endpoint requires an API key. Send it as a Bearer token in the Authorization header.

DELETE /drivers/{driver_id}/payment-methods/{payment_method_id} Detach a saved payment method

Detaches the card at the payment provider and marks it detached. If it was the default, the most recently added active method becomes the default. Operator role or higher. Idempotent (`204` when already detached). Emits `payment_method.detached`.

Parameters

Name In Type Required Description
driver_id path string required
payment_method_id path string required

Responses

204 Detached

401 Missing or invalid API key application/problem+json

PropertyTypeRequiredDescription
typestringformat: urirequired
titlestringrequired
statusintegerrequired
detailstringnullable
instancestringnullable
codestringStable machine-readable problem code, present on problems a client is expected to branch on (for example `org_payments_not_ready`, `driver_erased`, `token_already_linked`, `payment_method_not_active`, `idempotency_key_required`, `idempotency_key_reused`, `provider_unavailable`, `publishable_key_not_configured`).

403 Authenticated but not authorized for this action (insufficient role) application/problem+json

PropertyTypeRequiredDescription
typestringformat: urirequired
titlestringrequired
statusintegerrequired
detailstringnullable
instancestringnullable
codestringStable machine-readable problem code, present on problems a client is expected to branch on (for example `org_payments_not_ready`, `driver_erased`, `token_already_linked`, `payment_method_not_active`, `idempotency_key_required`, `idempotency_key_reused`, `provider_unavailable`, `publishable_key_not_configured`).

404 Resource not found application/problem+json

PropertyTypeRequiredDescription
typestringformat: urirequired
titlestringrequired
statusintegerrequired
detailstringnullable
instancestringnullable
codestringStable machine-readable problem code, present on problems a client is expected to branch on (for example `org_payments_not_ready`, `driver_erased`, `token_already_linked`, `payment_method_not_active`, `idempotency_key_required`, `idempotency_key_reused`, `provider_unavailable`, `publishable_key_not_configured`).

502 The payment provider did not complete the request (`provider_unavailable`); safe to retry with the same Idempotency-Key application/problem+json

PropertyTypeRequiredDescription
typestringformat: urirequired
titlestringrequired
statusintegerrequired
detailstringnullable
instancestringnullable
codestringStable machine-readable problem code, present on problems a client is expected to branch on (for example `org_payments_not_ready`, `driver_erased`, `token_already_linked`, `payment_method_not_active`, `idempotency_key_required`, `idempotency_key_reused`, `provider_unavailable`, `publishable_key_not_configured`).

Request example

curl -X DELETE "https://api.ampr.dev/v1/drivers/drv_example/payment-methods/dpm_example" \
  -H "Authorization: Bearer $AMPR_API_KEY"
Note
This endpoint requires an API key. Send it as a Bearer token in the Authorization header.