OpenAPI Specification
openapi: 3.0.3
info:
title: Astrada bank-accounts card API
version: '2024-02-28'
contact:
email: developer@astrada.co
description: 'Welcome to our API Reference. 👋
'
servers:
- url: https://api.astrada.co
security: null
tags:
- name: card
description: Card resource
paths:
/cards/{cardId}:
parameters:
- $ref: '#/components/parameters/card-id-2'
get:
tags:
- card
summary: Retrieve card
description: Returns detailed information about a specific card by its identifier.
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'
'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 cardholder information, related to a specific cardId, when it's available.
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.
**Note:** This endpoint requires the `cardholder:write` scope and must be directly enabled by Astrada.
'
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
type: object
properties:
id:
description: The identifier of the corporate
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'
/cards:
parameters:
- $ref: '#/components/parameters/country'
- $ref: '#/components/parameters/expiry-month'
- $ref: '#/components/parameters/expiry-year'
- $ref: '#/components/parameters/subaccount-id'
- $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.
By default, `GET /cards` returns cards ordered by the latest updatedAt. You can combine the different filters as documented.
This endpoint supports [offset-based pagination](https://docs.astrada.co/reference/pagination).
'
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 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'
components:
parameters:
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
subaccount-id:
in: query
name: subaccountId
required: false
schema:
type: string
format: uuid
example: 2fd4d402-b759-479c-87a6-58d85e345356
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
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
example: USA
expiry-year:
in: query
name: expiryYear
description: The card expiration year
required: false
schema:
type: integer
example: 2024
card-id-2:
in: path
name: cardId
required: true
schema:
type: string
format: uuid
example: 6d18f5bb-b9d6-4237-97c2-44b1bdb71d6b
expiry-month:
in: query
name: expiryMonth
description: The card expiration month
required: false
schema:
type: integer
minimum: 1
maximum: 12
example: 6
responses:
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.
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.
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.
examples:
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
createdAt: '2024-02-04T18:41:16.142Z'
updatedAt: '2024-02-04T18:41:16.142Z'
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:
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
schemas:
cardholder:
type: object
properties:
_links:
type: object
required:
- self
properties:
self:
$ref: '#/components/schemas/link'
corporate:
type: object
description: The corporate entity that this cardholder is associated with
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 identifier of the corporate
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
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
card:
type: object
properties:
_links:
type: object
required:
- self
properties:
self:
$ref: '#/components/schemas/link'
cardholder:
$ref: '#/components/schemas/link'
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
(created from a bank connection, where the full PAN is never seen) — populated when
known (e.g. the SDK captured the BIN before pivoting to the bank flow) and attached
when the card is later PAN-enrolled (upgrade-in-place keeps the same card id).
'
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
on bank-derived cards: Amex-institution connections mint `amex`; other institutions
cannot reveal the network from bank data, so it stays `null` until the card is
PAN-enrolled (upgrade-in-place).
'
country:
type: string
enum:
- USA
- CAN
- GBR
- SWE
- ITA
- AUS
- NZL
- PRT
- BEL
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
securitySchemes:
main-auth:
type: oauth2
flows:
implicit:
authorizationUrl: https://api.astrada.co/auth/realms/{accountId}/protocol/openid-connect/token
refreshUrl: https://api.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-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
externalDocs:
description: Find out more about Astrada API.
url: https://docs.astrada.co/reference