{"openapi":"3.0.3","info":{"title":"Astrada API","version":"2024-02-28","contact":{"email":"developer@astrada.co"},"description":"Welcome to our API Reference. 👋\n"},"servers":[{"url":"https://api.sandbox.astrada.co","description":"Sandbox"}],"tags":[{"name":"subaccounts","description":"Subaccount resource"},{"name":"webhooks","description":"Manage webhooks"},{"name":"card-subscription","description":"Card Subscription resource"},{"name":"card-verification","description":"Card Verification"},{"name":"card","description":"Card resource"},{"name":"transactions","description":"Transaction resource"},{"name":"transaction-messages","description":"Transaction messages resource"},{"name":"network-bulk-feeds","description":"Network bulk feed resource"},{"name":"network-bulk-enrollments","description":"Network bulk enrollment resource. A kickoff request to enroll a whole card program, fulfilled later by a network bulk feed. A confirmation request asks Astrada to check that a card program can join a bulk feed; it is never a kickoff."},{"name":"enrollment-methods","description":"Enrollment methods resource"},{"name":"enrollment-links","description":"Enrollment links. A link opens an Astrada-hosted page where the people you send it to enroll their own cards into one subaccount."},{"name":"bin-lookup","description":"BIN Lookup"}],"externalDocs":{"description":"Find out more about Astrada API.","url":"https://docs.astrada.co/reference"},"paths":{"/card-connector/tns/card-connector-data-links":{"parameters":[{"$ref":"#/components/parameters/account"}]},"/card-connector/vop/card-connector-data-links":{"parameters":[{"$ref":"#/components/parameters/account"}]},"/card-connector/tns/card-connector-data-links/{subscriptionId}/state-change":{"parameters":[{"$ref":"#/components/parameters/subscription-id"},{"$ref":"#/components/parameters/account"}]},"/card-connector/vop/card-connector-data-links/{subscriptionId}/state-change":{"parameters":[{"$ref":"#/components/parameters/subscription-id"},{"$ref":"#/components/parameters/account"}]},"/card-connector/smartdata/network-links":{"parameters":[{"$ref":"#/components/parameters/account"}]},"/card-connector/smartdata/network-links/{networkLinkId}":{"parameters":[{"$ref":"#/components/parameters/network-link-id"}]},"/card-connector/vbds/network-links":{"parameters":[{"$ref":"#/components/parameters/account"}]},"/card-connector/vbds/network-links/{networkLinkId}":{"parameters":[{"$ref":"#/components/parameters/network-link-id"}]},"/card-connector/amex-gl/network-links":{"parameters":[{"$ref":"#/components/parameters/account"}]},"/card-connector/amex-gl/network-links/{networkLinkId}":{"parameters":[{"$ref":"#/components/parameters/network-link-id"}]},"/card-connector/vcf/network-links":{"parameters":[{"$ref":"#/components/parameters/account"}]},"/card-connector/vcf/network-links/{networkLinkId}":{"parameters":[{"$ref":"#/components/parameters/network-link-id"}]},"/card-subscriptions":{"get":{"parameters":[{"$ref":"#/components/parameters/subaccount-id"},{"$ref":"#/components/parameters/card-id"},{"$ref":"#/components/parameters/bank-account-id"},{"$ref":"#/components/parameters/card-subscription-state"},{"$ref":"#/components/parameters/network-bulk-feed-id"},{"$ref":"#/components/parameters/company-id"},{"$ref":"#/components/parameters/legal-entity-id"},{"$ref":"#/components/parameters/legal-entity-name"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/offset"},{"$ref":"#/components/parameters/expand-card-subscription"}],"tags":["card-subscription"],"summary":"List card subscriptions","description":"Returns all card subscriptions under the account, ordered by `createdAt` descending (most recently created first).\n\nThe `subaccountId`, `cardId`, `bankAccountId`, `state`, `networkBulkFeedId`, `companyId`, `legalEntityId` and `legalEntityName` filters are independent and combine additively — supplying more than one narrows the result set to subscriptions matching **all** of them.\n\n`companyId`, `legalEntityId` and `legalEntityName` filter on the card's cardholder as it is now: `corporate.id`, `corporate.legalEntity.id` and `corporate.legalEntity.name` (see the [Glossary](https://docs.astrada.co/docs/glossary)). Each is an exact match; `legalEntityName` is case-sensitive, and each of `legalEntityId` and `legalEntityName` never matches a cardholder whose legal entity lacks that field, so copy it from the cardholder (`expand=cardholder` shows each cardholder's company and legal entity in the same response). For example, this returns the active subscriptions of one legal entity on one feed:\n\n`GET /card-subscriptions?networkBulkFeedId=<feed>&legalEntityId=<id>&state=active`\n\nThese three filters read cardholder data, so they need the `cardholder:read` scope, like `expand=cardholder`. Without it the request returns `403`.\n\nFiltering by `state` accepts any of the states a card subscription reports in its response payload:\n\n- `pending` — enrolled from a network roster while the card is still inactive at the network. The subscription is fully enrolled and billable, but has not yet transacted.\n- `active` — also returns subscriptions still completing activation, which already report their own `state` as `active`.\n- `deactivated`, `expired`, `reqSCA`, `failed-to-create` — matched exactly.\n\nThis endpoint supports [offset-based pagination](https://docs.astrada.co/reference/pagination). Pagination links preserve any filters applied to the original request.\n\nUse `expand` to embed each subscription's card and cardholder in the same response (`?expand=card,cardholder`) instead of calling `GET /cards/{cardId}` and `GET /cards/{cardId}/cardholder` per item. Each embedded resource appears under the item's `_embedded` with the exact body its own endpoint serves, and requires that endpoint's scope (`cards:read` for `card`, `cardholder:read` for `cardholder`). Pagination links preserve `expand` like any other parameter.\n","security":[{"main-auth":["card-subscriptions:read"]}],"operationId":"ListCardSubscriptions","responses":{"200":{"description":"Successful operation","content":{"application/hal+json":{"schema":{"type":"object","required":["_links","_embedded","totalItems"],"properties":{"_links":{"type":"object","required":["self"],"properties":{"self":{"$ref":"#/components/schemas/link"},"first":{"$ref":"#/components/schemas/link"},"next":{"$ref":"#/components/schemas/link"},"prev":{"$ref":"#/components/schemas/link"},"last":{"$ref":"#/components/schemas/link"}}},"_embedded":{"type":"object","required":["cardSubscriptions"],"properties":{"cardSubscriptions":{"type":"array","items":{"$ref":"#/components/schemas/card-subscription"}}}},"totalItems":{"type":"integer","description":"Total number of card subscriptions matching the search criteria"}}},"examples":{"Example List Card Subscriptions Response":{"value":{"_links":{"self":{"href":"/card-subscriptions"}},"_embedded":{"cardSubscriptions":[{"_links":{"self":{"href":"/card-subscriptions/75ea3c99-6bf5-4b16-8f68-0cdc43d75806"},"card":{"href":"/cards/5dec2c49-0aa5-4683-a317-427eb5d115f3"},"networkBulkFeed":{"href":"/network-bulk-feeds/7b3e4f12-9a8c-4d5e-b6f1-2c3d4e5f6a7b"}},"id":"75ea3c99-6bf5-4b16-8f68-0cdc43d75806","subaccountId":"f297d659-c13d-4219-aeaa-e10a845140a5","cardId":"5dec2c49-0aa5-4683-a317-427eb5d115f3","customerReferenceId":"5dec2c49-0aa5-4683-a317-427eb5d115f3","networkBulkFeedId":"7b3e4f12-9a8c-4d5e-b6f1-2c3d4e5f6a7b","enrollmentType":"network-bulk","state":"active","effectiveDate":"2024-12-20T14:45:00Z","expirationDate":"2025-06-19T14:45:00Z","createdAt":"2024-12-19T14:45:00Z","updatedAt":"2024-12-19T14:45:00Z"},{"_links":{"self":{"href":"/card-subscriptions/c73f2da7-aa1f-4775-ad38-864b1b6f3162"},"card":{"href":"/cards/0457c83a-8eb7-4526-b05a-dc9fb1854fe8"}},"id":"c73f2da7-aa1f-4775-ad38-864b1b6f3162","subaccountId":"29cb4277-b812-4137-b008-e0befa8c6a47","cardId":"0457c83a-8eb7-4526-b05a-dc9fb1854fe8","customerReferenceId":"0457c83a-8eb7-4526-b05a-dc9fb1854fe8","networkBulkFeedId":"d4e5f6a7-b8c9-4d0e-a1b2-c3d4e5f6a7b8","enrollmentType":"cardholder-single","state":"active","effectiveDate":"2024-10-20T14:45:00Z","expirationDate":"2025-05-19T14:45:00Z","createdAt":"2024-10-19T14:45:00Z","updatedAt":"2024-10-19T14:45:00Z"},{"_links":{"self":{"href":"/card-subscriptions/5f8e6832-97d3-4ab5-8144-9fbbbcd2b285"},"card":{"href":"/cards/24595efb-4fe5-4c76-a7d3-8bd9d44a96cc"},"networkBulkFeed":{"href":"/network-bulk-feeds/0a20c636-b445-4a95-a3ea-621306ed685c"}},"id":"5f8e6832-97d3-4ab5-8144-9fbbbcd2b285","subaccountId":"29cb4277-b812-4137-b008-e0befa8c6a47","cardId":"24595efb-4fe5-4c76-a7d3-8bd9d44a96cc","customerReferenceId":"0457c83a-8eb7-4526-b05a-dc9fb1854fe8","networkBulkFeedId":"0a20c636-b445-4a95-a3ea-621306ed685c","enrollmentType":"network-bulk","state":"active","effectiveDate":"2025-03-20T14:45:00Z","expirationDate":"2029-05-19T14:45:00Z","createdAt":"2025-03-19T14:45:00Z","updatedAt":"2025-03-19T14:45:00Z"},{"_links":{"self":{"href":"/card-subscriptions/9c1d0b47-3e5a-4f28-9d6b-71a4c8e2f503"},"card":{"href":"/cards/e8b45f19-2c76-4a83-b5d1-9f0e3a7c64d2"},"networkBulkFeed":{"href":"/network-bulk-feeds/0a20c636-b445-4a95-a3ea-621306ed685c"}},"id":"9c1d0b47-3e5a-4f28-9d6b-71a4c8e2f503","subaccountId":"29cb4277-b812-4137-b008-e0befa8c6a47","cardId":"e8b45f19-2c76-4a83-b5d1-9f0e3a7c64d2","customerReferenceId":"e8b45f19-2c76-4a83-b5d1-9f0e3a7c64d2","networkBulkFeedId":"0a20c636-b445-4a95-a3ea-621306ed685c","enrollmentType":"network-bulk","state":"pending","effectiveDate":"2025-04-02T09:15:00Z","expirationDate":"2029-05-19T14:45:00Z","createdAt":"2025-04-01T09:15:00Z","updatedAt":"2025-04-01T09:15:00Z"}]},"totalItems":4}},"Example List Card Subscriptions Response with expand=card,cardholder":{"value":{"_links":{"self":{"href":"/card-subscriptions?subaccountId=f297d659-c13d-4219-aeaa-e10a845140a5&expand=card,cardholder"}},"_embedded":{"cardSubscriptions":[{"_links":{"self":{"href":"/card-subscriptions/75ea3c99-6bf5-4b16-8f68-0cdc43d75806"},"card":{"href":"/cards/5dec2c49-0aa5-4683-a317-427eb5d115f3"},"verifications":{"href":"/card-verifications/3ds?cardId=5dec2c49-0aa5-4683-a317-427eb5d115f3"},"networkBulkFeed":{"href":"/network-bulk-feeds/7b3e4f12-9a8c-4d5e-b6f1-2c3d4e5f6a7b"}},"_embedded":{"card":{"_links":{"self":{"href":"/cards/5dec2c49-0aa5-4683-a317-427eb5d115f3"},"cardholder":{"href":"/cards/5dec2c49-0aa5-4683-a317-427eb5d115f3/cardholder"}},"id":"5dec2c49-0aa5-4683-a317-427eb5d115f3","expiryMonth":11,"expiryYear":2028,"network":"mastercard","country":"USA","createdAt":"2024-12-19T14:45:00Z","updatedAt":"2024-12-19T14:45:00Z","first6digits":"434343","last4digits":"4343","subaccountId":"f297d659-c13d-4219-aeaa-e10a845140a5"},"cardholder":{"_links":{"self":{"href":"/cards/5dec2c49-0aa5-4683-a317-427eb5d115f3/cardholder"}},"firstName":"John","lastName":"Doe","email":"john.doe@example.com","postalCode":"94105","corporate":{"alternativeEmployeeId":"ALT-EMP-12345","employeeId":"bb1afe4eb840","id":"ABC123456789"},"createdAt":"2024-12-19T14:45:00Z","updatedAt":"2024-12-19T14:45:00Z"}},"id":"75ea3c99-6bf5-4b16-8f68-0cdc43d75806","subaccountId":"f297d659-c13d-4219-aeaa-e10a845140a5","cardId":"5dec2c49-0aa5-4683-a317-427eb5d115f3","customerReferenceId":"5dec2c49-0aa5-4683-a317-427eb5d115f3","networkBulkFeedId":"7b3e4f12-9a8c-4d5e-b6f1-2c3d4e5f6a7b","enrollmentType":"network-bulk","state":"active","effectiveDate":"2024-12-20T14:45:00Z","expirationDate":"2025-06-19T14:45:00Z","createdAt":"2024-12-19T14:45:00Z","updatedAt":"2024-12-19T14:45:00Z"}]},"totalItems":1}},"No Card subscriptions found":{"value":{"_links":{"self":{"href":"/card-subscriptions"}},"_embedded":{"cardSubscriptions":[]},"totalItems":0}}}}}},"400":{"$ref":"#/components/responses/bad-request"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"500":{"$ref":"#/components/responses/server-error"}}}},"/card-subscriptions/{subscriptionId}":{"parameters":[{"$ref":"#/components/parameters/subscription-id"}],"get":{"parameters":[{"$ref":"#/components/parameters/expand-card-subscription"}],"tags":["card-subscription"],"summary":"Retrieve card subscription","description":"Returns detailed information about a specific card subscription by its identifier, including its data-sharing state.\n\nAdd `expand=card,cardholder` to embed the card and cardholder under `_embedded` in the same response instead of fetching them separately. Each embedded resource is the exact body its own endpoint serves and requires that endpoint's scope (`cards:read` for `card`, `cardholder:read` for `cardholder`).\n","security":[{"main-auth":["card-subscriptions:read"]}],"operationId":"GetCardSubscription","responses":{"200":{"description":"Successful operation","content":{"application/hal+json":{"schema":{"$ref":"#/components/schemas/card-subscription"},"examples":{"Example Get Card Subscription Response":{"$ref":"#/components/examples/card-subscription"},"Example Get Card Subscription Response with Network Bulk Feed":{"$ref":"#/components/examples/card-subscription-with-network-bulk-feed-reference"},"Example Get Card Subscription Response with Bank Feed":{"$ref":"#/components/examples/card-subscription-with-bank-feed"},"Example Get Card Subscription Response with expand=card,cardholder":{"$ref":"#/components/examples/card-subscription-expanded"}}}}},"400":{"$ref":"#/components/responses/bad-request"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/not-found"},"500":{"$ref":"#/components/responses/server-error"}}},"patch":{"tags":["card-subscription"],"summary":"Update card subscription","description":"Updates an existing card subscription, allowing changes to its data-sharing state. Subscriptions that were enrolled in bulk, and where `enrollmentType = 'network-bulk'` cannot be updated.\n\n**Note:** setting a card subscription to a `deactivated` state is a final action that cannot be undone.\n\nWhen deactivating, you can send an optional `deactivationReason` to record why the card was deactivated.\n","security":[{"main-auth":["card-subscriptions:write"]}],"operationId":"UpdateCardSubscription","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"state":{"type":"string","enum":["deactivated"]},"deactivationReason":{"allOf":[{"$ref":"#/components/schemas/card-subscription-deactivation-reason"}],"description":"Optional reason for the deactivation. Only accepted together with `state: deactivated`;\nsending it on its own returns `400`. Returned in the `deactivationReason` field of the card subscription.\n"}}},"examples":{"Deactivate with a reason":{"value":{"state":"deactivated","deactivationReason":"cardholder_offboarded"}},"Deactivate without a reason":{"value":{"state":"deactivated"}}}}}},"responses":{"200":{"description":"Successful operation","content":{"application/hal+json":{"schema":{"$ref":"#/components/schemas/card-subscription"},"examples":{"Example Deactivate Card Subscription Response":{"$ref":"#/components/examples/card-subscription-deactivated"}}}}},"400":{"$ref":"#/components/responses/bad-request"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/not-found"},"409":{"description":"Request conflict with the current state of the target resource","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/conflict"},{"example":{"title":"Conflict","detail":"The resource state does not allow this operation","currentValue":"expired","requestedValue":"deactivated"}}]}}}},"422":{"description":"The request is well formatted but it fails some business logic validation","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/unprocessable-entity"},{"example":{"title":"Unprocessable Entity","detail":"The state of a bulk enrolled subscription cannot be changed"}}]}}}},"500":{"$ref":"#/components/responses/server-error"}}}},"/card-subscriptions/search-by-fingerprint":{"parameters":[{"$ref":"#/components/parameters/card-subscription-state"},{"in":"query","name":"fingerprint","required":true,"schema":{"type":"string","format":"uuid"}},{"in":"query","name":"subaccountId","required":true,"schema":{"type":"string","format":"uuid"}},{"in":"query","name":"cardExpiryMonth","required":false,"schema":{"type":"integer","minimum":1,"maximum":12}},{"in":"query","name":"cardExpiryYear","required":false,"schema":{"type":"integer"}}]},"/card-subscriptions/actions/activate-card-connector-data-link":{"parameters":[{"$ref":"#/components/parameters/account"},{"$ref":"#/components/parameters/connector-name"}]},"/card-subscriptions/actions/deactivate-card-connector-data-link":{"parameters":[{"$ref":"#/components/parameters/account"},{"$ref":"#/components/parameters/connector-name"}]},"/card-verifications/3ds":{"get":{"tags":["card-verification"],"summary":"List a card's 3DS verifications","description":"List the 3DS verifications for a card, most recent first. Use the optional `state`\nfilter (e.g. `state=failed`) to retrieve only failed verifications — each failed\nverification carries a `failureReason` explaining why it failed. This includes\ncards declined synchronously at creation (the `POST` returned `400`): those\nattempts are persisted as failed verifications with `currentStepId: null`.\n","security":[{"main-auth":["card-verifications:read"]}],"operationId":"CardVerificationList","parameters":[{"$ref":"#/components/parameters/card-id.required"},{"in":"query","name":"state","required":false,"description":"Optional filter to retrieve only verifications in the given state.","schema":{"type":"string","enum":["completed","failed","in-progress"]}}],"responses":{"200":{"description":"Successful operation","content":{"application/hal+json":{"schema":{"type":"object","required":["_links","_embedded","totalItems"],"properties":{"_links":{"type":"object","required":["self"],"properties":{"self":{"$ref":"#/components/schemas/link"}}},"_embedded":{"type":"object","required":["cardVerifications"],"properties":{"cardVerifications":{"type":"array","items":{"$ref":"#/components/schemas/card-verification"}}}},"totalItems":{"type":"integer"}}},"examples":{"Example list filtered by state=failed":{"value":{"_links":{"self":{"href":"/card-verifications/3ds?cardId=8309b5f8-d5d8-49bb-9001-38bf1bb0f1e4&state=failed"}},"_embedded":{"cardVerifications":[{"_links":{"self":{"href":"/card-verifications/3ds/9fab1bea-bc1e-4757-bd47-479422e5983b"},"steps":{"href":"/card-verifications/3ds/9fab1bea-bc1e-4757-bd47-479422e5983b/steps"}},"id":"9fab1bea-bc1e-4757-bd47-479422e5983b","subaccountId":"f297d659-c13d-4219-aeaa-e10a845140a5","cardId":"8309b5f8-d5d8-49bb-9001-38bf1bb0f1e4","type":"3DS","state":"failed","authenticationFlow":"frictionless","failureReason":{"category":"authentication_declined","description":"The card issuer declined the 3-D Secure authentication.","retryable":true,"code":"05","providerMessage":"The card issuer declined this authentication attempt."},"createdAt":"2024-01-04T18:53:32.000Z","updatedAt":"2024-01-04T18:55:12.000Z"}]},"totalItems":1}}}}}},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"500":{"$ref":"#/components/responses/server-error"}}}},"/card-verifications/3ds/{verificationId}":{"parameters":[{"$ref":"#/components/parameters/verification-id"}],"get":{"tags":["card-verification"],"summary":"Retrieve 3DS verification","description":"Returns the current status and detailed information of a specific 3DS verification by its identifier.","security":[{"main-auth":["card-verifications:read"]}],"operationId":"GetCardVerification","responses":{"200":{"description":"Successful operation","content":{"application/hal+json":{"schema":{"$ref":"#/components/schemas/card-verification"},"examples":{"Example Get Card Verification Response":{"$ref":"#/components/examples/card-verification"},"Example Failed Verification with failureReason":{"$ref":"#/components/examples/card-verification-failed"}}}}},"400":{"$ref":"#/components/responses/bad-request"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/not-found"},"500":{"$ref":"#/components/responses/server-error"}}}},"/card-verifications/3ds/{verificationId}/steps":{"parameters":[{"$ref":"#/components/parameters/verification-id"}]},"/card-verifications/3ds/{verificationId}/steps/fingerprint":{"parameters":[{"$ref":"#/components/parameters/verification-id"}]},"/card-verifications/3ds/{verificationId}/steps/challenge":{"parameters":[{"$ref":"#/components/parameters/verification-id"}]},"/card-verifications/3ds/{verificationId}/steps/stripe-callback":{"parameters":[{"$ref":"#/components/parameters/verification-id"}]},"/card-verifications/3ds/{verificationId}/steps/place-holds":{"parameters":[{"$ref":"#/components/parameters/verification-id"}]},"/card-verifications/3ds/{verificationId}/steps/amount-confirm":{"parameters":[{"$ref":"#/components/parameters/verification-id"}]},"/card-verifications/3ds/{verificationId}/steps/restart":{"parameters":[{"$ref":"#/components/parameters/verification-id"}]},"/card-verifications/unlock":{"post":{"tags":["card-verification"],"summary":"Unlock a card's verification attempt lockout","description":"Clear the cross-network verification **attempt lockout** for a card,\nidentified by its `cardId`. This re-enables verification attempts for the\ncard after it has been throttled by too many recent hard failures — the\naccount-scoped, cross-network throttle that protects the non-HIGHEST tiers\n(Visa/Stripe, Mastercard/TNS). Idempotent: unlocking a card that has no\nactive lock succeeds and clears nothing. The HIGHEST per-fingerprint lockout\nis **not** affected by this endpoint.\n","security":[{"main-auth":["subaccounts:write"]}],"operationId":"CardVerificationAttemptLockoutUnlock","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["cardId"],"properties":{"cardId":{"description":"Identifier of the card whose attempt lockout to clear.","type":"string","format":"uuid"}}},"examples":{"UnlockAttemptLockoutRequestExample":{"value":{"cardId":"00cdba2d-01f0-46bb-b34a-c76d9699e991"}}}}}},"responses":{"200":{"description":"The card's attempt lockout was cleared, or the card had no active lock\n(idempotent).\n","content":{"application/hal+json":{"schema":{"type":"object","required":["unlocked","cleared"],"properties":{"unlocked":{"description":"Always `true` on success.","type":"boolean","enum":[true]},"cleared":{"description":"Whether an active lock actually existed and was cleared. `false`\nwhen the card had no active lock (the idempotent no-op case).\n","type":"boolean"}}},"examples":{"UnlockAttemptLockoutResponseExample":{"value":{"unlocked":true,"cleared":true}}}}}},"400":{"$ref":"#/components/responses/bad-request"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"500":{"$ref":"#/components/responses/server-error"}}}},"/cards":{"parameters":[{"$ref":"#/components/parameters/country"},{"$ref":"#/components/parameters/expiry-month"},{"$ref":"#/components/parameters/expiry-year"},{"$ref":"#/components/parameters/subaccount-id"},{"$ref":"#/components/parameters/network-bulk-feed-id"},{"$ref":"#/components/parameters/expand-card"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/offset"}],"get":{"tags":["card"],"summary":"List cards","description":"Returns a list of all cards linked to the account.\n\nBy default, `GET /cards` returns cards ordered by the latest updatedAt. You can combine the different filters as documented.\n\nUse `networkBulkFeedId` to filter the list to cards enrolled through a given network bulk feed. An unknown feed id returns an empty page. It combines with `expand=cardholder`.\n\nUse `expand=cardholder` to embed each card's cardholder under `_embedded` in the same response instead of calling `GET /cards/{cardId}/cardholder` per item. The embedded body is the exact body that endpoint serves and requires its `cardholder:read` scope. Pagination links preserve `expand` like any other parameter.\n\nThis endpoint supports [offset-based pagination](https://docs.astrada.co/reference/pagination).\n","security":[{"main-auth":["cards:read"]}],"operationId":"ListCards","responses":{"200":{"description":"Successful operation","content":{"application/hal+json":{"schema":{"type":"object","required":["_links","_embedded","totalItems"],"properties":{"_links":{"type":"object","required":["self"],"properties":{"self":{"$ref":"#/components/schemas/link"},"first":{"$ref":"#/components/schemas/link"},"next":{"$ref":"#/components/schemas/link"},"prev":{"$ref":"#/components/schemas/link"},"last":{"$ref":"#/components/schemas/link"}}},"_embedded":{"type":"object","required":["cards"],"properties":{"cards":{"type":"array","items":{"$ref":"#/components/schemas/card"}}}},"totalItems":{"type":"integer","description":"Total number of cards matching the search criteria"}}},"examples":{"Example List Cards Response":{"value":{"_links":{"self":{"href":"/cards"}},"_embedded":{"cards":[{"_links":{"self":{"href":"/cards/8309b5f8-d5d8-49bb-9001-38bf1bb0f1e4"}},"id":"8309b5f8-d5d8-49bb-9001-38bf1bb0f1e4","expiryMonth":12,"expiryYear":2026,"network":"mastercard","country":"USA","createdAt":"2024-02-04T18:41:16.142Z","updatedAt":"2024-02-04T18:41:16.142Z","first6digits":"424242","last4digits":"4242","subaccountId":"da6649a8-f0ea-4af0-b342-c0b5c3e024dd"},{"_links":{"self":{"href":"/cards/f744b691-bf05-4f2a-ab89-bb1afe4eb840"},"cardholder":{"href":"/cards/f744b691-bf05-4f2a-ab89-bb1afe4eb840/cardholder"}},"id":"f744b691-bf05-4f2a-ab89-bb1afe4eb840","expiryMonth":11,"expiryYear":2028,"network":"mastercard","country":"USA","createdAt":"2024-02-04T18:41:16.142Z","updatedAt":"2024-02-04T18:41:16.142Z","first6digits":"434343","last4digits":"4343","subaccountId":"da6649a8-f0ea-4af0-b342-c0b5c3e024dd"}]},"totalItems":2}},"Example List Cards Response with expand=cardholder":{"value":{"_links":{"self":{"href":"/cards?expand=cardholder&networkBulkFeedId=2fd4d402-b759-479c-87a6-58d85e345356"}},"_embedded":{"cards":[{"_links":{"self":{"href":"/cards/31e63088-48b3-42dd-b6d4-fdd058675ec9"},"cardholder":{"href":"/cards/31e63088-48b3-42dd-b6d4-fdd058675ec9/cardholder"}},"_embedded":{"cardholder":{"_links":{"self":{"href":"/cards/31e63088-48b3-42dd-b6d4-fdd058675ec9/cardholder"}},"firstName":"John","lastName":"Doe","email":"john.doe@example.com","postalCode":"94105","corporate":{"alternativeEmployeeId":"ALT-EMP-12345","employeeId":"bb1afe4eb840","id":"ABC123456789"},"createdAt":"2024-02-04T18:41:16.142Z","updatedAt":"2024-02-04T18:41:16.142Z"}},"id":"31e63088-48b3-42dd-b6d4-fdd058675ec9","expiryMonth":11,"expiryYear":2028,"network":"mastercard","country":"USA","createdAt":"2024-02-04T18:41:16.142Z","updatedAt":"2024-02-04T18:41:16.142Z","first6digits":"434343","last4digits":"4343","subaccountId":"fd03abe1-5ac3-41ac-96cc-d2a66aafc74f"}]},"totalItems":1}},"Example no Cards found":{"value":{"_links":{"self":{"href":"/cards"}},"_embedded":{"cards":[]},"totalItems":0}}}}}},"400":{"$ref":"#/components/responses/bad-request"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"500":{"$ref":"#/components/responses/server-error"}}}},"/cards/{cardId}":{"parameters":[{"$ref":"#/components/parameters/card-id-2"}],"get":{"parameters":[{"$ref":"#/components/parameters/expand-card"}],"tags":["card"],"summary":"Retrieve card","description":"Returns detailed information about a specific card by its identifier.\n\nAdd `expand=cardholder` to embed the cardholder under `_embedded` in the same response instead\nof calling `GET /cards/{cardId}/cardholder` separately. The embedded body is the exact body that\nendpoint serves and requires its `cardholder:read` scope.\n","security":[{"main-auth":["cards:read"]}],"operationId":"GetCard","responses":{"200":{"description":"Successful operation","content":{"application/hal+json":{"schema":{"$ref":"#/components/schemas/card"},"examples":{"Example Get Card Response":{"$ref":"#/components/examples/card"},"Example Get Card Response with cardholder, available only when card has been bulk enrolled":{"$ref":"#/components/examples/card-with-cardholder"},"Example Get Card Response with expand=cardholder":{"$ref":"#/components/examples/card-expanded"}}}}},"400":{"$ref":"#/components/responses/bad-request"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/not-found"},"500":{"$ref":"#/components/responses/server-error"}}}},"/cards/{cardId}/cardholder":{"parameters":[{"$ref":"#/components/parameters/card-id-2"}],"get":{"tags":["card"],"summary":"Retrieve cardholder information","description":"Returns the card's current cardholder information, when it's available.\n\nFor the company and legal entity the card belonged to at the time of a given transaction, use\n`expand=cardholder` on that transaction instead: `GET /transactions/{transactionId}?expand=cardholder`.\n","security":[{"main-auth":["cardholder:read"]}],"operationId":"GetCardholder","responses":{"200":{"description":"Successful operation","content":{"application/hal+json":{"schema":{"$ref":"#/components/schemas/cardholder"},"examples":{"Example Get Cardholder Response":{"$ref":"#/components/examples/cardholder"}}}}},"400":{"$ref":"#/components/responses/bad-request"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/not-found"},"500":{"$ref":"#/components/responses/server-error"}}},"patch":{"tags":["card"],"summary":"Update cardholder information","description":"Updates cardholder information for a specific card. Use this endpoint to simulate cardholder data that would typically be received through a Network Bulk Feed. This is useful for testing your integration against bulk-enrolled cards without waiting for actual network feed data.\n\n**Note:** This endpoint requires the `cardholder:write` scope and must be directly enabled by Astrada.\n","security":[{"main-auth":["cardholder:write"]}],"operationId":"UpdateCardholder","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"minProperties":1,"required":["subaccountId"],"properties":{"subaccountId":{"description":"The unique identifier of the subaccount related to the card","type":"string","format":"uuid"},"firstName":{"description":"The first name of the cardholder","type":"string"},"lastName":{"description":"The last name of the cardholder","type":"string"},"email":{"description":"Cardholder email address","type":"string","format":"email"},"postalCode":{"description":"Cardholder postal code. Format varies by country; no validation or normalization is applied.","type":"string"},"corporate":{"description":"The corporate entity that this cardholder is associated with. `legalEntity` is set by the card network and cannot be changed here: it is ignored if sent, and the stored value is kept.","type":"object","properties":{"id":{"description":"The company ID to store on the cardholder, the same value a network bulk feed supplies. See `cardholder.corporate.id`.","type":"string"},"employeeId":{"description":"The unique identifier of the employee","type":"string"},"alternativeEmployeeId":{"description":"An alternative employee identifier, typically configured for specific enterprise integrations.","type":"string"}}}}}}}},"responses":{"200":{"description":"Successful operation","content":{"application/hal+json":{"schema":{"$ref":"#/components/schemas/cardholder"},"examples":{"Example Update Cardholder Response":{"$ref":"#/components/examples/cardholder"}}}}},"400":{"$ref":"#/components/responses/bad-request"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/not-found"},"500":{"$ref":"#/components/responses/server-error"}}}},"/enrollment-methods":{"post":{"tags":["enrollment-methods"],"summary":"List the available enrollment methods given a card BIN","description":"List the available enrollment methods given a card BIN.\n\nThe Unified Enrollment SDK v2 calls this endpoint for each card: when a person presses **Continue** on the card number screen, with the first 8 to 11 digits they typed (8 by default), and on an employee page that opens on the card form, once 8 digits are typed there. It sends the session's `subaccountId` with the digits, and asks again with the digits alone when that answers `400` or `403`. It routes the session from the answer together with `GET /bin-lookup`. The SDK token therefore needs `enrollment-methods:write`. If your own backend calls it, send up to 11 digits for the most precise answer.\n\nSend `subaccountId` to ask whether that subaccount can enroll this card one at a time with `POST /card-subscriptions`. The response then adds `singleDecision`, from the single-enrollment controls that create runs for the subaccount, and `singleEligible` and `availableEnrollmentMethods` follow it. Create also checks the `country` sent with the card; this request has no country, so `singleDecision` does not cover that check. Without `subaccountId`, the response is about the card alone and no subaccount is read.\n\nWhen live card data is temporarily unavailable, the response falls back to Astrada's stored card data instead of failing, and `binInfo` comes from that stored data. `bulkLikelihood` is then capped at `medium`, except for BINs with proven bulk history, which stay `proven`. When nothing decides the grade, `bulkLikelihood` is omitted and `unavailable` lists it; `singleEligible` is then `true` and `availableEnrollmentMethods` is `[\"cardholder-single\"]`, unless `singleDecision` refuses the card. Retry later for a full answer.","security":[{"main-auth":["enrollment-methods:write"]}],"operationId":"EnrollmentMethods","requestBody":{"description":"Enrollment methods payload","required":true,"content":{"application/json":{"schema":{"type":"object","required":["bin"],"properties":{"bin":{"description":"The card's Bank Identification Number (BIN), consisting of the first 6 to 11 digits of the card number. Providing more digits yields more precise results — for example, two cards that share the same 6-digit BIN may support different enrollment methods. We recommend providing as many digits as available, up to 11.","type":"string","pattern":"^\\d{6,11}$"},"subaccountId":{"description":"The subaccount the card would enroll under. With it, the response adds `singleDecision` when the subaccount's controls can be run. It must be one of your account's subaccounts, otherwise the request gets `400`. With an enrollment link session's token it must be the session's own subaccount, otherwise the request gets `403`.","type":"string","format":"uuid"}}},"examples":{"EnrollmentGuidanceRequestExample":{"value":{"bin":"42424242"}},"EnrollmentGuidanceRequestWithSubaccountExample":{"value":{"bin":"42424242","subaccountId":"3f2b8c1e-5d4a-4e6b-9a7c-2d1e0f9b8a76"}}}}}},"responses":{"200":{"description":"Successful operation","content":{"application/hal+json":{"schema":{"type":"object","required":["availableEnrollmentMethods"],"properties":{"availableEnrollmentMethods":{"description":"The enrollment methods this card can use: `network-bulk` when `bulkLikelihood` is present and not `none`, and `cardholder-single` when `singleEligible` is `true`. Empty when neither applies, for example for a card from a country Astrada doesn't cover for its network.","type":"array","items":{"type":"string","enum":["network-bulk","cardholder-single"]}},"bulkLikelihood":{"description":"Graded likelihood that network-bulk enrollment will succeed for this BIN. A country-coverage veto forces `none`. Omitted when it could not be determined for this request; `unavailable` then lists it. `none` is only returned when it was established, never because the data was unavailable.","type":"string","enum":["proven","high","medium","low","none"]},"singleEligible":{"description":"Whether cardholder-single enrollment is supported for this BIN. When the response has `singleDecision`, it equals `singleDecision.allowed`.","type":"boolean"},"singleDecision":{"description":"Whether the subaccount named in `subaccountId` can enroll this card one at a time. Present only when the request names a `subaccountId` and that subaccount's controls could be run for these digits. When they could not (for example, the subaccount could not be read, or, in sandbox, the digits match test cards of more than one card type), `singleDecision` is omitted and the rest of the response is the one given without `subaccountId`.","type":"object","required":["allowed"],"properties":{"allowed":{"type":"boolean","description":"`true` when every single-enrollment control passes for the subaccount and the card's own `singleEligible`, as answered without `subaccountId`, is `true`."},"reason":{"type":"string","description":"Why single enrollment is refused. Present only when `allowed` is `false`. A control's refusal is named before `coverage`. Each control's reason stands for the refusal that control gives on `POST /card-subscriptions`, shown in parentheses. `bank-enrollment-required`: the subaccount's `enrollmentPolicy.bankEnrollment` is `amex-visa` and this Visa card is not classified as business (`card_subscription.subaccount_blocking_card_type` with `reasonCode` `card_subscription.bank_enrollment_required`). `card-type`: the subaccount's single-enrollment `blockedCardTypes` holds the card's type (`card_subscription.subaccount_blocking_card_type`). `funding-type`: its `blockedFundingCardTypes` holds the card's funding type (`card_subscription.subaccount_blocking_card_funding_type`). `issuer-country`: `enforceIssuerCountry` is on and the card's issuing country is unknown or not one of the subaccount's single-enrollment countries (`card_subscription.subaccount_blocking_card_country`). `network-rule`: a rule in the subaccount's `networkBlockedCards` matches the card (`card_subscription.network_blocking_card`). `coverage`: every control passes, but the card's own `singleEligible` is `false`, for example for any American Express card.","enum":["bank-enrollment-required","card-type","funding-type","issuer-country","network-rule","coverage"]}}},"binInfo":{"description":"Best-effort card metadata for the looked-up BIN, resolved server-side. Present only when the issuer name is known and omitted otherwise; the other fields are best-effort and may each be omitted even when `binInfo` is present. Lets integrators read this data without the `cards:read` scope that `GET /bin-lookup` requires (it rides on this endpoint's `enrollment-methods:write` scope); the SDK surfaces it on the bulk-enrollment success payload.","type":"object","required":["issuerName"],"properties":{"issuerName":{"type":"string","description":"The issuing bank's name for this BIN."},"issuerCountry":{"type":"string","description":"The country of the issuing bank following ISO 3166-1 alpha-3, for example `USA`. Omitted when the reference data does not record it."},"type":{"type":"string","description":"The card type (e.g., COMMERCIAL, CORPORATE, CONSUMER, SMALL_BUSINESS). Omitted when the reference data does not classify the BIN.","enum":["COMMERCIAL","CORPORATE","CONSUMER","SMALL_BUSINESS"]},"fundingType":{"type":"string","description":"The card funding type (e.g., prepaid, debit, credit). Omitted when the reference data does not classify the BIN.","enum":["CREDIT","DEBIT","PREPAID"]},"cardCategory":{"type":"string","description":"The card's classification, with the values of `cardCategory` on `GET /bin-lookup`. More specific than `type`, and set for many BINs where `type` is omitted. `UNKNOWN` means the card data does not classify the BIN. Omitted when there is no value. For Mastercard it is present only when the response falls back to stored card data.","enum":["CONSUMER","BUSINESS","CORPORATE","FLEET","PURCHASING","GIFT","PREPAID","SPECIALTY","UNKNOWN"]}}},"unavailable":{"description":"Response fields whose value could not be determined for this request, for example when live card data was temporarily unavailable and the stored card data doesn't decide the grade. Today it can only contain `bulkLikelihood`; more values may be added, so ignore any you don't recognize. Omitted when every field was determined.","type":"array","items":{"type":"string","enum":["bulkLikelihood"]}}}},"examples":{"Success example with card supported by single card enrollment flow":{"value":{"availableEnrollmentMethods":["cardholder-single"],"bulkLikelihood":"none","singleEligible":true}},"Success example with card supported by single card enrollment and network bulk enrollment flows":{"value":{"availableEnrollmentMethods":["network-bulk","cardholder-single"],"bulkLikelihood":"high","singleEligible":true,"binInfo":{"issuerName":"Stripe Payments Uk","issuerCountry":"GBR","type":"COMMERCIAL","fundingType":"CREDIT"}}},"Success example when the bulk likelihood could not be determined":{"value":{"availableEnrollmentMethods":["cardholder-single"],"singleEligible":true,"unavailable":["bulkLikelihood"]}},"Success example with a subaccountId whose controls allow the card":{"value":{"availableEnrollmentMethods":["cardholder-single"],"bulkLikelihood":"none","singleEligible":true,"singleDecision":{"allowed":true}}},"Success example with a subaccountId under amex-visa and a consumer Visa card":{"value":{"availableEnrollmentMethods":[],"bulkLikelihood":"none","singleEligible":false,"binInfo":{"issuerName":"Example Bank","issuerCountry":"USA","type":"CONSUMER","fundingType":"CREDIT","cardCategory":"CONSUMER"},"singleDecision":{"allowed":false,"reason":"bank-enrollment-required"}}}}}}},"400":{"description":"The request failed validation, for example a `bin` that is not 6 to 11 digits or a `subaccountId` that is not a UUID. A `subaccountId` that is not one of your account's subaccounts also gets `400`, with the detail `Given subaccount is not valid`.","content":{"application/problem+json":{"schema":{"type":"object","properties":{"detail":{"type":"string"},"title":{"type":"string","enum":["Bad Request"]},"errors":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"detail":{"type":"string"}},"required":["title","detail"]}}},"required":["detail","title"]},"examples":{"Example Generic Bad Request Payload Response":{"value":{"title":"Bad Request","detail":"Request object failed validation."}},"Subaccount Not Valid":{"value":{"title":"Bad Request","detail":"Given subaccount is not valid"}}}}}},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"413":{"$ref":"#/components/responses/content-too-large"},"500":{"$ref":"#/components/responses/server-error"}}}},"/enrollment-links":{"post":{"tags":["enrollment-links"],"summary":"Create enrollment link","description":"Creates an enrollment link for one of your subaccounts. The link opens a page on\nAstrada's SDK host where the person who has it enrolls their own cards into that\nsubaccount.\n\n- A personal link (`kind: cardholder`) is for one employee. It allows up to 5 session\n  starts and is used up by the first session that completes something.\n- A team link (`kind: team`) is for sharing. Each session start counts as a use, up to\n  `maxUses`.\n\nThe response's `url` carries the link's secret after `#`. This response is the only\none that returns it, and it is sent with `Cache-Control: no-store`. Astrada stores only\na hash of the secret. In sandbox the `url` starts with\n`https://sdk.sandbox.astrada.co/unified/v2/enroll.html#`.\n\nRequires `subaccounts:write`.\n\nRefusals carry a `code`:\n\n- `404` `SUBACCOUNT_NOT_FOUND`: `subaccountId` is not one of your subaccounts.\n- `409` `ENROLLMENT_LINKS_NOT_ENABLED`: enrollment links are not enabled for your\n  account.\n- `409` `CARD_ENROLLMENT_OFF`: card enrollment is off for the subaccount (its\n  `enrollmentPolicy.cardEnrollment` is `false`). The hosted page offers card enrollment\n  only, so a link would have nothing to enroll. This check runs before the daily limit\n  is counted, so a refused request does not use it up.\n- `400` `LINK_NAME_NOT_ALLOWED`: `organizationName` or `platformName` is a\n  well-known brand name, such as a card network or a large bank, matched ignoring case,\n  accents and punctuation. Astrada and Plaid are also refused inside a longer name.\n- `429` `RATE_LIMITED`: your account has created 2,000 links today (UTC), team links\n  made with `POST /subaccounts/{subaccountId}/team-link` included.\n\nA link made before card enrollment was turned off starts no session while card\nenrollment stays off: `POST /enrollment-link-sessions/preview` and\n`POST /enrollment-link-sessions` answer `409` `CARD_ENROLLMENT_OFF`, and no start is\ncounted.\n","operationId":"CreateEnrollmentLink","security":[{"main-auth":["subaccounts:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["subaccountId","kind"],"properties":{"subaccountId":{"type":"string","format":"uuid","description":"The subaccount that cards enrolled through the link join. It must be one of your subaccounts."},"kind":{"type":"string","enum":["cardholder","team"],"description":"`cardholder` for a personal link, `team` for a team link."},"customerReferenceId":{"type":"string","format":"uuid","description":"Your reference for the link, such as the employee a personal link is for. It\nmust be a UUID, as `customerReferenceId` on `POST /card-subscriptions` is;\nany other value answers `400`. A session from the link can create card\nsubscriptions only with this reference.\n"},"platformName":{"type":"string","minLength":1,"maxLength":60,"description":"The platform's name, shown on the hosted page. Letters, digits, spaces and\n`. , & ' ’ ( ) - _ + ! # @` only, with at least one letter or digit;\nsurrounding spaces are trimmed. Default: your account's name. A name\nthat is a well-known brand, such as a card network or a large bank, answers\n`400` `LINK_NAME_NOT_ALLOWED`. Once Astrada has set a brand profile for your\naccount, the hosted pages show its name and ignore this one.\n"},"organizationName":{"type":"string","minLength":1,"maxLength":80,"description":"The employer's name, shown on the hosted page. The same characters as\n`platformName`, and the same `LINK_NAME_NOT_ALLOWED` refusal. Default: none;\nthe hosted page then names only the platform.\n"},"startingPoint":{"type":"string","enum":["card"],"default":"card","description":"Where the hosted page starts. Only `card` is available now; any other value\nanswers `400`.\n"},"expiresInHours":{"type":"integer","minimum":1,"maximum":720,"description":"How long the link can start sessions. Default: 168 (7 days) for a personal\nlink, 336 (14 days) for a team link.\n"},"maxUses":{"type":"integer","minimum":1,"maximum":500,"description":"Team links only: the session starts the link allows. Default: 50. On a\npersonal link it answers `400`.\n"}}},"examples":{"Personal link":{"value":{"subaccountId":"6f1c2a3b-4d5e-4f60-8a7b-9c0d1e2f3a4b","kind":"cardholder","customerReferenceId":"2b7e9d14-5c3a-4f8e-9b21-0d6c4a8e7f35","platformName":"Ledgerly","organizationName":"Vertex Industries"}},"Team link":{"value":{"subaccountId":"6f1c2a3b-4d5e-4f60-8a7b-9c0d1e2f3a4b","kind":"team","expiresInHours":72,"maxUses":100}}}}}},"responses":{"201":{"description":"The link, with its `url`.","content":{"application/hal+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/enrollment-link"},{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","description":"The link to send. Its secret follows `#`."}}}]},"examples":{"Personal link":{"$ref":"#/components/examples/enrollment-link-created"}}}}},"400":{"description":"The body failed validation, and `errors` names the field. Or `organizationName` or\n`platformName` is a well-known brand name, with `code` `LINK_NAME_NOT_ALLOWED`.\n","content":{"application/problem+json":{"schema":{"type":"object","properties":{"title":{"type":"string","enum":["Bad Request"]},"detail":{"type":"string"},"code":{"type":"string","enum":["LINK_NAME_NOT_ALLOWED"]},"errors":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"detail":{"type":"string"}},"required":["title","detail"]}}},"required":["title","detail"]},"examples":{"Request failed validation":{"value":{"title":"Bad Request","detail":"Request object failed validation."}},"Name not allowed":{"value":{"title":"Bad Request","detail":"That platform name is not allowed.","code":"LINK_NAME_NOT_ALLOWED"}}}}}},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/enrollment_link_forbidden"},"404":{"$ref":"#/components/responses/enrollment_link_subaccount_not_found"},"409":{"$ref":"#/components/responses/enrollment_link_conflict"},"429":{"$ref":"#/components/responses/enrollment_link_rate_limited"},"500":{"$ref":"#/components/responses/server-error"}}},"get":{"tags":["enrollment-links"],"summary":"List enrollment links","description":"Lists the enrollment links of one of your subaccounts, newest first, without their\n`url`.\n\nA page holds at most `limit` links and can hold fewer, even none, while more remain.\nKeep following `_links.next` until a response has no `_links.next`. Use its `href` as\nit is: it keeps your `subaccountId`, `state` and `limit`.\n\nA subaccount that has no links, or that is not one of yours, gives an empty list.\n\nRequires `subaccounts:write`, so link details such as references and counts never\nreach a browser SDK token.\n","operationId":"ListEnrollmentLinks","security":[{"main-auth":["subaccounts:write"]}],"parameters":[{"in":"query","name":"subaccountId","required":true,"description":"The subaccount whose links to list.","schema":{"type":"string","format":"uuid"},"example":"6f1c2a3b-4d5e-4f60-8a7b-9c0d1e2f3a4b"},{"in":"query","name":"state","required":false,"description":"Only links in this state. `active` and `expired` are told apart by `expiresAt`.","schema":{"type":"string","enum":["active","used","revoked","expired"]},"example":"active"},{"in":"query","name":"limit","required":false,"description":"The most links a page holds.","schema":{"type":"integer","minimum":1,"maximum":50,"default":50},"example":50},{"in":"query","name":"cursor","required":false,"description":"Where the page starts, as set in `_links.next`. A cursor from another subaccount's\nlisting, or one that does not decode, answers `400` `INVALID_CURSOR`.\n","schema":{"type":"string","maxLength":1024}}],"responses":{"200":{"description":"A page of links.","content":{"application/hal+json":{"schema":{"type":"object","required":["_embedded","_links"],"properties":{"_embedded":{"type":"object","required":["enrollmentLinks"],"properties":{"enrollmentLinks":{"type":"array","items":{"$ref":"#/components/schemas/enrollment-link"}}}},"_links":{"type":"object","required":["self"],"properties":{"self":{"$ref":"#/components/schemas/link"},"next":{"$ref":"#/components/schemas/link"}}}}},"examples":{"A page with more to follow":{"$ref":"#/components/examples/enrollment-links-page"}}}}},"400":{"description":"A query parameter is not valid, and `errors` names it. Or the cursor is not one this\nlisting gave out, with `code` `INVALID_CURSOR`.\n","content":{"application/problem+json":{"schema":{"type":"object","properties":{"title":{"type":"string","enum":["Bad Request"]},"detail":{"type":"string"},"code":{"type":"string","enum":["INVALID_CURSOR"]},"errors":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"detail":{"type":"string"}},"required":["title","detail"]}}},"required":["title","detail"]},"examples":{"Invalid cursor":{"value":{"title":"Bad Request","detail":"The specified cursor is invalid","code":"INVALID_CURSOR"}}}}}},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/enrollment_link_forbidden"},"500":{"$ref":"#/components/responses/server-error"}}}},"/enrollment-links/{linkId}":{"parameters":[{"$ref":"#/components/parameters/link-id"}],"get":{"tags":["enrollment-links"],"summary":"Retrieve enrollment link","description":"Returns one of your enrollment links with its sessions, oldest first, without its\n`url`. With the `cardsubscription` webhooks, this is how you see what happened on the\nhosted page.\n\nEach session's `outcome` holds the ids the hosted page reported. Nothing checks them\nagainst the card or bank APIs: the `cardsubscription` webhooks are the source of truth\nfor what was enrolled.\n\nRequires `subaccounts:write`. A link that is not one of yours answers `404` with\n`code` `ENROLLMENT_LINK_NOT_FOUND`.\n","operationId":"GetEnrollmentLink","security":[{"main-auth":["subaccounts:write"]}],"responses":{"200":{"description":"The link and its sessions.","content":{"application/hal+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/enrollment-link"},{"type":"object","required":["sessions"],"properties":{"sessions":{"type":"array","description":"The sessions started from the link, oldest first.","items":{"$ref":"#/components/schemas/enrollment-link-session"}}}}]},"examples":{"A used personal link":{"$ref":"#/components/examples/enrollment-link-detail"}}}}},"400":{"$ref":"#/components/responses/bad-request"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/enrollment_link_forbidden"},"404":{"$ref":"#/components/responses/enrollment_link_not_found"},"500":{"$ref":"#/components/responses/server-error"}}}},"/enrollment-links/{linkId}/revoke":{"parameters":[{"$ref":"#/components/parameters/link-id"}],"post":{"tags":["enrollment-links"],"summary":"Revoke enrollment link","description":"Revokes one of your enrollment links. No body. An active link, an expired one\nincluded, becomes `revoked`: no session starts from it again, and its open sessions\nfail their next token refresh, so their access ends within one access token lifetime\n(at most 300 seconds). A link that is already used or revoked is returned as it is.\n\nRequires `subaccounts:write`. A link that is not one of yours answers `404` with\n`code` `ENROLLMENT_LINK_NOT_FOUND`.\n","operationId":"RevokeEnrollmentLink","security":[{"main-auth":["subaccounts:write"]}],"responses":{"200":{"description":"The link as it is now.","content":{"application/hal+json":{"schema":{"$ref":"#/components/schemas/enrollment-link"},"examples":{"A revoked team link":{"$ref":"#/components/examples/enrollment-link-revoked"}}}}},"400":{"$ref":"#/components/responses/bad-request"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/enrollment_link_forbidden"},"404":{"$ref":"#/components/responses/enrollment_link_not_found"},"500":{"$ref":"#/components/responses/server-error"}}}},"/network-bulk-feeds":{"post":{"tags":["network-bulk-feeds"],"summary":"Create network bulk feed","description":"Registers a new feed for network bulk.\n","security":[{"main-auth":["network-bulk-feeds:write"]}],"operationId":"CreateNetworkBulkFeed","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"networkReference":{"$ref":"#/components/schemas/network-reference"},"subaccountId":{"description":"The subaccount identifier","type":"string","format":"uuid"},"networkBulkEnrollmentId":{"description":"Optional. The network bulk enrollment (`POST /network-bulk-enrollments`)\nthis feed fulfils. The enrollment must exist on this account, its\n`subaccountId` and `network` must equal the body's, and its `state` must\nbe `requested` or `feed-created` (re-registering after a failed feed is\nallowed). Any mismatch is rejected with a 400 whose `detail` reads\n`networkBulkEnrollmentId does not match this subaccount and network`.\nWhen the feed is created, the enrollment's `networkBulkFeedId` is set and\nits state moves to `feed-created`; the link lives on the enrollment, so\nthe feed representation is unchanged. A duplicate feed still answers 409\nand leaves the enrollment untouched.\n","type":"string","format":"uuid"},"expectedCardCount":{"description":"The expected number of cards that will be enrolled under this bulk feed.\nOptional. When provided, the value is echoed back on the response and on the\n`networkbulkfeed.statechanged` webhook payload.\n","type":"integer","minimum":1,"maximum":1000000},"transactionStartDate":{"description":"Optional. Transactions posted on or after this calendar date (`YYYY-MM-DD`,\na valid date, not in the future) are ingested for this feed's deliveries,\nreplacing the default 15-day ingestion window. Currently supported for\n`SMARTDATA` feeds only — requests containing this field for any other feed\ntype are rejected with a 400. When unset, the 15-day window applies. Also\nsettable later via `PATCH /network-bulk-feeds/{networkBulkFeedId}`.\nThe comparison is calendar-day based in UTC: the network's posting date is\na date-only field, so a value of e.g. `2026-06-30` includes every\ntransaction whose posting date is 2026-06-30 or later, with no\nlocal-timezone adjustment.\n","type":"string","format":"date"},"cardCount":{"description":"Sandbox only. The number of synthetic Visa cards to create when this\nbulk feed is created in the sandbox environment. The cards are drawn\nfrom the head of Astrada's published sandbox Visa test-card pool —\nthe same cards every feed, deduplicated once enrolled (matching the\n`cardCount` field on the simulate-ingestion endpoints). Only valid\nfor `type: VBDS` feeds. Requests containing this field outside the\nsandbox environment, or for any other feed type, are rejected with\na 400.\n","type":"integer","minimum":1,"maximum":20,"default":5},"newCards":{"description":"Deprecated alias of `cardCount` — use `cardCount` instead. When both\nfields are provided, `cardCount` takes precedence. Same constraints\nand behavior.\n","type":"integer","minimum":1,"maximum":20,"default":5,"deprecated":true},"panFormat":{"description":"Sandbox only. Selects how card numbers arrive for this feed:\n`encrypted` (raw PAN) or `tokenized` (Amex network token /\n`tokenizedId`). Only valid for `type: GL` (AMEX) feeds.\nRequests containing this field outside the sandbox\nenvironment, or for any non-GL feed type, are rejected with\na 400. When omitted, the feed defaults to `encrypted`.\n","type":"string","enum":["encrypted","tokenized"]}},"required":["networkReference","network","subaccountId"]},{"oneOf":[{"type":"object","properties":{"network":{"description":"The network that the feed belongs","type":"string","enum":["AMEX"]},"type":{"description":"The type of card network's bulk enrollment feed","type":"string","enum":["GL"],"default":"GL"}},"required":["network"]},{"type":"object","properties":{"network":{"description":"The network that the feed belongs","type":"string","enum":["MASTERCARD"]},"type":{"description":"The type of card network's bulk enrollment feed","type":"string","enum":["SMARTDATA"],"default":"SMARTDATA"}},"required":["network"]},{"type":"object","properties":{"network":{"description":"The network that the feed belongs","type":"string","enum":["VISA"]},"type":{"description":"Optional. The Visa rail this feed is delivered on. Omit it and\nAstrada discovers the rail: the feed is registered on both VBDS\nand VCF, `type` is `null` while the feed is `submitted`, and it\nbecomes `VBDS` or `VCF` when the first delivery (a VBDS\nconnection or a VCF file) confirms the rail. Pass `VBDS` or `VCF`\nto pin the feed to one rail instead. Without a type the\n`networkReference` must be the full RPIC\n(`RegionId_ProcessorId_IssuerId_CompanyId`).\n","type":"string","enum":["VBDS","VCF"]}},"required":["network"]}]}]},"examples":{"Create Network Bulk Feed Request Example (Amex)":{"value":{"networkReference":"R123456","network":"AMEX","subaccountId":"24c4f90d-ab3b-4f6e-8a1d-d251a4fcf34c"}},"Create Network Bulk Feed Request Example (Mastercard)":{"value":{"networkReference":"G1234567","network":"MASTERCARD","subaccountId":"24c4f90d-ab3b-4f6e-8a1d-d251a4fcf34c"}},"Create Network Bulk Feed Request Example (Mastercard, fulfilling a bulk enrollment)":{"value":{"networkReference":"G1234567","network":"MASTERCARD","subaccountId":"24c4f90d-ab3b-4f6e-8a1d-d251a4fcf34c","networkBulkEnrollmentId":"9c1f0c4e-2f0e-4a9c-9a1b-0c1d2e3f4a5b"}},"Create Network Bulk Feed Request Example (Visa, rail discovered by Astrada)":{"value":{"networkReference":"1_123_45_6789","network":"VISA","subaccountId":"24c4f90d-ab3b-4f6e-8a1d-d251a4fcf34c"}},"Create Network Bulk Feed Request Example (Visa, pinned to VBDS)":{"value":{"networkReference":"1_123_45_6789","network":"VISA","type":"VBDS","subaccountId":"24c4f90d-ab3b-4f6e-8a1d-d251a4fcf34c"}},"Create Network Bulk Feed Request Example (Visa, sandbox synthetic cards)":{"value":{"networkReference":"1_123_45_6789","network":"VISA","type":"VBDS","subaccountId":"24c4f90d-ab3b-4f6e-8a1d-d251a4fcf34c","cardCount":5}},"Create Network Bulk Feed Request Example (Amex, sandbox tokenized)":{"value":{"networkReference":"R123456","network":"AMEX","subaccountId":"24c4f90d-ab3b-4f6e-8a1d-d251a4fcf34c","panFormat":"tokenized"}}}}}},"responses":{"201":{"description":"Resource created","content":{"application/hal+json":{"schema":{"$ref":"#/components/schemas/network-bulk-feeds"},"examples":{"Example Create Network Bulk Feed Response":{"$ref":"#/components/examples/network-bulk-feeds"}}}}},"400":{"$ref":"#/components/responses/bad-request"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"409":{"$ref":"#/components/responses/conflict"},"500":{"$ref":"#/components/responses/server-error"}}},"get":{"parameters":[{"$ref":"#/components/parameters/network-reference"},{"$ref":"#/components/parameters/subaccount-id"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/offset"}],"tags":["network-bulk-feeds"],"summary":"List network bulk feed","description":"Returns all network bulk feeds under the account.\n\nBy default, `GET /network-bulk-feeds` returns network bulk feeds ordered by the latest `createdAt`.\n\nThis endpoint supports [offset-based pagination](https://docs.astrada.co/reference/pagination).\n","security":[{"main-auth":["network-bulk-feeds:read"]}],"operationId":"ListNetworkBulkFeeds","responses":{"200":{"description":"Successful operation","content":{"application/hal+json":{"schema":{"type":"object","required":["_links","_embedded","totalItems"],"properties":{"_links":{"type":"object","required":["self"],"properties":{"self":{"$ref":"#/components/schemas/link"},"first":{"$ref":"#/components/schemas/link"},"next":{"$ref":"#/components/schemas/link"},"prev":{"$ref":"#/components/schemas/link"},"last":{"$ref":"#/components/schemas/link"}}},"_embedded":{"type":"object","required":["networkBulkFeeds"],"properties":{"networkBulkFeeds":{"type":"array","items":{"$ref":"#/components/schemas/network-bulk-feeds"}}}},"totalItems":{"type":"integer","description":"Total number of network bulk feeds"}}},"examples":{"Example List Network Bulk feeds Response":{"value":{"_links":{"self":{"href":"/network-bulk-feeds"}},"_embedded":{"networkBulkFeeds":[{"_links":{"self":{"href":"/network-bulk-feeds/75ea3c99-6bf5-4b16-8f68-0cdc43d75806"}},"id":"75ea3c99-6bf5-4b16-8f68-0cdc43d75806","subaccountId":"f297d659-c13d-4219-aeaa-e10a845140a5","network":"MASTERCARD","networkReference":"G1234567","state":"submitted","type":"SMARTDATA","panFormat":"encrypted","createdAt":"2024-12-19T14:45:00Z","updatedAt":"2024-12-19T14:45:00Z"},{"_links":{"self":{"href":"/network-bulk-feeds/c73f2da7-aa1f-4775-ad38-864b1b6f3162"}},"id":"c73f2da7-aa1f-4775-ad38-864b1b6f3162","subaccountId":"29cb4277-b812-4137-b008-e0befa8c6a47","network":"MASTERCARD","networkReference":"G1234567","state":"submitted","type":"SMARTDATA","panFormat":"encrypted","createdAt":"2024-10-19T14:45:00Z","updatedAt":"2024-10-19T14:45:00Z"},{"_links":{"self":{"href":"/network-bulk-feeds/a3b1c2d4-5e6f-7890-abcd-ef1234567890"}},"id":"a3b1c2d4-5e6f-7890-abcd-ef1234567890","subaccountId":"f297d659-c13d-4219-aeaa-e10a845140a5","network":"VISA","networkReference":"1_123_45_6789","state":"failed","type":"VBDS","panFormat":"encrypted","errorReason":"Starter data ingestion failed: invalid RPIC configuration","createdAt":"2024-12-19T14:45:00Z","updatedAt":"2024-12-20T10:30:00Z"}]},"totalItems":3}},"No network bulk feeds found":{"value":{"_links":{"self":{"href":"/network-bulk-feeds"}},"_embedded":{"networkBulkFeeds":[]},"totalItems":0}}}}}},"400":{"$ref":"#/components/responses/bad-request"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"500":{"$ref":"#/components/responses/server-error"}}}},"/network-bulk-feeds/{networkBulkFeedId}":{"parameters":[{"$ref":"#/components/parameters/network-bulk-feed-id-2"}],"get":{"tags":["network-bulk-feeds"],"summary":"Retrieve a network bulk feed","description":"Returns detailed information about a specific network bulk feed by its identifier.","security":[{"main-auth":["network-bulk-feeds:read"]}],"operationId":"GetNetworkBulkFeed","responses":{"200":{"description":"Successful operation","content":{"application/hal+json":{"schema":{"$ref":"#/components/schemas/network-bulk-feeds"},"examples":{"Example Get Network Bulk Subscription Response":{"$ref":"#/components/examples/network-bulk-feeds"},"Example Get Failed Network Bulk Subscription Response (VISA)":{"$ref":"#/components/examples/network-bulk-feeds-failed"}}}}},"400":{"$ref":"#/components/responses/bad-request"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/not-found"},"500":{"$ref":"#/components/responses/server-error"}}},"patch":{"tags":["network-bulk-feeds"],"summary":"Update a network bulk feed","description":"Updates a network bulk feed. Supports setting `transactionStartDate`\n(currently for `SMARTDATA` feeds only — other feed types are rejected with\na 422) and `expectedCardCount`. At least one field must be provided;\n`transactionStartDate` cannot be unset (`null` is rejected).\n\nSetting `transactionStartDate` widens the feed's ingestion window:\ntransactions posted on or after the date are ingested for the feed's\ndeliveries, replacing the default 15-day window.\n","security":[{"main-auth":["network-bulk-feeds:write"]}],"operationId":"UpdateNetworkBulkFeed","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","minProperties":1,"properties":{"transactionStartDate":{"description":"Transactions posted on or after this calendar date\n(`YYYY-MM-DD`, a valid date, not in the future) are ingested\nfor this feed's deliveries, replacing the default 15-day\ningestion window. Currently supported for `SMARTDATA` feeds\nonly. The comparison is calendar-day based in UTC: the\nnetwork's posting date is a date-only field, so a value of\ne.g. `2026-06-30` includes every transaction whose posting\ndate is 2026-06-30 or later, with no local-timezone\nadjustment.\n","type":"string","format":"date"},"expectedCardCount":{"description":"The expected number of cards that will be enrolled under this bulk feed.","type":"integer","minimum":1,"maximum":1000000}}},"examples":{"Set the transaction start date (Mastercard SMARTDATA)":{"value":{"transactionStartDate":"2026-07-01"}},"Update the expected card count":{"value":{"expectedCardCount":5000}}}}}},"responses":{"200":{"description":"Successful operation","content":{"application/hal+json":{"schema":{"$ref":"#/components/schemas/network-bulk-feeds"},"examples":{"Example Get Network Bulk Subscription Response":{"$ref":"#/components/examples/network-bulk-feeds"}}}}},"400":{"$ref":"#/components/responses/bad-request"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/not-found"},"422":{"$ref":"#/components/responses/unprocessable-entity"},"500":{"$ref":"#/components/responses/server-error"}}}},"/network-bulk-enrollments":{"post":{"tags":["network-bulk-enrollments"],"summary":"Create network bulk enrollment","description":"Starts a bulk enrollment kickoff for a whole card program. The request records the\ncompany, the card program admin, an optional bank contact and program size, and the\nadmin's consent, and Astrada's onboarding team takes it from there with the issuing\nbank. The Unified Enrollment SDK calls this endpoint when an admin sends the bulk\nkickoff form (in SDK v1, with `bulkFlow: \"kickoff\"`); you can also call it directly.\n\nNothing is enrolled yet at this point. Once the bank has issued the network\nreference, register the feed with `POST /network-bulk-feeds` and pass this\nenrollment's `id` as `networkBulkEnrollmentId`; the enrollment then moves to\n`feed-created` and links to the feed.\n\nThe subaccount must belong to the calling account. The BIN's bulk eligibility is not\nre-checked here. A validation failure or an unknown subaccount answers `400`.\n\nA program has one open kickoff at a time. A program is the calling account, the\n`subaccountId`, the `network` and the first 8 digits of the `bin`; a `bin` shorter than\n8 digits matches only a kickoff with exactly the same digits. A kickoff is open while it\nis `requested` and was created less than 90 days ago, or while it is `feed-created` and\nits feed is live (not `failed` or `deactivated`, and not deleted), at any age. When the\nprogram already has an open kickoff that another request wrote, this request stores no\nsecond kickoff and answers `200` with that kickoff's summary (`alreadyOpen: true`),\nwhatever new `requestId` it sent, or none. Astrada keeps the card admin named in this\nrequest with the open kickoff, so its onboarding team knows who else is waiting, and the\nopen kickoff stays the only one they work on. A repeat of the same `requestId` is kept once.\n`GET /network-bulk-enrollments/open` answers the same question before the form.\nTwo kickoffs for one program sent at the same time store one kickoff between them.\n\nThe 90 days count from the kickoff's `createdAt`. Once a `requested` kickoff is 90 days\nold it stops holding its program: nothing is written to it, it keeps its state and can\nstill be read, and the next kickoff for the program is created with `201`. A `cancelled`\nkickoff, or one whose feed failed, was deactivated or was deleted, does not hold its\nprogram either.\n\nRequires the `network-bulk-enrollments:write` scope. Tokens that only hold\n`network-bulk-feeds:write` are still accepted, so existing integrations keep working.\n","security":[{"main-auth":["network-bulk-enrollments:write"]},{"main-auth":["network-bulk-feeds:write"]}],"operationId":"CreateNetworkBulkEnrollment","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["subaccountId","network","bin","company","cardAdmin","outreach","consent"],"properties":{"requestId":{"description":"Optional. Your idempotency key for this enrollment, unique per account. Repeating the\nrequest with a `requestId` that was already used returns the stored enrollment, whole\nand unchanged, with `200` instead of creating a second one with `201`. A request\nwithout a `requestId` is never a replay: it creates a new enrollment unless its\nprogram already has an open kickoff, which answers `200` with that kickoff's summary.\n","type":"string","format":"uuid"},"subaccountId":{"description":"The subaccount the card program enrolls into. Must belong to the calling account.","type":"string","format":"uuid"},"network":{"description":"The network of the card program.","type":"string","enum":["AMEX","MASTERCARD","VISA"]},"bin":{"description":"The leading 6 to 11 digits of the card that opened the kickoff.","type":"string","pattern":"^[0-9]{6,11}$"},"binInfo":{"description":"Optional. The issuer details shown to the person submitting the kickoff, in\nthe `GET /bin-lookup` vocabulary. Stored as a display snapshot only; every\nfield is optional.\n","type":"object","properties":{"issuerName":{"type":"string","maxLength":200,"description":"The name of the issuing bank."},"issuerCountry":{"type":"string","description":"The country of the issuing bank, ISO 3166 alpha-3."},"type":{"type":"string","maxLength":50,"description":"The card type, for example `COMMERCIAL`."},"fundingType":{"type":"string","maxLength":50,"description":"The card funding type, for example `CREDIT`."}}},"company":{"type":"object","required":["legalName"],"properties":{"legalName":{"type":"string","minLength":1,"maxLength":200,"description":"The company's legal name, exactly as it reads on the card agreement."}}},"cardAdmin":{"description":"The card program administrator. Astrada keeps this person engaged throughout onboarding.","type":"object","required":["name","email"],"properties":{"name":{"type":"string","minLength":1,"maxLength":200},"email":{"type":"string","format":"email","maxLength":320}}},"bankContact":{"description":"Optional. The company's relationship contact at the issuing bank.","type":"object","required":["name","email"],"properties":{"name":{"type":"string","minLength":1,"maxLength":200},"email":{"type":"string","format":"email","maxLength":320}}},"cardCountBand":{"description":"Optional. The estimated number of cards in the program, as a band. An estimate helps the bank size the file.","type":"string","enum":["1-50","51-250","251-1000","1001-5000","5001-25000","25000+"]},"cardCount":{"description":"Optional. The estimated number of cards in the program. When sent, it decides the stored `cardCountBand`, even if `cardCountBand` is also sent.","type":"integer","minimum":1,"maximum":1000000},"outreach":{"description":"Who contacts the bank. `astrada`: Astrada reaches out to the bank, copying the\ncompany and the card admin. `self`: the company emails the bank itself and\ncopies onboarding@astrada.co so Astrada can guide the setup.\n","type":"string","enum":["astrada","self"]},"consent":{"description":"The card admin's approval for the company and Astrada to start bulk enrollment with the bank, including contacting the bank on the company's behalf.","type":"object","required":["accepted","version"],"properties":{"accepted":{"description":"Must be `true`. The request is rejected with a 400 otherwise.","type":"boolean","enum":[true]},"version":{"description":"The version of the consent wording that was accepted, for example `kickoff-consent-v1`. Stored as an opaque string.","type":"string"}}},"customerReferenceId":{"description":"Optional. Your own id for this enrollment, echoed back on the resource.","type":"string","minLength":1,"maxLength":100}}},"examples":{"Create Network Bulk Enrollment Request Example (Astrada outreach)":{"value":{"requestId":"3f8a1c52-7d4e-4b19-9c06-5e2b8d7a9f14","subaccountId":"24c4f90d-ab3b-4f6e-8a1d-d251a4fcf34c","network":"MASTERCARD","bin":"51075500","binInfo":{"issuerName":"Jack Henry And Associates","issuerCountry":"USA","type":"COMMERCIAL","fundingType":"CREDIT"},"company":{"legalName":"Vertex Industries, Inc."},"cardAdmin":{"name":"Dana Whitfield","email":"dana.whitfield@vertexind.com"},"bankContact":{"name":"Sam Lee","email":"sam.lee@bank.example"},"cardCountBand":"251-1000","cardCount":400,"outreach":"astrada","consent":{"accepted":true,"version":"kickoff-consent-v1"},"customerReferenceId":"ledgerly-customer-8842"}},"Create Network Bulk Enrollment Request Example (self outreach, required fields only)":{"value":{"subaccountId":"24c4f90d-ab3b-4f6e-8a1d-d251a4fcf34c","network":"VISA","bin":"414720","company":{"legalName":"Northwind Traders LLC"},"cardAdmin":{"name":"Priya Natarajan","email":"priya.natarajan@northwind.example"},"outreach":"self","consent":{"accepted":true,"version":"kickoff-consent-v1"}}}}}}},"responses":{"200":{"description":"A stored kickoff, returned unchanged, in one of two shapes:\n\n- An enrollment with this `requestId` already exists: the full enrollment, as your\n  request wrote it.\n- The program already has an open kickoff that another request wrote: its summary,\n  marked `alreadyOpen: true`, with the `requestId` this request sent (`null` when it\n  sent none) and only the `self` link. Names, emails, bank contact, `binInfo`, consent\n  and outreach are left out.\n","content":{"application/hal+json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/network-bulk-enrollment"},{"$ref":"#/components/schemas/network-bulk-enrollment-summary"}]},"examples":{"Example Repeat Network Bulk Enrollment Response (same requestId)":{"$ref":"#/components/examples/network-bulk-enrollment"},"Example Network Bulk Enrollment Response (program already open)":{"$ref":"#/components/examples/network-bulk-enrollment-summary"}}}}},"201":{"description":"Resource created. The program had no open kickoff, so this request wrote one.","content":{"application/hal+json":{"schema":{"$ref":"#/components/schemas/network-bulk-enrollment"},"examples":{"Example Create Network Bulk Enrollment Response":{"$ref":"#/components/examples/network-bulk-enrollment"},"Example Create Network Bulk Enrollment Response (self outreach, required fields only)":{"$ref":"#/components/examples/network-bulk-enrollment-minimal"}}}}},"400":{"$ref":"#/components/responses/bad-request"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"500":{"$ref":"#/components/responses/server-error"}}}},"/network-bulk-enrollments/open":{"get":{"tags":["network-bulk-enrollments"],"summary":"Check for an open network bulk enrollment","description":"Answers whether a card program already has an open bulk enrollment kickoff, before anyone\nfills in the kickoff form. The Unified Enrollment SDK calls it while it looks up a card, and\nshows \"Already under way\" instead of the program screen when the program has one; you can\nalso call it directly.\n\nA program is the calling account, the `subaccountId`, the `network` and the card's first 8\ndigits (`bin`). The rule is the one `POST /network-bulk-enrollments` uses: a kickoff is open\nwhile it is `requested` and was created less than 90 days ago, or while it is `feed-created`\nand its feed is live, at any age. The account comes from the token, never from the query.\n\nThe answer carries only the open kickoff's `enrollmentId`, `state` and `requestedAt`. A\n`bin` of more or fewer than 8 digits, a missing or unknown parameter, or an `accountId` in\nthe query answers `400`.\n\nRequires the `network-bulk-enrollments:write` scope, the one the kickoff itself takes.\nTokens that only hold `network-bulk-feeds:write` are also accepted. A token with only a read\nscope answers `403`.\n","security":[{"main-auth":["network-bulk-enrollments:write"]},{"main-auth":["network-bulk-feeds:write"]}],"operationId":"GetOpenNetworkBulkEnrollment","parameters":[{"name":"subaccountId","in":"query","required":true,"description":"The subaccount of the card program. Must belong to the calling account to find anything.","schema":{"type":"string","format":"uuid"}},{"name":"network","in":"query","required":true,"description":"The card's network.","schema":{"type":"string","enum":["AMEX","MASTERCARD","VISA"]}},{"name":"bin","in":"query","required":true,"description":"Exactly the card's first 8 digits.","schema":{"type":"string","pattern":"^[0-9]{8}$"}}],"responses":{"200":{"description":"Whether the program has an open kickoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/network-bulk-enrollment-open"},"examples":{"No open kickoff":{"value":{"open":false}},"Open kickoff, still requested":{"value":{"open":true,"enrollmentId":"3f2c9a41-6b1e-4d7a-9c55-0e8d2b7f6a13","state":"requested","requestedAt":"2026-11-02T10:15:00.000Z"}},"Open kickoff, feed created":{"value":{"open":true,"enrollmentId":"8b1d4e2f-0c7a-4f3e-a6d9-2e5b7c1f9a40","state":"feed-created","requestedAt":"2026-10-20T14:30:00.000Z"}}}}}},"400":{"$ref":"#/components/responses/bad-request"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"500":{"$ref":"#/components/responses/server-error"}}}},"/network-bulk-enrollments/{networkBulkEnrollmentId}":{"parameters":[{"$ref":"#/components/parameters/network-bulk-enrollment-id"}],"get":{"tags":["network-bulk-enrollments"],"summary":"Retrieve a network bulk enrollment","description":"Returns a network bulk enrollment by its identifier. Once a feed has been registered\nwith this enrollment's id on `POST /network-bulk-feeds`, the representation carries\n`networkBulkFeedId` and a `networkBulkFeed` link. An enrollment that belongs to\nanother account answers `404`.\n\nRequires the `network-bulk-enrollments:read` scope. Tokens that only hold\n`network-bulk-feeds:read` are still accepted, so existing integrations keep working.\n","security":[{"main-auth":["network-bulk-enrollments:read"]},{"main-auth":["network-bulk-feeds:read"]}],"operationId":"GetNetworkBulkEnrollment","responses":{"200":{"description":"Successful operation","content":{"application/hal+json":{"schema":{"$ref":"#/components/schemas/network-bulk-enrollment"},"examples":{"Example Get Network Bulk Enrollment Response":{"$ref":"#/components/examples/network-bulk-enrollment"},"Example Get Network Bulk Enrollment Response (feed registered)":{"$ref":"#/components/examples/network-bulk-enrollment-feed-created"}}}}},"400":{"$ref":"#/components/responses/bad-request"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/not-found"},"500":{"$ref":"#/components/responses/server-error"}}}},"/subaccounts/{subaccountId}":{"parameters":[{"$ref":"#/components/parameters/subaccount-id-2"}],"get":{"tags":["subaccounts"],"summary":"Retrieve subaccount","description":"Returns detailed information about a specific subaccount by its identifier, including configuration details and associated data.\n\n`_links.team-link` appears when enrollment links are enabled for the account, the token holds `card-subscriptions:write` or `subaccounts:write`, and the subaccount's card enrollment is on (its `enrollmentPolicy.cardEnrollment` is not `false`). It points to `POST /subaccounts/{subaccountId}/team-link`, which creates a team link for the subaccount. An enrollment link session's token never gets it.\n","operationId":"GetSubaccount","security":[{"main-auth":["subaccounts:read"]}],"responses":{"200":{"description":"Details of the subaccount giving the accountId and subaccountId","content":{"application/hal+json":{"schema":{"$ref":"#/components/schemas/subaccount"},"examples":{"Example Get Subaccount Response":{"$ref":"#/components/examples/subaccount"},"Example Get Subaccount Response (team link offered)":{"$ref":"#/components/examples/subaccount-team-link"}}}}},"400":{"$ref":"#/components/responses/bad-request"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/not-found"},"500":{"$ref":"#/components/responses/server-error"}}},"patch":{"tags":["subaccounts"],"summary":"Update subaccount configurations","description":"Update a subaccount name and configurations.\nAll updated configurations are validated against the capabilities of the main account to ensure compliance.\nIt is possible to add new networks and/or regions but it is not possible to remove any configurations that were previously set.\n\nEach network's `countries` can be set to either an array of specific ISO 3166 alpha-3 country codes, or the string `\"*\"` to inherit all countries from the parent account's capabilities for that network.\n\nWhen using `\"*\"`, the subaccount will automatically reflect the parent account's current country list. If the parent account's capabilities change, subaccounts configured with `\"*\"` will inherit the updated countries.\n\nThe single and bulk enrollment configurations are not required when creating a subaccount, but if not provided they will default to the same country list as the main countries property for that network. The supported card types for single and bulk enrollment is CONSUMER, while the supported funding card types is DEBIT. If not provided, the block rules for both card types will default to the parent account's default block rule for that network and enrollment level. Visa consumer debit and prepaid cards are blocked at the network level regardless of these settings; see `networkBlockedCards` on the subaccount.\n\nTo set the default rule on the parent account, please reach out to your account manager or support.\n","operationId":"UpdateSubaccount","security":[{"main-auth":["subaccounts:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"configurations":{"$ref":"#/components/schemas/create-subaccount-configurations"},"name":{"type":"string"},"verificationPolicy":{"description":"Set or clear the subaccount's card verification policy. Customers may set any\nlevel above LOW (MEDIUM, HIGH, HIGHEST), send a null level to clear the\noverride, and toggle the `sandbox` test flag. LOW is internal-only and is\nrejected on this endpoint.\n","allOf":[{"$ref":"#/components/schemas/verification-policy"}]},"enrollmentPolicy":{"$ref":"#/components/schemas/customer-enrollment-policy"}}},"examples":{"Update Subaccount Request Example (ignored enrollmentPolicy fields)":{"value":{"enrollmentPolicy":{"bankEnrollment":"on","bulkEnrolment":"suggested","linkAnotherCard":false}}}}}}},"responses":{"200":{"description":"Specified subaccount updated successfully. The body is the same effective read\nmodel `GET /subaccounts/{subaccountId}` returns (`enrollmentPolicy`,\n`bankLinkingPolicy`, `plaidEndCustomer` and `enforceIssuerCountry` resolved\nagainst the parent account, and `networkBlockedCards` resolved from the platform\nnetwork configuration), so it may include account-level and platform-level\nsettings that were not part of the request and that the subaccount stores no\nvalue for.\n\nWhen the request's `enrollmentPolicy` holds keys this endpoint does not accept, the\nbody also carries `ignoredFields`, which names each of them.\n","content":{"application/hal+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/subaccount"},{"type":"object","properties":{"ignoredFields":{"type":"array","items":{"type":"string"},"description":"The keys of the request's `enrollmentPolicy` that this endpoint\nignored, each written as `enrollmentPolicy.<key>`: every key other than\n`cardEnrollment`, `bankEnrollment` and `bulkEnrollment`, such as a\nmisspelled key or a field Astrada manages. Nothing is stored for them,\nand the accepted keys are applied as usual. Absent when no key was\nignored.\n"}}}]},"examples":{"Example Update Subaccount Response":{"$ref":"#/components/examples/subaccount"},"Example Update Subaccount Response (ignored enrollmentPolicy fields)":{"$ref":"#/components/examples/subaccount-ignored-fields"}}}}},"400":{"$ref":"#/components/responses/bad-request"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/not-found"},"500":{"$ref":"#/components/responses/server-error"}}}},"/subaccounts/{subaccountId}/verification-policy":{"parameters":[{"$ref":"#/components/parameters/subaccount-id-2"}]},"/subaccounts/{subaccountId}/enrollment-policy":{"parameters":[{"$ref":"#/components/parameters/subaccount-id-2"}]},"/subaccounts/{subaccountId}/bank-linking-policy":{"parameters":[{"$ref":"#/components/parameters/subaccount-id-2"}]},"/subaccounts/{subaccountId}/mastercard-ard-settlement":{"parameters":[{"$ref":"#/components/parameters/subaccount-id-2"}]},"/subaccounts/{subaccountId}/team-link":{"parameters":[{"$ref":"#/components/parameters/subaccount-id-2"}],"post":{"tags":["enrollment-links"],"summary":"Create team link","description":"Creates a team link for the subaccount: the route for the SDK's \"Invite your team\"\nending, which calls it with the SDK token's `card-subscriptions:write`. An API client\nmay call it with `subaccounts:write`. No body.\n\n`_links.team-link` on `GET /subaccounts/{subaccountId}` points here when the route is\navailable to the caller.\n\nThe link has the team defaults: it expires after 14 days and allows 50 session starts.\nThe response holds only what the SDK screen shows, and is sent with\n`Cache-Control: no-store`. Every call makes a new link. A new link does not revoke an\nolder one: each link ends at its own expiry, when its session starts are used up, or\nwhen it is revoked. Revoke a link you no longer want shared with\n`POST /enrollment-links/{linkId}/revoke`.\n\nRefusals carry a `code`:\n\n- `403` `LINK_SESSION_FORBIDDEN`: the token is an enrollment link session's. It holds\n  `card-subscriptions:write` too, but cannot make links.\n- `404` `SUBACCOUNT_NOT_FOUND`: the subaccount is not one of your account's.\n- `409` `ENROLLMENT_LINKS_NOT_ENABLED`: enrollment links are not enabled for your\n  account.\n- `409` `CARD_ENROLLMENT_OFF`: card enrollment is off for the subaccount (its\n  `enrollmentPolicy.cardEnrollment` is `false`). The hosted page offers card enrollment\n  only, so a link would have nothing to enroll. This check runs before the daily limits\n  are counted, so a refused request does not use them up.\n- `429` `RATE_LIMITED`: 20 links were made here for the subaccount today (UTC), or your\n  account has created 2,000 links today.\n\nA link made before card enrollment was turned off starts no session while card\nenrollment stays off: `POST /enrollment-link-sessions/preview` and\n`POST /enrollment-link-sessions` answer `409` `CARD_ENROLLMENT_OFF`, and no start is\ncounted.\n","operationId":"CreateTeamLink","security":[{"main-auth":["card-subscriptions:write"]},{"main-auth":["subaccounts:write"]}],"responses":{"201":{"description":"The team link.","content":{"application/hal+json":{"schema":{"type":"object","required":["id","url","expiresAt","maxUses"],"properties":{"id":{"type":"string","format":"uuid","description":"The link's identifier."},"url":{"type":"string","format":"uri","description":"The link to share. Its secret follows `#`, and only this response returns it."},"expiresAt":{"type":"string","format":"date-time","description":"After this time no session starts from the link."},"maxUses":{"type":"integer","description":"The session starts the link allows."}}},"examples":{"Team link":{"value":{"id":"8e2f4a6c-1b3d-4e5f-9a7b-2c4d6e8f0a1b","url":"https://sdk.sandbox.astrada.co/unified/v2/enroll.html#el1_Qm9Lx2Vt8RkZ1pW4nJ7cH0sD3fG6aY9uE2iO5rT8bN1","expiresAt":"2026-11-19T10:00:00.000Z","maxUses":50}}}}}},"400":{"$ref":"#/components/responses/bad-request"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/enrollment_link_forbidden"},"404":{"$ref":"#/components/responses/enrollment_link_subaccount_not_found"},"409":{"$ref":"#/components/responses/enrollment_link_conflict"},"429":{"$ref":"#/components/responses/enrollment_link_rate_limited"},"500":{"$ref":"#/components/responses/server-error"}}}},"/subaccounts":{"get":{"tags":["subaccounts"],"summary":"List subaccounts","description":"Returns a list of all subaccounts associated with the account.\n\nThis endpoint supports [cursor-based pagination](https://docs.astrada.co/reference/pagination).\n","operationId":"GetSubaccounts","parameters":[{"$ref":"#/components/parameters/cursor"},{"$ref":"#/components/parameters/limit"}],"security":[{"main-auth":["subaccounts:read"]}],"responses":{"200":{"description":"Subaccounts list retrieved successfully","content":{"application/hal+json":{"schema":{"type":"object","properties":{"_embedded":{"type":"object","required":["subaccounts"],"properties":{"subaccounts":{"type":"array","items":{"$ref":"#/components/schemas/subaccount"}}}},"_links":{"type":"object","properties":{"self":{"$ref":"#/components/schemas/link"},"next":{"$ref":"#/components/schemas/link"}},"required":["self"]}},"required":["_embedded","_links"]},"examples":{"Example List Subaccounts Response":{"value":{"_links":{"self":{"href":"/subaccounts"}},"_embedded":{"subaccounts":[{"_links":{"self":{"href":"/subaccounts/81e7c267-0927-4234-a2bd-78cef799de54"}},"accountId":"073fe1bb-3350-46ad-b3a6-32afb3780994","id":"81e7c267-0927-4234-a2bd-78cef799de54","name":"Subaccount A","createdAt":"2024-05-01T17:08:43.810Z","updatedAt":"2024-05-01T17:08:43.810Z","configurations":{"VISA":{"countries":["USA","CAN"],"single-enrollment":{"countries":["USA","CAN"],"blockedCardTypes":["CONSUMER"],"blockedFundingCardTypes":["DEBIT"]},"bulk-enrollment":{"countries":["USA","CAN"],"blockedCardTypes":["CONSUMER"],"blockedFundingCardTypes":["DEBIT"]}},"MASTERCARD":{"countries":["USA"],"single-enrollment":{"countries":["USA"],"blockedCardTypes":[],"blockedFundingCardTypes":[]},"bulk-enrollment":{"countries":["USA"],"blockedCardTypes":[],"blockedFundingCardTypes":[]}}}},{"_links":{"self":{"href":"/subaccounts/3788493c-49f5-4f5e-9152-56abc2a4e153"}},"accountId":"073fe1bb-3350-46ad-b3a6-32afb3780994","id":"3788493c-49f5-4f5e-9152-56abc2a4e153","name":"Subaccount B","createdAt":"2024-05-01T17:08:43.810Z","updatedAt":"2024-05-01T17:08:43.810Z","configurations":{"VISA":{"countries":["USA","CAN"],"single-enrollment":{"countries":["USA","CAN"],"blockedCardTypes":[],"blockedFundingCardTypes":["DEBIT"]},"bulk-enrollment":{"countries":["USA","CAN"],"blockedCardTypes":[],"blockedFundingCardTypes":[]}},"MASTERCARD":{"countries":["USA"],"single-enrollment":{"countries":["USA"],"blockedCardTypes":["CONSUMER"],"blockedFundingCardTypes":[]},"bulk-enrollment":{"countries":["USA"],"blockedCardTypes":[],"blockedFundingCardTypes":[]}}}}]}}},"Example no Subaccounts found":{"value":{"_links":{"self":{"href":"/subaccounts"}},"_embedded":{"subaccounts":[]}}}}}}},"400":{"$ref":"#/components/responses/bad-request"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/not-found"},"500":{"$ref":"#/components/responses/server-error"}}},"post":{"tags":["subaccounts"],"summary":"Create subaccount","description":"Creates a new subaccount, allowing you to set network and regional configurations.\n\nEach network's `countries` can be set to either an array of specific ISO 3166 alpha-3 country codes, or the string `\"*\"` to inherit all countries from the parent account's capabilities for that network.\n\nWhen using `\"*\"`, the subaccount will automatically reflect the parent account's current country list. If the parent account's capabilities change, subaccounts configured with `\"*\"` will inherit the updated countries.\n\nThe single and bulk enrollment configurations are not required when creating a subaccount, but if not provided they will default to the same country list as the main `countries` property for that network.\nThe supported card types for single and bulk enrollment is CONSUMER, while the supported funding card types is DEBIT. If not provided, the block rules for both card types will default to the parent account's default block rule for that network and enrollment level. Visa consumer debit and prepaid cards are blocked at the network level regardless of these settings; see `networkBlockedCards` on the subaccount.\n\nTo set the default rule on the parent account, please reach out to your account manager or support.\n","operationId":"CreateSubaccount","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"The name of the subaccount"},"configurations":{"$ref":"#/components/schemas/create-subaccount-configurations"}},"required":["name","configurations"]},"examples":{"Specific countries":{"value":{"name":"Subaccount A","configurations":{"VISA":{"countries":["USA","CAN"]},"MASTERCARD":{"countries":["USA"]}}}},"Wildcard countries":{"value":{"name":"Subaccount B","configurations":{"VISA":{"countries":"*"},"MASTERCARD":{"countries":"*"}}}}}}}},"security":[{"main-auth":["subaccounts:write"]}],"responses":{"201":{"description":"New subaccount created successfully. The body is the same effective read model\n`GET /subaccounts/{subaccountId}` returns (`enrollmentPolicy`,\n`bankLinkingPolicy`, `plaidEndCustomer` and `enforceIssuerCountry` resolved\nagainst the parent account, and `networkBlockedCards` resolved from the platform\nnetwork configuration), not the raw create-time snapshot. Account-level and\nplatform-level settings therefore appear here even though the new subaccount\nstores no value for them.\n","content":{"application/hal+json":{"schema":{"$ref":"#/components/schemas/subaccount"},"examples":{"Example Create Subaccount Response":{"$ref":"#/components/examples/subaccount"}}}}},"400":{"$ref":"#/components/responses/bad-request"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"500":{"$ref":"#/components/responses/server-error"}}}},"/transactions":{"get":{"tags":["transactions"],"summary":"List transactions","description":"Returns a list of all transactions under the account.\n\nBy default, `GET /transactions` returns transactions ordered by the latest `createdAt`. You can combine the different filters as documented.\n\nThis endpoint supports [cursor-based pagination](https://docs.astrada.co/reference/pagination).\n\nAdd `expand` to embed each transaction's related resources under `_embedded` in the same response,\nfor example `expand=cardSubscription,card,cardholder`. Each embedded resource is the exact body its own\nendpoint serves, shows its current values (not those at the time of the transaction) except\n`cardholder.corporate`, which is resolved as of the transaction's date (see the `expand` parameter), and\nrequires that endpoint's scope: `card-subscriptions:read` for `cardSubscription`, `cards:read` for `card`,\n`cardholder:read` for `cardholder`. Transactions without a given related resource simply omit that key.\nPagination links preserve `expand`.\n\nFor the company and legal entity a card belonged to when the transaction happened, use `expand=cardholder`\nand read `cardholder.corporate.id` and `cardholder.corporate.legalEntity`. They are the values in effect on\nthe transaction's `transactionOccurrenceDate` (through the end of that UTC day), or at the transaction's\n`createdAt` when that is null, so a card that later moved to another company or legal entity keeps its\nhistorical attribution on past transactions.\nTransactions themselves do not carry a company identifier.\n\nTo list the transactions of one company or legal entity, filter with `companyId`, `legalEntityId` or\n`legalEntityName`. They match the cardholder's `corporate.id`, `corporate.legalEntity.id` and\n`corporate.legalEntity.name` on the transaction date: the values `expand=cardholder` returns on each\ntransaction, not the cardholder's current ones (see the [Glossary](https://docs.astrada.co/docs/glossary)).\nEach is an exact, case-sensitive match, so copy the value from a transaction's `expand=cardholder`.\nThe filters use the same as-of resolution as `expand=cardholder`, including the earliest recorded values\nfor a transaction dated before Astrada started recording the card's corporate history. A transaction\nwhose card has no cardholder data, or whose card `GET /cards/{cardId}` no longer returns, does not match, just\nas `expand` embeds no `cardholder` for it.\nThey combine with each other and with `transactionMessageId`, `cardId`, `subaccountId` and\n`networkBulkFeedId`: supplying more than one returns only the transactions matching **all** of them.\nTransactions without a card never match. For example, this returns one legal entity's transactions on\none feed:\n\n`GET /transactions?networkBulkFeedId=<feed>&legalEntityId=<id>`\n\nURL-encode the values. In `legalEntityName` a space is `%20` (or `+`), and a literal `+` is read as a\nspace, so send a `+` in the name as `%2B`. Send each filter once. Leading and trailing spaces are\nignored. A value that is empty or only spaces, or longer than 255 characters, is refused with `400`.\n\nWith any of these filters a page can hold fewer than `limit` transactions, even none, while\n`_links.next` is present. Keep following `_links.next` until it is absent.\n\nThese three filters read cardholder data, so they need the `cardholder:read` scope, like\n`expand=cardholder`. Without it the request returns `403`.\n","operationId":"GetTransactions","parameters":[{"$ref":"#/components/parameters/transaction-message-id"},{"$ref":"#/components/parameters/subaccount-id"},{"$ref":"#/components/parameters/cursor"},{"$ref":"#/components/parameters/card-id"},{"$ref":"#/components/parameters/network-bulk-feed-id"},{"$ref":"#/components/parameters/transaction-company-id"},{"$ref":"#/components/parameters/transaction-legal-entity-id"},{"$ref":"#/components/parameters/transaction-legal-entity-name"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/order"},{"$ref":"#/components/parameters/expand-transaction"}],"security":[{"main-auth":["transactions:read"]}],"responses":{"200":{"description":"Transactions retrieved successfully","content":{"application/hal+json":{"schema":{"type":"object","required":["_links","_embedded"],"properties":{"_links":{"type":"object","required":["self"],"properties":{"self":{"$ref":"#/components/schemas/link"},"next":{"$ref":"#/components/schemas/link"}}},"_embedded":{"type":"object","required":["transactions"],"properties":{"transactions":{"type":"array","items":{"$ref":"#/components/schemas/transaction"}}}}}},"examples":{"Example List Transactions Response":{"value":{"_links":{"self":{"href":"/transactions"}},"_embedded":{"transactions":[{"_links":{"messages":[{"href":"/transaction-messages/f4b24a0a-6a37-4ce3-8845-ddf0b604a9b4"},{"href":"/transaction-messages/934f8701-53e3-4a2b-a000-6bb52195d2ea"}],"card":{"href":"/subaccounts/f4b24a0a-6a37-4ce3-8845-ddf0b604a9b6"},"subaccount":{"href":"/subaccounts/f4b24a0a-6a37-4ce3-8845-ddf0b604a9b5"},"self":{"href":"/transactions/f4b24a0a-6a37-4ce3-8845-ddf0b604a9b4"}},"acceptor":{"city":"LONDON","country":"GBR","mcc":"5734","state":"LND"},"cardId":"4d1ff59f-4286-4209-9662-92e174193562","cardholderBillingCurrency":"GBP","cardholderBillingHoldAmount":0,"cardholderBillingSettledAmount":0.81,"createdAt":"2024-05-01T06:41:43.810Z","descriptor":"Uber","id":"8697df0c-9011-47ca-a52b-8d2a7a4ad903","network":"MASTERCARD","networkBulkFeedId":"2fd4d402-b759-479c-87a6-58d85e345356","status":"SETTLED","subaccountId":"c6d5e036-361e-4773-a514-b9496cf2d2b5","supersededMessageIds":[],"transactionCurrency":"USD","transactionHoldAmount":0,"transactionOccurrenceDate":"2024-05-01","transactionSettledAmount":1,"transactionType":"DEBIT_01","updatedAt":"2024-05-02T08:41:43.810Z"}]}}},"Example List Transactions Response with expand=cardSubscription":{"value":{"_links":{"self":{"href":"/transactions?expand=cardSubscription"}},"_embedded":{"transactions":[{"_links":{"card":{"href":"/cards/4d1ff59f-4286-4209-9662-92e174193562"},"subaccount":{"href":"/subaccounts/c6d5e036-361e-4773-a514-b9496cf2d2b5"},"self":{"href":"/transactions/8697df0c-9011-47ca-a52b-8d2a7a4ad903"},"messages":[{"href":"/transaction-messages/f4b24a0a-6a37-4ce3-8845-ddf0b604a9b4"},{"href":"/transaction-messages/934f8701-53e3-4a2b-a000-6bb52195d2ea"}]},"_embedded":{"cardSubscription":{"_links":{"self":{"href":"/card-subscriptions/75ea3c99-6bf5-4b16-8f68-0cdc43d75806"},"card":{"href":"/cards/4d1ff59f-4286-4209-9662-92e174193562"},"networkBulkFeed":{"href":"/network-bulk-feeds/2fd4d402-b759-479c-87a6-58d85e345356"}},"id":"75ea3c99-6bf5-4b16-8f68-0cdc43d75806","subaccountId":"c6d5e036-361e-4773-a514-b9496cf2d2b5","cardId":"4d1ff59f-4286-4209-9662-92e174193562","customerReferenceId":null,"networkBulkFeedId":"2fd4d402-b759-479c-87a6-58d85e345356","bankAccountId":null,"enrollmentType":"network-bulk","state":"active","effectiveDate":"2024-04-01T00:00:00Z","expirationDate":"2027-04-01T00:00:00Z","createdAt":"2024-03-31T14:45:00Z","updatedAt":"2024-03-31T14:45:00Z"}},"acceptor":{"city":"LONDON","country":"GBR","mcc":"5734","state":"LND"},"cardId":"4d1ff59f-4286-4209-9662-92e174193562","cardholderBillingCurrency":"GBP","cardholderBillingHoldAmount":0,"cardholderBillingSettledAmount":0.81,"createdAt":"2024-05-01T06:41:43.810Z","descriptor":"Uber","id":"8697df0c-9011-47ca-a52b-8d2a7a4ad903","network":"MASTERCARD","networkBulkFeedId":"2fd4d402-b759-479c-87a6-58d85e345356","status":"SETTLED","subaccountId":"c6d5e036-361e-4773-a514-b9496cf2d2b5","supersededMessageIds":[],"transactionCurrency":"USD","transactionHoldAmount":0,"transactionOccurrenceDate":"2024-05-01","transactionSettledAmount":1,"updatedAt":"2024-05-02T08:41:43.810Z"}]}}},"Example List Transactions Response with expand=cardSubscription,card,cardholder":{"value":{"_links":{"self":{"href":"/transactions?expand=cardSubscription,card,cardholder"}},"_embedded":{"transactions":[{"_links":{"card":{"href":"/cards/4d1ff59f-4286-4209-9662-92e174193562"},"subaccount":{"href":"/subaccounts/c6d5e036-361e-4773-a514-b9496cf2d2b5"},"self":{"href":"/transactions/8697df0c-9011-47ca-a52b-8d2a7a4ad903"},"messages":[{"href":"/transaction-messages/f4b24a0a-6a37-4ce3-8845-ddf0b604a9b4"},{"href":"/transaction-messages/934f8701-53e3-4a2b-a000-6bb52195d2ea"}]},"_embedded":{"cardSubscription":{"_links":{"self":{"href":"/card-subscriptions/75ea3c99-6bf5-4b16-8f68-0cdc43d75806"},"card":{"href":"/cards/4d1ff59f-4286-4209-9662-92e174193562"},"networkBulkFeed":{"href":"/network-bulk-feeds/2fd4d402-b759-479c-87a6-58d85e345356"}},"id":"75ea3c99-6bf5-4b16-8f68-0cdc43d75806","subaccountId":"c6d5e036-361e-4773-a514-b9496cf2d2b5","cardId":"4d1ff59f-4286-4209-9662-92e174193562","customerReferenceId":null,"networkBulkFeedId":"2fd4d402-b759-479c-87a6-58d85e345356","bankAccountId":null,"enrollmentType":"network-bulk","state":"active","effectiveDate":"2024-04-01T00:00:00Z","expirationDate":"2027-04-01T00:00:00Z","createdAt":"2024-03-31T14:45:00Z","updatedAt":"2024-03-31T14:45:00Z"},"card":{"_links":{"self":{"href":"/cards/4d1ff59f-4286-4209-9662-92e174193562"},"cardholder":{"href":"/cards/4d1ff59f-4286-4209-9662-92e174193562/cardholder"}},"id":"4d1ff59f-4286-4209-9662-92e174193562","subaccountId":"c6d5e036-361e-4773-a514-b9496cf2d2b5","expiryMonth":11,"expiryYear":2028,"network":"mastercard","country":"GBR","first6digits":"434343","last4digits":"4343","createdAt":"2024-03-31T14:40:00Z","updatedAt":"2024-03-31T14:40:00Z"},"cardholder":{"_links":{"self":{"href":"/cards/4d1ff59f-4286-4209-9662-92e174193562/cardholder"}},"firstName":"John","lastName":"Doe","email":"john.doe@example.com","postalCode":"SW1A 1AA","corporate":{"alternativeEmployeeId":"ALT-EMP-12345","employeeId":"bb1afe4eb840","id":"ABC123456789","legalEntity":{"id":"FR01","name":"Example Company France SAS"}},"createdAt":"2024-03-31T14:45:00Z","updatedAt":"2024-03-31T14:45:00Z"}},"acceptor":{"city":"LONDON","country":"GBR","mcc":"5734","state":"LND"},"cardId":"4d1ff59f-4286-4209-9662-92e174193562","cardholderBillingCurrency":"GBP","cardholderBillingHoldAmount":0,"cardholderBillingSettledAmount":0.81,"createdAt":"2024-05-01T06:41:43.810Z","descriptor":"Uber","id":"8697df0c-9011-47ca-a52b-8d2a7a4ad903","network":"MASTERCARD","networkBulkFeedId":"2fd4d402-b759-479c-87a6-58d85e345356","status":"SETTLED","subaccountId":"c6d5e036-361e-4773-a514-b9496cf2d2b5","supersededMessageIds":[],"transactionCurrency":"USD","transactionHoldAmount":0,"transactionOccurrenceDate":"2024-05-01","transactionSettledAmount":1,"updatedAt":"2024-05-02T08:41:43.810Z"}]}}}}}}},"400":{"$ref":"#/components/responses/bad-request"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/not-found"},"500":{"$ref":"#/components/responses/server-error"}}}},"/transactions/{transactionId}":{"parameters":[{"$ref":"#/components/parameters/transaction-id"}],"get":{"parameters":[{"$ref":"#/components/parameters/expand-transaction"}],"tags":["transactions"],"summary":"Retrieve transaction","description":"Returns a transaction by its unique identifier, including details about the transaction's state and relevant transactional data.\n\nAdd `expand` to embed related resources under `_embedded` in the same response, for example\n`expand=cardSubscription,card,cardholder`. Each embedded resource is the exact body its own endpoint\nserves, shows its current values (not those at the time of the transaction) except\n`cardholder.corporate`, which is resolved as of the transaction's date (see the `expand` parameter), and\nrequires that endpoint's scope: `card-subscriptions:read` for `cardSubscription`, `cards:read` for `card`,\n`cardholder:read` for `cardholder`.\n\nFor the company and legal entity a card belonged to when the transaction happened, use `expand=cardholder`\nand read `cardholder.corporate.id` and `cardholder.corporate.legalEntity`. They are the values in effect on\nthe transaction's `transactionOccurrenceDate` (through the end of that UTC day), or at the transaction's\n`createdAt` when that is null, so a card that later moved to another company or legal entity keeps its\nhistorical attribution on past transactions.\nTransactions themselves do not carry a company identifier.\n","operationId":"GetTransactionById","security":[{"main-auth":["transactions:read"]}],"responses":{"200":{"description":"Transaction retrieved successfully","content":{"application/hal+json":{"schema":{"$ref":"#/components/schemas/transaction"},"examples":{"Example Get Transaction Response":{"$ref":"#/components/examples/transaction"},"Example Get Transaction Response with expand=cardSubscription":{"$ref":"#/components/examples/transaction-expanded"},"Example Get Transaction Response with expand=cardSubscription,card,cardholder":{"$ref":"#/components/examples/transaction-expanded-card-cardholder"}}}}},"400":{"$ref":"#/components/responses/bad-request"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/not-found"},"500":{"$ref":"#/components/responses/server-error"}}}},"/transaction-messages/{transactionMessageId}":{"parameters":[{"$ref":"#/components/parameters/transaction-message-id-2"}],"get":{"tags":["transaction-messages"],"summary":"Retrieve transaction message","description":"Return a transaction message by its unique identifier, including details about the transaction's type and relevant transactional data.\n\nTransaction messages are also delivered embedded in the transaction payload: `transaction.created` and `transaction.updated` webhook payloads include a projection of every correlated message under `_embedded.messages[]`, each entry carrying its financial fields plus a per-message `superseded` marker. See [Event Types](https://docs.astrada.co/reference/event-types) for the full payload structure.\n","operationId":"GetTransactionMessageById","security":[{"main-auth":["transaction-messages:read"]}],"responses":{"200":{"description":"Transaction message retrieved successfully","content":{"application/hal+json":{"schema":{"$ref":"#/components/schemas/transaction-message"},"examples":{"Example Get Transaction Message Response":{"$ref":"#/components/examples/transaction-message"}}}}},"400":{"$ref":"#/components/responses/bad-request"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/not-found"},"500":{"$ref":"#/components/responses/server-error"}}}},"/transaction-messages/{transactionMessageId}/raw":{"parameters":[{"$ref":"#/components/parameters/transaction-message-id-2"}],"get":{"tags":["transaction-messages"],"summary":"Retrieve the raw transaction message","description":"Return a raw transaction message by the transaction message unique identifier.","operationId":"GetRawTransactionMessageById","security":[{"main-auth":["transaction-messages:read"]}],"responses":{"200":{"description":"Raw transaction message retrieved successfully","content":{"application/hal+json":{"schema":{"$ref":"#/components/schemas/raw-transaction-message"},"examples":{"Example Get Raw Transaction Message Response":{"$ref":"#/components/examples/raw-transaction-message"}}}}},"204":{"$ref":"#/components/responses/no-content"},"400":{"$ref":"#/components/responses/bad-request"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/not-found"},"500":{"$ref":"#/components/responses/server-error"}}}},"/webhooks":{"post":{"tags":["webhooks"],"summary":"Create webhook","description":"Registers a new webhook for capturing event notifications.","operationId":"createWebhook","security":[{"main-auth":["webhooks:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","format":"uri"},"description":{"type":"string"},"eventTypes":{"$ref":"#/components/schemas/webhook-event-types"},"subaccountId":{"type":"string","format":"uuid"},"enabled":{"type":"boolean","default":true}},"required":["url","eventTypes","subaccountId"]},"examples":{"Card transaction events":{"value":{"url":"https://example-api.com/path","description":"Example of Webhook description","eventTypes":["transactionmessage.created"],"subaccountId":"f297d659-c13d-4219-aeaa-e10a845140a5"}},"Bank linking events":{"value":{"url":"https://example-api.com/bank-events","description":"Bank linking lifecycle and bank-record events","eventTypes":["banklink.completed","bankaccount.state_changed","banktransaction.created","transaction.match.created"],"subaccountId":"f297d659-c13d-4219-aeaa-e10a845140a5"}}}}}},"responses":{"201":{"description":"Successful operation","content":{"application/hal+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/webhook"},{"type":"object","properties":{"secret":{"type":"string","description":"Only returned on Webhook creation"}},"required":["secret"]}]},"examples":{"Example Create Webhook Response":{"value":{"_links":{"self":{"href":"/webhooks/3a45ba7f-8d8f-4f6a-86a5-a17ea0328241"}},"id":"3a45ba7f-8d8f-4f6a-86a5-a17ea0328241","url":"https://example-api.com/path","description":"Example of Webhook description","eventTypes":["transactionmessage.created"],"subaccountId":"f297d659-c13d-4219-aeaa-e10a845140a5","createdAt":"2023-12-19T14:45:00Z","updatedAt":"2023-12-19T14:45:00Z","enabled":true,"secret":"ODk4ZDAxYjYtZjM4NC00MzdmLWEzMDMtM2M0NjA1NWY5NTQ5"}}}}}},"400":{"$ref":"#/components/responses/bad-request"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/not-found"},"500":{"$ref":"#/components/responses/server-error"}}},"get":{"parameters":[{"$ref":"#/components/parameters/subaccount-id"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/cursor"}],"tags":["webhooks"],"summary":"List webhooks","description":"Returns all webhooks configured under the account, optionally filtered by subaccount, including details on the events each webhook is subscribed to.\n\nThis endpoint supports [cursor-based pagination](https://docs.astrada.co/reference/pagination).\n","operationId":"listWebhooks","security":[{"main-auth":["webhooks:read"]}],"responses":{"200":{"description":"Successful operation","content":{"application/hal+json":{"schema":{"type":"object","additionalProperties":false,"description":"Astrada's Webhook resources.","required":["_links","_embedded"],"properties":{"_links":{"type":"object","properties":{"self":{"$ref":"#/components/schemas/link"},"next":{"$ref":"#/components/schemas/link"}}},"_embedded":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/webhook"}}}}}},"examples":{"Example List Webhooks Response":{"value":{"_links":{"self":{"href":"/webhooks"}},"_embedded":{"webhooks":[{"_links":{"self":{"href":"/webhooks/3a45ba7f-8d8f-4f6a-86a5-a17ea0328241"}},"id":"3a45ba7f-8d8f-4f6a-86a5-a17ea0328241","url":"https://example-api.com/path","description":"Example of Webhook description","eventTypes":["transactionmessage.created"],"subaccountId":"f297d659-c13d-4219-aeaa-e10a845140a5","createdAt":"2023-12-19T14:45:00Z","updatedAt":"2023-12-19T14:45:00Z","enabled":true},{"_links":{"self":{"href":"/webhooks/627f9c6d-ec9f-4118-84f3-97a77f447e32"}},"id":"627f9c6d-ec9f-4118-84f3-97a77f447e32","url":"https://example-api.com/path","description":"Example of Webhook description","eventTypes":["transactionmessage.created"],"subaccountId":"f297d659-c13d-4219-aeaa-e10a845140a5","createdAt":"2023-12-19T14:46:00Z","updatedAt":"2023-12-19T14:46:00Z","enabled":true}]}}},"Example no Webhooks found":{"value":{"_links":{"self":{"href":"/webhooks"}},"_embedded":{"webhooks":[]}}}}}}},"400":{"$ref":"#/components/responses/bad-request"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"500":{"$ref":"#/components/responses/server-error"}}}},"/webhooks/{webhookId}":{"parameters":[{"$ref":"#/components/parameters/webhook-id"}],"get":{"tags":["webhooks"],"summary":"Retrieve webhook","description":"Returns detailed information about a specific webhook by its identifier, including its configuration and event subscription details.","operationId":"getWebhook","security":[{"main-auth":["webhooks:read"]}],"responses":{"200":{"description":"Successful operation","content":{"application/hal+json":{"schema":{"$ref":"#/components/schemas/webhook"},"examples":{"Example Get Webhook Response":{"$ref":"#/components/examples/webhook"}}}}},"400":{"$ref":"#/components/responses/bad-request"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/not-found"},"500":{"$ref":"#/components/responses/server-error"}}},"patch":{"tags":["webhooks"],"summary":"Update webhook","description":"Updates the configuration of an existing webhook, allowing changes to the event subscriptions or notification URL.","operationId":"updateWebhook","security":[{"main-auth":["webhooks:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","minProperties":1,"properties":{"url":{"type":"string","format":"uri"},"description":{"type":"string"},"eventTypes":{"$ref":"#/components/schemas/webhook-event-types"},"enabled":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Successful operation","content":{"application/hal+json":{"schema":{"$ref":"#/components/schemas/webhook"},"examples":{"Example Update Webhook Response":{"$ref":"#/components/examples/webhook"}}}}},"400":{"$ref":"#/components/responses/bad-request"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/not-found"},"500":{"$ref":"#/components/responses/server-error"}}},"delete":{"tags":["webhooks"],"summary":"Delete webhook","description":"Remove a configured webhook by its identifier. Results in the resource being deleted and no longer available.","operationId":"deleteWebhook","security":[{"main-auth":["webhooks:write"]}],"responses":{"204":{"description":"Successful operation"},"400":{"$ref":"#/components/responses/bad-request"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/not-found"},"500":{"$ref":"#/components/responses/server-error"}}}},"/bank-links/{bankLinkId}":{"parameters":[{"$ref":"#/components/parameters/bank-link-id"}]},"/bank-links/{bankLinkId}/webhook":{"parameters":[{"$ref":"#/components/parameters/bank-link-id"}]},"/bank-links/{bankLinkId}/sync":{"parameters":[{"$ref":"#/components/parameters/bank-link-id"}]},"/bank-accounts/{bankAccountId}":{"parameters":[{"$ref":"#/components/parameters/bank-account-id-2"}]},"/bank-accounts/{bankAccountId}/backfill":{"parameters":[{"$ref":"#/components/parameters/bank-account-id-2"}]},"/bank-accounts/{bankAccountId}/refresh":{"parameters":[{"$ref":"#/components/parameters/bank-account-id-2"}]},"/bank-accounts/{bankAccountId}/transactions/refresh":{"parameters":[{"$ref":"#/components/parameters/bank-account-id-2"}]},"/bank-subscriptions/{bankSubscriptionId}":{"parameters":[{"$ref":"#/components/parameters/bank-subscription-id"}]},"/bank-subscriptions/by-connection/{connectionId}":{"parameters":[{"$ref":"#/components/parameters/connection-id"}]},"/bank-subscriptions/{bankSubscriptionId}/webhook":{"parameters":[{"$ref":"#/components/parameters/bank-subscription-id"}]},"/bank-transactions/{subaccountId}":{"parameters":[{"$ref":"#/components/parameters/subaccount-id-2"}]},"/bank-transactions/{subaccountId}/{transactionId}":{"parameters":[{"$ref":"#/components/parameters/subaccount-id-2"},{"$ref":"#/components/parameters/transaction-id"}]},"/bank-transactions/{subaccountId}/webhooks":{"parameters":[{"$ref":"#/components/parameters/subaccount-id-2"}]},"/transaction-matches/{subaccountId}":{"parameters":[{"$ref":"#/components/parameters/subaccount-id-2"}]},"/transaction-matches/{subaccountId}/{transactionMatchId}":{"parameters":[{"$ref":"#/components/parameters/subaccount-id-2"},{"$ref":"#/components/parameters/transaction-match-id"}]},"/bin-lookup":{"parameters":[{"$ref":"#/components/parameters/bin-required"}],"get":{"tags":["bin-lookup"],"summary":"Lookup card information by BIN","description":"Retrieve card information such as network, type, and issuing bank by providing the card's\nBIN (Bank Identification Number): the first 6 to 11 digits of the card number. Never send\nthe full card number; more than 11 digits is rejected with `400`.\n\nThe card details are found under the first 6 digits. One 6-digit BIN can be shared by\nissuers in several countries, so for a Mastercard card looked up with 6 to 11 digits,\nAstrada also runs a more precise issuer-country check on the digits sent. That check can\nreturn a different `issuerCountry`, `issuerRegion` and `issuerName` than the first 6\ndigits alone would. Send more digits (up to 11) for a more precise issuer country; never\nsend the full card number.\n\nWhen the digits sent match card ranges in more than one country, the response keeps the\n6-digit values and adds `issuerCountryAmbiguous`, `issuerCountryCandidates`, and a\n`warnings` entry with code `ISSUER_COUNTRY_NOT_CONFIRMED`. In every other case none of\nthese three fields is present.\n\nLookups for every other network are unaffected. If the precise check gives no answer, the\nrequest still succeeds with the 6-digit values. In sandbox the precise check is not run,\nso sandbox responses never include these fields.\n","security":[{"main-auth":["cards:read"]}],"operationId":"BinLookup","responses":{"200":{"description":"Successful operation","content":{"application/hal+json":{"schema":{"$ref":"#/components/schemas/bin-lookup"},"examples":{"Example Bin Lookup Response":{"$ref":"#/components/examples/bin-lookup"},"Mastercard, 11 digits, precise issuer country":{"$ref":"#/components/examples/bin-lookup-precise"},"Mastercard, fewer than 11 digits, several possible countries":{"$ref":"#/components/examples/bin-lookup-ambiguous"},"Mastercard, 11 digits, several possible countries":{"$ref":"#/components/examples/bin-lookup-ambiguous-11-digit"}}}}},"400":{"description":"The `bin` is not 6 to 11 digits (too short, too long, or not digits only).\n","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/common-error"},{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"instance":{"type":"string"},"title":{"type":"string"},"detail":{"type":"string"}},"required":["title","detail"]}}}}]},"examples":{"Invalid bin":{"value":{"title":"Bad Request","detail":"Request parameters are invalid","errors":[{"instance":"/bin","title":"Invalid Parameter","detail":"bin must be between 6 and 11 digits"}]}}}}}},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/not-found"},"500":{"$ref":"#/components/responses/server-error"}}}},"/simulate/transactions/{transactionId}":{"parameters":[{"$ref":"#/components/parameters/transaction-id"}]}},"components":{"securitySchemes":{"main-auth":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.sandbox.astrada.co/auth/realms/{accountId}/protocol/openid-connect/token","scopes":{"accounts:write":"Accounts write resource","accounts:read":"Accounts read resource","subaccounts:write":"Subaccounts write resource","subaccounts:read":"Subaccounts read resource","card-connector-data-links:write":"card-connector-data-link resource","card-connector-consents:read":"Card Consent read resource","card-connector-consents:write":"Card Consent write resource","webhooks:read":"Read Webhook resources","webhooks:write":"Write Webhook resources","card-subscriptions:write":"Create card subscription","card-subscriptions:read":"Read card subscription","card-verifications:write":"Create card verification","card-verifications:read":"Read Card verification","cards:read":"Read Card resources","cardholder:read":"Read Cardholder resources","cardholder:write":"Write Cardholder resources","transactions:read":"Read Transaction resources","transaction-messages:read":"Read Transaction Message resources","network-bulk-feeds:read":"Read network bulk feed","network-bulk-feeds:write":"Write network bulk feed","network-bulk-enrollments:read":"Read network bulk enrollment","network-bulk-enrollments:write":"Write network bulk enrollment and confirmation, and check for an open enrollment","network-links:write":"Write network link","enrollment-methods:write":"Write enrollment methods","simulation:write":"Write sandbox simulations","banking:read":"Read banking resources","banking:write":"Write banking resources","banking:admin":"Admin banking operations","appstore:enrollment:write":"Enroll cards via the appstore B2C flow","appstore:cards:read":"View enrolled cards in the appstore","appstore:transactions:read":"View synced transactions in the appstore","appstore:transactions:sync":"Trigger transaction sync in the appstore","appstore:sessions:read":"Read appstore session state","appstore:sessions:write":"Write or delete appstore session state","appstore:tokens:read":"Read appstore stored tokens and connections","appstore:tokens:write":"Write appstore stored tokens and connections"}}}}},"parameters":{"account":{"in":"header","name":"Account","description":"The Astrada account identifier in the context of the request. Only present and required on service-to-service requests","schema":{"type":"string","format":"uuid"},"required":true},"subscription-id":{"in":"path","name":"subscriptionId","required":true,"schema":{"type":"string","format":"uuid"},"example":"eb2ded7e-11fa-46fc-bd3e-f5b1d56fd3b3"},"network-link-id":{"in":"path","name":"networkLinkId","required":true,"schema":{"type":"string","format":"uuid"},"example":"eb2ded7e-11fa-46fc-bd3e-f5b1d56fd3b3"},"subaccount-id":{"in":"query","name":"subaccountId","required":false,"schema":{"type":"string","format":"uuid"},"example":"2fd4d402-b759-479c-87a6-58d85e345356"},"card-id":{"in":"query","name":"cardId","required":false,"schema":{"type":"string","format":"uuid"},"example":"8164683a-8d23-4421-9694-1a81fc9b9c37"},"bank-account-id":{"in":"query","name":"bankAccountId","required":false,"description":"Filter to subscriptions whose card materialized from this bank account (bank-derived subscriptions).","schema":{"type":"string","format":"uuid"},"example":"2b9c1e77-5a3d-4c8b-9f21-6d0e4a7b8c90"},"card-subscription-state":{"in":"query","name":"state","required":false,"schema":{"type":"string","enum":["pending","active","deactivated","expired","reqSCA","failed-to-create"]},"example":"active"},"network-bulk-feed-id":{"in":"query","name":"networkBulkFeedId","required":false,"schema":{"type":"string","format":"uuid"},"example":"2fd4d402-b759-479c-87a6-58d85e345356"},"company-id":{"in":"query","name":"companyId","required":false,"description":"Only subscriptions whose card's cardholder currently has this company ID (`corporate.id`), not the value it had when the subscription was created. Exact match. Requires the `cardholder:read` scope.\n","schema":{"type":"string","minLength":1,"maxLength":255},"example":"10021528"},"legal-entity-id":{"in":"query","name":"legalEntityId","required":false,"description":"Only subscriptions whose card's cardholder currently belongs to this legal entity (`corporate.legalEntity.id`), not the one it belonged to when the subscription was created. Exact match. A cardholder whose legal entity has no id never matches this filter; filter by `legalEntityName` instead. Requires the `cardholder:read` scope.\n","schema":{"type":"string","minLength":1,"maxLength":255},"example":"1000001"},"legal-entity-name":{"in":"query","name":"legalEntityName","required":false,"description":"Only subscriptions whose card's cardholder currently belongs to a legal entity with this name (`corporate.legalEntity.name`), not the one it belonged to when the subscription was created. Exact, case-sensitive match. A cardholder whose legal entity has no name never matches this filter; filter by `legalEntityId` instead. URL-encode the value: a space is `%20` (or `+`), for example `legalEntityName=Astrada%20Life`. Requires the `cardholder:read` scope.\n","schema":{"type":"string","minLength":1,"maxLength":255},"example":"Astrada Life"},"limit":{"in":"query","name":"limit","description":"Maximum number of items to return","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"example":25},"offset":{"in":"query","name":"offset","description":"The offset to use for pagination. Identifies the position of the first item returned in the collection","required":false,"schema":{"type":"number","default":0},"example":20},"expand-card-subscription":{"in":"query","name":"expand","required":false,"description":"Comma-separated list of related resources to embed on each card subscription under `_embedded`, so one call returns\nthe subscription together with its card and cardholder instead of a `GET /cards/{cardId}` and a\n`GET /cards/{cardId}/cardholder` per item.\n\n- `card` embeds the card exactly as `GET /cards/{cardId}` serves it and requires the `cards:read` scope.\n- `cardholder` embeds the cardholder exactly as `GET /cards/{cardId}/cardholder` serves it and requires the\n  `cardholder:read` scope.\n\nA request naming a resource its credentials cannot read is refused with `403`. When a related resource does not\nexist (for example a card without cardholder data), its key is absent from `_embedded`; `_links` are unchanged.\n\nSend one comma-separated value (`expand=card,cardholder`). A repeated `expand` key, an empty value or an unknown\nvalue is refused with `400`.\n","schema":{"type":"array","items":{"type":"string","enum":["card","cardholder"]}},"style":"form","explode":false,"example":["card","cardholder"]},"connector-name":{"in":"header","name":"Connector-Name","description":"The connector name to activate a card connector data link","schema":{"type":"string","enum":["smartdata"]},"required":true},"card-id.required":{"in":"query","name":"cardId","required":true,"schema":{"type":"string","format":"uuid"},"example":"8164683a-8d23-4421-9694-1a81fc9b9c37"},"verification-id":{"in":"path","name":"verificationId","required":true,"schema":{"type":"string","format":"uuid"},"example":"9cac38a2-6584-4c1f-92fd-85223774979b"},"country":{"in":"query","name":"country","description":"The card country of issuance following ISO 3166 alpha-3","required":false,"schema":{"type":"string","enum":["USA","CAN","AUS","NZL","PRT","BEL","SGP"]},"example":"USA"},"expiry-month":{"in":"query","name":"expiryMonth","description":"The card expiration month","required":false,"schema":{"type":"integer","minimum":1,"maximum":12},"example":6},"expiry-year":{"in":"query","name":"expiryYear","description":"The card expiration year","required":false,"schema":{"type":"integer"},"example":2024},"expand-card":{"in":"query","name":"expand","required":false,"description":"Embed the card's related `cardholder` resource under `_embedded` so one call returns the card\ntogether with its cardholder instead of a follow-up `GET /cards/{cardId}/cardholder`.\n\n- `cardholder` embeds the cardholder exactly as `GET /cards/{cardId}/cardholder` serves it and\n  requires the `cardholder:read` scope.\n\nA request asking to expand a resource its credentials cannot read is refused with `403`\n(`Missing scope 'cardholder:read'`). When the cardholder does not exist (for example a card that\nwas not bulk-enrolled), the `cardholder` key is absent from `_embedded`; `_links` are unchanged.\n\nSend `expand=cardholder`. A repeated `expand` key, an empty value or an unknown value is refused\nwith `400`.\n","schema":{"type":"array","items":{"type":"string","enum":["cardholder"]}},"style":"form","explode":false,"example":["cardholder"]},"card-id-2":{"in":"path","name":"cardId","required":true,"schema":{"type":"string","format":"uuid"},"example":"6d18f5bb-b9d6-4237-97c2-44b1bdb71d6b"},"link-id":{"in":"path","name":"linkId","description":"The enrollment link's identifier, the `id` returned when the link was created.","required":true,"schema":{"type":"string","format":"uuid"},"example":"1d0a6c52-8f3e-4b7a-9c21-5e4d3b2a1f09"},"network-reference":{"in":"query","name":"networkReference","description":"Filters the returned feeds to an exact match on the feed's network reference. The network reference format depends on the card network (see the schema below).\n","required":false,"schema":{"$ref":"#/components/schemas/network-reference"},"example":"G1234567"},"network-bulk-feed-id-2":{"in":"path","name":"networkBulkFeedId","required":true,"schema":{"type":"string","format":"uuid"},"example":"eb2ded7e-11fa-46fc-bd3e-f5b1d56fd3b3"},"network-bulk-enrollment-id":{"in":"path","name":"networkBulkEnrollmentId","required":true,"schema":{"type":"string","format":"uuid"},"example":"9c1f0c4e-2f0e-4a9c-9a1b-0c1d2e3f4a5b"},"subaccount-id-2":{"in":"path","name":"subaccountId","required":true,"schema":{"type":"string","format":"uuid"},"example":"24c4f90d-ab3b-4f6e-8a1d-d251a4fcf34c"},"cursor":{"in":"query","name":"cursor","required":false,"description":"The cursor to use for pagination. Identifies your place on the list","schema":{"type":"string","format":"byte"},"example":"ZXhhbXBsZQ=="},"transaction-message-id":{"in":"query","name":"transactionMessageId","required":false,"schema":{"type":"string","format":"uuid"},"example":"9a88aa0e-c1d3-4e70-b5e1-45ab64eb5aac"},"transaction-company-id":{"in":"query","name":"companyId","required":false,"description":"Only transactions whose card's cardholder had this company ID (`corporate.id`) on the transaction date (the value `expand=cardholder` returns on that transaction; the `expand` parameter defines the date), not the cardholder's current company. Exact, case-sensitive match. Requires the `cardholder:read` scope.\n","schema":{"type":"string","minLength":1,"maxLength":255},"example":"10021528"},"transaction-legal-entity-id":{"in":"query","name":"legalEntityId","required":false,"description":"Only transactions whose card's cardholder belonged to this legal entity (`corporate.legalEntity.id`) on the transaction date (the value `expand=cardholder` returns on that transaction; the `expand` parameter defines the date), not the legal entity it belongs to now. Exact, case-sensitive match. Requires the `cardholder:read` scope.\n","schema":{"type":"string","minLength":1,"maxLength":255},"example":"1000001"},"transaction-legal-entity-name":{"in":"query","name":"legalEntityName","required":false,"description":"Only transactions whose card's cardholder belonged to a legal entity with this name (`corporate.legalEntity.name`) on the transaction date (the value `expand=cardholder` returns on that transaction; the `expand` parameter defines the date), not the legal entity it belongs to now. Exact, case-sensitive match. URL-encode the value: a space is `%20` (or `+`), for example `legalEntityName=Astrada%20Life`. A literal `+` is read as a space, so send a `+` in the name as `%2B`. Requires the `cardholder:read` scope.\n","schema":{"type":"string","minLength":1,"maxLength":255},"example":"Astrada Life"},"order":{"in":"query","name":"order","required":false,"schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"example":"desc"},"expand-transaction":{"in":"query","name":"expand","required":false,"description":"Comma-separated list of related resources to embed on the transaction under `_embedded`, so one call\nreturns the transaction together with its card subscription, card and cardholder instead of follow-up\ncalls to `GET /card-subscriptions?cardId=`, `GET /cards/{cardId}` and `GET /cards/{cardId}/cardholder`.\n\n- `cardSubscription` embeds the card subscription exactly as `GET /card-subscriptions/{subscriptionId}`\n  serves it (without its own `_embedded`) and requires the `card-subscriptions:read` scope.\n- `card` embeds the transaction's card exactly as `GET /cards/{cardId}` serves it (without its own\n  `_embedded`) and requires the `cards:read` scope.\n- `cardholder` embeds the card's cardholder as `GET /cards/{cardId}/cardholder` serves it, with one\n  difference: `corporate` is the cardholder's corporate as of the transaction (see below). Requires the\n  `cardholder:read` scope.\n\nEach value is checked separately: a request asking to expand a resource its credentials cannot read is\nrefused with `403`.\n\nThe embedded subscription is the card's subscription in the transaction's sub-account: the one from\nthe transaction's network bulk feed when the transaction has a `networkBulkFeedId`, otherwise the\ncard's current subscription, otherwise its most recent one.\n\n`cardSubscription` and `card` show their **current** values, not the values they had when the transaction\nhappened. So does the cardholder, except for `cardholder.corporate`: its `id`, `employeeId`,\n`alternativeEmployeeId` and `legalEntity` are the values in effect on the transaction's\n`transactionOccurrenceDate` (through the end of that UTC day), or at the transaction's `createdAt` when\n`transactionOccurrenceDate` is null. A card that moved to another company or legal entity after the\ntransaction therefore still shows the one it belonged to at the time. `firstName`, `lastName`, `email`,\n`postalCode`, `corporate.networkToken`, `createdAt` and `updatedAt` are the cardholder's current values. Changes\nare dated by when Astrada received them from the card network or through the API. For a transaction\ndated before Astrada started recording the card's corporate history, the earliest recorded values are\nreturned instead. Either way, a value that was not set in the values returned is null, or for\n`legalEntity` absent.\n\nA key is present only when it was requested and the related resource exists, and it is never null.\nA transaction with no card (`cardId` is null, for example a bank-sourced transaction with no linked\ncard) has no `cardSubscription`, `card` or `cardholder`. A card without cardholder data has no\n`cardholder`. A card that `GET /cards/{cardId}` no longer returns (it responds `404`, for example\nbecause all of its card subscriptions were deleted) is not embedded: both `card` and `cardholder` are\nabsent. `_links` are unchanged. Without `expand`, `_embedded` is absent. Whether `cardholder` is embedded\nis decided on the card and cardholder as they are now, not as of the transaction's date.\n\nSend one comma-separated value (`expand=cardSubscription,card,cardholder`). A repeated `expand` key,\nan empty value or an unknown value is refused with `400`.\n","schema":{"type":"array","items":{"type":"string","enum":["cardSubscription","card","cardholder"]}},"style":"form","explode":false,"example":["cardSubscription","card","cardholder"]},"transaction-id":{"in":"path","name":"transactionId","required":true,"schema":{"type":"string","format":"uuid"},"example":"9340721f-bdce-4afa-bd9d-26cceb9d2176"},"transaction-message-id-2":{"in":"path","name":"transactionMessageId","required":true,"schema":{"type":"string","format":"uuid"},"example":"9340721f-bdce-4afa-bd9d-26cceb9d2176"},"webhook-id":{"in":"path","name":"webhookId","required":true,"schema":{"type":"string","format":"uuid"},"example":"3c750084-a60f-478c-ab91-c53567d11fac"},"bank-link-id":{"in":"path","name":"bankLinkId","description":"The client-provided identifier of the bank link.","required":true,"schema":{"type":"string","minLength":1,"maxLength":256,"pattern":"^[a-zA-Z0-9_-]+$"},"example":"enrollment_792dcb7d"},"bank-account-id-2":{"in":"path","name":"bankAccountId","required":true,"schema":{"type":"string","format":"uuid"},"example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},"bank-subscription-id":{"in":"path","name":"bankSubscriptionId","required":true,"schema":{"type":"string","format":"uuid"},"example":"b2c3d4e5-f6a7-8901-bcde-f12345678901"},"connection-id":{"in":"path","name":"connectionId","required":true,"schema":{"type":"string"},"example":"conn_abc123def456"},"transaction-match-id":{"in":"path","name":"transactionMatchId","required":true,"schema":{"type":"string","format":"uuid"},"example":"c3d4e5f6-a7b8-9012-cdef-123456789012"},"bin-required":{"in":"query","name":"bin","required":true,"schema":{"type":"string","pattern":"^\\d{6,11}$","minLength":6,"maxLength":11},"description":"The first 6 to 11 digits of the card number. Send digits only, and never the full card\nnumber. Input that is shorter than 6 digits, longer than 11 digits, or contains anything\nother than digits is rejected with `400`; longer input is not truncated.\n\nFor a Mastercard card, send more digits (up to 11) for a more precise issuer country. 11\ndigits gives the most precise answer.\n","example":"55891900000"}},"schemas":{"link":{"type":"object","properties":{"href":{"type":"string"},"templated":{"type":"boolean"},"type":{"type":"string"},"deprecation":{"type":"string"},"name":{"type":"string"},"profile":{"type":"string"},"title":{"type":"string"},"hreflang":{"type":"string"}},"required":["href"]},"cardholder":{"type":"object","properties":{"_links":{"type":"object","required":["self"],"properties":{"self":{"$ref":"#/components/schemas/link"}}},"corporate":{"type":"object","description":"The company the cardholder belongs to, as the bank or card network supplies it in a network bulk feed, unless it was set with `PATCH /cards/{cardId}/cardholder`. See the [Glossary](https://docs.astrada.co/docs/glossary) for the terms used here.\n\nOn `GET /cards/{cardId}/cardholder` this is the current value. When the cardholder is embedded on a transaction (`expand=cardholder`, or the transaction webhooks), `corporate` is the value in effect on the transaction's `transactionOccurrenceDate` (through the end of that UTC day), or at the transaction's `createdAt` when that is null; the other cardholder fields stay current. The one exception inside `corporate` is `networkToken`, which is always the card's current value.\n","properties":{"alternativeEmployeeId":{"type":"string","nullable":true,"description":"An alternative employee identifier, typically configured for specific enterprise integrations."},"employeeId":{"type":"string","nullable":true,"description":"The unique identifier of the employee"},"id":{"type":"string","nullable":true,"description":"The **company ID**: the identifier the bank or card network gives the cardholder's company in the network bulk feed. Every card from the same company carries the same value, so it is the field to group cards by company.\n\n- **Visa (VCF and VBDS)**: the company ID, the `C` in the feed's RPIC network reference (`RegionId_ProcessorId_IssuerId_CompanyId`), always its last segment. For the feed `1_123_45_6789` (or the VCF PIC form `123_45_6789`), `corporate.id` is `6789`.\n- **Mastercard (SmartData)**: the company ID from the file, which Mastercard calls the corporation number.\n- **American Express**: the company ID, the 6-digit corporate ID (CID), such as `014640`. For a feed whose network reference is the CID, `corporate.id` is that same value.\n\n`null` when the feed does not supply one. The legal entity within the company is in `legalEntity`.\n"},"legalEntity":{"type":"object","readOnly":true,"description":"The legal entity the card belongs to in the card network's company hierarchy. Visa VCF: the hierarchy node directly under the root. Mastercard SmartData: the corporation the card is filed under. American Express: the legal company the card is issued under (the Basic Control Account is a division within a company, not a legal entity, and is not used here). Present only when the card network supplies one; absent otherwise, never null. `id` and `name` are each present only when the network supplies them, and at least one of them is always present. Once set it is kept until the network sends a new one. The same entity sent again with a field left out keeps that field: entities match on `id` when both have one, otherwise on `name`; a different entity replaces the stored one entirely. When the cardholder is embedded on a transaction, this is the value as of the transaction's date (see `corporate`).","properties":{"id":{"type":"string","minLength":1,"description":"The network's identifier for the legal entity, an opaque string. Present only when the network supplies one (Visa VCF currently always does; Mastercard SmartData files usually carry none and American Express files never do); absent otherwise, never null. Filter by `legalEntityName` when it is absent."},"name":{"type":"string","minLength":1,"description":"The legal entity's name as provided by the card network. Present only when the network supplies a name (Visa VCF and Mastercard SmartData currently always do; American Express sends the legal company name; when the file leaves it blank, `legalEntity` is omitted entirely); absent otherwise, never null. Filter by `legalEntityId` when it is absent."}},"minProperties":1},"networkToken":{"type":"string","minLength":1,"readOnly":true,"description":"The network token the card network issued for the card, for a tokenized American Express card. It is the same token the network sends you in its own files, so it is a stable identifier for matching the cardholder to your records. On these cards the card's `first6digits` and `last4digits` are the token's digits, not the physical card's. Present only for tokenized American Express cards; absent otherwise, never null. Always the card's current value, also when the cardholder is embedded on a transaction."}}},"firstName":{"type":"string","nullable":true,"description":"The first name of the cardholder"},"lastName":{"nullable":true,"type":"string","description":"The last name of the cardholder"},"email":{"type":"string","format":"email","nullable":true,"description":"Cardholder email address"},"postalCode":{"type":"string","nullable":true,"description":"Cardholder postal code as provided by the card network. Format varies by country; no validation or normalization is applied."},"createdAt":{"description":"Date and time when this resource was created, in UTC, following ISO 8601 format.","type":"string","format":"date-time"},"updatedAt":{"description":"Date and time when this resource was last updated, in UTC, following ISO 8601 format.","type":"string","format":"date-time"}},"required":["_links","corporate","createdAt","updatedAt"]},"card":{"type":"object","properties":{"_links":{"type":"object","required":["self"],"properties":{"self":{"$ref":"#/components/schemas/link"},"cardholder":{"$ref":"#/components/schemas/link"}}},"_embedded":{"type":"object","description":"Related resources inlined on request with the `expand` query parameter (`?expand=cardholder`).\nThe `cardholder` key is present only when it was requested and the cardholder exists; its body\nis identical to the one served by `GET /cards/{cardId}/cardholder`. Absent entirely when\n`expand` is not sent.\n","properties":{"cardholder":{"$ref":"#/components/schemas/cardholder"}}},"id":{"type":"string","format":"uuid","description":"The unique identifier of this card entity."},"subaccountId":{"type":"string","format":"uuid","description":"The unique identifier of the subaccount related to this entity."},"expiryMonth":{"type":"integer","minimum":1,"maximum":12,"description":"The month that the card will expire in MM format."},"expiryYear":{"type":"integer","description":"The year that the card will expire in YYYY format."},"first6digits":{"type":"string","nullable":true,"description":"The first 6 digits of the card number (PAN). Nullable for bank-derived cards\n(created from a bank connection, where the full PAN is never seen) — populated when\nknown (e.g. the SDK captured the BIN before pivoting to the bank flow) and attached\nwhen the card is later PAN-enrolled (upgrade-in-place keeps the same card id).\n"},"last4digits":{"type":"string","description":"The last 4 digits of the card number (PAN)."},"network":{"type":"string","nullable":true,"enum":["visa","mastercard","amex"],"description":"The card network that processes payments for this card. `amex` and `null` occur only\non bank-derived cards: Amex-institution connections mint `amex`; other institutions\ncannot reveal the network from bank data, so it stays `null` until the card is\nPAN-enrolled (upgrade-in-place).\n"},"country":{"type":"string","enum":["USA","CAN","GBR","SWE","ITA","AUS","NZL","PRT","BEL","SGP"],"description":"The country of issuance for this card following ISO 3166 alpha-3."},"createdAt":{"description":"Date and time when this resource was created, in UTC, following ISO 8601 format.","type":"string","format":"date-time"},"updatedAt":{"description":"Date and time when this resource was last updated, in UTC, following ISO 8601 format.","type":"string","format":"date-time"}},"required":["_links","id","subaccountId","expiryMonth","expiryYear","last4digits","country","createdAt","updatedAt"]},"card-subscription-deactivation-reason":{"type":"string","description":"Why a card subscription was deactivated, as given by the customer in the deactivation request.\n\n- `card_lost`: the cardholder lost the card.\n- `card_stolen`: the card was stolen.\n- `card_replaced`: the card was reissued or replaced with a new card number.\n- `card_closed`: the issuer or bank closed the card or its account.\n- `cardholder_offboarded`: the cardholder no longer works for the business.\n- `organization_offboarded`: the business no longer uses your platform.\n- `suspected_fraud`: the card is suspected of fraudulent use.\n- `duplicate_enrollment`: the card was enrolled more than once.\n- `no_longer_needed`: the card no longer needs to share data.\n- `other`: any other reason.\n\nNew values may be added later. Handle a value you don't recognize as `other`.\n","enum":["card_lost","card_stolen","card_replaced","card_closed","cardholder_offboarded","organization_offboarded","suspected_fraud","duplicate_enrollment","no_longer_needed","other"]},"card-subscription":{"type":"object","required":["_links","id","subaccountId","cardId","enrollmentType","state","effectiveDate","expirationDate","createdAt","updatedAt"],"properties":{"_links":{"type":"object","required":["self","card"],"properties":{"self":{"$ref":"#/components/schemas/link"},"card":{"$ref":"#/components/schemas/link"},"verifications":{"$ref":"#/components/schemas/link","description":"The link to this card's 3-D Secure verifications (`/card-verifications/3ds?cardId=`). Useful when a subscription is stuck at `reqSCA` to inspect why verification failed.\n"},"networkBulkFeed":{"$ref":"#/components/schemas/link","description":"The link to the network bulk feed associated with this card subscription, if applicable. This link may be present when the `enrollmentType` is `network-bulk`. It will not be present for subscriptions created through the `cardholder-single` flow.\n"},"bankAccount":{"$ref":"#/components/schemas/link","description":"The link to the bank account this subscription's card was materialized from (`/bank-accounts/{bankAccountId}`). Present only when the `enrollmentType` is `bank-feed` — the bank-connected analog of `networkBulkFeed`. Not present for `cardholder-single` or `network-bulk` subscriptions.\n"}}},"_embedded":{"type":"object","description":"Related resources inlined on request with the `expand` query parameter (`?expand=card,cardholder`). A key is\npresent only when it was requested and the related resource exists; each embedded body is identical to the one\nserved by the resource's own endpoint. Absent entirely when `expand` is not sent.\n","properties":{"card":{"$ref":"#/components/schemas/card"},"cardholder":{"$ref":"#/components/schemas/cardholder"}}},"id":{"type":"string","format":"uuid","description":"The unique identifier of this subscription entity."},"accountId":{"type":"string","format":"uuid","description":"The unique identifier of the account related to this entity."},"subaccountId":{"type":"string","format":"uuid","description":"The unique identifier of the subaccount related to this entity."},"cardId":{"type":"string","format":"uuid","description":"The unique identifier of the card related to this entity."},"customerReferenceId":{"type":"string","format":"uuid","nullable":true,"description":"An optional id in UUID format passed by the customer to associate a context with the subscription."},"state":{"type":"string","description":"State of the subscription. `active` and `pending` subscriptions are both considered enrolled in Astrada's\nplatform. A `pending` subscription is enrolled from a network roster while the card is still inactive at the\nnetwork (e.g. Mastercard Smart Data `I` status): it is customer-visible but has not yet received a\ntransaction. It exits only by promotion to `active` (a later roster `active` record or the card's first\nclearing transaction), explicit deactivation, or expiry. Virtual cards are excluded from `pending` enrollment.\n","enum":["pending","active","deactivated","expired","reqSCA","failed-to-create"]},"deactivationReason":{"allOf":[{"$ref":"#/components/schemas/card-subscription-deactivation-reason"}],"description":"The reason given when this subscription was deactivated. Only present on a deactivated subscription\nthat was given a reason; the field is left out otherwise. New values may be added, so treat an\nunknown value as `other`.\n"},"effectiveDate":{"description":"Date and time when this card subscription will be activated and start receiving data, in UTC, following ISO 8601 format.","type":"string","format":"date-time"},"expirationDate":{"description":"Date and time when this card subscription will become expired and stop receiving data, in UTC, following ISO 8601 format.","type":"string","format":"date-time"},"networkBulkFeedId":{"type":"string","format":"uuid","nullable":true,"description":"The unique identifier of the network bulk feed associated with this card subscription. Present when the `enrollmentType` is `network-bulk`, null otherwise."},"bankAccountId":{"type":"string","format":"uuid","nullable":true,"description":"The bank account this subscription's card was originally materialized from — present only when `enrollmentType` is `bank-feed` (the analog of `networkBulkFeedId` for bank-connected enrollments). This is provenance and does not re-point if a re-link later attaches the card to a successor account; the current link surface is the bank account's `cardIds`."},"enrollmentType":{"type":"string","description":"The flow that led to the creation of the card subscription. `cardholder-single` refers to enrollments where cardholders themselves are responsible for inputting card data and where a single card is attempted at a time. `network-bulk` refers to enrollments where card data will be captured by Astrada using network data sources (eg Mastercard Smart Data) and where many cards may be attempted at once. `bank-feed` refers to cards materialized from a bank connection (e.g. American Express via the hosted bank-linking flow) — the bank-side analog of `network-bulk`, with `bankAccountId` as the back-reference.","enum":["cardholder-single","network-bulk","bank-feed"]},"createdAt":{"description":"Date and time when this resource was created, in UTC, following ISO 8601 format.","type":"string","format":"date-time"},"updatedAt":{"description":"Date and time when this resource was last updated, in UTC, following ISO 8601 format.","type":"string","format":"date-time"}}},"conflict":{"type":"object","properties":{"detail":{"type":"string"},"title":{"type":"string","enum":["Conflict"]},"currentValue":{"type":"string","description":"Current value for the property causing the conflict"},"requestedValue":{"type":"string","description":"Requested value for the property causing the conflict"}},"required":["detail"]},"unprocessable-entity":{"type":"object","properties":{"detail":{"type":"string"},"title":{"type":"string","enum":["Unprocessable Entity"]}},"required":["detail","title"]},"failure-reason":{"type":"object","description":"Normalized, customer-facing reason a card verification failed. Present only when the\nverification `state` is `failed`. `category`, `description` and `retryable` are always\npresent; `issuerMessage` and `acsReferences` appear only when the issuer returned them\n(typically on a frictionless decline — when the issuer renders its own challenge UI no\nper-attempt message is available).\n","properties":{"category":{"description":"Stable, provider-agnostic failure category an integrator can branch on without\nenumerating raw issuer codes.\n","type":"string","enum":["authentication_declined","authentication_canceled","cvc_check_failed","card_declined","contact_issuer","card_blocked","too_many_attempts","not_supported","temporary_issue","processing_error"]},"description":{"description":"Human-readable explanation of the failure, safe to relay to the cardholder.","type":"string"},"retryable":{"description":"Whether the cardholder can retry now and plausibly succeed.","type":"boolean"},"issuerMessage":{"description":"The issuer's own cardholder-facing message, when provided (frictionless declines only).","type":"string"},"code":{"description":"Raw provider reason code (e.g. a 3DS `transStatusReason` or a Stripe `decline_code`),\nsurfaced for support escalation.\n","type":"string"},"providerMessage":{"description":"The payment provider's cardholder-safe message for the specific failure code (e.g.\n\"Your card does not support this type of purchase.\"). Finer-grained than the\ncategory-level `description`; absent when the provider supplied none.\n","type":"string"},"adviceCode":{"description":"The issuer's advice code on authorization declines, verbatim from the payment\nprovider. Documented values: `try_again_later`, `do_not_try_again`,\n`confirm_card_data`; values the provider introduces later pass through unchanged.\nAbsent when the issuer gave no advice (e.g. 3-D Secure authentication failures).\n","type":"string"},"acsReferences":{"description":"3DS ACS reference identifiers, when returned by the issuer — useful when escalating to the issuer.","type":"object","properties":{"acsTransactionId":{"type":"string"},"acsReferenceNumber":{"type":"string"},"dsTransactionId":{"type":"string"}}}},"required":["category","description","retryable"]},"card-verification":{"type":"object","properties":{"_links":{"type":"object","properties":{"self":{"$ref":"#/components/schemas/link","description":"The link to this verification resource."},"steps":{"$ref":"#/components/schemas/link","description":"The link to this verification's steps (`/card-verifications/3ds/{verificationId}/steps`)."},"currentStep":{"$ref":"#/components/schemas/link","description":"The link to the step the client should execute next. Absent once the\nverification reaches a terminal `state` (`completed` or `failed`).\n"}},"required":["self","steps"]},"id":{"description":"The unique identifier of the Verification entity.","type":"string","format":"uuid"},"subaccountId":{"description":"The unique identifier of the subaccount related to this entity.","type":"string","format":"uuid"},"cardId":{"description":"The unique identifier of the card related to this entity.","type":"string","format":"uuid"},"type":{"description":"Verification Step Type","type":"string","enum":["3DS"]},"currentStepId":{"description":"The identifier of the next step the client should execute. `null` when\nthe verification has no follow-up step — typically because the issuer\nsupports frictionless authentication, or because the card did not\nrequire interactive 3DS. When `null`, `state` will be `completed` on the\ncreation response and clients should not call any `/steps/...` endpoint.\n\nOn retrieved/listed verifications, `currentStepId` is also `null` with\n`state: failed` when the card was declined synchronously at creation\n(the creation call returned `400`, and the attempt is persisted as a\nfailed verification with its `failureReason`).\n\nFor the HIGHEST tier, a frictionless 3DS outcome does NOT complete the\nverification: it returns `stripe-holds-pending` (the cardholder must\ninitiate two small verification holds via `/steps/place-holds`), which\nthen advances to `stripe-amount-confirm` (the cardholder reads the two\namounts back via `/steps/amount-confirm`).\n","type":"string","nullable":true,"enum":["fingerprint","challenge","stripe-3ds","stripe-holds-pending","stripe-amount-confirm",null]},"state":{"description":"Current Verification state","type":"string","enum":["completed","failed","in-progress"]},"clientSecret":{"description":"Stripe SetupIntent or PaymentIntent client secret, used by the client to run `stripe.handleNextAction`. Returned whenever the verification is on the Stripe 3DS step — on the creation response (`POST /card-verifications/3ds`) and on the retrieve response (`GET /card-verifications/3ds/{verificationId}`) while `currentStepId` is `stripe-3ds`.","type":"string"},"stripePublishableKey":{"description":"Stripe publishable key to initialize Stripe.js on the client. Returned alongside `clientSecret` (creation response and retrieve response while `currentStepId` is `stripe-3ds`).","type":"string"},"authenticationFlow":{"description":"The 3DS authentication flow attested by the issuer, surfaced at the terminal state.\n`challenge` = the cardholder actively authenticated; `frictionless` = the issuer approved\nwithout interaction; `null` = 3DS was not engaged (e.g. a low-risk automatic skip).\n","type":"string","nullable":true,"enum":["challenge","frictionless",null]},"failureReason":{"$ref":"#/components/schemas/failure-reason","description":"Normalized, customer-facing reason the verification failed. Present only when\n`state` is `failed` — read it to triage the failure (category, retryability,\nand the issuer's message). See the `FailureReason` schema.\n"},"createdAt":{"description":"Date and time when this resource was created, in UTC, following ISO 8601 format.","type":"string","format":"date-time"},"updatedAt":{"description":"Date and time when this resource was last updated, in UTC, following ISO 8601 format.","type":"string","format":"date-time"}},"required":["id","subaccountId","cardId","type","state","createdAt","updatedAt","_links"]},"enrollment-link":{"type":"object","description":"An enrollment link to the Astrada-hosted page where people enroll their own cards into\none subaccount. The link's `url` is returned only by the request that creates it.\n","required":["_links","id","kind","subaccountId","startingPoint","state","expiresAt","maxUses","uses","starts","createdBy","createdAt","updatedAt"],"properties":{"_links":{"type":"object","required":["self"],"properties":{"self":{"$ref":"#/components/schemas/link"}}},"id":{"type":"string","format":"uuid","description":"The link's identifier."},"kind":{"type":"string","enum":["cardholder","team"],"description":"- `cardholder`: a personal link for one employee. It allows up to 5 session starts and\n  is used up by the first session that completes something.\n- `team`: a link to share with a team. Every session start counts as a use, up to\n  `maxUses`.\n"},"subaccountId":{"type":"string","format":"uuid","description":"The subaccount that cards enrolled through the link join."},"startingPoint":{"type":"string","enum":["card"],"description":"Where the hosted page starts. Only `card` is available now; links made before the field existed read as `card`."},"state":{"type":"string","enum":["active","used","revoked","expired"],"description":"- `active`: sessions can start.\n- `used`: a personal link whose session completed something.\n- `revoked`: revoked with `POST /enrollment-links/{linkId}/revoke` or by deleting its\n  subaccount. Team links revoked by the former five-active-link limit on\n  `POST /subaccounts/{subaccountId}/team-link` stay revoked.\n- `expired`: an active link past `expiresAt`.\n"},"expiresAt":{"type":"string","format":"date-time","description":"After this time no session starts from the link."},"maxUses":{"type":"integer","description":"1 on a personal link. On a team link, the session starts it allows."},"uses":{"type":"integer","description":"On a team link, the sessions started so far. On a personal link, 1 once it is used, otherwise 0."},"starts":{"type":"integer","description":"The sessions started from the link so far."},"customerReferenceId":{"type":"string","format":"uuid","description":"The reference given when the link was created. Absent when none was given."},"platformName":{"type":"string","description":"The platform name given when the link was created. Absent when none was given. The\nhosted page ignores it once the account has a brand profile.\n"},"organizationName":{"type":"string","description":"The organization name given when the link was created. Absent when none was given."},"createdBy":{"type":"object","required":["via"],"properties":{"via":{"type":"string","enum":["api","sdk","staff"],"description":"- `api`: `POST /enrollment-links` with `subaccounts:write`.\n- `staff`: `POST /enrollment-links` with Astrada's `accounts:write`.\n- `sdk`: `POST /subaccounts/{subaccountId}/team-link`, the route for the SDK's\n  \"Invite your team\" ending.\n"},"clientId":{"type":"string","description":"The client ID of the credential that created the link, when known."}}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"usedAt":{"type":"string","format":"date-time","description":"When a personal link was used up."},"revokedAt":{"type":"string","format":"date-time","description":"When the link was revoked."}}},"enrollment-link-session-outcome":{"type":"object","description":"What the hosted page reported when the session completed. A session completes something\nwhen it reports at least one id.\n\nThe ids are as the page sent them: nothing checks them against the card or bank APIs.\nThe `cardsubscription` webhooks are the source of truth for what was enrolled. When the\nlink has a `customerReferenceId`, the card subscriptions created through it carry that\nreference.\n","properties":{"subscriptionIds":{"type":"array","maxItems":20,"items":{"type":"string","format":"uuid"},"description":"Card subscriptions the page reports it created."},"cardIds":{"type":"array","maxItems":20,"items":{"type":"string","format":"uuid"},"description":"Cards the page reports it enrolled."},"bankLinkIds":{"type":"array","maxItems":20,"items":{"type":"string","format":"uuid"},"description":"Bank links the page reports it completed."},"summary":{"type":"object","maxProperties":10,"additionalProperties":{"type":"integer","minimum":0,"maximum":1000},"description":"Up to 10 counts the page reports. Each name is 1 to 40 letters and digits and starts\nwith a letter.\n"}}},"enrollment-link-session":{"type":"object","description":"A session started from an enrollment link, as the hosted page ran it.","required":["id","state","startedAt","expiresAt"],"properties":{"id":{"type":"string","format":"uuid","description":"The session's identifier."},"state":{"type":"string","enum":["open","completed","expired"],"description":"- `open`: started and not yet completed.\n- `completed`: the page reported the session's outcome.\n- `expired`: an open session past `expiresAt`. It can no longer complete.\n"},"startedAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time","description":"60 minutes after `startedAt`."},"completedAt":{"type":"string","format":"date-time"},"outcome":{"$ref":"#/components/schemas/enrollment-link-session-outcome"}}},"network-reference":{"type":"string","description":"The identifier associated with the card network's bulk enrollment feed. Its format depends on the network.\nFor Amex, the Recipient ID in the format 'R{RecipientId}', such as 'R123456', or the 6-digit Amex corporate ID (CID), such as '014640'.\nFor Mastercard, the Delivery ID, such as 'G1234567'.\nFor Visa-VBDS, the RPIC in the format 'RegionId_ProcessorId_IssuerId_CompanyId', such as '1_123_45_6789'.\nFor Visa-VCF, the same RPIC 'RegionId_ProcessorId_IssuerId_CompanyId', such as '1_123_45_6789' (the region segment is ignored), or the 3-segment PIC form 'ProcessorId_IssuerId_CompanyId', such as '123_45_6789'.\nFor more details on our bulk enrollment process, refer to [this guide](https://docs.astrada.co/docs/network-bulk-enrollment).\n","example":"G1234567"},"network-bulk-feeds":{"type":"object","required":["_links","id","subaccountId","network","networkReference","state","type","panFormat","createdAt","updatedAt"],"properties":{"_links":{"type":"object","required":["self"],"properties":{"self":{"$ref":"#/components/schemas/link"}}},"id":{"type":"string","format":"uuid","description":"The unique identifier of this network bulk feed entity."},"subaccountId":{"type":"string","format":"uuid","description":"The unique identifier of the subaccount related to this entity."},"network":{"type":"string","enum":["AMEX","MASTERCARD","VISA"],"description":"The network where the feed belongs."},"networkReference":{"$ref":"#/components/schemas/network-reference"},"state":{"type":"string","enum":["submitted","active","deactivated","failed"],"description":"The state of the network bulk feed entity.\n\n> **Note**: The `failed` state is currently only applicable to VISA bulk feeds.\n"},"type":{"type":"string","nullable":true,"enum":["GL","SMARTDATA","VBDS","VCF"],"description":"The feed's delivery rail. Always set for `AMEX` (`GL`) and `MASTERCARD`\n(`SMARTDATA`), and for a `VISA` feed created with an explicit type.\n\n`null` while a `VISA` feed created without a type is still discovering\nits rail: it stays `submitted` and becomes `VBDS` or `VCF` (and\n`active`) as soon as a VBDS connection or a VCF file confirms the rail.\nThe `networkbulkfeed.statechanged` webhook for that transition carries\nthe resolved value.\n"},"panFormat":{"type":"string","enum":["encrypted","tokenized"],"description":"The PAN format of the feed's card data: `encrypted` (raw PAN) or\n`tokenized` (Amex network token / `tokenizedId`).\n\nOutside the sandbox environment this is derived internally at feed\ncreation — determined by Astrada from the network/file signals, never\naccepted on the create request — and defaults to `encrypted`. In the\nsandbox environment it may be set explicitly on the create request for\n`type: GL` (AMEX) feeds only, so the Simulate flow can register a\ntokenized feed (see `panFormat` on `POST /network-bulk-feeds`). It is\nalways returned on the feed representation.\n"},"errorReason":{"type":"string","nullable":true,"description":"A human-readable reason explaining why the bulk feed failed. Present when `state` is `failed`.\nFor a `VISA` feed still discovering its rail (`type` is `null`, `state` is `submitted`) it may\nalso carry the latest error reported by one rail, prefixed with that rail (for example `VBDS: ...`);\nthe feed keeps waiting for the other rail and the field is cleared when the feed becomes `active`.\n\n> **Note**: Currently only applicable to VISA bulk feeds.\n"},"expectedCardCount":{"type":"integer","minimum":1,"maximum":1000000,"description":"The expected number of cards that will be enrolled under this bulk feed, as provided at creation time.\nOnly present when the feed was created with this field.\n"},"transactionStartDate":{"type":"string","format":"date","description":"Transactions posted on or after this calendar date are ingested for this\nfeed's deliveries, replacing the default 15-day ingestion window.\nCurrently supported for SMARTDATA feeds only. Only present when set —\nwhen absent, the default 15-day window applies. The comparison is\ncalendar-day based in UTC: the network's posting date is a date-only\nfield, so the cutoff is the start of the stated day with no\nlocal-timezone adjustment.\n"},"createdAt":{"description":"Date and time when this resource was created, in UTC, following ISO 8601 format.","type":"string","format":"date-time"},"updatedAt":{"description":"Date and time when this resource was last updated, in UTC, following ISO 8601 format.","type":"string","format":"date-time"}}},"network-bulk-enrollment":{"type":"object","required":["_links","id","subaccountId","network","bin","binInfo","company","cardAdmin","bankContact","cardCountBand","outreach","consent","state","networkBulkFeedId","customerReferenceId","createdAt","updatedAt"],"properties":{"_links":{"type":"object","required":["self"],"properties":{"self":{"$ref":"#/components/schemas/link"},"networkBulkFeed":{"$ref":"#/components/schemas/link","description":"The network bulk feed registered against this enrollment\n(`/network-bulk-feeds/{networkBulkFeedId}`). Present once `state` is\n`feed-created`, absent before that.\n"}}},"id":{"type":"string","format":"uuid","description":"The unique identifier of this network bulk enrollment."},"subaccountId":{"type":"string","format":"uuid","description":"The unique identifier of the subaccount the card program enrolls into."},"network":{"type":"string","enum":["AMEX","MASTERCARD","VISA"],"description":"The network of the card program."},"bin":{"type":"string","pattern":"^[0-9]{6,11}$","description":"The leading 6 to 11 digits of the card that opened the kickoff, exactly as submitted."},"binInfo":{"type":"object","nullable":true,"description":"A snapshot of the issuer details shown to the person who submitted the kickoff,\nkept for display only. `null` when the request carried none. The fields use the\n`GET /bin-lookup` vocabulary.\n","properties":{"issuerName":{"type":"string","nullable":true,"description":"The name of the issuing bank."},"issuerCountry":{"type":"string","nullable":true,"description":"The country of the issuing bank, ISO 3166 alpha-3."},"type":{"type":"string","nullable":true,"description":"The card type, for example `COMMERCIAL`."},"fundingType":{"type":"string","nullable":true,"description":"The card funding type, for example `CREDIT`."}}},"company":{"type":"object","required":["legalName"],"properties":{"legalName":{"type":"string","description":"The legal name of the company whose card program is being enrolled."}}},"cardAdmin":{"type":"object","required":["name","email"],"description":"The card program administrator. Astrada keeps this person engaged throughout onboarding.","properties":{"name":{"type":"string"},"email":{"type":"string","format":"email"}}},"bankContact":{"type":"object","nullable":true,"required":["name","email"],"description":"The company's relationship contact at the issuing bank. `null` when not provided.","properties":{"name":{"type":"string"},"email":{"type":"string","format":"email"}}},"cardCountBand":{"type":"string","nullable":true,"enum":["1-50","51-250","251-1000","1001-5000","5001-25000","25000+",null],"description":"The estimated number of cards in the program, as a band. `null` when not provided."},"outreach":{"type":"string","enum":["astrada","self"],"description":"Who contacts the bank. `astrada`: Astrada reaches out to the bank, copying the\ncompany and the card admin. `self`: the company emails the bank itself and copies\nonboarding@astrada.co so Astrada can guide the setup.\n"},"consent":{"type":"object","required":["acceptedAt","version"],"properties":{"acceptedAt":{"type":"string","format":"date-time","description":"When the consent was recorded, which is the server time of the create request, in UTC, following ISO 8601 format."},"version":{"type":"string","description":"The version of the consent wording that was accepted, as sent by the client (for example `kickoff-consent-v1`)."}}},"state":{"type":"string","enum":["requested","feed-created","cancelled"],"description":"`requested` until a network bulk feed is registered with this enrollment's id,\nthen `feed-created`. `cancelled` when the request is closed without a feed.\n"},"networkBulkFeedId":{"type":"string","format":"uuid","nullable":true,"description":"The network bulk feed registered with this enrollment's id on `POST /network-bulk-feeds`. `null` until then."},"customerReferenceId":{"type":"string","nullable":true,"description":"An optional id passed by the customer to associate a context with the enrollment. `null` when not provided."},"createdAt":{"description":"Date and time when this resource was created, in UTC, following ISO 8601 format.","type":"string","format":"date-time"},"updatedAt":{"description":"Date and time when this resource was last updated, in UTC, following ISO 8601 format.","type":"string","format":"date-time"}}},"network-bulk-enrollment-summary":{"type":"object","description":"The `200` body of `POST /network-bulk-enrollments` when the request's program already has\nan open kickoff that another request wrote. A program is the calling account, the\n`subaccountId`, the `network` and the first 8 digits of the `bin`. The summary names the\nopen kickoff and leaves out its contact details: no names, emails, bank contact, `binInfo`,\nconsent or outreach. `alreadyOpen` is always `true` here, and the full enrollment never\ncarries it, a replay of your own `requestId` included.\n","required":["_links","alreadyOpen","id","subaccountId","network","state","networkBulkFeedId","requestId","createdAt"],"properties":{"_links":{"type":"object","required":["self"],"properties":{"self":{"$ref":"#/components/schemas/link","description":"The open kickoff (`/network-bulk-enrollments/{id}`). A token with\n`network-bulk-enrollments:read` or `network-bulk-feeds:read` can follow it to the\nfull enrollment; any other token gets `403`.\n"}}},"alreadyOpen":{"type":"boolean","enum":[true],"description":"Always `true`. Tells this summary apart from the full enrollment."},"id":{"type":"string","format":"uuid","description":"The unique identifier of the open kickoff."},"subaccountId":{"type":"string","format":"uuid","description":"The subaccount of the open kickoff, the same as the request's."},"network":{"type":"string","enum":["AMEX","MASTERCARD","VISA"],"description":"The network of the open kickoff, the same as the request's."},"state":{"type":"string","enum":["requested","feed-created"],"description":"The open kickoff's state. `requested`: it was created less than 90 days ago and no\nfeed has been registered against it yet. `feed-created`: a feed was registered against\nit and that feed is live.\n"},"networkBulkFeedId":{"type":"string","format":"uuid","nullable":true,"description":"The live feed registered against the open kickoff. `null` while the kickoff is `requested`."},"requestId":{"type":"string","format":"uuid","nullable":true,"description":"The `requestId` this request sent, or `null` when it sent none. It is never the\n`requestId` the open kickoff was stored under.\n"},"createdAt":{"type":"string","format":"date-time","description":"When the open kickoff was created, in UTC, following ISO 8601 format. Its 90-day window counts from this time."}}},"network-bulk-enrollment-open":{"type":"object","description":"Whether the card program has an open kickoff, the answer of\n`GET /network-bulk-enrollments/open`. When it has none, the body is `{ \"open\": false }`\nand nothing else. When it has one, the body carries only that kickoff's `enrollmentId`,\n`state` and `requestedAt`: no names, emails, bank contact, `binInfo`, consent or outreach,\nas the kickoff may have been sent by someone else.\n","required":["open"],"properties":{"open":{"type":"boolean","description":"Whether the program has an open kickoff, by the same rule `POST /network-bulk-enrollments` uses."},"enrollmentId":{"type":"string","format":"uuid","description":"The open kickoff's identifier, the `id` that `POST /network-bulk-enrollments` answers\nwith when it finds the same kickoff. Present only when `open` is `true`.\n"},"state":{"type":"string","enum":["requested","feed-created"],"description":"The open kickoff's state. `requested`: it was created less than 90 days ago and no feed\nis registered yet. `feed-created`: its feed is registered and live. Present only when\n`open` is `true`.\n"},"requestedAt":{"type":"string","format":"date-time","description":"When the open kickoff was created, in UTC, following ISO 8601 format. Present only when\n`open` is `true`.\n"}}},"subaccount-configuration":{"type":"object","additionalProperties":false,"description":"Subaccount network and regional configurations which determine the available networks and geographies during card enrollment.","properties":{"VISA":{"type":"object","additionalProperties":false,"properties":{"countries":{"type":"array","description":"List of contracted regional areas for Visa","uniqueItems":true,"items":{"type":"string","enum":["USA","CAN","IRL","DEU","CZE","SWE","NLD","LTU","GBR","SVN","LUX","POL","SVK","HUN","ITA","ROU","FIN","DNK","MLT","LVA","GRC","AUT","HRV","CHE","NOR","ISL","FRA","ESP","ISR","SMR","VAT","AND","GIB","AUS","NZL","PRT","BEL","SGP"],"description":"Country Code following ISO 3166 alpha-3"}},"single-enrollment":{"type":"object","additionalProperties":false,"properties":{"countries":{"type":"array","description":"List of countries supported for Visa single enrollment","uniqueItems":true,"items":{"type":"string","enum":["USA","CAN","IRL","DEU","CZE","SWE","NLD","LTU","GBR","SVN","LUX","POL","SVK","HUN","ITA","ROU","FIN","DNK","MLT","LVA","GRC","AUT","HRV","CHE","NOR","ISL","FRA","ESP","ISR","SMR","VAT","AND","GIB","PRT","BEL"],"description":"Country Code following ISO 3166 alpha-3"}},"blockedCardTypes":{"type":"array","description":"Card types blocked for Visa single enrollment. The account's defaults for this network and enrollment mode are always added, so the stored list can include values that were not sent.","uniqueItems":true,"items":{"type":"string","enum":["CONSUMER"]}},"blockedFundingCardTypes":{"type":"array","description":"Funding card types blocked for Visa single enrollment. The account's defaults for this network and enrollment mode are always added, so the stored list can include values that were not sent.","uniqueItems":true,"items":{"type":"string","enum":["DEBIT"]}}},"required":["countries","blockedCardTypes","blockedFundingCardTypes"]},"bulk-enrollment":{"type":"object","additionalProperties":false,"properties":{"countries":{"type":"array","description":"List of countries supported for Visa bulk enrollment","uniqueItems":true,"items":{"type":"string","enum":["USA","CAN","IRL","DEU","CZE","SWE","NLD","GBR","SVN","LUX","POL","SVK","HUN","ITA","ROU","FIN","MLT","AUT","FRA","ESP","NOR","CHE","AUS","NZL","PRT","BEL","SGP"],"description":"Country Code following ISO 3166 alpha-3"}},"blockedCardTypes":{"type":"array","description":"Card types blocked for Visa bulk enrollment. The account's defaults for this network and enrollment mode are always added, so the stored list can include values that were not sent.","uniqueItems":true,"items":{"type":"string","enum":["CONSUMER"]}},"blockedFundingCardTypes":{"type":"array","description":"Funding card types blocked for Visa bulk enrollment. The account's defaults for this network and enrollment mode are always added, so the stored list can include values that were not sent.","uniqueItems":true,"items":{"type":"string","enum":["DEBIT"]}}},"required":["countries","blockedCardTypes","blockedFundingCardTypes"]}},"required":["countries","single-enrollment","bulk-enrollment"]},"MASTERCARD":{"type":"object","additionalProperties":false,"properties":{"countries":{"type":"array","description":"List of contracted regional areas for Mastercard","uniqueItems":true,"items":{"type":"string","enum":["USA","CAN","GBR","IRL","SWE","DEU","NLD","DNK","ITA","POL","FIN","BEL","ESP","FRA","PRT","AUT","GRC","MLT","NOR","CHE","ISR","AUS","NZL","SGP"],"description":"Country Code following ISO 3166 alpha-3"}},"single-enrollment":{"type":"object","additionalProperties":false,"properties":{"countries":{"type":"array","description":"List of countries supported for Mastercard single enrollment","uniqueItems":true,"items":{"type":"string","enum":["USA","CAN","GBR","IRL","SWE","DEU","NLD","DNK","ITA","POL","FIN","BEL","ESP","FRA","PRT","AUT","GRC","MLT","NOR","CHE","ISR","AUS","NZL"],"description":"Country Code following ISO 3166 alpha-3"}},"blockedCardTypes":{"type":"array","description":"Card types blocked for Mastercard single enrollment. The account's defaults for this network and enrollment mode are always added, so the stored list can include values that were not sent.","uniqueItems":true,"items":{"type":"string","enum":["CONSUMER"]}},"blockedFundingCardTypes":{"type":"array","description":"Funding card types blocked for Mastercard single enrollment. The account's defaults for this network and enrollment mode are always added, so the stored list can include values that were not sent.","uniqueItems":true,"items":{"type":"string","enum":["DEBIT"]}}},"required":["countries","blockedCardTypes","blockedFundingCardTypes"]},"bulk-enrollment":{"type":"object","additionalProperties":false,"properties":{"countries":{"type":"array","description":"List of countries supported for Mastercard bulk enrollment","uniqueItems":true,"items":{"type":"string","enum":["USA","CAN","GBR","IRL","SWE","DEU","NLD","DNK","ITA","POL","FIN","BEL","ESP","FRA","AUT","NOR","CHE","ISR","AUS","NZL","SGP"],"description":"Country Code following ISO 3166 alpha-3"}},"blockedCardTypes":{"type":"array","description":"Card types blocked for Mastercard bulk enrollment. The account's defaults for this network and enrollment mode are always added, so the stored list can include values that were not sent.","uniqueItems":true,"items":{"type":"string","enum":["CONSUMER"]}},"blockedFundingCardTypes":{"type":"array","description":"Funding card types blocked for Mastercard bulk enrollment. The account's defaults for this network and enrollment mode are always added, so the stored list can include values that were not sent.","uniqueItems":true,"items":{"type":"string","enum":["DEBIT"]}}},"required":["countries","blockedCardTypes","blockedFundingCardTypes"]}},"required":["countries","single-enrollment","bulk-enrollment"]},"AMEX":{"type":"object","additionalProperties":false,"properties":{"countries":{"type":"array","description":"List of contracted regional areas for American Express","uniqueItems":true,"items":{"type":"string","enum":["USA","CAN","GBR","ITA","SWE","AUS","NZL"],"description":"Country Code following ISO 3166 alpha-3"}},"single-enrollment":{"type":"object","additionalProperties":false,"properties":{"countries":{"type":"array","description":"List of countries supported for AMEX single enrollment","uniqueItems":true,"items":{"type":"string","enum":["USA","CAN","GBR","ITA","SWE"],"description":"Country Code following ISO 3166 alpha-3"}},"blockedCardTypes":{"type":"array","description":"Card types blocked for AMEX single enrollment. The account's defaults for this network and enrollment mode are always added, so the stored list can include values that were not sent.","uniqueItems":true,"items":{"type":"string","enum":["CONSUMER"]}},"blockedFundingCardTypes":{"type":"array","description":"Funding card types blocked for AMEX single enrollment. The account's defaults for this network and enrollment mode are always added, so the stored list can include values that were not sent.","uniqueItems":true,"items":{"type":"string","enum":["DEBIT"]}}},"required":["countries","blockedCardTypes","blockedFundingCardTypes"]},"bulk-enrollment":{"type":"object","additionalProperties":false,"properties":{"countries":{"type":"array","description":"List of countries supported for AMEX bulk enrollment","uniqueItems":true,"items":{"type":"string","enum":["USA","CAN","GBR","ITA","SWE","AUS","NZL"],"description":"Country Code following ISO 3166 alpha-3"}},"blockedCardTypes":{"type":"array","description":"Card types blocked for AMEX bulk enrollment. The account's defaults for this network and enrollment mode are always added, so the stored list can include values that were not sent.","uniqueItems":true,"items":{"type":"string","enum":["CONSUMER"]}},"blockedFundingCardTypes":{"type":"array","description":"Funding card types blocked for AMEX bulk enrollment. The account's defaults for this network and enrollment mode are always added, so the stored list can include values that were not sent.","uniqueItems":true,"items":{"type":"string","enum":["DEBIT"]}}},"required":["countries","blockedCardTypes","blockedFundingCardTypes"]}},"required":["countries","single-enrollment","bulk-enrollment"]}},"example":{"VISA":{"countries":["USA","CAN"],"single-enrollment":{"countries":["USA"],"blockedCardTypes":["CONSUMER"],"blockedFundingCardTypes":["DEBIT"]},"bulk-enrollment":{"countries":["CAN"],"blockedCardTypes":["CONSUMER"],"blockedFundingCardTypes":["DEBIT"]}},"MASTERCARD":{"countries":["USA"],"single-enrollment":{"countries":["USA"],"blockedCardTypes":["CONSUMER"],"blockedFundingCardTypes":["DEBIT"]},"bulk-enrollment":{"countries":["GBR"],"blockedCardTypes":["CONSUMER"],"blockedFundingCardTypes":["DEBIT"]}},"AMEX":{"countries":["ITA"],"single-enrollment":{"countries":["ITA"],"blockedCardTypes":["CONSUMER"],"blockedFundingCardTypes":["DEBIT"]},"bulk-enrollment":{"countries":["SWE"],"blockedCardTypes":["CONSUMER"],"blockedFundingCardTypes":["DEBIT"]}}}},"verification-policy":{"type":"object","description":"Admin-managed overrides controlling how card verification is performed for an account or subaccount.\nFields are optional and nullable; absent fields leave the current value unchanged, explicit `null` clears an override.\n","properties":{"stripeValidationLevel":{"type":"string","nullable":true,"enum":["HIGHEST","HIGH","MEDIUM","LOW"],"description":"Routes card verifications through Stripe at the specified risk tier when set.\n`null` (or absent) routes through the default TokenEx/IXOPAY (Visa) or TNS (Mastercard) path.\n\nTiers (increasing strictness):\n  * `LOW` — internal-only; 3DS engaged only when risk/regulation requires it; issuer-unsupported\n    soft declines are tolerated. Cannot be self-assigned via this endpoint.\n  * `MEDIUM` — 3DS always requested (challenge preferred); the standard tier to opt into.\n  * `HIGH` — 3DS plus a transient authorization hold (no settled charge) and added fraud signals.\n  * `HIGHEST` — 3DS challenge; if the issuer approves frictionlessly, a two-hold confirmation\n    becomes a mandatory second factor. See the \"HIGHEST Verification\" guide.\n\nNetwork note: Visa uses Stripe at every set tier; Mastercard uses its network 3DS at all tiers and\nengages Stripe only at `HIGHEST` (for the two-hold second factor).\n\nResolution: the subaccount value is operative at request time; the account-level value is the\ninheritance source applied when a subaccount is created, not a live fallback.\n"},"sandbox":{"type":"boolean","nullable":true,"description":"Test flag, settable by the customer via `PATCH /subaccounts` (and internally via the\nverification-policy endpoints). When `true`, card verifications on this subaccount route KNOWN\ntest PANs through the Stripe/TNS sandbox (real cards still go live), and new bank links are\ncreated against Plaid Sandbox (Plaid test fixtures only — real bank credentials require the\nflag off), so an integrator can deterministically test against a provisioned subaccount.\nAbsent / `null` / `false` → live processing only.\n"},"failedAttemptLockout":{"type":"boolean","nullable":true,"description":"When `true`, ENFORCE the cross-network attempt lockout for this tenant: a card with too many recent\nhard verification failures is refused at create (`400` `verification.attempts_locked`) before any\nprovider is called. Account-level fallback (set once for all partner subaccounts), overridable per\nsubaccount. Absent / `null` / `false` → not enforced (failures are still recorded; only enforcement\nis gated).\n"}}},"enrollment-policy":{"type":"object","description":"Enrollment policy for an account or subaccount. Two groups of fields:\n\n**Unified-SDK rails** (`cardEnrollment`, `bankEnrollment`, `bulkEnrollment`): which\nenrollment options the unified SDK renders. Customer-writable per subaccount via\n`PATCH /subaccounts/{subaccountId}`; account-level defaults are admin-managed. Rails\nresolve live per field (subaccount value if set, else account) and reads are SPARSE:\nonly explicitly-configured rail fields are returned: an absent field means \"not\nconfigured here\" and the SDK falls back to the host page's client configuration, then\nits card-only default.\n\n**Admin fields** (`linkAnotherCard`, `bankEnrollmentLocked`): `linkAnotherCard` sets whether\nthe success screen offers the \"Link another card\" CTA (shown as \"Connect another company\ncard\"), and `bankEnrollmentLocked` is the lock on `bankEnrollment`. Managed only on the\ninternal enrollment-policy endpoints.\n\nFields are optional and nullable; absent fields leave the current value unchanged, explicit\n`null` clears a field.\n","properties":{"linkAnotherCard":{"type":"boolean","nullable":true,"description":"Whether the unified SDK's success screen offers the \"Link another card\" secondary CTA.\nAbsent / `null` = not configured: enabled by default (the SDK falls back to the host\npage's `open()` configuration, then its built-in default: shown).\n\nResolution (fail-open): subaccount GETs return the **effective**\nvalue: `false` when either the account or the subaccount stores an explicit `false`,\n`true` when either side stores `true` and neither stores `false`, omitted when neither\nlevel sets it. Resolves live on every read (no create-time snapshot), so an account-level\n`false` immediately hides the CTA for every subaccount and clearing it restores stored\nsubaccount values. No account gate on writes: any value is accepted on the subaccount\nregardless of the account's value.\n"},"bulkEnrollmentEnabled":{"type":"boolean","nullable":true,"deprecated":true,"description":"**Deprecated:** superseded by the `bulkEnrollment` tri-state rail (the SDK maps\n`true` to `suggested`, `false` to `off`, and prefers the tri-state when present).\n\nWhether the unified enrollment SDK offers bulk-enrollment steering (BIN eligibility\ncheck + bulk feed wizard) for this account/subaccount. `false` = the SDK skips the\neligibility check entirely and opens the card form directly (American Express cards\npivot to the bank-linking flow). Absent / `null` = not configured: the SDK falls\nback to the host page's client configuration, then its card-only default (bulk off).\n\nResolution: plain override-fallback: a subaccount value overrides the account value\nwhen set (no master gate). An explicit `bulkEnrollment`\nflag in the SDK's `open()` config wins over this policy in SDK v1. In SDK v2 the\nserver value wins field by field over `open()`; the boolean is read only when\n`bulkEnrollment` is absent (`true` is `suggested`, `false` is `off`), and a boolean\n`bulkEnrollment` in `open()` is itself read as a set of rails (`true` is card on,\nbank `on`, bulk `suggested`; `false` is card on, bank `amex-only`, bulk `off`).\n"},"cardEnrollment":{"type":"boolean","nullable":true,"description":"Unified-SDK rail: offer manual card enrollment (PAN entry + 3DS verification).\nResolution: live per-field override-fallback (subaccount value if set, else account).\n"},"bankEnrollment":{"type":"string","nullable":true,"enum":["off","amex-only","amex-visa","on"],"description":"Unified-SDK rail: offer bank linking. `on` = offered for every network that can link a bank (a route after the card number in SDK v2, a chooser tile in SDK v1); `amex-only` = reachable only via the American Express card number; `amex-visa` = the American Express route plus the Visa rule below (an interim mode while a program's Visa approval is pending; still reachable only through the card number; expected to be retired once approval lands: do not build long-lived integrations on it); `off` = disabled. Resolution: live per-field override-fallback, except for the two account settings at the end of this description.\n\nUnder `amex-visa`, `POST /card-subscriptions` single-enrolls a Visa card only when its BIN is classified as business: a `cardCategory` of `BUSINESS`, `CORPORATE`, `FLEET` or `PURCHASING`, or, when `cardCategory` is absent or `UNKNOWN`, a `type` of `COMMERCIAL`, `CORPORATE` or `SMALL_BUSINESS` (the fields `GET /bin-lookup` returns). It refuses every other Visa card with `403`. Unless another enrollment control refuses the card first, the code is `card_subscription.subaccount_blocking_card_type` and the body adds `reasonCode: card_subscription.bank_enrollment_required` and `cardClass`, the class the rule read (`CONSUMER`, `PREPAID`, `GIFT`, `SPECIALTY`, or `UNCLASSIFIED` when the BIN has no class). A refused credit card can enroll through bank linking (`POST /bank-links`) instead, and the unified SDK sends it there itself; the SDK offers no bank route to a debit or prepaid Visa card. `POST /enrollment-methods` with a `subaccountId` names this refusal `bank-enrollment-required` in `singleDecision.reason`. Bulk enrollment is not affected.\n\nRollout note for `amex-visa`: SDK bundles released before this value treat it as\n`off` (lenient parsing turns an unknown rail value into the safest mode), and\n`off` disables bank linking ENTIRELY: a program sitting on `amex-only` that is\nflipped early does not merely miss the new Visa pivot, it loses its existing\nAmerican Express pivot and Amex cards cannot enroll at all. The SDK deploy must\nprecede flipping any account or subaccount to this value, and rolling the SDK\nbundle back while accounts still carry `amex-visa` re-opens the same hazard in\nreverse.\n\nAstrada can lock the account's value: while `bankEnrollmentLocked` is `true`, the\naccount's `bankEnrollment` applies to every subaccount.\n\nAn `amex-visa` set on the account applies to every subaccount too, with or without the lock: subaccount reads return `amex-visa` whatever the subaccount stores. Stored subaccount values are kept.\n"},"bankEnrollmentLocked":{"type":"boolean","nullable":true,"description":"Astrada-admin lock on the account's `bankEnrollment`. Customers cannot set it: it is\nread-only on subaccounts, and `PATCH /subaccounts/{subaccountId}` ignores it.\n\nSet on the account only, together with an account-level `bankEnrollment`. While it is\n`true`, the account's `bankEnrollment` applies to every subaccount, whatever value a\nsubaccount stores. Stored subaccount values are kept and apply again once the lock is\ncleared.\n\nSubaccount reads return `bankEnrollmentLocked: true` while the lock is on and omit the\nfield otherwise. Account reads return the stored value. While the lock is on,\n`POST /bank-links` can refuse a link that the account's `bankEnrollment` does not allow,\nwith `403` and the code `BANK_ENROLLMENT_DISABLED`.\n"},"bulkEnrollment":{"type":"string","nullable":true,"enum":["off","suggested","forced"],"description":"Unified-SDK rail: offer network bulk-feed enrollment for bulk-capable programs.\n`suggested` = the bulk flow (the kickoff form in SDK v2, a wizard in SDK v1) offered\nnext to a connect-this-card-now option; `forced` = the bulk flow\nis the only path for bulk-capable cards; `off` = no bulk routing (direct card\nform). Supersedes the deprecated `bulkEnrollmentEnabled` boolean; when both are\nset, the SDK prefers this field. Resolution: live per-field override-fallback.\n"}}},"subaccount-enrollment-policy":{"allOf":[{"$ref":"#/components/schemas/enrollment-policy"},{"type":"object","properties":{"bankEnrollmentLocked":{"type":"boolean","nullable":true,"readOnly":true,"description":"Read-only. `true` while the account has locked `bankEnrollment`, and the account's\n`bankEnrollment` then applies whatever value the subaccount stores. Absent otherwise.\nA subaccount accepts no value for it: the lock is set on the account only.\n"}}}]},"plaid-end-customer":{"type":"object","description":"Admin-managed policy controlling whether an account's bank links are created under the\naccount's own Plaid reseller End-Customer (EC) client instead of the shared legacy client.\nFields are optional and nullable; absent fields leave the current value unchanged, explicit\n`null` clears a field.\n","properties":{"enabled":{"type":"boolean","nullable":true,"description":"Master gate for routing this account's bank links through its own Plaid reseller\nEnd-Customer client. Absent / `null` / `false` → disabled (legacy shared client).\n\nAdmin-set, account-level. When `true`, the account's bank links are created under the\naccount's own Plaid reseller End-Customer client; once that client is provisioned and\nPlaid's registration with the relevant institutions has completed, the hosted Link\nexperience carries the account's own branding (display name and Link customization)\nrather than Astrada's. Enabling an account whose End-Customer client is not yet\nprovisioned fails link creation rather than silently falling back to the shared client.\n\nResolution is passthrough from the account onto the effective subaccount read: this\nobject is account-level only in v1 — there is no subaccount-level override — and\nsubaccount GETs return the account's stored value as their **effective** value.\n"}}},"bank-linking-policy":{"type":"object","description":"Admin-managed policy controlling which account types and institutions are offered when\nlinking bank accounts via the hosted (Plaid) flow. Fields are optional and nullable;\nabsent fields leave the current value unchanged, explicit `null` clears a field.\n\nResolution is per-field and LIVE: a subaccount field applies when set; when absent/`null`\nthe parent account's value applies; when neither is set the field reads `null` and the\nsystem default is applied downstream at bank-link creation\n(`accountTypes: [credit]` — credit-card accounts only, the historical behavior).\nSubaccount GETs return these EFFECTIVE resolved values (nulls included — the default is\nnever materialized in reads).\n","properties":{"accountTypes":{"type":"array","nullable":true,"minItems":1,"items":{"type":"string","enum":["checking","savings","credit"]},"description":"Account types selectable during bank linking. Enforced by the provider at link-token\ncreation (Plaid account_filters: checking/savings → depository subtypes, credit →\ncredit card); institutions offering none of the allowed types are hidden from\ninstitution search. Default: `[credit]`.\n"},"pinnedInstitutionId":{"type":"string","nullable":true,"pattern":"^ins_[A-Za-z0-9]+$","description":"Provider institution id to pre-select at link creation (e.g. `ins_10` for American\nExpress). NOTE: Plaid's `institution_id` pre-selection is currently rejected on\nproduction (`INVALID_INSTITUTION`) — this field is stored and forwarded only behind a\nprovider capability flag; until the provider supports it, institution limiting is\nachieved with `plaidLinkCustomizationName` plus account-type filtering.\n"},"plaidLinkCustomizationName":{"type":"string","nullable":true,"maxLength":256,"description":"Name of a Plaid Dashboard Link customization to pin on created link tokens\n(institution shortlist, Account Select mode). The customization must already exist for\nthe account's Plaid client in the Plaid Dashboard. A `POST /bank-links` may name\n`amex_only` in `filters.linkCustomizationName`, which then takes this value's place,\nand a policy `amex_only` is not applied to a link whose `bin6` does not start with `3`.\nIf Plaid refuses the name, `POST /bank-links` answers `403`\n`PLAID_CUSTOMIZATION_NOT_PROVISIONED`, except for `amex_only`, which is first retried\nonce with the environment's pinned customization in its place, or with none.\n"},"providers":{"type":"array","nullable":true,"minItems":1,"items":{"type":"string","enum":["plaid","mastercard"]},"description":"Open-banking provider allowlist for bank-link creation. Unset/`null` = unrestricted:\nthe client's requested `provider` governs, bounded only by which providers are\nenabled on the platform. Set: a `POST /bank-links` requesting a provider outside the\nlist is rejected with `400`.\n\nThe `mastercard` rail is not yet generally available; requesting it on an\nenvironment where it is not enabled is rejected with `400`.\n"},"defaultProvider":{"type":"string","nullable":true,"enum":["plaid","mastercard"],"description":"Provider used when `POST /bank-links` doesn't name one. Unset/`null` = the system\ndefault (`plaid`).\n"},"defaultCountryCode":{"type":"string","nullable":true,"pattern":"^[A-Z]{3}$","description":"ISO 3166-1 alpha-3 country used when `POST /bank-links` doesn't name one.\nUnset/`null` = the system default (`USA`).\n"}}},"consent-policy":{"type":"object","readOnly":true,"description":"Which consent records `POST /card-subscriptions` accepts for this subaccount. Astrada sets\nit, on the account as a default and on the subaccount as an override; there is no route to\nchange it. The value is the effective one: each field comes from the subaccount when it sets\none, otherwise from the account, except that an account `mode` of `off` turns the mode off\nfor every subaccount. Absent (never `null`) when neither level sets a field.\n\nA subaccount with no `consentPolicy` behaves as `log` with every channel allowed. Which mode\na new or existing account starts in: [When consent is required](https://docs.astrada.co/docs/direct-api-card-enrollment-integration#when-consent-is-required).\n","properties":{"allowedChannels":{"type":"array","minItems":1,"uniqueItems":true,"description":"The channels a consent may come from. A consent from any other channel fails with `consent_channel_not_allowed`.","items":{"type":"string","enum":["sdk-unified","sdk-legacy","api"]}},"mode":{"type":"string","enum":["off","log","enforce"],"description":"`off` records nothing, `log` records without refusing, `enforce` refuses a missing or\nfailing consent. What each mode answers: [When consent is required](https://docs.astrada.co/docs/direct-api-card-enrollment-integration#when-consent-is-required).\n"}},"example":{"allowedChannels":["sdk-unified","api"],"mode":"log"}},"subaccount":{"type":"object","description":"A subaccount. Every representation of this resource (`GET /subaccounts/{subaccountId}`,\n`GET /subaccounts`, and the `POST /subaccounts` / `PATCH /subaccounts/{subaccountId}`\nresponses) reports the same EFFECTIVE read model: `enforceIssuerCountry`,\n`enrollmentPolicy`, `bankLinkingPolicy`, `plaidEndCustomer` and `consentPolicy` are resolved\nlive against the parent account rather than echoed as stored on the subaccount, and\n`networkBlockedCards` is resolved live from the platform network configuration. A write\nresponse therefore matches the subaccount you would read back immediately afterwards, and\ncan surface account-level and platform-level settings the subaccount stores nothing for.\n\nException: `enforceIssuerCountry` is omitted from the `GET /subaccounts` list items.\n","properties":{"_links":{"type":"object","required":["self"],"properties":{"self":{"$ref":"#/components/schemas/link"},"team-link":{"allOf":[{"$ref":"#/components/schemas/link"}],"description":"Only on `GET /subaccounts/{subaccountId}`: `POST /subaccounts/{subaccountId}/team-link`,\nwhich creates a team link for the subaccount, the \"Invite your team\" action. Present\nwhen enrollment links are enabled for the account, the token holds\n`card-subscriptions:write` or `subaccounts:write`, and the subaccount's card\nenrollment is on (its `enrollmentPolicy.cardEnrollment` is not `false`). Never\noffered to an enrollment link session's token. If the check cannot be made, the link\nis left out and the read still succeeds.\n"}}},"accountId":{"type":"string","format":"uuid","description":"The unique identifier of the account related to this entity."},"id":{"type":"string","format":"uuid","description":"The unique identifier of this subaccount entity."},"name":{"type":"string","description":"The name of this subaccount entity."},"createdAt":{"type":"string","format":"date-time","description":"Date and time when this resource was created, in UTC, following ISO 8601 format."},"updatedAt":{"type":"string","format":"date-time","description":"Date and time when this resource was last updated, in UTC, following ISO 8601 format."},"configurations":{"$ref":"#/components/schemas/subaccount-configuration"},"verificationPolicy":{"$ref":"#/components/schemas/verification-policy","nullable":true,"description":"Admin-managed card verification policy for this subaccount. Overrides the parent account's policy when set. `null` or absent means no subaccount-level override."},"enforceIssuerCountry":{"type":"boolean","description":"Whether card enrollment is restricted to issuer countries within the account's\ncapabilities. Account-level setting, resolved onto the subaccount at read time —\nthere is no subaccount-level override, so the subaccount never stores its own\nvalue. Absent on the subaccount list; `false` when the account has not enabled it.\n"},"networkBlockedCards":{"type":"object","readOnly":true,"description":"Platform-level enrollment rules resolved from the network configuration at read time.\nApplied before the subaccount's own block lists and not configurable per account or\nsubaccount. Keyed by network (`VISA`, `MASTERCARD`, `AMEX`); a network with no rules is\nomitted. A rule matches a card when `cardType` equals the BIN's `type` and\n`fundingTypes` contains the BIN's `fundingType`. An omitted or empty `fundingTypes`\nmatches every funding type. Enrolling a matching card fails with\n`card_subscription.network_blocking_card`.\n","additionalProperties":{"type":"object","properties":{"single-enrollment":{"type":"array","description":"Rules applied to single (SDK or API) enrollment on this network.","items":{"type":"object","required":["cardType"],"properties":{"cardType":{"type":"string","description":"The BIN `type` this rule blocks.","enum":["COMMERCIAL","CORPORATE","CONSUMER","SMALL_BUSINESS"]},"fundingTypes":{"type":"array","description":"The BIN `fundingType` values this rule blocks. Omitted or empty means every funding type.","uniqueItems":true,"items":{"type":"string","enum":["CREDIT","DEBIT","PREPAID"]}}}}},"bulk-enrollment":{"type":"array","description":"Rules applied to bulk enrollment on this network.","items":{"type":"object","required":["cardType"],"properties":{"cardType":{"type":"string","description":"The BIN `type` this rule blocks.","enum":["COMMERCIAL","CORPORATE","CONSUMER","SMALL_BUSINESS"]},"fundingTypes":{"type":"array","description":"The BIN `fundingType` values this rule blocks. Omitted or empty means every funding type.","uniqueItems":true,"items":{"type":"string","enum":["CREDIT","DEBIT","PREPAID"]}}}}}}},"example":{"VISA":{"single-enrollment":[{"cardType":"CONSUMER","fundingTypes":["DEBIT","PREPAID"]}],"bulk-enrollment":[{"cardType":"CONSUMER","fundingTypes":["DEBIT","PREPAID"]}]}}},"enrollmentPolicy":{"type":"object","nullable":true,"description":"Enrollment policy. Fields are the EFFECTIVE values: the unified-SDK rails\n(`cardEnrollment`, `bankEnrollment`, `bulkEnrollment`) and the deprecated\n`bulkEnrollmentEnabled` resolve as subaccount-overrides-account, and are SPARSE — only\nexplicitly-configured fields appear; `linkAnotherCard` resolves live to `false`\nwhen either level stores an explicit `false` (absent everywhere = enabled, field\nomitted). `bankEnrollmentLocked` is read-only: it\nappears, as `true`, only while the account has locked `bankEnrollment`, and\n`bankEnrollment` is then the account's value. `null` means the subaccount stores\nno policy and neither a rail nor `linkAnotherCard` is set at the account level\n(account-level admin snapshot fields do not surface through a `null` here).\n","allOf":[{"$ref":"#/components/schemas/subaccount-enrollment-policy"}]},"plaidEndCustomer":{"type":"object","nullable":true,"description":"Plaid End-Customer routing. `enabled` is the EFFECTIVE value — resolved\nfrom the parent account. This object is account-level only: there is no\nsubaccount-level override, so the subaccount never stores its own value. `null` means\nthe account has Plaid End-Customer routing disabled.\n","allOf":[{"$ref":"#/components/schemas/plaid-end-customer"}]},"bankLinkingPolicy":{"$ref":"#/components/schemas/bank-linking-policy","nullable":true,"description":"Admin-managed bank-linking policy. Fields are the EFFECTIVE values —\nper-field live resolution against the parent account (subaccount field if set,\nelse account, else `null`). A whole-`null` policy means neither level has one\nset. The credit-only system default (`accountTypes: [credit]`) is applied\ndownstream at bank-link creation, not materialized in this read.\n"},"consentPolicy":{"description":"The effective consent policy, set by Astrada. A subaccount with no `consentPolicy` behaves\nas `log` with every channel allowed, and an account `mode` of `off` turns the mode off for\nevery subaccount. Which mode a new or existing account starts in: [When consent is required](https://docs.astrada.co/docs/direct-api-card-enrollment-integration#when-consent-is-required).\n","allOf":[{"$ref":"#/components/schemas/consent-policy"}]}},"required":["_links","accountId","id","name","createdAt","updatedAt","configurations"]},"create-subaccount-configurations":{"type":"object","additionalProperties":false,"description":"Subaccount network and regional configurations which determine the available networks and geographies during card enrollment.\n\nThe `countries` property for each network accepts either:\n- An array of ISO 3166 alpha-3 country codes (e.g. `[\"USA\", \"CAN\"]`)\n- The string `\"*\"` to inherit all countries from the parent account's capabilities for that network\n\nWhen `\"*\"` is used, the subaccount automatically reflects the parent account's current country list. If the parent account's capabilities change, subaccounts using `\"*\"` will inherit the updated countries. API responses always return the resolved country list, never the `\"*\"` literal.\n\nThe single and bulk enrollment configurations are not required when creating a subaccount, but if not provided they will default to the same country list as the main countries property for that network. The supported card types for single and bulk enrollment is CONSUMER, while the supported funding card types is DEBIT. If not provided, the block rules for both card types will default to the parent account's default block rule for that network and enrollment level. Visa consumer debit and prepaid cards are blocked at the network level regardless of these settings; see `networkBlockedCards` on the subaccount.\n\nTo set the default rule on the parent account, please reach out to your account manager or support.\n","properties":{"VISA":{"type":"object","additionalProperties":false,"properties":{"countries":{"oneOf":[{"type":"array","description":"List of contracted regional areas for Visa","uniqueItems":true,"items":{"type":"string","enum":["USA","CAN","IRL","DEU","CZE","SWE","NLD","LTU","GBR","SVN","LUX","POL","SVK","HUN","ITA","ROU","FIN","DNK","MLT","LVA","GRC","AUT","HRV","CHE","NOR","ISL","FRA","ESP","ISR","SMR","VAT","AND","GIB","AUS","NZL","PRT","BEL","SGP"],"description":"Country Code following ISO 3166 alpha-3"}},{"type":"string","enum":["*"],"description":"Wildcard value that inherits all countries from the parent account's VISA capabilities.\n"}]},"single-enrollment":{"type":"object","additionalProperties":false,"properties":{"blockedCardTypes":{"type":"array","description":"Card types blocked for Visa single enrollment. The account's defaults for this network and enrollment mode are always added, so the stored list can include values that were not sent.","uniqueItems":true,"items":{"type":"string","enum":["CONSUMER"]}},"blockedFundingCardTypes":{"type":"array","description":"Funding card types blocked for Visa single enrollment. The account's defaults for this network and enrollment mode are always added, so the stored list can include values that were not sent.","uniqueItems":true,"items":{"type":"string","enum":["DEBIT"]}}}},"bulk-enrollment":{"type":"object","additionalProperties":false,"properties":{"blockedCardTypes":{"type":"array","description":"Card types blocked for Visa bulk enrollment. The account's defaults for this network and enrollment mode are always added, so the stored list can include values that were not sent.","uniqueItems":true,"items":{"type":"string","enum":["CONSUMER"]}},"blockedFundingCardTypes":{"type":"array","description":"Funding card types blocked for Visa bulk enrollment. The account's defaults for this network and enrollment mode are always added, so the stored list can include values that were not sent.","uniqueItems":true,"items":{"type":"string","enum":["DEBIT"]}}}}},"required":["countries"]},"MASTERCARD":{"type":"object","additionalProperties":false,"properties":{"countries":{"oneOf":[{"type":"array","description":"List of contracted regional areas for Mastercard","uniqueItems":true,"items":{"type":"string","enum":["USA","CAN","GBR","IRL","SWE","DEU","NLD","DNK","ITA","POL","FIN","BEL","ESP","FRA","PRT","AUT","GRC","MLT","NOR","CHE","ISR","AUS","NZL","SGP"],"description":"Country Code following ISO 3166 alpha-3"}},{"type":"string","enum":["*"],"description":"Wildcard value that inherits all countries from the parent account's MASTERCARD capabilities.\n"}]},"single-enrollment":{"type":"object","additionalProperties":false,"properties":{"blockedCardTypes":{"type":"array","description":"Card types blocked for Mastercard single enrollment. The account's defaults for this network and enrollment mode are always added, so the stored list can include values that were not sent.","uniqueItems":true,"items":{"type":"string","enum":["CONSUMER"]}},"blockedFundingCardTypes":{"type":"array","description":"Funding card types blocked for Mastercard single enrollment. The account's defaults for this network and enrollment mode are always added, so the stored list can include values that were not sent.","uniqueItems":true,"items":{"type":"string","enum":["DEBIT"]}}}},"bulk-enrollment":{"type":"object","additionalProperties":false,"properties":{"blockedCardTypes":{"type":"array","description":"Card types blocked for Mastercard bulk enrollment. The account's defaults for this network and enrollment mode are always added, so the stored list can include values that were not sent.","uniqueItems":true,"items":{"type":"string","enum":["CONSUMER"]}},"blockedFundingCardTypes":{"type":"array","description":"Funding card types blocked for Mastercard bulk enrollment. The account's defaults for this network and enrollment mode are always added, so the stored list can include values that were not sent.","uniqueItems":true,"items":{"type":"string","enum":["DEBIT"]}}}}},"required":["countries"]},"AMEX":{"type":"object","additionalProperties":false,"properties":{"countries":{"oneOf":[{"type":"array","description":"List of contracted regional areas for American Express","uniqueItems":true,"items":{"type":"string","enum":["USA","CAN","GBR","ITA","SWE","AUS","NZL"],"description":"Country Code following ISO 3166 alpha-3"}},{"type":"string","enum":["*"],"description":"Wildcard value that inherits all countries from the parent account's AMEX capabilities.\n"}]},"single-enrollment":{"type":"object","additionalProperties":false,"properties":{"blockedCardTypes":{"type":"array","description":"Card types blocked for AMEX single enrollment. The account's defaults for this network and enrollment mode are always added, so the stored list can include values that were not sent.","uniqueItems":true,"items":{"type":"string","enum":["CONSUMER"]}},"blockedFundingCardTypes":{"type":"array","description":"Funding card types blocked for AMEX single enrollment. The account's defaults for this network and enrollment mode are always added, so the stored list can include values that were not sent.","uniqueItems":true,"items":{"type":"string","enum":["DEBIT"]}}}},"bulk-enrollment":{"type":"object","additionalProperties":false,"properties":{"blockedCardTypes":{"type":"array","description":"Card types blocked for AMEX bulk enrollment. The account's defaults for this network and enrollment mode are always added, so the stored list can include values that were not sent.","uniqueItems":true,"items":{"type":"string","enum":["CONSUMER"]}},"blockedFundingCardTypes":{"type":"array","description":"Funding card types blocked for AMEX bulk enrollment. The account's defaults for this network and enrollment mode are always added, so the stored list can include values that were not sent.","uniqueItems":true,"items":{"type":"string","enum":["DEBIT"]}}}}},"required":["countries"]}},"example":{"VISA":{"countries":["USA","CAN"],"single-enrollment":{"blockedCardTypes":["CONSUMER"],"blockedFundingCardTypes":["DEBIT"]},"bulk-enrollment":{"blockedCardTypes":["CONSUMER"],"blockedFundingCardTypes":["DEBIT"]}},"MASTERCARD":{"countries":["USA"],"single-enrollment":{"blockedCardTypes":["CONSUMER"],"blockedFundingCardTypes":["DEBIT"]},"bulk-enrollment":{"blockedCardTypes":["CONSUMER"],"blockedFundingCardTypes":["DEBIT"]}},"AMEX":{"countries":["ITA"],"single-enrollment":{"blockedCardTypes":["CONSUMER"],"blockedFundingCardTypes":["DEBIT"]},"bulk-enrollment":{"blockedCardTypes":["CONSUMER"],"blockedFundingCardTypes":["DEBIT"]}}}},"customer-enrollment-policy":{"type":"object","description":"The customer-writable subset of the enrollment policy: the three unified-SDK\nrails. All other fields (`linkAnotherCard`, `bankEnrollmentLocked`, and the\ndeprecated `bulkEnrollmentEnabled`) are managed on the internal\nenrollment-policy endpoints and are ignored if sent here. The `200` names\nevery ignored key, these and misspelled ones alike, in `ignoredFields`.\n\nFields are optional and nullable; absent fields leave the current value\nunchanged, explicit `null` clears the subaccount-level value. A cleared\nrail falls back to the account-level value when one is set; only when\nneither level sets the rail does it disappear from reads, letting the\nhost page's client configuration and then the SDK's card-only default\napply.\n","properties":{"cardEnrollment":{"type":"boolean","nullable":true,"description":"Whether the unified SDK offers manual card enrollment (PAN entry + 3DS\nverification).\n"},"bankEnrollment":{"type":"string","nullable":true,"enum":["off","amex-only","amex-visa","on"],"description":"Whether the unified SDK offers bank linking. In SDK v2 the bank link is a route after the card number, not a separate tile: `on` offers it for every network that can link a bank (SDK v1 shows a chooser tile instead); `amex-only` keeps it reachable only via the American Express card number; `amex-visa` is the American Express route plus a Visa rule: a Visa card enrolls through `POST /card-subscriptions` only when it is classified as business, and the SDK sends every other Visa card to the bank route, except a debit or prepaid one (a temporary mode for programs whose Visa approval is pending: expect it to be retired once approval lands; do not build long-lived integrations on it); `off` disables it (American Express cards then can't enroll unless a bulk program qualifies).\n\nBefore setting `amex-visa`, confirm with your Astrada contact that the\nSDK release supporting it is live: older SDK bundles treat unknown rail\nvalues as `off`, which disables bank linking entirely, the existing\nAmerican Express pivot included.\n\nAstrada can lock the account's `bankEnrollment`: the subaccount's\n`enrollmentPolicy` then returns `bankEnrollmentLocked: true`. While it is\nlocked, the account's value applies. The value you set here is kept, and\nhas no effect until the lock is removed.\n\nAn `amex-visa` set on the account applies to every subaccount in the same way, without a lock: the subaccount's `enrollmentPolicy` returns `amex-visa` whatever value you set here. The value you set is kept, and has no effect while the account's value is `amex-visa`.\n"},"bulkEnrollment":{"type":"string","nullable":true,"enum":["off","suggested","forced"],"description":"Whether the unified SDK offers network bulk-feed enrollment for\nbulk-capable programs. In SDK v2 the bulk flow is the kickoff form, reached\nfrom the program screen or the callout after the card number (SDK v1 shows a\nbulk wizard). `suggested` offers it next to a connect-this-card-now option;\n`forced` makes it the only path for bulk-capable cards; `off` skips bulk\nrouting entirely (direct card form).\n"}}},"transaction":{"type":"object","properties":{"_links":{"type":"object","properties":{"messages":{"type":"array","items":{"$ref":"#/components/schemas/link"}},"card":{"$ref":"#/components/schemas/link"},"self":{"$ref":"#/components/schemas/link"},"subaccount":{"$ref":"#/components/schemas/link"}},"required":["messages"]},"_embedded":{"type":"object","description":"Related resources inlined on request with the `expand` query parameter\n(`?expand=cardSubscription,card,cardholder`). A key is present only when it was requested and the\nrelated resource exists, and it is never null. Each embedded body is identical to the one served by\nthe resource's own endpoint. Absent entirely when `expand` is not sent. Embedded resources show their\ncurrent values, not those at the time of the transaction, with one exception: `cardholder.corporate` is\nthe cardholder's corporate as of the transaction's `transactionOccurrenceDate` (end of that UTC day), or\nits `createdAt` when that is null.\n\n`cardSubscription` is the transaction's card subscription exactly as\n`GET /card-subscriptions/{subscriptionId}` serves it (not itself expanded): the card's subscription in\nthe transaction's sub-account, that is the one from the transaction's network bulk feed when the\ntransaction has a `networkBulkFeedId`, otherwise the card's current subscription, otherwise its most\nrecent one. Fields that apply only to some subscriptions (for example network bulk feed ones) follow\nthat endpoint's rules.\n\n`card` is the transaction's card (`cardId`) exactly as `GET /cards/{cardId}` serves it (not itself\nexpanded, so it never carries its own `_embedded.cardholder`). `cardholder` is that card's cardholder as\n`GET /cards/{cardId}/cardholder` serves it, except that `corporate` (`id`, `employeeId`,\n`alternativeEmployeeId`, `legalEntity`) is the value in effect at the transaction's date while every other\nfield is current; absent when the card has no cardholder data. When `GET /cards/{cardId}` would respond\n`404` for the card (for example because all of its card subscriptions were deleted), neither `card` nor\n`cardholder` is present. When `cardId` is null, none of the three keys is present. Presence is decided on\nthe card and cardholder as they are now.\n\nTransaction webhooks can also carry `_embedded` (see [Event Types](https://docs.astrada.co/reference/event-types)).\n","properties":{"cardSubscription":{"$ref":"#/components/schemas/card-subscription"},"card":{"$ref":"#/components/schemas/card"},"cardholder":{"$ref":"#/components/schemas/cardholder"}}},"acceptor":{"type":"object","description":"The details relating to the acceptor (merchant) from the latest transaction message.","properties":{"city":{"type":"string","nullable":true,"description":"The acceptor's registered city. Defined by the acquirer/processor."},"country":{"type":"string","nullable":true,"description":"The acceptor's registered country following ISO 3166 alpha-3."},"mcc":{"type":"string","nullable":true,"description":"The Merchant Category Code provided by the acquirer/processor. Used to classify businesses by the types of goods provided or services rendered."},"state":{"type":"string","nullable":true,"description":"The acceptor's registered state (e.g. Michigan) as assigned by the acquirer/processor."}},"required":["city","country","mcc","state"]},"cardId":{"type":"string","format":"uuid","nullable":true,"description":"The unique identifier of the card related to this entity. Null only for bank-sourced transactions on a bank account with no linked cards (the card-less unified feed); the `_links.card` link is omitted in that case."},"cardholderBillingCurrency":{"type":"string","description":"The currency of the country of issuance following ISO 4217 alpha-3 format."},"cardholderBillingHoldAmount":{"type":"number","format":"double","description":"This amount models the hold on the cardholder account, in the card's issued currency, that occurs after an authorization and before a financial message. This amount will change as both authorization and financial messages are added to the Transaction in order to reflect the remaining hold amount. A pending refund (an approved credit authorization) reflects its signed amount here as a negative hold while pending, released back to zero once the clearing financial message settles it."},"cardholderBillingSettledAmount":{"type":"number","format":"double","description":"The settled amount models the bottom line impact to the customer's bank statement in the card's issued currency. This amount will change as financial messages are added to the Transaction."},"controlAccountNumber":{"type":"string","description":"The American Express Basic Control Account number associated with the card, as provided by the Amex real-time authorization (RTA) and General Ledger (GL) feeds. Treat it as an opaque string and keep it exactly as returned: it is numeric today and may contain leading zeros, so never parse it as a number. Present only on American Express transactions where the feed supplies it; absent for all other networks and for transactions ingested before this field was introduced. It is never returned as null or an empty string. This is an account identifier, not a card number."},"descriptor":{"type":"string","nullable":true,"description":"Cleansed merchant name."},"id":{"type":"string","format":"uuid","description":"The unique identifier of this transaction entity."},"network":{"type":"string","description":"The card network that processed this payment."},"networkBulkFeedId":{"type":"string","format":"uuid","description":"The network bulk feed that delivered this transaction's first feed-carrying message (SmartData for Mastercard, VBDS for Visa clearing). Present only on transactions sourced from a network bulk feed; absent otherwise. Transactions delivered before the producers began emitting this field, or never delivered via a bulk feed, omit it entirely. It is never returned as null or an empty string."},"subaccountId":{"type":"string","format":"uuid","description":"The unique identifier of the subaccount related to this entity."},"supersededMessageIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Message ids from `_links.messages` whose financial contribution was superseded during aggregation — typically duplicate deliveries of the same clearing across network feeds, or a provisional bank-sourced settlement replaced by the network clearing. Superseded messages stay listed in `_links.messages` for audit but do not count toward the settled amounts, so exclude them when deriving totals from individual messages (or better, use `transactionSettledAmount` / `cardholderBillingSettledAmount` directly). Always a subset of `_links.messages`. Each payload carries the full current set (a snapshot, not a delta). Transactions last updated before this field was introduced report `[]` until their next update."},"status":{"type":"string","description":"A semantic understanding of the state of the transaction within the transaction lifecycle. `VOIDED` is not final: a clearing can still arrive after a full reversal, and the transaction then moves to `SETTLED` at the cleared amount. [Learn More](https://docs.astrada.co/docs/transaction)","enum":["PENDING","VOIDED","DECLINED","SETTLED"]},"transactionCurrency":{"type":"string","description":"The currency in which the transaction took place following ISO 4217 alpha-3 format."},"transactionHoldAmount":{"type":"number","format":"double","description":"This amount models the hold on the cardholder account, in the currency the transaction was conducted in, that occurs after an authorization and before a financial message. This amount will change as both authorization and financial messages are added to the Transaction in order to reflect the remaining hold amount. A pending refund (an approved credit authorization) reflects its signed amount here as a negative hold while pending, released back to zero once the clearing financial message settles it."},"transactionOccurrenceDate":{"type":"string","format":"date","nullable":true,"description":"The UTC date when the transaction took place, following ISO 8601 format (YYYY-MM-DD). This is a date-only field with no time component."},"transactionSettledAmount":{"type":"number","format":"double","description":"The settled amount models the bottom line impact to the customer's bank statement in the currency the transaction was conducted in. This amount will change as financial messages are added to the Transaction."},"createdAt":{"description":"Date and time when this resource was created, in UTC, following ISO 8601 format.","type":"string","format":"date-time"},"updatedAt":{"description":"Date and time when this resource was last updated, in UTC, following ISO 8601 format.","type":"string","format":"date-time"}},"required":["_links","acceptor","cardId","cardholderBillingCurrency","cardholderBillingHoldAmount","cardholderBillingSettledAmount","createdAt","descriptor","id","network","subaccountId","status","transactionCurrency","transactionHoldAmount","transactionOccurrenceDate","transactionSettledAmount","updatedAt"]},"transaction-message":{"type":"object","properties":{"_links":{"type":"object","properties":{"self":{"$ref":"#/components/schemas/link"},"raw":{"$ref":"#/components/schemas/link"}},"required":["self"]},"id":{"type":"string","format":"uuid","description":"The unique identifier of this transaction message entity."},"acceptor":{"type":"object","description":"The details relating to the acceptor (merchant) that initiated the transaction message.","properties":{"acquirerId":{"type":"string","nullable":true,"description":"The identifier of the acquirer/processor used by the acceptor as assigned by the network."},"city":{"type":"string","nullable":true,"description":"The acceptor's registered city. Defined by the acquirer/processor."},"country":{"type":"string","nullable":true,"description":"The acceptor's registered country following ISO 3166 alpha-3."},"id":{"type":"string","nullable":true,"description":"The identifier of the payment acceptor (merchant) as assigned by the acquirer/processor."},"mcc":{"type":"string","nullable":true,"description":"The Merchant Category Code provided by the acquirer/processor. Used to classify businesses by the types of goods provided or services rendered."},"name":{"type":"string","nullable":true,"description":"The acceptor (merchant) name."},"state":{"type":"string","nullable":true,"description":"The acceptor's registered state (e.g. Michigan) as assigned by the acquirer/processor."}},"required":["acquirerId","id","city","mcc","name","state"]},"approvalCode":{"type":"string","nullable":true,"description":"Unique code that authorizes a transaction message, sent by the card issuer/issuer-processor when approving a transaction. Always absent on bank-only messages — no card authorization occurred (its absence, together with the `bank_`-prefixed transactionReference, is the marker of a bank-only message)."},"traceId":{"type":"string","nullable":true,"example":"000123456789","description":"The American Express trace identifier for this transaction message. Populated only when `network` is `AMEX`, where it is the reconciliation handle used to match against Amex settlement data — Amex real-time authorizations are not observed to carry an `approvalCode`, so `traceId` is the identifier to reconcile on. The value is a numeric string and leading zeros are significant, so treat it as an opaque string and never parse it as a number; its width can vary by Amex feed, so do not assume a fixed length. Null on every other network — Visa and Mastercard authorizations correlate on `transactionReference` / `approvalCode` instead. Treat null as normal, not as an error."},"discountAmount":{"type":"number","nullable":true,"example":0.64,"description":"The issuer-reported discount that the merchant netted from the settled amount. Today this is populated for Corpay fleet fuel coupons on Mastercard SmartData clearings. It is a positive amount in the message's `cardholderBillingCurrency`. The parent transaction's `cardholderBillingSettledAmount` is grossed up to the pre-discount statement figure, so `discountAmount` is informational. Use it to reconcile the settled amount against the receipt or fuel-card statement, which shows the discounted figure. Null on every other message, including authorizations and clearings with no coupon. Treat null as normal, not as an error."},"bankData":{"type":"object","nullable":true,"description":"Bank-side provenance, present only on bank-sourced messages (null otherwise). Deliberately slim — the bank's merchant string, dates and amounts map into the canonical fields above; `bankTransactionId` is the stable join key back to the bank feed. It equals `banktransaction.created.id` and `transaction.match.created.matches[].id`, and resolves via `GET /bank-transactions/{id}` for the full bank record.","properties":{"provider":{"type":"string","enum":["plaid","mastercard-open-finance"],"description":"Open banking provider that observed the bank transaction. `mastercard-open-finance` appears once the Mastercard rail is enabled for the subaccount; the payload shape is identical across providers."},"bankTransactionId":{"type":"string","format":"uuid","description":"The bank transaction entity id — the canonical, lifecycle-stable join key across every bank-data surface."},"personalFinanceCategory":{"type":"object","nullable":true,"description":"Provider categorization of the bank transaction — the one bank-only datum with no card-side equivalent.","properties":{"primary":{"type":"string","description":"Primary category (e.g. FOOD_AND_DRINK)."},"detailed":{"type":"string","nullable":true,"description":"Detailed category (e.g. FOOD_AND_DRINK_RESTAURANT)."}}}},"required":["provider","bankTransactionId"]},"cardId":{"type":"string","format":"uuid","nullable":true,"description":"The unique identifier of the card related to this entity. Null only for bank-sourced messages from a bank account with no linked cards (the card-less unified feed)."},"cardType":{"type":"string","description":"The type of card used in the transaction. The only available value is 'virtual' and the field is nullable."},"cardholderBillingAmount":{"type":"number","description":"The amount in the currency of the country of issuance. The transactionAmount and cardholderBillingAmount values may differ in case of international transactions."},"cardholderBillingCurrency":{"type":"string","description":"The currency of the country of issuance following ISO 4217 alpha-3 format."},"createdDateTime":{"type":"string","format":"date-time","description":"Date and time when this resource was created, in UTC, following ISO 8601 format."},"dateTime":{"type":"string","format":"date-time","description":"The timestamp of the transaction message (e.g. authorization, movement of funds, etc) following ISO 8601 format. The timezone depends on the card network:\n- **Visa/Amex**: UTC (suffixed with `Z`)\n- **Mastercard**: Local time zone of the merchant/acquirer (no `Z` suffix, timezone offset not included)\n\nThe presence or absence of the `Z` suffix indicates whether the value is UTC or local time.\n\nSome messages carry an end-of-day value rather than the moment they happened:\n- **Visa clearings** (`FINL_ADVC`, `FINL_REQU`): the settlement date at `23:59:59Z`.\n- **Visa reversals** (`AUTH_ADVC` with a negative `transactionAmount`): `23:59:59Z` on the UTC day Astrada received the reversal.\n- **Amex clearings**: the business date at `23:59:59Z`.\n\nFor the date of the purchase itself, use the transaction's `transactionOccurrenceDate`.\n"},"messageType":{"type":"string","description":"The type of operation this transaction message represents. [Learn More](https://docs.astrada.co/docs/transaction-message)","enum":["AUTH_ADVC","AUTH_REQU","FINL_ADVC","CBCK_ADVC","FINL_REQU"]},"network":{"type":"string","description":"The rail that processed this payment. `OPEN_BANKING` marks a bank-sourced message with no card-network involvement (the concrete provider is in `bankData.provider`).","enum":["VISA","MASTERCARD","AMEX","OPEN_BANKING"]},"subaccountId":{"type":"string","description":"The unique identifier of the subaccount related to this entity.","format":"uuid"},"result":{"type":"string","description":"The issuer's decision on whether the transaction message is authorized.","enum":["APPROVED","DECLINED"]},"transactionAmount":{"type":"number","description":"The amount of the transaction message in the currency it was charged in. In the case of international transactions, the transactionAmount and cardholderBillingAmount may differ due to being in different currencies."},"transactionCurrency":{"type":"string","description":"The currency in which the transaction took place following ISO 4217 alpha-3 format."},"transactionReference":{"type":"string","description":"Identification of the Transaction that has to be unique for a time period."},"transactionType":{"type":"string","nullable":true,"description":"Types provide additional information about the transaction message, describing the effect that it had on the customer account and the type of accounts affected. [Learn More](https://docs.astrada.co/docs/transaction-message)","enum":["DEBIT_01","DEBIT_02","DEBIT_19","CREDIT_01","CREDIT_02","INQUIRY_01","TRANSFER_01","ADMIN_01","ADMIN_02"]},"transmissionDateTime":{"type":"string","nullable":true,"format":"date-time","description":"The timestamp of when the transaction message was received by the data source (i.e. Mastercard or Visa), in UTC, following ISO 8601 format."}},"required":["_links","acceptor","cardId","cardholderBillingAmount","cardholderBillingCurrency","createdDateTime","dateTime","id","messageType","network","result","subaccountId","transactionAmount","transactionCurrency","transactionReference","transactionType","transmissionDateTime"]},"raw-transaction-message":{"type":"object","properties":{"_links":{"type":"object","properties":{"self":{"$ref":"#/components/schemas/link"},"message":{"$ref":"#/components/schemas/link"}},"required":["message","self"]},"raw":{"type":"object","description":"The raw payload from the network that originated the underlying transaction message (will vary by network and message)."}},"required":["_links","raw"]},"webhook-event-types":{"type":"array","minItems":1,"items":{"type":"string","enum":["cardsubscription.created","cardsubscription.updated","cardholder.updated","transaction.created","transaction.updated","transactionmessage.created","networkbulkfeed.statechanged","enrichment.merchant.created","banklink.completed","bankaccount.state_changed","banktransaction.created","banktransaction.deleted","transaction.match.created","transaction.match.deleted"]}},"webhook":{"type":"object","description":"Astrada's Webhook resource.","properties":{"_links":{"type":"object","required":["self"],"properties":{"self":{"$ref":"#/components/schemas/link"}}},"id":{"type":"string","format":"uuid"},"url":{"type":"string","format":"uri"},"description":{"nullable":true,"type":"string"},"eventTypes":{"$ref":"#/components/schemas/webhook-event-types"},"subaccountId":{"type":"string","format":"uuid"},"createdAt":{"type":"string","format":"date-time","description":"Date and time when this resource was created, in UTC, following ISO 8601 format."},"updatedAt":{"type":"string","format":"date-time","description":"Date and time when this resource was last updated, in UTC, following ISO 8601 format."},"enabled":{"type":"boolean","default":true}},"required":["_links","id","url","description","eventTypes","subaccountId","createdAt","updatedAt"]},"bin-lookup":{"type":"object","properties":{"bin":{"type":"string","description":"The 6-digit Bank Identification Number (BIN) the answer was found under. It is always\nthe first 6 digits of the `bin` you sent, even when you sent more; the rest of your\ninput is never echoed back.\n","example":"411111"},"network":{"type":"string","description":"The card network (e.g., VISA, MASTERCARD, AMEX)","example":"VISA"},"type":{"type":"string","description":"The card type (e.g., COMMERCIAL, CORPORATE, CONSUMER, SMALL_BUSINESS )","enum":["COMMERCIAL","CORPORATE","CONSUMER","SMALL_BUSINESS"]},"fundingType":{"type":"string","description":"The card funding type (e.g., prepaid, debit, credit)","enum":["CREDIT","DEBIT","PREPAID"]},"cardCategory":{"type":"string","description":"The card's commercial classification, carried through from the BIN reference dataset.\nMore specific than `type`: it separates `FLEET`, `PURCHASING` and `GIFT` cards that\n`type` reports as `COMMERCIAL` or `CORPORATE`, and it is populated for many BINs where\n`type` is absent. `UNKNOWN` means the reference data does not classify the BIN — treat\nit as \"not determined\", not as \"consumer\".\n","nullable":true,"enum":["CONSUMER","BUSINESS","CORPORATE","FLEET","PURCHASING","GIFT","PREPAID","SPECIALTY","UNKNOWN",null]},"cardFundingType":{"type":"string","description":"How the card is funded, carried through from the BIN reference dataset. Broader than\n`fundingType`: it separates `CHARGE` cards (which `fundingType` reports as `CREDIT`)\nand `GIFT` cards (which `fundingType` reports as `PREPAID` or `DEBIT`). `UNKNOWN` means\nthe reference data does not classify the BIN.\n","nullable":true,"enum":["CREDIT","CHARGE","DEBIT","PREPAID","GIFT","UNKNOWN",null]},"issuerName":{"type":"string","description":"The name of the issuing bank. For a Mastercard card, this can be more specific to the\ndigits sent than the 6-digit BIN's issuer name (see `issuerCountry`).\n","example":"Bank of America"},"issuerCountry":{"type":"string","description":"The country of the issuing bank following ISO 3166 alpha-3. May be `null` when the\nBIN is known but the reference data does not record its issuing country (an unknown\nBIN returns 404, not `null`).\n\nFor a Mastercard card, this is checked against the digits sent and can differ from what\nthe first 6 digits alone would give, because one BIN can be shared by issuers in several\ncountries. Send more digits (up to 11) for a more precise issuer country; never send the\nfull card number.\n","nullable":true,"example":"USA"},"issuerCountryAmbiguous":{"type":"boolean","description":"Present, and always `true`, only when the digits sent match card ranges in more than\none country. `issuerCountry` is then the 6-digit BIN's value and may not be this card's\ncountry; `issuerCountryCandidates` lists the possible countries and `warnings` explains\nwhat to do. With fewer than 11 digits, sending more can resolve it. Omitted in every\nother case.\n","enum":[true],"example":true},"issuerCountryCandidates":{"type":"array","description":"The possible issuer countries (ISO 3166 alpha-3, sorted, at least two) when the digits\nsent match card ranges in more than one country. Present only together with\n`issuerCountryAmbiguous: true`.\n","items":{"type":"string","pattern":"^[A-Z]{3}$"},"minItems":2,"example":["DNK","NOR","SWE"]},"issuerRegion":{"type":"string","description":"The region of the issuing bank, derived from the issuer country. `EU` covers Europe\nand `MEA` covers the Middle East & Africa — these are separate buckets; there is no\ncombined `EMEA` value. `UNKNOWN` means the issuer country is missing or not mapped\nto a region — treat it as \"not determined\". It always matches the returned\n`issuerCountry`.\n","nullable":true,"enum":["NA","LATAM","EU","APAC","MEA","UNKNOWN",null],"example":"NA"},"warnings":{"type":"array","description":"Notes about the answer that a caller may want to act on. Present only when there is\nsomething to report, and never empty. Branch on `code`; `message` is for people and\nmay change.\n\nToday the only code is `ISSUER_COUNTRY_NOT_CONFIRMED`, sent together with\n`issuerCountryAmbiguous: true` when the digits sent match card ranges in more than one\ncountry. With fewer than 11 digits, sending more digits (up to 11) may confirm the\nissuer country. With 11 digits, the issuer country could not be confirmed.\n","minItems":1,"items":{"type":"object","properties":{"code":{"type":"string","description":"A stable code for programs to branch on. New codes may be added; ignore codes you\ndon't recognize.\n","enum":["ISSUER_COUNTRY_NOT_CONFIRMED"],"example":"ISSUER_COUNTRY_NOT_CONFIRMED"},"message":{"type":"string","description":"A human-readable explanation. The wording may change.","example":"These digits match card ranges in more than one country. Send up to 11 digits of the card number for a precise issuer country."}},"required":["code","message"]}}},"required":["bin","network","fundingType"]},"common-error":{"type":"object","properties":{"detail":{"type":"string"},"title":{"type":"string"}},"required":["detail","title"]}},"responses":{"bad-request":{"description":"The server cannot or will not process the request due to something that is perceived to be a client error","content":{"application/problem+json":{"schema":{"type":"object","properties":{"detail":{"type":"string"},"title":{"type":"string","enum":["Bad Request"]},"errors":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"detail":{"type":"string"}},"required":["title","detail"]}}},"required":["detail","title"]},"examples":{"Example Generic Bad Request Payload Response":{"value":{"title":"Bad Request","detail":"Request object failed validation."}},"Example Generic Bad Request Parameters Response":{"value":{"title":"Bad Request","detail":"Request parameters are invalid."}}}}}},"unauthorized":{"description":"Authentication credentials were either missing or incorrect","content":{"application/problem+json":{"schema":{"type":"object","properties":{"detail":{"type":"string"},"title":{"type":"string","enum":["Unauthorized"]}},"required":["detail","title"]},"example":{"title":"Unauthorized","detail":"Authentication credentials were either missing or incorrect."}}}},"forbidden":{"description":"Authentication credentials used do not have have permissions to perform the request","content":{"application/problem+json":{"schema":{"type":"object","properties":{"detail":{"type":"string"},"title":{"type":"string","enum":["Forbidden"]}},"required":["detail","title"]},"example":{"title":"Forbidden","detail":"You do not have permission to access the requested resource."}}}},"server-error":{"description":"The server encountered an unexpected condition that prevented it from fulfilling the request","content":{"application/problem+json":{"schema":{"type":"object","properties":{"detail":{"type":"string"},"title":{"type":"string","enum":["Internal Server Error"]}},"required":["detail","title"]},"example":{"title":"Internal Server Error","detail":"The server encountered an unexpected condition that prevented it from fulfilling the request."}}}},"not-found":{"description":"The requested resource was not found on the server","content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"instance":{"type":"string"},"detail":{"type":"string"},"title":{"type":"string","enum":["Not Found"]}},"required":["detail","title"]},"example":{"title":"Not Found","detail":"The requested resource was not found on the server."}}}},"content-too-large":{"description":"Content Too Large","content":{"application/problem+json":{"schema":{"type":"object","properties":{"detail":{"type":"string"},"title":{"type":"string","enum":["Content Too Large"]}},"required":["detail","title"]},"example":{"title":"Content Too Large","detail":"The size of the request payload exceeds the maximum limit allowed by the server. Please reduce the size of your request."}}}},"enrollment_link_forbidden":{"description":"The token holds none of the scopes the route accepts, or it is an enrollment link\nsession's token, which no scope lets manage links. A missing scope answers without a\n`code`. A link session token that holds an accepted scope answers with `code`\n`LINK_SESSION_FORBIDDEN`.\n","content":{"application/problem+json":{"schema":{"type":"object","properties":{"title":{"type":"string","enum":["Forbidden"]},"detail":{"type":"string"},"code":{"type":"string","enum":["LINK_SESSION_FORBIDDEN"]}},"required":["title","detail"]},"example":{"title":"Forbidden","detail":"An enrollment link session cannot call this route.","code":"LINK_SESSION_FORBIDDEN"}}}},"enrollment_link_subaccount_not_found":{"description":"The subaccount is not one of your account's subaccounts. Nothing is created.\n","content":{"application/problem+json":{"schema":{"type":"object","properties":{"title":{"type":"string","enum":["Not Found"]},"detail":{"type":"string"},"code":{"type":"string","enum":["SUBACCOUNT_NOT_FOUND"]}},"required":["title","detail","code"]},"example":{"title":"Not Found","detail":"Subaccount with the given ID was not found.","code":"SUBACCOUNT_NOT_FOUND"}}}},"enrollment_link_conflict":{"description":"The link was not created, and nothing is stored. `code` says why:\n\n- `ENROLLMENT_LINKS_NOT_ENABLED`: enrollment links are not enabled for the account.\n  Astrada enables them per account.\n- `CARD_ENROLLMENT_OFF`: card enrollment is off for the subaccount (its\n  `enrollmentPolicy.cardEnrollment` is `false`). The hosted page offers card enrollment\n  only, so a link would have nothing to enroll.\n","content":{"application/problem+json":{"schema":{"type":"object","properties":{"title":{"type":"string","enum":["Conflict"]},"detail":{"type":"string"},"code":{"type":"string","enum":["ENROLLMENT_LINKS_NOT_ENABLED","CARD_ENROLLMENT_OFF"]}},"required":["title","detail","code"]},"examples":{"Links not enabled":{"value":{"title":"Conflict","detail":"Enrollment links are not enabled for this account.","code":"ENROLLMENT_LINKS_NOT_ENABLED"}},"Card enrollment off":{"value":{"title":"Conflict","detail":"Card enrollment is off for this subaccount, so an enrollment link would have nothing to enroll.","code":"CARD_ENROLLMENT_OFF"}}}}}},"enrollment_link_rate_limited":{"description":"A rate limit was reached. The operation's description names its limits. Retry later.\n","content":{"application/problem+json":{"schema":{"type":"object","properties":{"title":{"type":"string","enum":["Too Many Requests"]},"detail":{"type":"string"},"code":{"type":"string","enum":["RATE_LIMITED"]}},"required":["title","detail","code"]},"example":{"title":"Too Many Requests","detail":"Too many requests. Retry later.","code":"RATE_LIMITED"}}}},"enrollment_link_not_found":{"description":"No link with this id belongs to your account. Another account's link answers the same.\n","content":{"application/problem+json":{"schema":{"type":"object","properties":{"title":{"type":"string","enum":["Not Found"]},"detail":{"type":"string"},"code":{"type":"string","enum":["ENROLLMENT_LINK_NOT_FOUND"]}},"required":["title","detail","code"]},"example":{"title":"Not Found","detail":"Enrollment link with the given ID was not found.","code":"ENROLLMENT_LINK_NOT_FOUND"}}}},"conflict":{"description":"Request conflict with the current state of the target resource","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/conflict"},"examples":{"Minimum shape (detail only)":{"value":{"detail":"Card verification with id=9fab1bea-bc1e-4757-bd47-479422e5983b was abandoned by the user during the authentication process. Please start a new verification."}},"Resource conflict with currentValue":{"value":{"title":"Conflict","detail":"The target resource already exists.","currentValue":"396aebd2-002f-4ccf-9b4d-f961c693e6e2"}}}}}},"unprocessable-entity":{"description":"The request is well formatted but it fails some business logic validation","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/unprocessable-entity"},"example":{"title":"Unprocessable Entity","detail":"The request is well formatted but it fails some business logic validation"}}}},"no-content":{"description":"The request has been successfully processed and there is no content to return"}},"examples":{"card-subscription":{"description":"Example of Card Subscription resource","value":{"_links":{"self":{"href":"/card-subscriptions/75ea3c99-6bf5-4b16-8f68-0cdc43d75806"},"card":{"href":"/cards/5dec2c49-0aa5-4683-a317-427eb5d115f3"}},"id":"75ea3c99-6bf5-4b16-8f68-0cdc43d75806","subaccountId":"f297d659-c13d-4219-aeaa-e10a845140a5","cardId":"5dec2c49-0aa5-4683-a317-427eb5d115f3","customerReferenceId":"5dec2c49-0aa5-4683-a317-427eb5d115f3","networkBulkFeedId":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","enrollmentType":"cardholder-single","state":"active","effectiveDate":"2024-12-20T14:45:00Z","expirationDate":"2025-06-19T14:45:00Z","createdAt":"2024-12-19T14:45:00Z","updatedAt":"2024-12-19T14:45:00Z"}},"card-subscription-with-network-bulk-feed-reference":{"description":"Example of Card Subscription resource","value":{"_links":{"self":{"href":"/card-subscriptions/75ea3c99-6bf5-4b16-8f68-0cdc43d75806"},"card":{"href":"/cards/5dec2c49-0aa5-4683-a317-427eb5d115f3"},"networkBulkFeed":{"href":"/network-bulk-feeds/5ccc9922-e763-4492-b693-b6a922d96049"}},"id":"75ea3c99-6bf5-4b16-8f68-0cdc43d75806","subaccountId":"f297d659-c13d-4219-aeaa-e10a845140a5","cardId":"5dec2c49-0aa5-4683-a317-427eb5d115f3","customerReferenceId":"5dec2c49-0aa5-4683-a317-427eb5d115f3","networkBulkFeedId":"5ccc9922-e763-4492-b693-b6a922d96049","enrollmentType":"network-bulk","state":"active","effectiveDate":"2024-12-20T14:45:00Z","expirationDate":"2025-06-19T14:45:00Z","createdAt":"2024-12-19T14:45:00Z","updatedAt":"2024-12-19T14:45:00Z"}},"card-subscription-with-bank-feed":{"description":"Example of a bank-feed Card Subscription resource — a card materialized from a connected bank account at bank-link completion (e.g. American Express via the hosted bank-linking flow). `bankAccountId` back-references the source account and the `bankAccount` link is present; the subscription is born `active`.","value":{"_links":{"self":{"href":"/card-subscriptions/1b671a64-40d5-491e-99b0-da01ff1f3341"},"card":{"href":"/cards/9e107d9d-372b-4d1a-9f4a-654321abcdef"},"bankAccount":{"href":"/bank-accounts/059d5e6a-cfb1-46e6-ab84-6586582b6b58"}},"id":"1b671a64-40d5-491e-99b0-da01ff1f3341","subaccountId":"6103874b-248d-4825-af88-a0d24dd9b123","cardId":"9e107d9d-372b-4d1a-9f4a-654321abcdef","customerReferenceId":null,"bankAccountId":"059d5e6a-cfb1-46e6-ab84-6586582b6b58","networkBulkFeedId":null,"enrollmentType":"bank-feed","state":"active","effectiveDate":"2026-07-14T12:00:00.000Z","expirationDate":"2099-12-31T23:59:59.999Z","createdAt":"2026-07-14T12:00:00.000Z","updatedAt":"2026-07-14T12:00:00.000Z"}},"card-subscription-expanded":{"description":"Example of Card Subscription resource requested with `expand=card,cardholder`","value":{"_links":{"self":{"href":"/card-subscriptions/75ea3c99-6bf5-4b16-8f68-0cdc43d75806"},"card":{"href":"/cards/5dec2c49-0aa5-4683-a317-427eb5d115f3"},"verifications":{"href":"/card-verifications/3ds?cardId=5dec2c49-0aa5-4683-a317-427eb5d115f3"}},"_embedded":{"card":{"_links":{"self":{"href":"/cards/5dec2c49-0aa5-4683-a317-427eb5d115f3"},"cardholder":{"href":"/cards/5dec2c49-0aa5-4683-a317-427eb5d115f3/cardholder"}},"id":"5dec2c49-0aa5-4683-a317-427eb5d115f3","expiryMonth":11,"expiryYear":2028,"network":"mastercard","country":"USA","createdAt":"2024-12-19T14:45:00Z","updatedAt":"2024-12-19T14:45:00Z","first6digits":"434343","last4digits":"4343","subaccountId":"f297d659-c13d-4219-aeaa-e10a845140a5"},"cardholder":{"_links":{"self":{"href":"/cards/5dec2c49-0aa5-4683-a317-427eb5d115f3/cardholder"}},"firstName":"John","lastName":"Doe","email":"john.doe@example.com","postalCode":"94105","corporate":{"alternativeEmployeeId":"ALT-EMP-12345","employeeId":"bb1afe4eb840","id":"ABC123456789","legalEntity":{"id":"FR01","name":"Example Company France SAS"}},"createdAt":"2024-12-19T14:45:00Z","updatedAt":"2024-12-19T14:45:00Z"}},"id":"75ea3c99-6bf5-4b16-8f68-0cdc43d75806","subaccountId":"f297d659-c13d-4219-aeaa-e10a845140a5","cardId":"5dec2c49-0aa5-4683-a317-427eb5d115f3","customerReferenceId":"5dec2c49-0aa5-4683-a317-427eb5d115f3","networkBulkFeedId":null,"enrollmentType":"cardholder-single","state":"active","effectiveDate":"2024-12-20T14:45:00Z","expirationDate":"2025-06-19T14:45:00Z","createdAt":"2024-12-19T14:45:00Z","updatedAt":"2024-12-19T14:45:00Z"}},"card-subscription-deactivated":{"description":"Example of a deactivated Card Subscription with a deactivation reason","value":{"_links":{"self":{"href":"/card-subscriptions/75ea3c99-6bf5-4b16-8f68-0cdc43d75806"},"card":{"href":"/cards/5dec2c49-0aa5-4683-a317-427eb5d115f3"}},"id":"75ea3c99-6bf5-4b16-8f68-0cdc43d75806","subaccountId":"f297d659-c13d-4219-aeaa-e10a845140a5","cardId":"5dec2c49-0aa5-4683-a317-427eb5d115f3","customerReferenceId":"5dec2c49-0aa5-4683-a317-427eb5d115f3","enrollmentType":"cardholder-single","state":"deactivated","deactivationReason":"cardholder_offboarded","effectiveDate":"2024-12-20T14:45:00Z","expirationDate":"2025-06-19T14:45:00Z","createdAt":"2024-12-19T14:45:00Z","updatedAt":"2025-02-03T09:12:00Z"}},"card-verification":{"description":"Example of Card Verification resource","value":{"_links":{"self":{"href":"/card-verifications/3ds/9fab1bea-bc1e-4757-bd47-479422e5983b"},"steps":{"href":"/card-verifications/3ds/9fab1bea-bc1e-4757-bd47-479422e5983b/steps"},"currentStep":{"href":"/card-verifications/3ds/9fab1bea-bc1e-4757-bd47-479422e5983b/steps/fingerprint"}},"id":"9fab1bea-bc1e-4757-bd47-479422e5983b","subaccountId":"f297d659-c13d-4219-aeaa-e10a845140a5","cardId":"8309b5f8-d5d8-49bb-9001-38bf1bb0f1e4","type":"3DS","currentStepId":"fingerprint","state":"in-progress","createdAt":"2024-01-04T18:53:32.000Z","updatedAt":"2023-01-04T10:55:12.000Z"}},"card-verification-failed":{"description":"Example of a failed Card Verification, with a populated failureReason explaining why the 3DS verification failed.","value":{"_links":{"self":{"href":"/card-verifications/3ds/9fab1bea-bc1e-4757-bd47-479422e5983b"},"steps":{"href":"/card-verifications/3ds/9fab1bea-bc1e-4757-bd47-479422e5983b/steps"}},"id":"9fab1bea-bc1e-4757-bd47-479422e5983b","subaccountId":"f297d659-c13d-4219-aeaa-e10a845140a5","cardId":"8309b5f8-d5d8-49bb-9001-38bf1bb0f1e4","type":"3DS","currentStepId":null,"state":"failed","authenticationFlow":"frictionless","failureReason":{"category":"authentication_declined","description":"The card issuer declined the 3-D Secure authentication.","retryable":true,"issuerMessage":"Your bank declined this verification. Please contact your bank or try another card.","code":"05","acsReferences":{"acsTransactionId":"8a880dc0-d2d2-4067-bcb1-b08d1690b26e","acsReferenceNumber":"ACME-ACS-2024-0042","dsTransactionId":"97267598-fae6-494f-8453-2d3807e0c77f"}},"createdAt":"2024-01-04T18:53:32.000Z","updatedAt":"2024-01-04T18:55:12.000Z"}},"card":{"description":"Example of Card resource","value":{"_links":{"self":{"href":"/cards/f744b691-bf05-4f2a-ab89-bb1afe4eb840"}},"id":"f744b691-bf05-4f2a-ab89-bb1afe4eb840","expiryMonth":11,"expiryYear":2028,"network":"mastercard","country":"USA","createdAt":"2024-02-04T18:41:16.142Z","updatedAt":"2024-02-04T18:41:16.142Z","first6digits":"434343","last4digits":"4343","subaccountId":"da6649a8-f0ea-4af0-b342-c0b5c3e024dd"}},"card-with-cardholder":{"description":"Example of Card resource with cardholder link, available only when card has been bulk enrolled","value":{"_links":{"self":{"href":"/cards/31e63088-48b3-42dd-b6d4-fdd058675ec9"},"cardholder":{"href":"/cards/31e63088-48b3-42dd-b6d4-fdd058675ec9/cardholder"}},"id":"31e63088-48b3-42dd-b6d4-fdd058675ec9","expiryMonth":11,"expiryYear":2028,"network":"mastercard","country":"USA","createdAt":"2024-02-04T18:41:16.142Z","updatedAt":"2024-02-04T18:41:16.142Z","first6digits":"434343","last4digits":"4343","subaccountId":"fd03abe1-5ac3-41ac-96cc-d2a66aafc74f"}},"card-expanded":{"description":"Example of a Card resource requested with `expand=cardholder`","value":{"_links":{"self":{"href":"/cards/31e63088-48b3-42dd-b6d4-fdd058675ec9"},"cardholder":{"href":"/cards/31e63088-48b3-42dd-b6d4-fdd058675ec9/cardholder"}},"_embedded":{"cardholder":{"_links":{"self":{"href":"/cards/31e63088-48b3-42dd-b6d4-fdd058675ec9/cardholder"}},"firstName":"John","lastName":"Doe","email":"john.doe@example.com","postalCode":"94105","corporate":{"alternativeEmployeeId":"ALT-EMP-12345","employeeId":"bb1afe4eb840","id":"ABC123456789","legalEntity":{"id":"FR01","name":"Example Company France SAS"}},"createdAt":"2024-02-04T18:41:16.142Z","updatedAt":"2024-02-04T18:41:16.142Z"}},"id":"31e63088-48b3-42dd-b6d4-fdd058675ec9","expiryMonth":11,"expiryYear":2028,"network":"mastercard","country":"USA","createdAt":"2024-02-04T18:41:16.142Z","updatedAt":"2024-02-04T18:41:16.142Z","first6digits":"434343","last4digits":"4343","subaccountId":"fd03abe1-5ac3-41ac-96cc-d2a66aafc74f"}},"cardholder":{"description":"Example of Cardholder resource","value":{"_links":{"self":{"href":"/cards/f744b691-bf05-4f2a-ab89-bb1afe4eb840/cardholder"}},"firstName":"John","lastName":"Doe","email":"john.doe@example.com","postalCode":"94105","corporate":{"alternativeEmployeeId":"ALT-EMP-12345","employeeId":"bb1afe4eb840","id":"ABC123456789","legalEntity":{"id":"FR01","name":"Example Company France SAS"}},"createdAt":"2024-02-04T18:41:16.142Z","updatedAt":"2024-02-04T18:41:16.142Z"}},"enrollment-links-page":{"description":"A page of two links with more to follow: a team link made from the SDK and a used\npersonal link.\n","value":{"_embedded":{"enrollmentLinks":[{"_links":{"self":{"href":"/enrollment-links/8e2f4a6c-1b3d-4e5f-9a7b-2c4d6e8f0a1b"}},"id":"8e2f4a6c-1b3d-4e5f-9a7b-2c4d6e8f0a1b","kind":"team","subaccountId":"6f1c2a3b-4d5e-4f60-8a7b-9c0d1e2f3a4b","startingPoint":"card","state":"active","expiresAt":"2026-11-19T10:00:00.000Z","maxUses":50,"uses":12,"starts":12,"createdBy":{"via":"sdk","clientId":"5a7c9e1b-3d5f-4a6c-8e0b-2d4f6a8c0e1f"},"createdAt":"2026-11-05T10:00:00.000Z","updatedAt":"2026-11-06T16:41:05.000Z"},{"_links":{"self":{"href":"/enrollment-links/1d0a6c52-8f3e-4b7a-9c21-5e4d3b2a1f09"}},"id":"1d0a6c52-8f3e-4b7a-9c21-5e4d3b2a1f09","kind":"cardholder","subaccountId":"6f1c2a3b-4d5e-4f60-8a7b-9c0d1e2f3a4b","startingPoint":"card","state":"used","expiresAt":"2026-11-11T18:00:00.000Z","maxUses":1,"uses":1,"starts":2,"customerReferenceId":"2b7e9d14-5c3a-4f8e-9b21-0d6c4a8e7f35","platformName":"Ledgerly","organizationName":"Vertex Industries","createdBy":{"via":"api","clientId":"3f9c1e7a-2b4d-4c6e-8f0a-1b3d5e7f9a2c"},"createdAt":"2026-11-04T18:00:00.000Z","updatedAt":"2026-11-05T09:14:22.000Z","usedAt":"2026-11-05T09:14:22.000Z"}]},"_links":{"self":{"href":"/enrollment-links?subaccountId=6f1c2a3b-4d5e-4f60-8a7b-9c0d1e2f3a4b&limit=2"},"next":{"href":"/enrollment-links?subaccountId=6f1c2a3b-4d5e-4f60-8a7b-9c0d1e2f3a4b&limit=2&cursor=eyJwayI6ImxpbmsjMWQwYTZjNTIifQ"}}}},"enrollment-link-created":{"description":"A personal link just created in sandbox. The url is returned only here.","value":{"_links":{"self":{"href":"/enrollment-links/1d0a6c52-8f3e-4b7a-9c21-5e4d3b2a1f09"}},"id":"1d0a6c52-8f3e-4b7a-9c21-5e4d3b2a1f09","kind":"cardholder","subaccountId":"6f1c2a3b-4d5e-4f60-8a7b-9c0d1e2f3a4b","startingPoint":"card","state":"active","expiresAt":"2026-11-11T18:00:00.000Z","maxUses":1,"uses":0,"starts":0,"customerReferenceId":"2b7e9d14-5c3a-4f8e-9b21-0d6c4a8e7f35","platformName":"Ledgerly","organizationName":"Vertex Industries","createdBy":{"via":"api","clientId":"3f9c1e7a-2b4d-4c6e-8f0a-1b3d5e7f9a2c"},"createdAt":"2026-11-04T18:00:00.000Z","updatedAt":"2026-11-04T18:00:00.000Z","url":"https://sdk.sandbox.astrada.co/unified/v2/enroll.html#el1_4bT7m2QxwZ9lK1pN0vYcRfHsUeGdJaLoWiXqBnMzE3S"}},"enrollment-link-detail":{"description":"The personal link after use: the first session expired without completing, the second\nreported one card.\n","value":{"_links":{"self":{"href":"/enrollment-links/1d0a6c52-8f3e-4b7a-9c21-5e4d3b2a1f09"}},"id":"1d0a6c52-8f3e-4b7a-9c21-5e4d3b2a1f09","kind":"cardholder","subaccountId":"6f1c2a3b-4d5e-4f60-8a7b-9c0d1e2f3a4b","startingPoint":"card","state":"used","expiresAt":"2026-11-11T18:00:00.000Z","maxUses":1,"uses":1,"starts":2,"customerReferenceId":"2b7e9d14-5c3a-4f8e-9b21-0d6c4a8e7f35","platformName":"Ledgerly","organizationName":"Vertex Industries","createdBy":{"via":"api","clientId":"3f9c1e7a-2b4d-4c6e-8f0a-1b3d5e7f9a2c"},"createdAt":"2026-11-04T18:00:00.000Z","updatedAt":"2026-11-05T09:14:22.000Z","usedAt":"2026-11-05T09:14:22.000Z","sessions":[{"id":"7b9d1f3a-5c7e-4a9b-8d1f-3a5c7e9b1d3f","state":"expired","startedAt":"2026-11-05T08:02:10.000Z","expiresAt":"2026-11-05T09:02:10.000Z"},{"id":"9a3e5c7b-1d2f-4e6a-8b0c-3e5a7c9e1b2d","state":"completed","startedAt":"2026-11-05T09:05:40.000Z","expiresAt":"2026-11-05T10:05:40.000Z","completedAt":"2026-11-05T09:14:22.000Z","outcome":{"subscriptionIds":["c4e6a8b0-2d4f-4a6c-9e1b-3d5f7a9c1e3b"],"cardIds":["e1b3d5f7-9a1c-4e3b-8d5f-7a9c1e3b5d7f"],"summary":{"cardsEnrolled":1}}}]}},"enrollment-link-revoked":{"description":"The team link after it was revoked.","value":{"_links":{"self":{"href":"/enrollment-links/8e2f4a6c-1b3d-4e5f-9a7b-2c4d6e8f0a1b"}},"id":"8e2f4a6c-1b3d-4e5f-9a7b-2c4d6e8f0a1b","kind":"team","subaccountId":"6f1c2a3b-4d5e-4f60-8a7b-9c0d1e2f3a4b","startingPoint":"card","state":"revoked","expiresAt":"2026-11-19T10:00:00.000Z","maxUses":50,"uses":12,"starts":12,"createdBy":{"via":"sdk","clientId":"5a7c9e1b-3d5f-4a6c-8e0b-2d4f6a8c0e1f"},"createdAt":"2026-11-05T10:00:00.000Z","updatedAt":"2026-11-07T09:30:00.000Z","revokedAt":"2026-11-07T09:30:00.000Z"}},"network-bulk-feeds":{"description":"Example of a Network Bulk Feed resource","value":{"_links":{"self":{"href":"/network-bulk-feeds/75ea3c99-6bf5-4b16-8f68-0cdc43d75806"}},"id":"75ea3c99-6bf5-4b16-8f68-0cdc43d75806","subaccountId":"f297d659-c13d-4219-aeaa-e10a845140a5","network":"MASTERCARD","networkReference":"G1234567","state":"submitted","type":"SMARTDATA","panFormat":"encrypted","createdAt":"2024-12-19T14:45:00Z","updatedAt":"2024-12-19T14:45:00Z"}},"network-bulk-feeds-failed":{"description":"Example of a Network Bulk Feed resource in failed state (VISA)","value":{"_links":{"self":{"href":"/network-bulk-feeds/a3b1c2d4-5e6f-7890-abcd-ef1234567890"}},"id":"a3b1c2d4-5e6f-7890-abcd-ef1234567890","subaccountId":"f297d659-c13d-4219-aeaa-e10a845140a5","network":"VISA","networkReference":"1_1_9999_789452","state":"failed","type":"VBDS","panFormat":"encrypted","errorReason":"Starter data ingestion failed: invalid RPIC configuration","createdAt":"2024-12-19T14:45:00Z","updatedAt":"2024-12-20T10:30:00Z"}},"network-bulk-enrollment":{"description":"Example of a Network Bulk Enrollment resource, before a feed is registered","value":{"_links":{"self":{"href":"/network-bulk-enrollments/9c1f0c4e-2f0e-4a9c-9a1b-0c1d2e3f4a5b"}},"id":"9c1f0c4e-2f0e-4a9c-9a1b-0c1d2e3f4a5b","subaccountId":"24c4f90d-ab3b-4f6e-8a1d-d251a4fcf34c","network":"MASTERCARD","bin":"51075500","binInfo":{"issuerName":"Jack Henry And Associates","issuerCountry":"USA","type":"COMMERCIAL","fundingType":"CREDIT"},"company":{"legalName":"Vertex Industries, Inc."},"cardAdmin":{"name":"Dana Whitfield","email":"dana.whitfield@vertexind.com"},"bankContact":{"name":"Sam Lee","email":"sam.lee@bank.example"},"cardCountBand":"251-1000","outreach":"astrada","consent":{"acceptedAt":"2026-09-10T21:30:00.000Z","version":"kickoff-consent-v1"},"state":"requested","networkBulkFeedId":null,"customerReferenceId":"ledgerly-customer-8842","createdAt":"2026-09-10T21:30:00.000Z","updatedAt":"2026-09-10T21:30:00.000Z"}},"network-bulk-enrollment-summary":{"description":"Example of the summary returned when the program already has an open kickoff that another request wrote","value":{"_links":{"self":{"href":"/network-bulk-enrollments/9c1f0c4e-2f0e-4a9c-9a1b-0c1d2e3f4a5b"}},"alreadyOpen":true,"id":"9c1f0c4e-2f0e-4a9c-9a1b-0c1d2e3f4a5b","subaccountId":"24c4f90d-ab3b-4f6e-8a1d-d251a4fcf34c","network":"MASTERCARD","state":"requested","networkBulkFeedId":null,"requestId":"6b0e2a94-3d71-4c58-9f2e-1a7c5d8b3e60","createdAt":"2026-09-10T21:30:00.000Z"}},"network-bulk-enrollment-minimal":{"description":"Example of a Network Bulk Enrollment resource created with the required fields only (self outreach)","value":{"_links":{"self":{"href":"/network-bulk-enrollments/2b7e4d10-6c3a-4f8e-9d21-5a0c7b9e1f43"}},"id":"2b7e4d10-6c3a-4f8e-9d21-5a0c7b9e1f43","subaccountId":"24c4f90d-ab3b-4f6e-8a1d-d251a4fcf34c","network":"VISA","bin":"414720","binInfo":null,"company":{"legalName":"Northwind Traders LLC"},"cardAdmin":{"name":"Priya Natarajan","email":"priya.natarajan@northwind.example"},"bankContact":null,"cardCountBand":null,"outreach":"self","consent":{"acceptedAt":"2026-09-11T08:05:12.000Z","version":"kickoff-consent-v1"},"state":"requested","networkBulkFeedId":null,"customerReferenceId":null,"createdAt":"2026-09-11T08:05:12.000Z","updatedAt":"2026-09-11T08:05:12.000Z"}},"network-bulk-enrollment-feed-created":{"description":"Example of a Network Bulk Enrollment resource after its network bulk feed was registered","value":{"_links":{"self":{"href":"/network-bulk-enrollments/9c1f0c4e-2f0e-4a9c-9a1b-0c1d2e3f4a5b"},"networkBulkFeed":{"href":"/network-bulk-feeds/75ea3c99-6bf5-4b16-8f68-0cdc43d75806"}},"id":"9c1f0c4e-2f0e-4a9c-9a1b-0c1d2e3f4a5b","subaccountId":"24c4f90d-ab3b-4f6e-8a1d-d251a4fcf34c","network":"MASTERCARD","bin":"51075500","binInfo":{"issuerName":"Jack Henry And Associates","issuerCountry":"USA","type":"COMMERCIAL","fundingType":"CREDIT"},"company":{"legalName":"Vertex Industries, Inc."},"cardAdmin":{"name":"Dana Whitfield","email":"dana.whitfield@vertexind.com"},"bankContact":{"name":"Sam Lee","email":"sam.lee@bank.example"},"cardCountBand":"251-1000","outreach":"astrada","consent":{"acceptedAt":"2026-09-10T21:30:00.000Z","version":"kickoff-consent-v1"},"state":"feed-created","networkBulkFeedId":"75ea3c99-6bf5-4b16-8f68-0cdc43d75806","customerReferenceId":"ledgerly-customer-8842","createdAt":"2026-09-10T21:30:00.000Z","updatedAt":"2026-10-02T15:12:40.000Z"}},"subaccount":{"description":"Example of Subaccount resource","value":{"_links":{"self":{"href":"/subaccounts/81e7c267-0927-4234-a2bd-78cef799de54"}},"accountId":"073fe1bb-3350-46ad-b3a6-32afb3780994","id":"81e7c267-0927-4234-a2bd-78cef799de54","name":"Subaccount A","createdAt":"2024-05-01T17:08:43.810Z","updatedAt":"2024-05-01T17:08:43.810Z","configurations":{"VISA":{"countries":["USA","CAN"],"single-enrollment":{"countries":["USA"],"blockedCardTypes":["CONSUMER"],"blockedFundingCardTypes":["DEBIT"]},"bulk-enrollment":{"countries":["CAN"],"blockedCardTypes":["CONSUMER"],"blockedFundingCardTypes":["DEBIT"]}},"MASTERCARD":{"countries":["USA"],"single-enrollment":{"countries":["USA"],"blockedCardTypes":["CONSUMER"],"blockedFundingCardTypes":["DEBIT"]},"bulk-enrollment":{"countries":["GBR"],"blockedCardTypes":["CONSUMER"],"blockedFundingCardTypes":["DEBIT"]}},"AMEX":{"countries":["ITA"],"single-enrollment":{"countries":["ITA"],"blockedCardTypes":["CONSUMER"],"blockedFundingCardTypes":["DEBIT"]},"bulk-enrollment":{"countries":["SWE"],"blockedCardTypes":["CONSUMER"],"blockedFundingCardTypes":["DEBIT"]}}}}},"subaccount-team-link":{"description":"A subaccount read with an SDK token (card-subscriptions:write) while enrollment links are\nenabled for the account and the subaccount's card enrollment is on, so _links.team-link\nis present\n","value":{"_links":{"self":{"href":"/subaccounts/6f1c2a3b-4d5e-4f60-8a7b-9c0d1e2f3a4b"},"team-link":{"href":"/subaccounts/6f1c2a3b-4d5e-4f60-8a7b-9c0d1e2f3a4b/team-link"}},"accountId":"073fe1bb-3350-46ad-b3a6-32afb3780994","id":"6f1c2a3b-4d5e-4f60-8a7b-9c0d1e2f3a4b","name":"Vertex Industries","createdAt":"2026-10-01T12:00:00.000Z","updatedAt":"2026-10-20T08:30:00.000Z","configurations":{"VISA":{"countries":["USA"],"single-enrollment":{"countries":["USA"],"blockedCardTypes":["CONSUMER"],"blockedFundingCardTypes":["DEBIT"]},"bulk-enrollment":{"countries":["USA"],"blockedCardTypes":["CONSUMER"],"blockedFundingCardTypes":["DEBIT"]}}}}},"subaccount-ignored-fields":{"description":"Example of an updated Subaccount whose request sent enrollmentPolicy keys the endpoint ignores (a misspelled bulkEnrolment and the Astrada-managed linkAnotherCard)","value":{"_links":{"self":{"href":"/subaccounts/81e7c267-0927-4234-a2bd-78cef799de54"}},"accountId":"073fe1bb-3350-46ad-b3a6-32afb3780994","id":"81e7c267-0927-4234-a2bd-78cef799de54","name":"Subaccount A","createdAt":"2024-05-01T17:08:43.810Z","updatedAt":"2026-11-03T18:20:11.402Z","configurations":{"VISA":{"countries":["USA"],"single-enrollment":{"countries":["USA"],"blockedCardTypes":["CONSUMER"],"blockedFundingCardTypes":["DEBIT"]},"bulk-enrollment":{"countries":["USA"],"blockedCardTypes":["CONSUMER"],"blockedFundingCardTypes":["DEBIT"]}}},"enrollmentPolicy":{"bankEnrollment":"on"},"ignoredFields":["enrollmentPolicy.bulkEnrolment","enrollmentPolicy.linkAnotherCard"]}},"transaction":{"description":"Example of Transaction resource","value":{"_links":{"card":{"href":"/cards/4d1ff59f-4286-4209-9662-92e174193562"},"subaccount":{"href":"/subaccounts/c6d5e036-361e-4773-a514-b9496cf2d2b5"},"self":{"href":"/transactions/8697df0c-9011-47ca-a52b-8d2a7a4ad903"},"messages":[{"href":"/transaction-messages/f4b24a0a-6a37-4ce3-8845-ddf0b604a9b4"},{"href":"/transaction-messages/934f8701-53e3-4a2b-a000-6bb52195d2ea"}]},"acceptor":{"city":"LONDON","country":"GBR","mcc":"5734","state":"LND"},"cardId":"4d1ff59f-4286-4209-9662-92e174193562","cardholderBillingCurrency":"GBP","cardholderBillingHoldAmount":0,"cardholderBillingSettledAmount":0.81,"createdAt":"2024-05-01T06:41:43.810Z","descriptor":"Uber","id":"8697df0c-9011-47ca-a52b-8d2a7a4ad903","network":"MASTERCARD","status":"SETTLED","subaccountId":"c6d5e036-361e-4773-a514-b9496cf2d2b5","supersededMessageIds":[],"transactionCurrency":"USD","transactionHoldAmount":0,"transactionOccurrenceDate":"2024-05-01","transactionSettledAmount":1,"updatedAt":"2024-05-02T08:41:43.810Z"}},"transaction-expanded":{"description":"Example of Transaction resource requested with `expand=cardSubscription`","value":{"_links":{"card":{"href":"/cards/4d1ff59f-4286-4209-9662-92e174193562"},"subaccount":{"href":"/subaccounts/c6d5e036-361e-4773-a514-b9496cf2d2b5"},"self":{"href":"/transactions/8697df0c-9011-47ca-a52b-8d2a7a4ad903"},"messages":[{"href":"/transaction-messages/f4b24a0a-6a37-4ce3-8845-ddf0b604a9b4"},{"href":"/transaction-messages/934f8701-53e3-4a2b-a000-6bb52195d2ea"}]},"_embedded":{"cardSubscription":{"_links":{"self":{"href":"/card-subscriptions/75ea3c99-6bf5-4b16-8f68-0cdc43d75806"},"card":{"href":"/cards/4d1ff59f-4286-4209-9662-92e174193562"},"networkBulkFeed":{"href":"/network-bulk-feeds/2fd4d402-b759-479c-87a6-58d85e345356"}},"id":"75ea3c99-6bf5-4b16-8f68-0cdc43d75806","subaccountId":"c6d5e036-361e-4773-a514-b9496cf2d2b5","cardId":"4d1ff59f-4286-4209-9662-92e174193562","customerReferenceId":null,"networkBulkFeedId":"2fd4d402-b759-479c-87a6-58d85e345356","bankAccountId":null,"enrollmentType":"network-bulk","state":"active","effectiveDate":"2024-04-01T00:00:00Z","expirationDate":"2027-04-01T00:00:00Z","createdAt":"2024-03-31T14:45:00Z","updatedAt":"2024-03-31T14:45:00Z"}},"acceptor":{"city":"LONDON","country":"GBR","mcc":"5734","state":"LND"},"cardId":"4d1ff59f-4286-4209-9662-92e174193562","cardholderBillingCurrency":"GBP","cardholderBillingHoldAmount":0,"cardholderBillingSettledAmount":0.81,"createdAt":"2024-05-01T06:41:43.810Z","descriptor":"Uber","id":"8697df0c-9011-47ca-a52b-8d2a7a4ad903","network":"MASTERCARD","networkBulkFeedId":"2fd4d402-b759-479c-87a6-58d85e345356","status":"SETTLED","subaccountId":"c6d5e036-361e-4773-a514-b9496cf2d2b5","supersededMessageIds":[],"transactionCurrency":"USD","transactionHoldAmount":0,"transactionOccurrenceDate":"2024-05-01","transactionSettledAmount":1,"updatedAt":"2024-05-02T08:41:43.810Z"}},"transaction-expanded-card-cardholder":{"description":"Example of Transaction resource requested with `expand=cardSubscription,card,cardholder`","value":{"_links":{"card":{"href":"/cards/4d1ff59f-4286-4209-9662-92e174193562"},"subaccount":{"href":"/subaccounts/c6d5e036-361e-4773-a514-b9496cf2d2b5"},"self":{"href":"/transactions/8697df0c-9011-47ca-a52b-8d2a7a4ad903"},"messages":[{"href":"/transaction-messages/f4b24a0a-6a37-4ce3-8845-ddf0b604a9b4"},{"href":"/transaction-messages/934f8701-53e3-4a2b-a000-6bb52195d2ea"}]},"_embedded":{"cardSubscription":{"_links":{"self":{"href":"/card-subscriptions/75ea3c99-6bf5-4b16-8f68-0cdc43d75806"},"card":{"href":"/cards/4d1ff59f-4286-4209-9662-92e174193562"},"networkBulkFeed":{"href":"/network-bulk-feeds/2fd4d402-b759-479c-87a6-58d85e345356"}},"id":"75ea3c99-6bf5-4b16-8f68-0cdc43d75806","subaccountId":"c6d5e036-361e-4773-a514-b9496cf2d2b5","cardId":"4d1ff59f-4286-4209-9662-92e174193562","customerReferenceId":null,"networkBulkFeedId":"2fd4d402-b759-479c-87a6-58d85e345356","bankAccountId":null,"enrollmentType":"network-bulk","state":"active","effectiveDate":"2024-04-01T00:00:00Z","expirationDate":"2027-04-01T00:00:00Z","createdAt":"2024-03-31T14:45:00Z","updatedAt":"2024-03-31T14:45:00Z"},"card":{"_links":{"self":{"href":"/cards/4d1ff59f-4286-4209-9662-92e174193562"},"cardholder":{"href":"/cards/4d1ff59f-4286-4209-9662-92e174193562/cardholder"}},"id":"4d1ff59f-4286-4209-9662-92e174193562","subaccountId":"c6d5e036-361e-4773-a514-b9496cf2d2b5","expiryMonth":11,"expiryYear":2028,"network":"mastercard","country":"GBR","first6digits":"434343","last4digits":"4343","createdAt":"2024-03-31T14:40:00Z","updatedAt":"2024-03-31T14:40:00Z"},"cardholder":{"_links":{"self":{"href":"/cards/4d1ff59f-4286-4209-9662-92e174193562/cardholder"}},"firstName":"John","lastName":"Doe","email":"john.doe@example.com","postalCode":"SW1A 1AA","corporate":{"alternativeEmployeeId":"ALT-EMP-12345","employeeId":"bb1afe4eb840","id":"ABC123456789","legalEntity":{"id":"FR01","name":"Example Company France SAS"}},"createdAt":"2024-03-31T14:45:00Z","updatedAt":"2024-03-31T14:45:00Z"}},"acceptor":{"city":"LONDON","country":"GBR","mcc":"5734","state":"LND"},"cardId":"4d1ff59f-4286-4209-9662-92e174193562","cardholderBillingCurrency":"GBP","cardholderBillingHoldAmount":0,"cardholderBillingSettledAmount":0.81,"createdAt":"2024-05-01T06:41:43.810Z","descriptor":"Uber","id":"8697df0c-9011-47ca-a52b-8d2a7a4ad903","network":"MASTERCARD","networkBulkFeedId":"2fd4d402-b759-479c-87a6-58d85e345356","status":"SETTLED","subaccountId":"c6d5e036-361e-4773-a514-b9496cf2d2b5","supersededMessageIds":[],"transactionCurrency":"USD","transactionHoldAmount":0,"transactionOccurrenceDate":"2024-05-01","transactionSettledAmount":1,"updatedAt":"2024-05-02T08:41:43.810Z"}},"transaction-message":{"description":"Example of Transaction Message resource","value":{"_links":{"self":{"href":"/transaction-messages/80b08eeb-c4cc-4e5c-8d0b-15bc2e04b4dc"},"raw":{"href":"/transaction-messages/80b08eeb-c4cc-4e5c-8d0b-15bc2e04b4dc/raw"}},"acceptor":{"acquirerId":null,"city":"LONDON","country":"GBR","id":"KWGBYTEI4FL0QQQ","mcc":"5734","name":"Uber","state":"LND"},"accountId":"a49fdf13-62ce-4704-80bf-82f317cc215e","approvalCode":"537254","bankData":null,"cardId":"bf4d1e23-0f5a-42a7-81f2-bc66f392a98c","cardType":"virtual","cardholderBillingAmount":1.18,"cardholderBillingCurrency":"GBP","createdDateTime":"2024-04-26T01:41:22.544Z","dateTime":"2024-04-24T13:39:45Z","discountAmount":null,"id":"80b08eeb-c4cc-4e5c-8d0b-15bc2e04b4dc","messageType":"FINL_ADVC","network":"MASTERCARD","result":"APPROVED","subaccountId":"cb4d801e-a10a-4f42-b9de-1c51685ffd8a","traceId":null,"transactionAmount":1.45,"transactionCurrency":"USD","transactionReference":"IWVQ22_2024-04-24","transactionType":"DEBIT_01","transmissionDateTime":"2024-04-25T00:00:00.000Z"}},"raw-transaction-message":{"description":"Example of Raw Transaction Message resource","value":{"_links":{"self":{"href":"/transaction-messages/80b08eeb-c4cc-4e5c-8d0b-15bc2e04b4dc/raw"},"message":{"href":"/transaction-messages/80b08eeb-c4cc-4e5c-8d0b-15bc2e04b4dc"}},"raw":{"messageTypeIndicator":"0100","primaryAccountNumber":"444444******0000","processingCode":"000000","transactionAmount":"000000000145","transmissionDateTime":"0425000000","systemsTraceAuditNumber":"537254","localTransactionTime":"133945","localTransactionDate":"0424","merchantType":"5734","acquiringInstitutionIdentificationCode":"KWGBYTEI4FL0QQQ","retrievalReferenceNumber":"IWVQ22_2024-04-24","authorizationIdentificationResponse":"537254","responseCode":"00","cardAcceptorTerminalIdentification":"TERMINAL01","cardAcceptorIdentificationCode":"KWGBYTEI4FL0QQQ","cardAcceptorNameLocation":"Uber                    LONDON      LNDGBR","transactionCurrencyCode":"840","cardholderBillingAmount":"000000000118","cardholderBillingCurrency":"826","networkManagementInformationCode":"MASTERCARD"}}},"webhook":{"description":"Example of Webhook resource","value":{"_links":{"self":{"href":"/webhooks/3a45ba7f-8d8f-4f6a-86a5-a17ea0328241"}},"id":"3a45ba7f-8d8f-4f6a-86a5-a17ea0328241","url":"https://example-api.com/path","description":"Example of Webhook description","eventTypes":["transactionmessage.created"],"subaccountId":"f297d659-c13d-4219-aeaa-e10a845140a5","createdAt":"2023-12-19T14:45:00Z","updatedAt":"2023-12-19T14:45:00Z","enabled":true}},"bin-lookup":{"description":"Example response for BIN lookup request","value":{"bin":"411111","network":"VISA","type":"COMMERCIAL","fundingType":"CREDIT","cardCategory":"PURCHASING","cardFundingType":"CREDIT","issuerName":"Example Bank","issuerCountry":"USA","issuerRegion":"NA"}},"bin-lookup-precise":{"description":"A Mastercard card looked up with 11 digits, where the digits sent point to a single issuer\ncountry. The issuer country, region and name are specific to those digits; the first 6\ndigits alone would have answered POL. No extra fields are added.\n","value":{"bin":"558919","network":"MASTERCARD","fundingType":"CREDIT","cardCategory":"BUSINESS","cardFundingType":"CREDIT","issuerName":"Silverline Financial Group 2","issuerCountry":"NLD","issuerRegion":"EU"}},"bin-lookup-ambiguous":{"description":"A Mastercard card looked up with fewer than 11 digits that match card ranges in more than\none country. The country fields keep the 6-digit BIN's values, `issuerCountryCandidates`\nlists the possible countries, and a warning suggests sending more digits (up to 11).\nThe `issuerCountry` shown is the default answer for the 6-digit BIN, used when the digits\nsent match more than one country, so it need not be one of the candidates.\n","value":{"bin":"533347","network":"MASTERCARD","type":"CONSUMER","fundingType":"CREDIT","cardCategory":"CONSUMER","cardFundingType":"CREDIT","issuerName":"Pribank Sh A","issuerCountry":"XKX","issuerCountryAmbiguous":true,"issuerCountryCandidates":["DNK","NOR","SWE"],"issuerRegion":"EU","warnings":[{"code":"ISSUER_COUNTRY_NOT_CONFIRMED","message":"These digits match card ranges in more than one country. Send up to 11 digits of the card number for a precise issuer country."}]}},"bin-lookup-ambiguous-11-digit":{"description":"A Mastercard card looked up with 11 digits that still match card ranges in more than one\ncountry. The country fields keep the 6-digit BIN's values, `issuerCountryCandidates` lists\nthe possible countries, and the warning says the issuer country could not be confirmed.\nThe `issuerCountry` shown is the default answer for the 6-digit BIN, used when the digits\nsent match more than one country, so it need not be one of the candidates.\n","value":{"bin":"533347","network":"MASTERCARD","type":"CONSUMER","fundingType":"CREDIT","cardCategory":"CONSUMER","cardFundingType":"CREDIT","issuerName":"Pribank Sh A","issuerCountry":"XKX","issuerCountryAmbiguous":true,"issuerCountryCandidates":["DNK","NOR","SWE"],"issuerRegion":"EU","warnings":[{"code":"ISSUER_COUNTRY_NOT_CONFIRMED","message":"These digits match card ranges in more than one country, so the issuer country could not be confirmed."}]}}}},"x-readme":{"proxy-enabled":false,"metrics-enabled":false}}