C2A API

Overview

The C2A API is the surface your backend calls when it acts on behalf of your customers - without going through the hosted portal. It covers the full customer lifecycle: identity sync, offer resolution, checkout, payment-method management, and the subscription cancel / reactivate flows.

If you are looking for the management and helpdesk portal API, see the B2A section.

Base URL & Versioning

Live:    https://{projectName}.azotte.com/api/v1/c2a/
Sandbox: https://{projectName}.sandbox.azotte.com/api/v1/c2a/

All C2A endpoints are versioned under /api/v1/. Routes documented here are relative to the C2A/ prefix.

Authentication

Every request must include:

Header	Required	Notes
x-api-key	yes	Tenant API key (Sandbox or Live; non-interchangeable).
x-tn	yes	Tenant identifier (project context).
Content-Type	when body present	application/json.

Auth is enforced by the JwtTenant scheme + PolicyApiKey policy. C2A responses use the content type application/clientOutput+Json.

See Getting Started for end-to-end credential setup.

Endpoint Map

Area	Route prefix	Purpose	Doc
Customers	/c2a/customer	Identity projection, GDPR delete, lookup.	C2A-01
Offers	/c2a/offer	Resolve purchase offers and showcase offers.	C2A-02
Checkout	/c2a/offer/checkout	Submit orders, poll status, 3DS.	C2A-03
Payment Methods	/c2a/customer/payment/methods	Tokenize / list / activate / delete stored cards.	C2A-04
Subscriptions	/c2a/subscription	List, cancel (two-phase), reactivate.	C2A-05

Typical Integration Flow

A first-purchase flow strings together four of these endpoints:

1. POST /c2a/customer/validate          - check ExternalId is free
2. POST /c2a/customer/store             - create Azotte projection -> customerUrn
3. POST /c2a/offer/bundles              - resolve purchase offer  -> offerIdentifier
4. POST /c2a/offer/checkout             - submit order            -> trackingNumber  (202)
5. GET  /c2a/offer/checkout/{id}/status - poll until terminal     - handle 3DS if present
6. GET  /c2a/subscription/{customerUrn} - confirm subscription is Active

A cancellation flow:

1. GET  /c2a/subscription/{customerUrn} - find orderIdentifier of subscription
2. POST /c2a/subscription/cancel/request  - get cancellation reasons / retention offer
3. (optional) accept retention offer:
       POST /c2a/offer/checkout            - apply offer
   or proceed to cancel:
       POST /c2a/subscription/cancel/confirm

Cross-cutting Rules

• Tenant isolation - every URN (customer, payment method, order, bundle, storefront) is scoped to x-tn. A URN from one tenant is not resolvable in another and will return *_NOT_FOUND.
• Amounts - all monetary values are in milpieces (1/1000 minor-unit). Display amounts are milpieces / 100. Never convert mid-calculation.
• Idempotency - checkout and payment-method operations are idempotent on caller-supplied keys (correlationId, paymentMethodUrn).
• Webhook-first - payment capture is finalized only after the PSP webhook is received. The status endpoint is the source of truth for terminal state.
• Async checkout - submitting a checkout returns 202 with a trackingNumber. Always poll status; never assume capture from the submit response.

Response Envelope

Most C2A responses use a GeneralResponse<T> shape:

{
  "result": { /* T payload, e.g. AzotteCustomer */ },
  "status": {
    "messageCode": "SUCCESS",
    "message": "..."     // optional
  }
}

Some endpoints (Offer, Checkout) inline domain-specific fields next to status rather than under result - the per-endpoint pages document the exact shape.

Postman

A ready-to-import collection lives in the backend repo:

Azotte.Api/documents/PostmanSamples/C2A API.postman_collection.json

Import it into Postman, set the host, x-tn, and x-api-key collection variables, and you have a working playground against Sandbox.

Source Map

Area	Controller
Customers	Azotte.Api.Gateway.Controllers.C2A.C2A_01_CustomersController
Offers	Azotte.Api.Gateway.Controllers.C2A.C2A_02_OfferController
Checkout	Azotte.Api.Gateway.Controllers.C2A.C2A_03_CheckoutController
Payment Methods	Azotte.Api.Gateway.Controllers.C2A.C2A_04_PaymentMethodsController
Subscriptions	Azotte.Api.Gateway.Controllers.C2A.C2A_05_SubscriptionController

All five share a common base: C2A_00_BaseController ([ApiController], [Produces(application/clientOutput+Json)]).