OpenAPI Specification
openapi: 3.0.3
info:
title: Astrada bank-accounts network-bulk-feeds 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: network-bulk-feeds
description: Network bulk feed resource
paths:
/network-bulk-feeds:
post:
tags:
- network-bulk-feeds
summary: Create network bulk feed
description: Registers a new feed for network bulk
security:
- main-auth:
- network-bulk-feeds:write
operationId: CreateNetworkBulkFeed
requestBody:
required: true
content:
application/json:
schema:
allOf:
- type: object
properties:
networkReference:
description: 'The identifier associated with the card network''s bulk enrollment feed.
For Amex, this field should contain the Recipient ID in the following format ''R{RecipientId}'', such as ''R123456''.
For Mastercard, this field should contain the Delivery ID.
For Visa-VBDS, this field should contain the RPIC in the following format ''RegionId_ProcessorId_IssuerId_CompanyId'', such as ''123_456_789_1''.
For Visa-VCF, this field should contain the PIC in the following format ''ProcessorId_IssuerId_CompanyId'', such as ''123_45_6789''.
For more details on our bulk enrollment process, refer to [this guide](https://docs.astrada.co/docs/network-bulk-enrollment).
'
type: string
subaccountId:
description: The subaccount identifier
type: string
format: uuid
expectedCardCount:
description: 'The expected number of cards that will be enrolled under this bulk feed.
Optional. When provided, the value is echoed back on the response and on the
`networkbulkfeed.statechanged` webhook payload.
'
type: integer
minimum: 1
maximum: 1000000
newCards:
description: 'Sandbox only. The number of synthetic Visa cards to create when this
bulk feed is created in the sandbox environment. The cards are drawn
from Astrada''s published sandbox Visa test-card pool. Only valid for
`network: VISA`. Requests containing this field outside the sandbox
environment, or for other networks, are rejected with a 400.
'
type: integer
minimum: 1
maximum: 20
default: 5
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: The type of card network's bulk enrollment feed
type: string
enum:
- VBDS
- VCF
default: VBDS
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 (Visa):
value:
networkReference: 119999789452
network: VISA
type: VBDS
subaccountId: 24c4f90d-ab3b-4f6e-8a1d-d251a4fcf34c
Create Network Bulk Feed Request Example (Visa, sandbox synthetic cards):
value:
networkReference: 119999789452
network: VISA
type: VBDS
subaccountId: 24c4f90d-ab3b-4f6e-8a1d-d251a4fcf34c
newCards: 5
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.
By default, `GET /network-bulk-feeds` returns network bulk feeds ordered by the latest `createdAt`.
This endpoint supports [offset-based pagination](https://docs.astrada.co/reference/pagination).
'
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
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
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: 119999789452
state: failed
type: VBDS
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'
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'
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
network-reference:
in: query
name: networkReference
required: false
schema:
type: string
example: ABC12345
network-bulk-feed-id:
in: path
name: networkBulkFeedId
required: true
schema:
type: string
format: uuid
example: eb2ded7e-11fa-46fc-bd3e-f5b1d56fd3b3
examples:
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: 119999789452
state: failed
type: VBDS
errorReason: 'Starter data ingestion failed: invalid RPIC configuration'
createdAt: '2024-12-19T14:45:00Z'
updatedAt: '2024-12-20T10:30:00Z'
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
createdAt: '2024-12-19T14:45:00Z'
updatedAt: '2024-12-19T14:45:00Z'
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.
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
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.
schemas:
network-bulk-feeds:
type: object
required:
- _links
- id
- subaccountId
- network
- networkReference
- state
- type
- 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:
type: string
description: The identifier associated with the card network's bulk enrollment feed.
state:
type: string
enum:
- submitted
- active
- deactivated
- failed
description: 'The state of the network bulk feed entity.
> **Note**: The `failed` state is currently only applicable to VISA bulk feeds.
'
type:
type: string
enum:
- GL
- SMARTDATA
- VBDS
- VCF
errorReason:
type: string
nullable: true
description: 'A human-readable reason explaining why the bulk feed failed. Only present when `state` is `failed`.
> **Note**: Currently only applicable to VISA bulk feeds.
'
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.
Only present when the feed was created with this field.
'
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
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
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
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