openapi: 3.0.0
servers:
- url: 'https://api.devbank.apiture.com/cards'
info:
title: Cards
description: |
Monitor and manage debit cards associated with a bank account.
This API defines models and operations for the following resources:
* ***Card Requests*** represent customer-initiated requests for new
cards or for replacements for lost, stolen, or damaged cards.
* ***Cards*** represent physical debit cards issued by the
financial institution (FI)
to the bank customer. A card is associated with a deposit account.
This API provides the following features to customers (the card holder):
* List their cards and other cards on accounts, optionally filtered by account
* View the details of each card, including its state and associated banking account number
* Request a new card for an account
* Lock a card so that it may not be used until the customer unlocks it
* Unlock a card
* Report a card as lost, stolen, or damaged
* Close (cancel) a card
* Request a replacement card for a lost, stolen, or damaged card
* Review the status of their new or replacement card requests
Only the card holder (the individual the card is issued to) may
access the card control and card replacement operations.
This API provides the following features to financial institution
administrative users:
* Reject a user's card request
Additionally, administrative users may perform the following operations
on behalf of the customer:
* Create new or replacement cards
* Activate a new or replacement card
* Lock or unlock cards
* Close (cancel) a card
## Multi-factor authentication challenges
To prevent account takeover attacks, some operations to request cards
or to operate on cards require _multi-factor authentication_ (MFA). An MFA
_challenge_ is a process to verify the user's identity through one
or more additional authentication steps.
For example, when the client tries the [`createCardRequest`](#op-createCardRequest)
without a valid redeemable `Apiture-Challenge` request header, the
operation may fail with a 409 Conflict. The response body, defined by
the [`challengeErrorResponse`](#schema-challengeErrorResponse) schema, contains
a `challenge` resource which includes one or more _authenticators_.
An authenticator may require the user to enter a verification code
sent to the user's email account or mobile phone. (The client may let the user
choose which authenticators to use, if there are more options than the required minimum.)
Next, the client should start least one of the authenticators.
The user completes the authenticator(s), for example by entering the verification code.
Once the user has completed all the authenticators successfully, the client passes the
resource ID of the challenge resource in the `Apiture-Challenge`
request header to continue the operation that required MFA.
Thus, these operations may require
two tries: the first (without the `Apiture-Challenge` header),
which fails with a 409 status (the response contains the challenge object),
then after completing the challenges' authenticators, a second try,
passing in the `Apiture-Challenge` header.
# Error Types
Error responses in this API may have one of the `type` values described below.
See [Errors](https://developer.apiture.com/docs/concepts/errors) for more information
on error responses and error types.
## cardRequestRefNotFound
**Description**: The request card request resource ID does not identify a card.
**Remediation**: Pass the ID of an existing card request resource.
## cardRefNotFound
**Description**: The request card resource ID does not identify a card.
**Remediation**: Pass the ID of an existing card resource.
## invalidAccountLink
**Description**: The request contains an invalid reference to an account.
**Remediation**: Pass the URI of a valid account that the current user holds.
##
**Description**: The Apiture-Challenge request header was not passed.
**Remediation**: Pass the _id of a valid, verified challenge resource in the Apiture-Challenge request header.
## productDoesNotSupportCards
**Description**: The banking product associated with the account does not support card requests.
**Remediation**: Select an account that supports cards.
## challengedExpired
**Description**: The challenge resource specified in the Apiture-Challenge request header has expired.
**Remediation**: Obtain a new challenge resource.
## challengedNotVerified
**Description**: The challenge resource specified in the Apiture-Challenge request header has not been verified.
**Remediation**: Complete the challenge verification before using a challenge resource.
## challengedAlreadyRedeemed
**Description**: The challenge resource specified in the Apiture-Challenge request header has been redeemed the maximum number of times.
**Remediation**: Obtain a new challenge resource.
version: 0.15.1
contact:
name: Apiture
url: 'https://developer.apiture.com'
email: api@apiture.com
termsOfService: 'https://developer.apiture.com/docs/Apiture-Open-API-License-Agreement.pdf'
tags:
- name: Card Requests
description: Requests to Issue New or Replacement Cards
- name: Card Request Actions
description: Actions on Card Requests
- name: Cards
description: Debit Cards Issued by the Financial Institution
- name: Card Actions
description: Actions on Debit cards
- name: API
description: The Cards API
paths:
/cardRequests:
get:
summary: Return a collection of card requests
description: |-
Return a
[paginated](http://developer.apiture.com/docs/concepts/pagination)
[sortable](http://developer.apiture.com/docs/concepts/sorting)
[filterable](http://developer.apiture.com/docs/concepts/filtering)
[searchable](http://developer.apiture.com/docs/concepts/searching)
collection of requests for new or replacement card. The
[links](http://developer.apiture.com/docs/concepts/links) in the
response include pagination links.
For financial institution customers, this collection only returns card requests
that the customer has created or which apply to their cards.
operationId: getCardRequests
tags:
- Card Requests
x-apiture-traits:
sortBy:
- state
- submittedAt
- resolvedAt
- updatedAt
filters:
description:
filter:
- contains
- search
resolutionReason:
filter:
- contains
- search
state:
filter:
- eq
- ne
- in
submittedOn:
filter:
- eq
- ne
- lt
- le
- gt
- ge
- in
as: date(submittedAt)
resolvedOn:
filter:
- eq
- ne
- lt
- le
- gt
- ge
- in
as: date(resolveAt)
modifiedOn:
filter:
- eq
- ne
- lt
- le
- gt
- ge
- in
as: date(updatedAt)
updatedAt:
filter:
- eq
- ne
- lt
- le
- gt
- ge
multiMatch: false
updatedBy:
filter:
- eq
- ne
- lt
- le
- gt
- ge
- startsWith
- endsWith
- contains
- search
parameters:
- name: start
in: query
description: The zero-based index of the first card request item to include in this page. The default 0 denotes the beginning of the collection.
schema:
type: integer
format: int64
default: 0
- name: limit
in: query
description: The maximum number of card request representations to return in this page.
schema:
type: integer
format: int32
default: 100
- name: sortBy
in: query
description: 'Optional sort criteria. See [sort criteria format](http://developer.apiture.com/docs/concepts/sorting), such as `?sortBy=field1,-field2`.'
schema:
type: string
- $ref: '#/components/parameters/filterQueryParam'
- $ref: '#/components/parameters/qQueryParam'
- name: state
in: query
description: >-
Filter responses to list only cards in the listed `state` or `|`-separated set of states. Examples: `?state=submitted` ,
`?state=canceled|completed|rejected`
schema:
type: string
enum:
- pending
- submitted
- canceled
- rejected
- completed
- name: submittedOn
in: query
description: >-
Filter the response to card requests submitted on this date or set of `|`-separated dates. Dates are in [RFC
3339](https://tools.ietf.org/html/rfc3339) YYYY-MM-DD format. Examples: `?submittedDate=2019-06-10` or
`?submittedDate=2019-06-10|2019-06-08|2019-06-07`
schema:
type: string
format: date
- name: modifiedOn
in: query
description: >-
Filter the response to card requests last modified on this date or set of `|`-separated dates. Dates are in [RFC
3339](https://tools.ietf.org/html/rfc3339) YYYY-MM-DD format. Examples: `?modifiedOn=2019-06-10` or
`?modifiedOn=2019-06-10|2019-06-08|2019-06-07`
schema:
type: string
format: date
- name: resolvedOn
in: query
description: >-
Filter the response to card requests resolved on this date or set of `|`-separated dates. Dates are in [RFC
3339](https://tools.ietf.org/html/rfc3339) YYYY-MM-DD format. Examples: `?resolvedOn=2019-06-10` or
`?resolvedOn=2019-06-10|2019-06-08|2019-06-07`
schema:
type: string
format: date
- name: updatedBy
in: query
description: Filter the response to card requests created by the user named by this user ID.
schema:
type: string
responses:
'200':
description: OK
content:
application/hal+json:
schema:
$ref: '#/components/schemas/cardRequests'
application/json:
schema:
$ref: '#/components/schemas/cardRequests'
'400':
$ref: '#/components/responses/400'
'422':
$ref: '#/components/responses/422'
security:
- apiKey: []
accessToken:
- card/read
post:
summary: Request a new or replacement card
description: >-
Request a new or replacement card by creating a new card request resource, adding it to the `cardRequests` collection.
This operation may require the user to complete an additional multi-factor authentication (MFA) challenge if the financial institution has
configured MFA on new or replacement card requests. If the request fails because MFA is required, the response code is 409 and the
`_error.type` in the response is `missingApitureChallengeHeader`. The client should complete the MFA challenge and retry the operation with
the `Apiture-Challenge` request header as described in [Multi-factor authentication challenges](#MFA) above.
operationId: createCardRequest
tags:
- Card Requests
parameters:
- $ref: '#/components/parameters/apitureChallengeHeaderParam'
responses:
'201':
description: Created
headers:
Location:
description: >-
The URI of the new resource. If the URI begins with / it is relative to the API root context. Else, it is a full URI starting with
*`scheme`*`://host`
schema:
type: string
format: uri
ETag:
description: >-
The `ETag` response header specifies an entity tag which must be provided in an `If-Match` request header for *`PUT`* or *`PATCH`*
operations which update the resource.
schema:
type: string
content:
application/hal+json:
schema:
$ref: '#/components/schemas/cardRequest'
application/json:
schema:
$ref: '#/components/schemas/cardRequest'
'400':
$ref: '#/components/responses/400'
'409':
description: >-
Conflict. The request is not allowed or requires a valid `Apiture-Challenge` header The error response will contain a challenge object and
one or more authenticators for the client to start and complete before retrying. See See [Multi-factor authentication challenges](#MFA)
above.
This error response may have one of the following `type` values:
* [`missingApitureChallengeHeader`](#err-missingApitureChallengeHeader)
* [`challengedNotVerified`](#err-challengedNotVerified)
* [`challengedExpired`](#err-challengedExpired)
* [`challengedAlreadyRedeemed`](#err-challengedAlreadyRedeemed)
* [`productDoesNotSupportCards`](#err-productDoesNotSupportCards)
x-apiture-errors:
- missingApitureChallengeHeader
- challengedNotVerified
- challengedExpired
- challengedAlreadyRedeemed
- productDoesNotSupportCards
content:
application/hal+json:
schema:
$ref: '#/components/schemas/challengeErrorResponse'
application/json:
schema:
$ref: '#/components/schemas/challengeErrorResponse'
security:
- apiKey: []
accessToken:
- card/write
requestBody:
content:
application/hal+json:
schema:
$ref: '#/components/schemas/createCardRequest'
application/json:
schema:
$ref: '#/components/schemas/createCardRequest'
description: The data necessary to create a new card request resource.
required: true
'/cardRequests/{cardRequestId}':
get:
summary: Fetch a representation of this card request
description: 'Return a [HAL](http://developer.apiture.com/docs/concepts/hal) representation of this card request resource.'
operationId: getCardRequest
tags:
- Card Requests
parameters:
- $ref: '#/components/parameters/cardRequestIdPathParam'
- $ref: '#/components/parameters/ifNoneMatchHeaderParam'
responses:
'200':
description: OK
headers:
ETag:
description: >-
The `ETag` response header specifies an entity tag which must be provided in an `If-Match` request header for *`PUT`* or *`PATCH`*
operations which update this card request resource.
schema:
type: string
content:
application/hal+json:
schema:
$ref: '#/components/schemas/cardRequest'
application/json:
schema:
$ref: '#/components/schemas/cardRequest'
'304':
$ref: '#/components/responses/304'
'404':
$ref: '#/components/responses/404CardRequest'
security:
- apiKey: []
accessToken:
- card/read
delete:
summary: Delete this card request resource
description: >-
Delete this card request resource and any resources that are owned by it. This effectively cancels the card request request if the request has
not been processed.
operationId: deleteCardRequest
x-apiture-implemented: false
tags:
- Card Requests
parameters:
- $ref: '#/components/parameters/cardRequestIdPathParam'
responses:
'204':
$ref: '#/components/responses/204Deleted'
security:
- apiKey: []
accessToken:
- card/delete
/shippingCharges:
post:
summary: Get estimated (expedited) shipping changes
description: Get estimated expedited shipping changes for a card.
operationId: estimateCardShippingCharges
tags:
- Card Requests
security:
- apiKey: []
accessToken:
- data/read
responses:
'200':
description: OK.
content:
application/hal+json:
schema:
$ref: '#/components/schemas/cardShippingEstimate'
application/json:
schema:
$ref: '#/components/schemas/cardShippingEstimate'
'400':
$ref: '#/components/responses/400'
'422':
$ref: '#/components/responses/422CardShippingEstimate'
requestBody:
content:
application/hal+json:
schema:
$ref: '#/components/schemas/cardShippingEstimateRequest'
application/json:
schema:
$ref: '#/components/schemas/cardShippingEstimateRequest'
description: Information required to estimate the shipping.
required: true
/completedCardRequests:
post:
operationId: completeCardRequest
summary: Complete a card request
description: >-
Mark a card request as completed when the card has been issued. This changes the `state` property of the card request to `completed`. This
operation is available via the `apiture:complete` link on the card request resource, if and only if the card request is eligible for the
complete operation. Only the FI admin may invoke this operation. The response is the updated representation of the card request. The
`If-Match` request header value must match the current entity tag value of the card request.
tags:
- Card Requests Actions
parameters:
- $ref: '#/components/parameters/cardRequestQueryParam'
- $ref: '#/components/parameters/ifMatchHeaderParam'
responses:
'200':
description: OK. The operation succeeded. The card request was updated and its `state` changed to `completed`.
headers:
ETag:
description: >-
The `ETag` response header specifies an entity tag which must be provided in an `If-Match` request header for *`PUT`* or *`PATCH`*
operations which update the resource.
schema:
type: string
content:
application/hal+json:
schema:
$ref: '#/components/schemas/cardRequest'
application/json:
schema:
$ref: '#/components/schemas/cardRequest'
'400':
$ref: '#/components/responses/400CompleteCardRequest'
'409':
$ref: '#/components/responses/409CompleteCardRequestConflict'
'412':
$ref: '#/components/responses/412'
security:
- apiKey: []
accessToken:
- admin/write
/rejectedCardRequests:
post:
operationId: rejectCardRequest
summary: Reject a card request
description: |-
Mark a card request as _rejected_.
This changes the `state` property of the card request to `rejected`.
Only the FI admin may invoke this operation.
This operation is available via the `apiture:reject` link on the card
request resource, if and only if the card request is eligible for the
reject operation. The response is the updated representation of the
card request. The `If-Match` request header value, if passed, must match the current
entity tag value of the card request.
tags:
- Card Requests Actions
parameters:
- $ref: '#/components/parameters/cardRequestQueryParam'
- $ref: '#/components/parameters/ifMatchHeaderParam'
responses:
'200':
description: OK. The operation succeeded. The card request was updated and its `state` changed to `rejected`.
headers:
ETag:
description: >-
The `ETag` response header specifies an entity tag which must be provided in an `If-Match` request header for *`PUT`* or *`PATCH`*
operations which update the resource.
schema:
type: string
content:
application/hal+json:
schema:
$ref: '#/components/schemas/cardRequest'
application/json:
schema:
$ref: '#/components/schemas/cardRequest'
'400':
$ref: '#/components/responses/400RejectCardRequest'
'409':
$ref: '#/components/responses/409RejectCardRequestConflict'
'412':
$ref: '#/components/responses/412'
security:
- apiKey: []
accessToken:
- admin/write
/canceledCardRequests:
post:
operationId: cancelCardRequest
summary: Cancel a card request
description: >-
Cancel a card replacement request. This changes the `state` property of the card request to `canceled`. This operation is available via the
`apiture:cancel` link on the card request resource, if and only if the card request is eligible for the cancel operation. The response is the
updated representation of the card request. The `If-Match` request header value, if passed, must match the current entity tag value of the
card request.
tags:
- Card Requests Actions
parameters:
- $ref: '#/components/parameters/cardRequestQueryParam'
- $ref: '#/components/parameters/ifMatchHeaderParam'
responses:
'200':
description: OK. The operation succeeded. The card request was updated and its `state` changed to `canceled`.
headers:
ETag:
description: >-
The `ETag` response header specifies an entity tag which must be provided in an `If-Match` request header for *`PUT`* or *`PATCH`*
operations which update the resource.
schema:
type: string
content:
application/hal+json:
schema:
$ref: '#/components/schemas/cardRequest'
application/json:
schema:
$ref: '#/components/schemas/cardRequest'
'400':
$ref: '#/components/responses/400CancelCardRequest'
'409':
$ref: '#/components/responses/409CancelCardRequestConflict'
'412':
$ref: '#/components/responses/412'
security:
- apiKey: []
accessToken:
- card/write
/cards:
get:
summary: Return a collection of cards
description: |-
Return a
[paginated](http://developer.apiture.com/docs/concepts/pagination)
[sortable](http://developer.apiture.com/docs/concepts/sorting)
[filterable](http://developer.apiture.com/docs/concepts/filtering)
[searchable](http://developer.apiture.com/docs/concepts/searching)
collection of cards for the user's accounts or the subset of those cards that
satisfy the filter criteria.
[links](http://developer.apiture.com/docs/concepts/links) in the
response include pagination links.
For an account owner or joint owner of a personal account, the default response
includes all cards issued to all primary or joint owners of the account.
For authorized signers on business accounts, the default response
includes cards for all authorized signers for that account.
There is another version of this operation which allows
getting a list of cards based on the query constraints
passed in the request body; see the `getCardsForAccount` operation.
operationId: getCards
tags:
- Cards
x-apiture-traits:
sortBy:
- accountName
- state
- replacementState
- fulfillmentState
- updatedAt
filters:
account:
filter:
- eq
- ne
- in
accountName:
filter:
- eq
- ne
- lt
- le
- gt
- ge
- startsWith
- endsWith
- contains
- search
accountCategory:
filter:
- eq
- ne
- in
accountType:
filter:
- eq
- ne
- in
state:
filter:
- eq
- ne
- in
replacementState:
filter:
- eq
- ne
- in
fulfillmentState:
filter:
- eq
- ne
- in
updatedAt:
filter:
- eq
- ne
- lt
- le
- gt
- ge
multiMatch: false
modifiedOn:
filter:
- eq
- ne
- lt
- le
- gt
- ge
- in
as: date(updatedAt)
issuedOn:
filter:
- eq
- ne
- lt
- le
- gt
- ge
- in
as: date(issuedAt)
expiresOn:
filter:
- eq
- ne
- lt
- le
- gt
- ge
- in
as: date(expiresAt)
parameters:
- name: start
in: query
description: The zero-based index of the first card item to include in this page. The default 0 denotes the beginning of the collection.
schema:
type: integer
format: int64
default: 0
- name: limit
in: query
description: The maximum number of card representations to return in this page.
schema:
type: integer
format: int32
default: 100
- name: sortBy
in: query
description: 'Optional sort criteria. See [sort criteria format](http://developer.apiture.com/docs/concepts/sorting), such as `?sortBy=field1,-field2`.'
schema:
type: string
- $ref: '#/components/parameters/filterQueryParam'
- $ref: '#/components/parameters/qQueryParam'
- $ref: '#/components/parameters/unmaskedQueryParam'
- name: mine
description: 'If `true`, limit the response to only cards issued to the user making the request.'
in: query
schema:
type: boolean
default: false
- name: account
in: query
description: >-
Filter cards to only those for the account with the account ID named in this query parameter. (By default, the list is pre-filtered to
only accounts that the user has access to; this further narrows that list. FI admins can use this to view cards for a user.) This can
match exactly one account ID, or a set of `|`-separated IDs This parameter is mutually exclusive with `?accountName=`. Examples:
`?account=a223db933809` or `?account=a223db933809|fd89d651283b`.
style: pipeDelimited
schema:
type: array
items:
type: string
- name: accountName
in: query
description: >-
Filter cards to those whose account name matches this value. This can match exactly one account name, or a set of `|`-separated names.
This parameter is mutually exclusive with `?account=`. Examples: `?accountName=My%20Basic%20Savings` or
`?accountName=My%20Basic%20Savings|My%20Joint%02Savings`.
style: pipeDelimited
schema:
type: array
items:
type: string
- name: state
in: query
description: >-
Filter cards on the state of the card. This can match exactly one state, or a set of `|`-separated states. Examples: `?state=requested` ,
`?state=lost|stolen|damaged`.
schema:
type: string
items:
type: string
enum:
- requested
- issued
- active
- locked
- lost
- stolen
- damaged
- closed
- name: fulfillmentState
in: query
description: >-
Filter the response to card by the state of their replacement states. This can match exactly one state, or a set of `|`-separated states.
Examples: `?fulfillmentState=requested` , `?fulfillmentState=ordered|reordered`
style: pipeDelimited
schema:
type: array
items:
type: string
enum:
- none
- requested
- ordered
- issued
- shipped
- rejected
- name: modifiedOn
in: query
description: >-
Filter the response to cards last modified on this date or set of `|`-separated dates. Dates are in [RFC
3339](https://tools.ietf.org/html/rfc3339) YYYY-MM-DD format. Examples: `?modifiedOn=2019-06-10` ,
`?modifiedOn=2019-06-10|2019-06-08|2019-06-07`
style: pipeDelimited
schema:
type: array
items:
type: string
format: date
- name: issuedOn
in: query
description: >-
Filter the response to cards issued on this date or set of `|`-separated dates. Dates are in [RFC
3339](https://tools.ietf.org/html/rfc3339) YYYY-MM-DD format. Examples: `?issuedOn=2019-06-10` ,
`?issuedOn=2019-06-10|2019-06-08|2019-06-07`
style: pipeDelimited
schema:
type: array
items:
type: string
format: date
- name: updatedBy
in: query
description: Filter the response to card requests created by the user named by this user ID.
schema:
type: string
responses:
'200':
description: OK
content:
application/hal+json:
schema:
$ref: '#/components/schemas/cards'
application/json:
schema:
$ref: '#/components/schemas/cards'
'400':
$ref: '#/components/responses/400'
'422':
$ref: '#/components/responses/422'
security:
- apiKey: []
accessToken:
- card/read
post:
summary: Create a new card
description: >-
Create a new card resource that represents a physical debit card. The URI to the associated account should be passed in the request in the
link named `apiture:account'. Only administrative applications can create cards.
operationId: createCard
x-apiture-implemented: false
tags:
- Cards
responses:
'201':
description: Created
headers:
Location:
description: >-
The URI of the new resource. If the URI begins with / it is relative to the API root context. Else, it is a full URI starting with
*`scheme`*`://host`
schema:
type: string
format: uri
ETag:
description: >-
The `ETag` response header specifies an entity tag which must be provided in an `If-Match` request header for *`PUT`* or *`PATCH`*
operations which update the resource.
schema:
type: string
content:
application/hal+json:
schema:
$ref: '#/components/schemas/card'
application/json:
schema:
$ref: '#/components/schemas/card'
'400':
$ref: '#/components/responses/400'
'409':
description: |-
Conflict. The request is not allowed for the selected account or banking product.
This error response may have one of the following `type` values:
* [`productDoesNotSupportCards`](#err-productDoesNotSupportCards)
x-apiture-errors:
- productDoesNotSupportCards
content:
application/hal+json:
schema:
$ref: '#/components/schemas/errorResponse'
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
security:
- apiKey: []
accessToken:
- admin/write
requestBody:
content:
application/hal+json:
schema:
$ref: '#/components/schemas/createCard'
application/json:
schema:
$ref: '#/components/schemas/createCard'
description: The data necessary to create a new card.
required: true
'/cards/{cardId}':
get:
summary: Fetch a representation of this card
description: 'Return a [HAL](http://developer.apiture.com/docs/concepts/hal) representation of this card resource.'
operationId: getCard
tags:
- Cards
parameters:
- $ref: '#/components/parameters/cardIdPathParam'
- $ref: '#/components/parameters/ifNoneMatchHeaderParam'
- $ref: '#/components/parameters/unmaskedQueryParam'
responses:
'200':
description: OK
headers:
ETag:
description: >-
The `ETag` response header specifies an entity tag which must be provided in an `If-Match` request header for *`PUT`* or *`PATCH`*
operations which update this card resource.
schema:
type: string
content:
application/hal+json:
schema:
$ref: '#/components/schemas/card'
application/json:
schema:
$ref: '#/components/schemas/card'
'304':
$ref: '#/components/responses/304'
'404':
$ref: '#/components/responses/404Card'
security:
- apiKey: []
accessToken:
- card/read
/issuerParameters:
post:
summary: Generate card issuer parameters
description: >-
Generate parameters for integrating with the card issuer. The client may embed a secure application component. This operation fetches
parameters to allow this integration, based on the current user and optionally a card. There is no request body for this operation.
operationId: createCardIssuerParameters
parameters:
- name: card
in: query
description: >-
The optional resource identifier of an existing card. This is the card's `_id` property, **not** the card/account number. Use this to
request parameters for the card issuer integration to change the card's PIN.
schema:
type: string
- name: issuer
in: query
required: true
description: 'The name of the card issuer, such as `marqueta`. This determines which issue parameters are returned to the client.'
schema:
type: string
tags:
- Card Requests
responses:
'201':
description: Created. The response contains the parameters to integrate with the card issuer components.
content:
application/hal+json:
schema:
$ref: '#/components/schemas/cardIssuerParameters'
application/json:
schema:
$ref: '#/components/schemas/cardIssuerParameters'
'400':
description: Bad Request. The parameters are not well-formed.
content:
application/hal+json:
schema:
$ref: '#/components/schemas/errorResponse'
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
'422':
description: |-
Unprocessable Entity. The parameters, while well-formed, are invalid.
This error response may have one of the following `type` values:
* [`cardRefNotFound`](#err-cardRefNotFound)
x-apiture-errors:
- cardRefNotFound
content:
application/hal+json:
schema:
$ref: '#/components/schemas/errorResponse'
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
security:
- apiKey: []
accessToken:
- card/read
/activeCards:
post:
operationId: activateCard
summary: Activate a card
description: |-
Activate a card so a customer can use it and change the card's `state` property to `active`.
Services or administrative users may activate a `requested` card after a card
request has been approved. Customers may _not_ use this operation for
activating new cards.
This operation is available via the `apiture:activate` link on the card
resource, if and only if the activation operation is available. The
response is the updated representation of the card. The `If-Match`
request header value must match the current entity tag value of the
card.
tags:
- Card Actions
parameters:
- $ref: '#/components/parameters/cardsQueryParam'
- $ref: '#/components/parameters/ifMatchHeaderParam'
responses:
'200':
description: OK. The operation succeeded. The card was updated and its `state` changed to `active`.
headers:
ETag:
description: >-
The `ETag` response header specifies an entity tag which must be provided in an `If-Match` request header for *`PUT`* or *`PATCH`*
operations which update the resource.
schema:
type: string
content:
application/hal+json:
schema:
$ref: '#/components/schemas/card'
application/json:
schema:
$ref: '#/components/schemas/card'
'400':
$ref: '#/components/responses/400ActivateCard'
'409':
$ref: '#/components/responses/409ActivateCardConflict'
'412':
$ref: '#/components/responses/412'
security:
- apiKey: []
accessToken:
- card/write
/lockedCards:
post:
operationId: lockCard
summary: Lock a card
description: |-
Lock a card so that it cannot be used for debits or other financial activity.
(This differs from locking the entire account.) This is also referred to
a _placing a hold on the card_.
This is one step before reporting a card as lost or stolen. A user can
unlock the card (restore it to the normal, active state) by using the
`apiture:unlock` link which invokes the
[`unlockCard`](#op-unlockCard) operation.
This is a self-service operation which a card holder may take if they
want to prevent fraudulent use of the card, such as if they have
misplaced it (but expect to find it again), or will be out of the
country.
This operation changes the `state` property of the card to `locked`.
This operation is available via the `apiture:lock` link on the card
resource, if and only if the card is eligible for the lock operation.
The response is the updated representation of the card. The `If-Match`
request header value must match the current entity tag value of the
card.
Only the card holder or an admin can lock a card.
tags:
- Card Actions
parameters:
- $ref: '#/components/parameters/cardsQueryParam'
- $ref: '#/components/parameters/ifMatchHeaderParam'
responses:
'200':
description: OK. The operation succeeded. The card was updated and its `state` changed to `locked`.
headers:
ETag:
description: >-
The `ETag` response header specifies an entity tag which must be provided in an `If-Match` request header for *`PUT`* or *`PATCH`*
operations which update the resource.
schema:
type: string
content:
application/hal+json:
schema:
$ref: '#/components/schemas/card'
application/json:
schema:
$ref: '#/components/schemas/card'
'400':
$ref: '#/components/responses/400LockCard'
'409':
$ref: '#/components/responses/409LockCardConflict'
'412':
$ref: '#/components/responses/412'
security:
- apiKey: []
accessToken:
- card/write
/unlockedCards:
post:
operationId: unlockCard
summary: Unlock a card
description: |-
Unlock a locked card so that it can be used for debits or other financial activity.
This changes the `state` property of the card back to
`active`. This operation is available via the `apiture:unlock`
link on the card resource, if and only if the card is currently `locked`.
The response is the updated representation of the
card. The `If-Match` request header value, if passed, must match the current entity
tag value of the card.
Only the card holder or an admin can unlock a card.
tags:
- Card Actions
parameters:
- $ref: '#/components/parameters/cardsQueryParam'
- $ref: '#/components/parameters/ifMatchHeaderParam'
responses:
'200':
description: OK. The operation succeeded. The card was updated and its `state` changed to `active`.
headers:
ETag:
description: >-
The `ETag` response header specifies an entity tag which must be provided in an `If-Match` request header for *`PUT`* or *`PATCH`*
operations which update the resource.
schema:
type: string
content:
application/hal+json:
schema:
$ref: '#/components/schemas/card'
application/json:
schema:
$ref: '#/components/schemas/card'
'400':
$ref: '#/components/responses/400UnlockCard'
'409':
$ref: '#/components/responses/409UnlockCardConflict'
'412':
$ref: '#/components/responses/412'
security:
- apiKey: []
accessToken:
- card/write
/closedCards:
post:
operationId: closeCard
summary: Close a card
description: >-
Close a card by adding it to the set of closed cards. This changes the `state` property of the card to `closed`. This operation is available
via the `apiture:close` link on the card resource, if and only if the card is eligible for the close operation. The response is the updated
representation of the card. The `If-Match` request header value, if passed, must match the current entity tag value of the card.
Only the card holder or an admin can close a card.
tags:
- Card Actions
parameters:
- $ref: '#/components/parameters/cardsQueryParam'
- $ref: '#/components/parameters/ifMatchHeaderParam'
responses:
'200':
description: OK. The operation succeeded. The card was updated and its `state` changed to `closed`.
headers:
ETag:
description: >-
The `ETag` response header specifies an entity tag which must be provided in an `If-Match` request header for *`PUT`* or *`PATCH`*
operations which update the resource.
schema:
type: string
content:
application/hal+json:
schema:
$ref: '#/components/schemas/card'
application/json:
schema:
$ref: '#/components/schemas/card'
'400':
$ref: '#/components/responses/400CloseCard'
'409':
$ref: '#/components/responses/409CloseCardConflict'
'412':
$ref: '#/components/responses/412'
security:
- apiKey: []
accessToken:
- card/write
/labels:
get:
summary: Localized Labels
description: >-
Return a JSON object which defines labels for enumeration types defined by the schemas defined in this API. The labels in the response may not
all match the requested language; some may be in the default language (`en-us`).
operationId: getLabels
security:
- apiKey: []
parameters:
- name: Accept-Language
in: header
description: >-
The weighted language tags which indicate the user's preferred natural language for the localized labels in the response, as per [RFC
7231](https://tools.ietf.org/html/rfc7231#section-5.3.5).
schema:
type: string
responses:
'200':
description: OK
content:
application/hal+json:
schema:
$ref: '#/components/schemas/localizedLabels'
application/json:
schema:
$ref: '#/components/schemas/localizedLabels'
tags:
- API
/:
get:
summary: Top-level resources and operations in this API
description: Return links to the top-level resources and operations in this API.
operationId: getApi
responses:
'200':
description: OK
content:
application/hal+json:
schema:
$ref: '#/components/schemas/root'
application/json:
schema:
$ref: '#/components/schemas/root'
tags:
- API
security:
- apiKey: []
/apiDoc:
get:
summary: Return API definition document
description: Return the OpenAPI document that describes this API.
operationId: getApiDoc
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
application/openapi+json;version=2.0:
schema:
type: object
application/openapi+yaml;version=2.0:
schema:
type: object
application/hal+json:
schema:
type: object
tags:
- API
security:
- apiKey: []
x-apiture-errors:
cardRequestRefNotFound:
description: The request card request resource ID does not identify a card
remediation: Pass the ID of an existing card request resource
cardRefNotFound:
description: The request card resource ID does not identify a card
remediation: Pass the ID of an existing card resource
invalidAccountLink:
description: The request contains an invalid reference to an account
remediation: Pass the URI of a valid account that the current user holds.
missingApitureChallengeHeader:
description: The Apiture-Challenge request header was not passed
remediation: 'Pass the _id of a valid, verified challenge resource in the Apiture-Challenge request header.'
productDoesNotSupportCards:
description: The banking product associated with the account does not support card requests.
remediation: Select an account that supports cards.
challengedExpired:
description: The challenge resource specified in the Apiture-Challenge request header has expired
remediation: Obtain a new challenge resource
challengedNotVerified:
description: The challenge resource specified in the Apiture-Challenge request header has not been verified
remediation: Complete the challenge verification before using a challenge resource
challengedAlreadyRedeemed:
description: The challenge resource specified in the Apiture-Challenge request header has been redeemed the maximum number of times
remediation: Obtain a new challenge resource
x-apiture-traits:
- api:
name: Cards
links:
- getApi
- getApiDoc
- getLabels
- getCards
- createCardRequest
- getCards
- createCard
- estimateCardShippingCharges
- resource:
name: card
description: Debit cards associated with a banking account and credit cards.
excludeMethods:
- put
- patch
- resource:
name: card request
description: 'A request to issue a new card or to replace a lost, stolen, or damaged card.'
excludeMethods:
- put
- patch
- state:
name: card
verb: activate
state: active
- state:
name: card
verb: lock
state: locked
- state:
name: card
verb: close
state: closed
- state:
name: card request
verb: cancel
state: canceled
- state:
name: card request
verb: reject
state: rejected
- state:
name: card request
verb: complete
state: completed
- labels:
applied: true
- security:
baseScope: card
x-apiture-annotated-at: '2020-08-12T16:15:09.192Z'
components:
schemas:
createCard:
title: Create Card (v2.0.0)
description: Representation used to create a new card.
x-apiture-version: 2.0.0
required:
- accountName
example:
_profile: 'https://api.apiture.com/schemas/cards/createCard/v2.0.0/profile.json'
accountName: My Premiere Savings
_links:
'apiture:account':
href: /accounts/accounts/e7076b86-0f0b-4126-92eb-d90f4be1ae6a
x-apiture-composition:
- $ref: '#/components/schemas/abstractResource'
- $ref: '#/components/schemas/cardFields'
properties:
_links:
description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
allOf:
- $ref: '#/components/schemas/links'
_embedded:
description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
type: object
_profile:
description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
type: string
format: uri
_error:
description: An object which describes an error. This value is omitted if the operation succeeded without error.
type: object
allOf:
- $ref: '#/components/schemas/error'
accountName:
description: The name of the account that this card is tied to.
type: string
minLength: 1
maxLength: 128
example: Premiere Checking
readOnly: true
accountNumbers:
description: >-
The masked and (optionally) full number for the account this card is associated with. This is derived from the account used in the initial
card request. By default, only the `masked` number is returned; use `?unmasked=true` to reveal the `full` account number.
allOf:
- $ref: '#/components/schemas/accountNumbers'
readOnly: true
type: object
x-apiture-flattened: true
summaryCard:
title: Card Summary (v2.0.0)
description: >-
Summary representation of a card resource in cards collections. This representation normally does not contain any `_embedded` objects. If
needed, call the `GET` operation on the item's `self` link to get `_embedded` objects.
x-apiture-version: 2.0.0
example:
_id: 0399abed-fd3d-4830-a88b-30f38b8a365c
_profile: 'https://api.apiture.com/schemas/cards/summaryCard/v2.0.0/profile.json'
holderName: LUCILLE WELLPHUNDED
label: Premiere Checking *3210
accountName: Premiere Checking
accountNumbers:
masked: '*************3210'
full: '9876543210'
cardNumbers:
masked: '************3210'
state: active
fulfillmentState: shipped
fulfillmentDescription: 'Shipped on June 7, 2020'
issuedAt: '2019-06-07T05:18:30.375Z'
updatedAt: '2019-06-07T05:18:30.375Z'
mine: true
updatedBy: lucy.wellphunded@bankcustomer.example.com
expiresOn: '2012-04-30'
_embedded: {}
_links:
self:
href: /cards/cards/0399abed-fd3d-4830-a88b-30f38b8a365c
'apiture:lock':
href: /cards/lockedCards?card=0399abed-fd3d-4830-a88b-30f38b8a365c
'apiture:account':
href: /accounts/accounts/d62c0701-0d74-4836-83f9-ebf3709442ea
x-apiture-composition:
- $ref: '#/components/schemas/abstractResource'
- $ref: '#/components/schemas/cardFields'
- properties:
- _id
- label
- holderName
- cardNumbers
- fulfillmentState
- fulfillmentDescription
- mine
- state
- issuedAt
- activatedAt
- expiresOn
- updatedAt
- updatedBy
properties:
_links:
description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
allOf:
- $ref: '#/components/schemas/links'
_embedded:
description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
type: object
_profile:
description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
type: string
format: uri
_error:
description: An object which describes an error. This value is omitted if the operation succeeded without error.
type: object
allOf:
- $ref: '#/components/schemas/error'
accountName:
description: The name of the account that this card is tied to.
type: string
minLength: 1
maxLength: 128
example: Premiere Checking
readOnly: true
accountNumbers:
description: >-
The masked and (optionally) full number for the account this card is associated with. This is derived from the account used in the initial
card request. By default, only the `masked` number is returned; use `?unmasked=true` to reveal the `full` account number.
allOf:
- $ref: '#/components/schemas/accountNumbers'
readOnly: true
_id:
description: The unique identifier for this card resource. This is an immutable opaque string.
readOnly: true
type: string
label:
description: The text label for this card.
type: string
minLength: 1
maxLength: 128
readOnly: true
example: My debit card for Premiere Checking
holderName:
description: 'The card holder''s full name, as it appears on the card. This value is often ALL CAPS.'
type: string
example: LUCILLE WELLPHUNDED
readOnly: true
cardNumbers:
description: The masked and full card number this card.
allOf:
- $ref: '#/components/schemas/cardNumbers'
readOnly: true
fulfillmentState:
description: Indicates the state of a card replacement request. The user cannot change this property.
allOf:
- $ref: '#/components/schemas/cardFulfillmentState'
readOnly: true
example: replacedWithNewNumber
fulfillmentDescription:
description: The card provider's explanation of the current `fulfillmentState`.
type: string
readOnly: true
mine:
description: >-
If `true`, the card is owned by the user making the request. By default a user can view all cards for a given Account, but they may only
take action on cards they own.
type: boolean
readOnly: true
state:
description: The state of this card. This is derived.
allOf:
- $ref: '#/components/schemas/cardState'
readOnly: true
issuedAt:
description: >-
The date-time when this card was issued. This is in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC format. This field is present only
after the card has been issued, _and_ if the card vendor provides the time stamp.
type: string
format: date-time
example: {}
readOnly: true
activatedAt:
description: >-
The date-time when this card was activated. This is in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC format. This field is present
only after the card has been activated, _and_ if the card vendor provides the time stamp.
type: string
format: date-time
example: {}
readOnly: true
expiresOn:
description: >-
The card's expiration date. The day should is the last day of the month, such as 2021-10-31 if the card expires at the end of October,
2021. in [RFC 3339](https://tools.ietf.org/html/rfc3339) `YYYY-MM-DD` format.
type: string
format: date
example: '2012-04-30'
readOnly: true
updatedAt:
description: >-
The date-time when this card's state or other attributes were last changed. This is in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC
format.
type: string
format: date-time
example: {}
readOnly: true
updatedBy:
description: 'The username of the person who last modified this card resource. '
type: string
readOnly: true
example: lucy.wellphunded@bankcustomer.example.com
type: object
x-apiture-flattened: true
cardState:
title: Card State (v1.0.0)
description: |
The state of a card.
cardState
strings may have one of the following
[enumerated values](https://developer.apiture.com/concepts/label-groups#enumerations) values
(described by the named cardState)
Value | Description |
These enumeration values are further described by the [label group](https://developer.apiture.com/concepts/label-groups)
named `cardState` in the response from the [`getLabels`](#op-getLabels) operation.
unknown | Unknown |
requested | Requested: The used has submitted the request to issue the card but the request has not been completed. |
issued | Issued: The card has been issued but the card holder has not activated it. |
active | Active: The card has been issued and activated an is available for use. |
locked | Locked: The user has requested that the card be locked so that it may not be used. This is useful if they have misplaced the card but do not yet want to report it as lost. |
lost | Reported as lost: The user has reported the card as lost. The card is disabled. A new card (with a new card number) will be issued. |
stolen | Reported as stolen: The user has reported the card as stolen. The card is disabled. A new card (with a new card number) will be issued. |
damaged | Reported as damaged: The user has reported the card as stolen. A new card with the same card number will be issued. |
frozen | Frozen: The financial institution has frozen the card or the account associated with this card. |
closed | Closed: The card has been closed at the card holder's request or by the financial institution. The card is disabled and the card holder cannot use it for banking activity. |
type: string
enum:
- unknown
- requested
- issued
- active
- locked
- lost
- stolen
- damaged
- frozen
- closed
x-apiture-enum: cardState
x-apiture-version: 1.0.0
x-apiture-flattened: true
cardReplacementState:
description: |
The state of a card replacement request.
cardReplacementState
strings may have one of the following
[enumerated values](https://developer.apiture.com/concepts/label-groups#enumerations) values
(described by the named cardReplacementState)
Value | Description |
These enumeration values are further described by the [label group](https://developer.apiture.com/concepts/label-groups)
named `cardReplacementState` in the response from the [`getLabels`](#op-getLabels) operation.
none | None: No card replacement requests are active. |
requested | Requested: The user has requested a card replacement. |
ordered | Ordered: The card replacement order has been sent to the card provider. |
issued | Issued: The card has been issued by the card provider. |
shipped | Shipped: The issued card has been shipped by the card provider. |
replacedWithSameNumber | Replaced with same card number: The card for this account number has been replaced; the card has been issued, shipped, and activated. |
replacedWithNewNumber | Replaced with new card number: The card for this account has been replaced with a new card and new card number; the card has been issued, shipped, and activated. |
title: Card Replacement State (v1.0.0)
type: string
enum:
- none
- requested
- ordered
- issued
- shipped
- replacedWithSameNumber
- replacedWithNewNumber
- rejected
x-apiture-enum: cardReplacementState
x-apiture-version: 1.0.0
x-apiture-flattened: true
cardFulfillmentState:
description: |
The state of a card order fulfillment from the provider.
cardFulfillmentState
strings may have one of the following
[enumerated values](https://developer.apiture.com/concepts/label-groups#enumerations) values
(described by the named cardReplacementState)
Value | Description |
These enumeration values are further described by the [label group](https://developer.apiture.com/concepts/label-groups)
named `cardReplacementState` in the response from the [`getLabels`](#op-getLabels) operation.
none | None: No card replacement requests are active. |
requested | Requested: The user has requested a card replacement. |
ordered | Ordered: The card replacement order has been sent to the card provider. |
issued | Issued: The card has been issued by the card provider. |
shipped | Shipped: The issued card has been shipped by the card provider. |
replacedWithSameNumber | Replaced with same card number: The card for this account number has been replaced; the card has been issued, shipped, and activated. |
replacedWithNewNumber | Replaced with new card number: The card for this account has been replaced with a new card and new card number; the card has been issued, shipped, and activated. |
title: Card Fulfillment State (v1.0.0)
type: string
enum:
- none
- requested
- ordered
- reordered
- issued
- shipped
- rejected
x-apiture-enum: cardReplacementState
x-apiture-version: 1.0.0
x-apiture-flattened: true
card:
title: Card (v2.0.0)
description: >
A card resource, which represents physical Debit cards associated with a banking
account or credit cards.
The default representation includes only a masked card number. Use `?unmasked=true`
on the request to include the full card number.
The hypermedia `_links` in the response (listed below) include several action
links which change the state of the card.
These links should be used with the `POST` verb
(see [Resource sets](https://developer.apiture.com/docs/concepts/resource-sets/)).
Links
Response and request bodies using this card
schema may contain
the following links:
x-apiture-version: 2.0.0
example:
_id: 0399abed-fd3d-4830-a88b-30f38b8a365c
_profile: 'https://api.apiture.com/schemas/cards/card/v2.0.0/profile.json'
holderName: LUCILLE WELLPHUNDED
name: My debit card for Premiere Checking
accountName: Premiere Checking
accountNumbers:
masked: '*************3210'
full: '9876543210'
cardNumbers:
masked: '************3210'
state: active
fulfillmentState: shipped
fulfillmentDescription: 'Shipped on June 7, 2020'
issuedAt: '2019-06-07T05:18:30.375Z'
updatedAt: '2019-06-07T05:18:30.375Z'
mine: true
updatedBy: lucy.wellphunded@bankcustomer.example.com
expiresOn: '2012-04-30'
_embedded: {}
_links:
self:
href: /cards/cards/0399abed-fd3d-4830-a88b-30f38b8a365c
'apiture:lock':
href: /cards/lockedCards?card=0399abed-fd3d-4830-a88b-30f38b8a365c
'apiture:account':
href: /accounts/accounts/d62c0701-0d74-4836-83f9-ebf3709442ea
x-apiture-links:
- rel: self
operationId: getCard
- rel: 'apiture:account'
title: The Account associated with this card
verb: get
- rel: 'apiture:unlock'
operationId: unlockCard
- rel: 'apiture:close'
operationId: closeCard
- rel: 'apiture:lock'
operationId: lockCard
- rel: 'apiture:activate'
operationId: activateCard
- rel: 'apiture:replace'
operationId: createCardRequest
x-apiture-composition:
- $ref: '#/components/schemas/summaryCard'
properties:
_links:
description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
allOf:
- $ref: '#/components/schemas/links'
_embedded:
description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
type: object
_profile:
description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
type: string
format: uri
_error:
description: An object which describes an error. This value is omitted if the operation succeeded without error.
type: object
allOf:
- $ref: '#/components/schemas/error'
accountName:
description: The name of the account that this card is tied to.
type: string
minLength: 1
maxLength: 128
example: Premiere Checking
readOnly: true
accountNumbers:
description: >-
The masked and (optionally) full number for the account this card is associated with. This is derived from the account used in the initial
card request. By default, only the `masked` number is returned; use `?unmasked=true` to reveal the `full` account number.
allOf:
- $ref: '#/components/schemas/accountNumbers'
readOnly: true
_id:
description: The unique identifier for this card resource. This is an immutable opaque string.
readOnly: true
type: string
label:
description: The text label for this card.
type: string
minLength: 1
maxLength: 128
readOnly: true
example: My debit card for Premiere Checking
holderName:
description: 'The card holder''s full name, as it appears on the card. This value is often ALL CAPS.'
type: string
example: LUCILLE WELLPHUNDED
readOnly: true
cardNumbers:
description: The masked and full card number this card.
allOf:
- $ref: '#/components/schemas/cardNumbers'
readOnly: true
fulfillmentState:
description: Indicates the state of a card replacement request. The user cannot change this property.
allOf:
- $ref: '#/components/schemas/cardFulfillmentState'
readOnly: true
example: replacedWithNewNumber
fulfillmentDescription:
description: The card provider's explanation of the current `fulfillmentState`.
type: string
readOnly: true
mine:
description: >-
If `true`, the card is owned by the user making the request. By default a user can view all cards for a given Account, but they may only
take action on cards they own.
type: boolean
readOnly: true
state:
description: The state of this card. This is derived.
allOf:
- $ref: '#/components/schemas/cardState'
readOnly: true
issuedAt:
description: >-
The date-time when this card was issued. This is in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC format. This field is present only
after the card has been issued, _and_ if the card vendor provides the time stamp.
type: string
format: date-time
example: {}
readOnly: true
activatedAt:
description: >-
The date-time when this card was activated. This is in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC format. This field is present
only after the card has been activated, _and_ if the card vendor provides the time stamp.
type: string
format: date-time
example: {}
readOnly: true
expiresOn:
description: >-
The card's expiration date. The day should is the last day of the month, such as 2021-10-31 if the card expires at the end of October,
2021. in [RFC 3339](https://tools.ietf.org/html/rfc3339) `YYYY-MM-DD` format.
type: string
format: date
example: '2012-04-30'
readOnly: true
updatedAt:
description: >-
The date-time when this card's state or other attributes were last changed. This is in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC
format.
type: string
format: date-time
example: {}
readOnly: true
updatedBy:
description: 'The username of the person who last modified this card resource. '
type: string
readOnly: true
example: lucy.wellphunded@bankcustomer.example.com
type: object
x-apiture-flattened: true
cardFields:
title: Card Fields (v2.0.0)
description: 'Common fields of the card resource, used to build other model schemas.'
x-apiture-fragment: true
x-apiture-version: 2.0.0
properties:
accountName:
description: The name of the account that this card is tied to.
type: string
minLength: 1
maxLength: 128
example: Premiere Checking
readOnly: true
accountNumbers:
description: >-
The masked and (optionally) full number for the account this card is associated with. This is derived from the account used in the initial
card request. By default, only the `masked` number is returned; use `?unmasked=true` to reveal the `full` account number.
allOf:
- $ref: '#/components/schemas/accountNumbers'
readOnly: true
type: object
x-apiture-flattened: true
cards:
title: Card Collection (v2.0.0)
description: |-
Collection of cards. The items in the collection are ordered in the `_embedded.items` array; the `name` is `cards`.
The top-level `_links` object may contain pagination links (`self`, `next`, `prev`, `first`, `last`, `collection`).
x-apiture-version: 2.0.0
example:
_profile: 'https://api.apiture.com/schemas/cards/cards/v2.0.0/profile.json'
start: 10
limit: 10
count: 67
name: cards
_links:
self:
href: /cards/cards?start=10&limit=10
first:
href: /cards/cards?start=0&limit=10
next:
href: /cards/cards?start=20&limit=10
collection:
href: /cards/cards
_embedded:
items:
_id: 0399abed-fd3d-4830-a88b-30f38b8a365c
_profile: 'https://api.apiture.com/schemas/cards/card/v2.0.0/profile.json'
holderName: LUCILLE WELLPHUNDED
label: Premiere Checking *3210
accountName: Premiere Checking
accountNumbers:
masked: '*************3210'
full: '9876543210'
cardNumbers:
masked: '************3210'
state: active
fulfillmentState: shipped
fulfillmentDescription: 'Shipped on June 7, 2020'
mine: true
issuedAt: '2019-06-07T05:18:30.375Z'
updatedAt: '2019-06-07T05:18:30.375Z'
updatedBy: lucy.wellphunded@bankcustomer.example.com
expiresOn: '2012-04-30'
_links:
self:
href: /cards/cards/0399abed-fd3d-4830-a88b-30f38b8a365c
'apiture:account':
href: /accounts/accounts/d62c0701-0d74-4836-83f9-ebf3709442ea
x-apiture-composition:
- $ref: '#/components/schemas/collection'
- properties:
- _embedded
properties:
_links:
description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
allOf:
- $ref: '#/components/schemas/links'
_embedded:
type: object
description: Embedded objects.
properties:
items:
description: An array containing a page of card items.
type: array
items:
$ref: '#/components/schemas/summaryCard'
_profile:
description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
type: string
format: uri
_error:
description: An object which describes an error. This value is omitted if the operation succeeded without error.
type: object
allOf:
- $ref: '#/components/schemas/error'
count:
description: >-
The number of items in the collection. This value is _optional_ and may be omitted if the count is not computable efficiently. If a filter
is applied to the collection (either implicitly or explicitly), the count, if present, indicates the number of items that satisfy the
filter.
type: integer
start:
description: The start index of this page of items.
type: integer
limit:
description: The maximum number of items per page.
type: integer
name:
description: The name of the collection.
type: string
type: object
x-apiture-flattened: true
createCardRequest:
title: Create Card Request (v1.1.0)
description: >
Representation used to create a request for a new or replacement card. The `_links` in the request must contain a `apiture:account` link to
the user's banking account; that account must allow card ordering (as contained in the banking product's `card` object; see the Products API.)
Links
Response and request bodies using this createCardRequest
schema may contain
the following links:
Rel | Summary | Method |
apiture:account |
The banking account associated with the card | GET |
x-apiture-version: 1.1.0
example:
_profile: 'https://api.apiture.com/schemas/cards/cardRequest/v1.0.0/profile.json'
cardId: 9e5a519c-ed3d-48ec-84d0-ef29b2843803
reason: lost
description: Replace lost card
_links:
'apiture:account':
href: 'https://api.example.com/accounts/accounts/617c31ce-7bf0-4e55-a5df-12916ff22ada'
x-apiture-links:
- rel: 'apiture:account'
title: The banking account associated with the card
description: The account for which the user is requesting a new card.
verb: get
x-apiture-composition:
- $ref: '#/components/schemas/abstractResource'
- $ref: '#/components/schemas/cardRequestFields'
properties:
_links:
description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
allOf:
- $ref: '#/components/schemas/links'
_embedded:
description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
type: object
_profile:
description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
type: string
format: uri
_error:
description: An object which describes an error. This value is omitted if the operation succeeded without error.
type: object
allOf:
- $ref: '#/components/schemas/error'
cardId:
description: The resource ID of the card that is to be replaced.
type: string
example: 9e5a519c-ed3d-48ec-84d0-ef29b2843803
reason:
description: Reasons which describe why the user is requesting a a card.
allOf:
- $ref: '#/components/schemas/cardRequestReason'
example: lost
description:
description: |-
The card holder's description, note, or explanation of why they requested a card.
type: string
accountNumbers:
description: >-
The masked and (optionally) full number for the account this card is associated with. The `full` number is only returned when requests
contain the `?unmasked` query parameter.
readOnly: true
allOf:
- $ref: '#/components/schemas/accountNumbers'
type: object
x-apiture-flattened: true
summaryCardRequest:
title: Card Request Summary (v1.1.0)
description: >-
Summary representation of a card request resource in replacements collections. This representation normally does not contain any `_embedded`
objects. If needed, call the `GET` operation on the item's `self` link to get `_embedded` objects.
x-apiture-version: 1.1.0
example:
_id: 35eb0e67-ac9b-44d7-8799-6648ba6b1c65
_profile: 'https://api.apiture.com/schemas/cards/cardRequest/v1.0.0/profile.json'
cardId: 9e5a519c-ed3d-48ec-84d0-ef29b2843803
reason: lost
description: Replace lost card
submittedAt: '2019-06-07T05:18:30.375Z'
updatedAt: '2019-06-07T05:18:30.375Z'
updatedBy: lucy.wellphunded@bankcustomer.example.com
_links:
self:
href: /cards/cards/35eb0e67-ac9b-44d7-8799-6648ba6b1c65
'apiture:account':
href: 'https://api.example.com/accounts/accounts/617c31ce-7bf0-4e55-a5df-12916ff22ada'
'apiture:cancel':
href: 'https://api.example.com/cards/canceledCardRequests?cardRequest=617c31ce-7bf0-4e55-a5df-12916ff22ada'
x-apiture-composition:
- $ref: '#/components/schemas/abstractResource'
- $ref: '#/components/schemas/cardRequestFields'
- properties:
- _id
- state
- submittedAt
- resolvedAt
- updatedAt
- resolutionReason
- updatedBy
properties:
_links:
description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
allOf:
- $ref: '#/components/schemas/links'
_embedded:
description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
type: object
_profile:
description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
type: string
format: uri
_error:
description: An object which describes an error. This value is omitted if the operation succeeded without error.
type: object
allOf:
- $ref: '#/components/schemas/error'
cardId:
description: The resource ID of the card that is to be replaced.
type: string
example: 9e5a519c-ed3d-48ec-84d0-ef29b2843803
reason:
description: Reasons which describe why the user is requesting a a card.
allOf:
- $ref: '#/components/schemas/cardRequestReason'
example: lost
description:
description: |-
The card holder's description, note, or explanation of why they requested a card.
type: string
accountNumbers:
description: >-
The masked and (optionally) full number for the account this card is associated with. The `full` number is only returned when requests
contain the `?unmasked` query parameter.
readOnly: true
allOf:
- $ref: '#/components/schemas/accountNumbers'
_id:
description: The unique identifier for this card request resource. This is an immutable opaque string.
readOnly: true
type: string
state:
description: Indicates the state of a card request.
allOf:
- $ref: '#/components/schemas/cardRequestState'
readOnly: true
example: submitted
submittedAt:
description: 'The date-time when this card request request was submitted. This is in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC format.'
type: string
format: date-time
example: {}
resolvedAt:
description: >-
The date-time when this card request request was completed, rejected, or canceled. This is in [RFC
3339](https://tools.ietf.org/html/rfc3339) UTC format.
type: string
format: date-time
example: {}
updatedAt:
description: 'The date-time when this card request attributes were last changed. This is in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC format.'
type: string
format: date-time
example: {}
resolutionReason:
description: The explanation for why the card was resolved. This may be the reason the card request was rejected.
type: string
maxLength: 2048
example: Suspected fraudulent activity has been detected.
updatedBy:
description: The username of the person who last modified or resolved this card request.
type: string
type: object
x-apiture-flattened: true
cardRequestState:
title: Card Request State (v1.0.0)
description: |
Indicates the state of a card request.
cardRequestState
strings may have one of the following
[enumerated values](https://developer.apiture.com/concepts/label-groups#enumerations) values
(described by the named cardRequestState)
Value | Description |
These enumeration values are further described by the [label group](https://developer.apiture.com/concepts/label-groups)
named `cardRequestState` in the response from the [`getLabels`](#op-getLabels) operation.
pending | Pending: A card request has been created but not yet submitted. |
submitted | Submitted: A card request has been submitted but not processed. |
canceled | Canceled: A card request has been canceled. |
rejected | Rejected: A card request has been rejected. |
completed | Completed: A card request has been completed. |
type: string
enum:
- pending
- submitted
- canceled
- rejected
- completed
x-apiture-enum: cardRequestState
x-apiture-version: 1.0.0
x-apiture-flattened: true
cardRequest:
title: Card Request (v1.1.0)
description: >
Representation of a card request resource.
This represents a request to issue a new card or replace a lost,
stolen, or damaged card.
The hypermedia `_links` in the card request representation (listed below)
include several action links which change the state of the card request.
These links should be used with the `POST` verb
(see [Resource sets](https://developer.apiture.com/docs/concepts/resource-sets/)).
Links
Response and request bodies using this cardRequest
schema may contain
the following links:
x-apiture-version: 1.1.0
x-apiture-links:
- rel: 'apiture:cancel'
operationId: cancelCardRequest
- rel: 'apiture:complete'
operationId: completeCardRequest
- rel: 'apiture:reject'
operationId: rejectCardRequest
example:
_id: 35eb0e67-ac9b-44d7-8799-6648ba6b1c65
_profile: 'https://api.apiture.com/schemas/cards/cardRequest/v1.0.0/profile.json'
cardId: 9e5a519c-ed3d-48ec-84d0-ef29b2843803
reason: lost
description: Replace lost card
submittedAt: '2019-06-07T05:18:30.375Z'
updatedAt: '2019-06-07T05:18:30.375Z'
updatedBy: lucy.wellphunded@bankcustomer.example.com
_links:
self:
href: /cards/cardRequests/35eb0e67-ac9b-44d7-8799-6648ba6b1c65
'apiture:card':
href: /cards/cards/9e5a519c-ed3d-48ec-84d0-ef29b2843803
'apiture:account':
href: 'https://api.example.com/accounts/accounts/617c31ce-7bf0-4e55-a5df-12916ff22ada'
'apiture:cancel':
href: 'https://api.example.com/cards/canceledCardRequests?cardRequest=617c31ce-7bf0-4e55-a5df-12916ff22ada'
x-apiture-composition:
- $ref: '#/components/schemas/summaryCardRequest'
properties:
_links:
description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
allOf:
- $ref: '#/components/schemas/links'
_embedded:
description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
type: object
_profile:
description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
type: string
format: uri
_error:
description: An object which describes an error. This value is omitted if the operation succeeded without error.
type: object
allOf:
- $ref: '#/components/schemas/error'
cardId:
description: The resource ID of the card that is to be replaced.
type: string
example: 9e5a519c-ed3d-48ec-84d0-ef29b2843803
reason:
description: Reasons which describe why the user is requesting a a card.
allOf:
- $ref: '#/components/schemas/cardRequestReason'
example: lost
description:
description: |-
The card holder's description, note, or explanation of why they requested a card.
type: string
accountNumbers:
description: >-
The masked and (optionally) full number for the account this card is associated with. The `full` number is only returned when requests
contain the `?unmasked` query parameter.
readOnly: true
allOf:
- $ref: '#/components/schemas/accountNumbers'
_id:
description: The unique identifier for this card request resource. This is an immutable opaque string.
readOnly: true
type: string
state:
description: Indicates the state of a card request.
allOf:
- $ref: '#/components/schemas/cardRequestState'
readOnly: true
example: submitted
submittedAt:
description: 'The date-time when this card request request was submitted. This is in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC format.'
type: string
format: date-time
example: {}
resolvedAt:
description: >-
The date-time when this card request request was completed, rejected, or canceled. This is in [RFC
3339](https://tools.ietf.org/html/rfc3339) UTC format.
type: string
format: date-time
example: {}
updatedAt:
description: 'The date-time when this card request attributes were last changed. This is in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC format.'
type: string
format: date-time
example: {}
resolutionReason:
description: The explanation for why the card was resolved. This may be the reason the card request was rejected.
type: string
maxLength: 2048
example: Suspected fraudulent activity has been detected.
updatedBy:
description: The username of the person who last modified or resolved this card request.
type: string
type: object
x-apiture-flattened: true
cardRequests:
title: Card Requests Collection (v1.1.0)
description: >-
Collection of requests to issue a new or replacement card. The items in the collection are ordered in the `_embedded.items` array; the `name`
is `replacements`.
The top-level `_links` object may contain pagination links (`self`, `next`, `prev`, `first`, `last`, `collection`).
x-apiture-version: 1.1.0
example:
_profile: 'https://api.apiture.com/schemas/cards/cardRequests/v1.0.0/profile.json'
start: 10
limit: 10
count: 67
name: cardRequests
_links:
self:
href: /cards/cardRequests?start=10&limit=10
first:
href: /cards/cardRequests?start=0&limit=10
next:
href: /cards/cardRequests?start=20&limit=10
collection:
href: /cards/cardRequests
_embedded:
items:
anyOf:
- _id: 0399abed-fd3d-4830-a88b-30f38b8a365c
_profile: 'https://api.apiture.com/schemas/cards/cardRequest/v1.0.0/profile.json'
_links:
self:
href: /cards/cardRequests/0399abed-fd3d-4830-a88b-30f38b8a365c
- _id: d62c0701-0d74-4836-83f9-ebf3709442ea
_profile: 'https://api.apiture.com/schemas/cards/cardRequest/v1.0.0/profile.json'
_links:
self:
href: /cards/cardRequests/d62c0701-0d74-4836-83f9-ebf3709442ea
x-apiture-composition:
- $ref: '#/components/schemas/collection'
- properties:
- _embedded
properties:
_links:
description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
allOf:
- $ref: '#/components/schemas/links'
_embedded:
type: object
description: Embedded objects.
properties:
items:
description: An array containing a page of replacement items.
type: array
items:
$ref: '#/components/schemas/summaryCardRequest'
_profile:
description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
type: string
format: uri
_error:
description: An object which describes an error. This value is omitted if the operation succeeded without error.
type: object
allOf:
- $ref: '#/components/schemas/error'
count:
description: >-
The number of items in the collection. This value is _optional_ and may be omitted if the count is not computable efficiently. If a filter
is applied to the collection (either implicitly or explicitly), the count, if present, indicates the number of items that satisfy the
filter.
type: integer
start:
description: The start index of this page of items.
type: integer
limit:
description: The maximum number of items per page.
type: integer
name:
description: The name of the collection.
type: string
type: object
x-apiture-flattened: true
cardRequestFields:
title: Card Request Fields (v1.1.0)
x-apiture-version: 1.1.0
description: >-
Common fields of the card request resource used to build other model schemas. The estimated shipping charges are based on the user's preferred
mailing address.
x-apiture-todo: Add the mailing address for the new card
x-apiture-fragment: true
required:
- reason
properties:
cardId:
description: The resource ID of the card that is to be replaced.
type: string
example: 9e5a519c-ed3d-48ec-84d0-ef29b2843803
reason:
description: Reasons which describe why the user is requesting a a card.
allOf:
- $ref: '#/components/schemas/cardRequestReason'
example: lost
description:
description: |-
The card holder's description, note, or explanation of why they requested a card.
type: string
accountNumbers:
description: >-
The masked and (optionally) full number for the account this card is associated with. The `full` number is only returned when requests
contain the `?unmasked` query parameter.
readOnly: true
allOf:
- $ref: '#/components/schemas/accountNumbers'
type: object
x-apiture-flattened: true
cardRequestReason:
title: Card Request Reason (v1.1.0)
x-apiture-version: 1.1.0
description: |
The reason the user is requesting a replacement card.
cardRequestReason
strings may have one of the following
[enumerated values](https://developer.apiture.com/concepts/label-groups#enumerations) values
(described by the named cardRequestReason)
Value | Description |
These enumeration values are further described by the [label group](https://developer.apiture.com/concepts/label-groups)
named `cardRequestReason` in the response from the [`getLabels`](#op-getLabels) operation.
initial | Initial Card Request |
lost | Lost Card |
stolen | Stolen Card |
damaged | Damaged Card |
neverReceived | Never Received: The card holder is requesting a replacement of card that was shipped but never received. |
reorder | Reorder Closed Card: The card holder is requesting a replacement of a previously closed card. |
type: string
enum:
- initial
- lost
- stolen
- damaged
- neverReceived
- reorder
x-apiture-enum: cardRequestReason
x-apiture-flattened: true
cardNumbers:
title: Card Numbers (v1.0.0)
description: Masked and full representation of a card number.
properties:
masked:
description: >-
A partial (masked) card number that does not contain all the digits of the full card number. This masked number appears in statements or
in user experience presentation. It is sufficient for a user to differentiate this card from other cards the user holds, but is not
sufficient for initiating transactions, etc. The first character is the mask character and is repeated; this does not indicate that the
full card number is the same as the mask length. This value is derived and immutable.
type: string
maxLength: 16
readOnly: true
example: '************3210'
x-apiture-version: 1.0.0
type: object
x-apiture-flattened: true
cardShippingEstimateRequest:
title: Card Shipping Estimate Request (v1.0.0)
x-apiture-version: 1.0.0
description: >
Information required to estimate the expedited shipping costs for a card. The shipping address is the preferred mailing address for the user
making the request.
Links
Response and request bodies using this cardShippingEstimateRequest
schema may contain
the following links:
Rel | Summary | Method |
apiture:account |
The account associated with the card | GET |
example:
_profile: 'https://production.api.apiture.com/schemas/cards/cardShippingEstimateRequest/v1.0.0/profile.json'
cardId: 0399abed-fd3d-4830-a88b-30f38b8a365c
_links:
'apiture:account':
href: /accounts/accounts/c4fff7a4-8654-4085-aeba-a984de81dcc3
x-apiture-links:
- rel: 'apiture:account'
title: The account associated with the card
verb: get
x-apiture-composition:
- $ref: '#/components/schemas/abstractRequest'
- properties:
- cardId
properties:
_links:
description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
allOf:
- $ref: '#/components/schemas/links'
_embedded:
description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
type: object
_profile:
description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
type: string
format: uri
cardId:
description: 'The `_id` property of a card if requesting card replacement. For a new card, pass the `apiture:account` link instead.'
type: string
type: object
x-apiture-flattened: true
cardShippingEstimate:
title: Card Shipping Estimate (v1.0.0)
description: >
The estimated shipping costs for a new or replacement card.
Links
Response and request bodies using this cardShippingEstimate
schema may contain
the following links:
Rel | Summary | Method |
apiture:card | Fetch a representation of this
card | GET |
apiture:account |
The account associated with the card | GET |
x-apiture-links:
- rel: 'apiture:card'
operationId: getCard
- rel: 'apiture:account'
title: The account associated with the card
description: The account for which the user is requesting a new card.
verb: get
example:
_profile: 'https://production.api.apiture.com/schemas/cards/cardShippingEstimate/v1.0.0/profile.json'
cardId: 0399abed-fd3d-4830-a88b-30f38b8a365c
normal:
value: '0.00'
currency: USD
expedited:
value: '12.00'
currency: USD
_links:
'apiture:account':
href: /accounts/accounts/c4fff7a4-8654-4085-aeba-a984de81dcc3
'apiture:card':
href: /cards/card/0399abed-fd3d-4830-a88b-30f38b8a365c
x-apiture-version: 1.0.0
x-apiture-composition:
- $ref: '#/components/schemas/abstractResource'
- properties:
- cardId
- normal
- expedited
properties:
_links:
description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
allOf:
- $ref: '#/components/schemas/links'
_embedded:
description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
type: object
_profile:
description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
type: string
format: uri
_error:
description: An object which describes an error. This value is omitted if the operation succeeded without error.
type: object
allOf:
- $ref: '#/components/schemas/error'
cardId:
description: >-
The `_id` property of a card if requesting card replacement. For a new card, this is blank; refer to the the `apiture:account` link
instead.
type: string
readOnly: true
normal:
description: The normal (non-expedited) shipping charges.
allOf:
- $ref: '#/components/schemas/positiveMoney'
expedited:
description: >-
The optional expedited shipping charges. This is omitted from the response if expedited shipping is not allowed for the account's banking
product. (The `card` object of the banking product reveals if expedited shipping is for that product.)
allOf:
- $ref: '#/components/schemas/positiveMoney'
type: object
x-apiture-flattened: true
cardIssuerParameters:
title: Card Issuer Parameters (v1.0.0)
description: >-
Parameters that the client passes to the card issuer user interface component. The example shows possible parameters for the card issuer
Marqueta.
x-apiture-version: 1.0.0
example:
_profile: 'https://api.apiture.com/schemas/cards/cardIssuerParameters/v1.0.0/profile.json'
issuer: marqueta
parameters:
- name: user_token
value: 'cd8775f7f49a/408a|9afa-982a78bd08bd::7466c8c38489/4541|b695/af7ac2ba4537'
- name: onetime_token
value: '130d1a7d_fa0c/453a|86a9_93c411a9df3a::5f1d4ade5c34/40e4|8098/493475dd0c92'
- name: application_id
value: 09CF5D57C6084956866126610758E149
- name: card_token
value: '77639FAF::7E77::4CDF::B096::4B5C5F971691--fc09b0af::a30b::4D34834F682826EE1C44'
x-apiture-composition:
- $ref: '#/components/schemas/abstractResource'
- properties:
- issuer
- parameters
properties:
_links:
description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
allOf:
- $ref: '#/components/schemas/links'
_embedded:
description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
type: object
_profile:
description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
type: string
format: uri
_error:
description: An object which describes an error. This value is omitted if the operation succeeded without error.
type: object
allOf:
- $ref: '#/components/schemas/error'
issuer:
description: The name of the card issuer associated with the parameters.
type: string
parameters:
description: An array of individual card issuer parameters.
type: array
items:
$ref: '#/components/schemas/cardIssuerParameter'
type: object
x-apiture-flattened: true
cardIssuerParameter:
title: Card Issuer Parameter (v1.0.0)
description: A single name/value parameter that the client passes to the card issuer user interface component.
type: object
x-apiture-version: 1.0.0
required:
- name
- value
properties:
name:
description: The parameter name.
type: string
minLength: 4
maxLength: 32
pattern: '^[a-zA-Z][-a-zA-Z0-9_]{3,31}'
value:
description: The parameter value.
type: string
maxLength: 256
example:
name: card_token
value: '77639FAF::7E77::4CDF::B096::4B5C5F971691--fc09b0af::a30b::4D34834F682826EE1C44'
x-apiture-flattened: true
challengeErrorResponse:
title: Challenge Error Response (v1.0.0)
description: >-
When an operation requires an additional identity verification challenge, it returns a 401 Unauthorized response status code and an error
response with a challenge resource embedded in the `_error._embedded.challenge`. This informs the caller that they should verify the challenge
via one or more of its `authenticators`, then retry the operation with the `Apiture-Challenge` header that references the challenge's `_id`.
x-apiture-version: 1.0.0
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/auth/challengeErrorResponse/v1.0.0/model.json'
x-apiture-namespace: auth
x-apiture-composition:
- $ref: '#/components/schemas/errorResponse'
- properties:
- _error
properties:
_links:
description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
allOf:
- $ref: '#/components/schemas/links'
_embedded:
description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
type: object
_profile:
description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
type: string
format: uri
_error:
description: The description of the error.
type: object
allOf:
- $ref: '#/components/schemas/challengeError'
type: object
x-apiture-flattened: true
errorResponse:
x-apiture-version: 2.0.0
title: Error Response (v2.0.0)
description: 'Describes an error response, typically returned on 4xx or 5xx errors from API operations. The `_error` object contains the error details.'
example:
_profile: 'https://api.apiture.com/schemas/common/errorResponse/v2.0.0/profile.json'
_error:
_id: 2eae46e1-575c-4d69-8a8f-0a7b0115a4b3
message: The value for deposit must be greater than 0.
statusCode: 422
type: positiveNumberRequired
attributes:
value: -125.5
remediation: Provide a value which is greater than 0
occurredAt: '2018-01-25T05:50:52.375Z'
_links:
describedby:
href: 'https://api.apiture.com/errors/positiveNumberRequired'
_embedded:
errors: []
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/errorResponse/v2.0.0/model.json'
x-apiture-namespace: common
x-apiture-composition:
- $ref: '#/components/schemas/abstractResource'
properties:
_links:
description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
allOf:
- $ref: '#/components/schemas/links'
_embedded:
description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
type: object
_profile:
description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
type: string
format: uri
_error:
description: An object which describes an error. This value is omitted if the operation succeeded without error.
type: object
allOf:
- $ref: '#/components/schemas/error'
type: object
x-apiture-flattened: true
localizedLabels:
title: Localized Labels (v1.0.0)
description: >-
A map that defines lables for an enumeration or other item in a JSON schema. This is a map which maps enumeration schema names to an
`localizedLabel` object. This schema is deprecated. Use [`labelGroups`](#schema-labelgroups)` instead.
x-apiture-version: 1.0.0
x-apiture-deprecated:
since: 1.0.0
replacement: labelGroups
additionalProperties:
$ref: '#/components/schemas/localizedLabel'
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/localizedLabels/v1.0.0/model.json'
x-apiture-namespace: common
type: object
properties: {}
x-apiture-flattened: true
root:
x-apiture-version: 2.0.0
title: API Root (v2.0.0)
description: 'A HAL response, with hypermedia `_links` for the top-level resources and operations in API.'
example:
id: apiName
name: API name
apiVersion: 1.0.0
_profile: 'https://production.api.apiture.com/schemas/common/root/v2.0.0/profile.json'
_links: {}
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/root/v2.0.0/model.json'
x-apiture-namespace: common
x-apiture-composition:
- $ref: '#/components/schemas/abstractResource'
- properties:
- _id
- name
- apiVersion
properties:
_links:
description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
allOf:
- $ref: '#/components/schemas/links'
_embedded:
description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
type: object
_profile:
description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
type: string
format: uri
_error:
description: An object which describes an error. This value is omitted if the operation succeeded without error.
type: object
allOf:
- $ref: '#/components/schemas/error'
_id:
description: This API's unique ID.
readOnly: true
type: string
name:
type: string
description: This API's name.
apiVersion:
type: string
description: This API's version.
type: object
x-apiture-flattened: true
abstractResource:
x-apiture-version: 2.0.0
title: Abstract Resource (v2.0.0)
description: >-
An abstract schema used to define other schemas for request and response bodies. This is a
[HAL](https://tools.ietf.org/html/draft-kelly-json-hal-08) resource representation. This model contains hypermedia `_links`, and either
optional domain object data with `_profile` and optional `_embedded` objects, or an `_error` object. In responses, if the operation was
successful, this object will not include the `_error`, but if the operation was a 4xx or 5xx error, this object will not include `_embedded`
or any data fields, only `_error` and optionally `_links`.
example:
_profile: '{uri of resource profile.json}'
_links:
self:
href: '{uri of current resource}'
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/abstractResource/v2.0.0/model.json'
x-apiture-namespace: common
x-apiture-composition:
- $ref: '#/components/schemas/abstractRequest'
- properties:
- _error
properties:
_links:
description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
allOf:
- $ref: '#/components/schemas/links'
_embedded:
description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
type: object
_profile:
description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
type: string
format: uri
_error:
description: An object which describes an error. This value is omitted if the operation succeeded without error.
type: object
allOf:
- $ref: '#/components/schemas/error'
type: object
x-apiture-flattened: true
accountNumbers:
title: Account Numbers (v1.0.0)
description: Different representations of an account number.
properties:
masked:
description: >-
A partial account number that does not contain all the digits of the full account number. This masked number appears in statements or in
user experience presentation. It is sufficient for a user to differentiate this account from other accounts they hold, but is not
sufficient for initiating transfers, etc. The first character is the mask character and is repeated; this does not indicate that the full
account number is the same as the mask length. This value is derived and immutable.
type: string
minLength: 8
maxLength: 32
readOnly: true
example: '*************3210'
full:
description: >-
The full account number. This value only appears when `?unmasked=true` is passed on the `GET` request. Not included in the summary
representation of the account that is included in account collection responses. This value is derived and immutable.
type: string
minLength: 4
maxLength: 17
example: '9876543210'
readOnly: true
x-apiture-version: 1.0.0
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/accountNumbers/v1.0.0/model.json'
x-apiture-namespace: common
type: object
x-apiture-flattened: true
collection:
x-apiture-version: 2.0.0
title: Collection (v2.0.0)
description: A collection of resources. This is an abstract model schema which is extended to define specific resource collections.
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/collection/v2.0.0/model.json'
x-apiture-namespace: common
x-apiture-composition:
- $ref: '#/components/schemas/abstractResource'
- properties:
- count
- start
- limit
- name
properties:
_links:
description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
allOf:
- $ref: '#/components/schemas/links'
_embedded:
description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
type: object
_profile:
description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
type: string
format: uri
_error:
description: An object which describes an error. This value is omitted if the operation succeeded without error.
type: object
allOf:
- $ref: '#/components/schemas/error'
count:
description: >-
The number of items in the collection. This value is _optional_ and may be omitted if the count is not computable efficiently. If a filter
is applied to the collection (either implicitly or explicitly), the count, if present, indicates the number of items that satisfy the
filter.
type: integer
start:
description: The start index of this page of items.
type: integer
limit:
description: The maximum number of items per page.
type: integer
name:
description: The name of the collection.
type: string
type: object
x-apiture-flattened: true
abstractRequest:
x-apiture-version: 2.0.0
title: Abstract Request (v2.0.0)
description: >-
An abstract schema used to define other request-only schemas. This is a [HAL](https://tools.ietf.org/html/draft-kelly-json-hal-08) resource
representation, minus the `_error` defined in `abstractResource`.
properties:
_links:
description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
allOf:
- $ref: '#/components/schemas/links'
_embedded:
description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
type: object
_profile:
description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
type: string
format: uri
example:
_profile: '{uri of resource profile.json}'
_links:
self:
href: '{uri of current resource}'
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/abstractRequest/v2.0.0/model.json'
x-apiture-namespace: common
type: object
x-apiture-flattened: true
positiveMoney:
title: Positive Money (v1.0.0)
description: 'An amount of money in a specific currency, supporting only positive amounts.'
properties:
value:
description: >-
The monetary value, supporting only positive amounts. The numeric value is represented as a string so that it can be exact with no loss
of precision.
example: '3456.78'
type: string
currency:
description: 'The [ISO 4217 currency code](https://en.wikipedia.org/wiki/ISO_4217) for this monetary value. This is always upper case ASCII.'
x-apiture-todo: 'ISO 4217 defines three-character codes. However, ISO 4217 does not account for cryptocurrencies. Of note, `DASH` uses 4 characters.'
type: string
minLength: 3
maxLength: 3
x-apiture-version: 1.0.0
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/transfers/positiveMoney/v1.0.0/model.json'
x-apiture-namespace: transfers
type: object
x-apiture-flattened: true
links:
title: Links (v1.0.0)
x-apiture-version: 1.0.0
description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
type: object
x-apiture-key: linkRelationName
additionalProperties:
$ref: '#/components/schemas/link'
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/links/v1.0.0/model.json'
x-apiture-namespace: common
properties: {}
x-apiture-flattened: true
error:
x-apiture-version: 2.0.0
title: Error (v2.0.0)
description: Describes an error in an API request or in a service called via the API.
required:
- message
properties:
message:
type: string
description: A localized message string describing the error condition.
_id:
description: >-
A unique identifier for this error instance. This may be used as a correlation ID with the root cause error (i.e. this ID may be logged at
the source of the error). This is is an opaque string.
readOnly: true
type: string
statusCode:
description: The HTTP status code associate with this error.
type: integer
minimum: 100
maximum: 599
example: 422
type:
type: string
description: >-
An error identifier which indicates the category of error and associate it with API support documentation or which the UI tier can use to
render an appropriate message or hint. This provides a finer level of granularity than the `statusCode`. For example, instead of just 400
Bad Request, the `type` may be much more specific. such as `integerValueNotInAllowedRange` or `numericValueExceedsMaximum` or
`stringValueNotInAllowedSet`.
occurredAt:
type: string
format: date-time
description: 'An [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC time stamp indicating when the error occurred.'
example: '2018-02-02T03:37:15.375Z'
attributes:
description: >-
Informative values or constraints which describe the error. For example, for a value out of range error, the attributes may specify the
`minimum` and `maximum` values. This allows clients to present error messages as they see fit (the API does not assume the
client/presentation tier). The set of attributes varies by error `type`.
allOf:
- $ref: '#/components/schemas/attributes'
remediation:
type: string
description: An optional localized string which provides hints for how the user or client can resolve the error.
errors:
description: An optional array of nested error objects. This property is not always present.
type: array
items:
$ref: '#/components/schemas/error'
_links:
$ref: '#/components/schemas/links'
example:
_id: 2eae46e1575c0a7b0115a4b3
message: Descriptive error message...
statusCode: 422
type: errorType1
remediation: Remediation string...
occurredAt: '2018-01-25T05:50:52.375Z'
errors:
- _id: ccdbe2c5c938a230667b3827
message: An optional embedded error
- _id: dbe9088dcfe2460f229338a3
message: Another optional embedded error
_links:
describedby:
href: 'https://developer.apiture.com/errors/errorType1'
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/error/v2.0.0/model.json'
x-apiture-namespace: common
type: object
x-apiture-flattened: true
localizedLabel:
title: Localized Label (v1.0.0)
description: >-
A localized label and optional description for localizable content defined in this API. This schema is deprecated; use
[`labelItem`](#schema-labelitem) instead.
x-apiture-version: 1.0.0
x-apiture-deprecated:
since: 1.0.0
replacement: labelGroups
type: object
properties:
label:
type: string
description: A localized label or title which may be used labels or other UI controls which present a value.
example: Limited Liability Corporation
description:
type: string
description: A more detailed localized description of a localizable label.
language:
type: string
description: >-
The actual natural language tag to which this localized label is associated, as per [RFC
7231](https://tools.ietf.org/html/rfc7231#section-3.1.3.1)
example: en-us
code:
type: string
description: 'If the localized value is associated with an external standard, this is a lookup code or key or URI for that value.'
example: '31'
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/localizedLabel/v1.0.0/model.json'
x-apiture-namespace: common
x-apiture-flattened: true
link:
x-apiture-version: 1.0.0
title: Link (v1.0.0)
description: >-
Describes a hypermedia link within a `_links` object in HAL representations. In Apiture APIs, links are [HAL
links](https://developer.apiture.com/docs/concepts/links), but Apiture APIs do not use the `name` or `hreflang` properties of HAL. Apiture
links _may_ include a `method` property.
required:
- href
properties:
href:
type: string
format: uri
description: The URI or URI template for the resource/operation this link refers to.
type:
type: string
description: The media type for the resource.
templated:
type: boolean
description: 'If true, the link''s href is a [URI template](https://tools.ietf.org/html/rfc6570).'
title:
type: string
description: An optional human-readable localized title for the link.
deprecation:
type: string
format: uri
description: 'If present, the containing link is deprecated and the value is a URI which provides human-readable text information about the deprecation.'
profile:
type: string
format: uri
description: 'The URI of a profile document, a JSON document which describes the target resource/operation.'
example:
href: /contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f
title: Applicant
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/link/v1.0.0/model.json'
x-apiture-namespace: common
type: object
x-apiture-flattened: true
attributes:
x-apiture-version: 2.0.0
title: Attributes (v2.0.0)
description: An optional map of name/value pairs which contains additional dynamic data about the resource.
type: object
x-apiture-key: attributeName
additionalProperties:
$ref: '#/components/schemas/attributeValue'
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/attributes/v2.0.0/model.json'
x-apiture-namespace: common
properties: {}
x-apiture-flattened: true
challengeError:
title: Challenge Error (v1.0.0)
description: The operation error description with an embedded identity challenge.
type: object
x-apiture-version: 1.0.0
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/auth/challengeError/v1.0.0/model.json'
x-apiture-namespace: auth
x-apiture-composition:
- $ref: '#/components/schemas/error'
- properties:
- _embedded
properties:
message:
type: string
description: A localized message string describing the error condition.
_id:
description: >-
A unique identifier for this error instance. This may be used as a correlation ID with the root cause error (i.e. this ID may be logged at
the source of the error). This is is an opaque string.
readOnly: true
type: string
statusCode:
description: The HTTP status code associate with this error.
type: integer
minimum: 100
maximum: 599
example: 422
type:
type: string
description: >-
An error identifier which indicates the category of error and associate it with API support documentation or which the UI tier can use to
render an appropriate message or hint. This provides a finer level of granularity than the `statusCode`. For example, instead of just 400
Bad Request, the `type` may be much more specific. such as `integerValueNotInAllowedRange` or `numericValueExceedsMaximum` or
`stringValueNotInAllowedSet`.
occurredAt:
type: string
format: date-time
description: 'An [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC time stamp indicating when the error occurred.'
example: '2018-02-02T03:37:15.375Z'
attributes:
description: >-
Informative values or constraints which describe the error. For example, for a value out of range error, the attributes may specify the
`minimum` and `maximum` values. This allows clients to present error messages as they see fit (the API does not assume the
client/presentation tier). The set of attributes varies by error `type`.
allOf:
- $ref: '#/components/schemas/attributes'
remediation:
type: string
description: An optional localized string which provides hints for how the user or client can resolve the error.
errors:
description: An optional array of nested error objects. This property is not always present.
type: array
items:
$ref: '#/components/schemas/error'
_links:
$ref: '#/components/schemas/links'
_embedded:
description: Embedded objects
type: object
properties:
challenge:
description: The details of the identity verification challenge.
allOf:
- $ref: '#/components/schemas/challenge'
x-apiture-flattened: true
attributeValue:
x-apiture-version: 2.0.0
title: Attribute Value (v2.0.0)
description: The data associated with this attribute.
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/attributeValue/v2.0.0/model.json'
x-apiture-namespace: common
type: object
properties: {}
x-apiture-flattened: true
challenge:
title: Challenge (v1.0.1)
description: >
A resource which represents an identity verification challenge to a user. The user must verify one or more of the authentication methods
defined in this challenge in order to proceed with a banking operation (such as scheduling a larger than normal transfer, adding a joint owner
or authorized signer to an account, or changing their mailing address or mobile phone number).
Links
Response and request bodies using this challenge
schema may contain
the following links:
x-apiture-version: 1.0.1
example:
_id: 0399abed-fd3d-4830-a88b-30f38b8a365c
_profile: 'https://api.apiture.com/schemas/auth/challenge/v1.0.1/profile.json'
reason: Transfer amount much higher than normal
contextUri: 'https://fi.apiture.com/transfers/scheduledTransfers/50b9df19-d6bf-4ac0-b5f4-3e6448b7dacd'
minimumAuthenticatorCount: 1
authenticators:
- _id: 7fadd35b-6f6b-4901-b1ba-d3b91c9dcee3
_profile: 'https://api.apiture.com/schemas/auth/authenticator/v1.0.1/profile.json'
userId: b2720469-3497-4b82-8b85-30f2155aa66d
state: started
type:
name: sms
label: SMS Code
description: Enter a code sent via SMS to the user's preferred mobile device.
category: device
schema:
title: SMS attributes
description: Schema for an authenticator's `attributes` when the authenticator type is `sms`.
type: object
required:
- code
- length
properties:
code:
type: string
description: >-
A code that was sent to the user's mobile device via SMS. The user should enter the code in the app, then set `attributes.code`
to that. The length of the code (the number of characters or digits) must equal the `length'.
minLength: 3
maxLength: 10
length:
description: The number of digits/characters that are sent to the user via SMS.
type: integer
minimum: 3
maximum: 10
example: 6
maximumRetries: 3
retryCount: 1
createdAt: '2019-08-23T12:42:50.375Z'
expiresAt: '2019-08-23T13:12:50.375Z'
_links:
self:
href: /auth/challenges/0399abed-fd3d-4830-a88b-30f38b8a365c/authenticators/7fadd35b-6f6b-4901-b1ba-d3b91c9dcee3
'apiture:challenge':
href: /auth/challenges/0399abed-fd3d-4830-a88b-30f38b8a365c
'apiture:retry':
href: /auth/challenges/retriedAuthenticators?authenticator=7fadd35b-6f6b-4901-b1ba-d3b91c9dcee3
'apiture:verify':
href: /auth/challenges/verifiedAuthenticators
maximumRedemptionCount: 1
redemptionCount: 0
state: pending
createdAt: '2019-08-23T11:37:55.375Z'
expiresAt: '2019-08-23T12:37:55.375Z'
_links:
self:
href: /auth/challenges/5d63053d-435c-4455-a0b5-6f88ab729d1a
'apiture:redeem':
href: /auth/redeemedChallenges?challenge=5d63053d-435c-4455-a0b5-6f88ab729d1a
x-apiture-links:
- rel: 'apiture:redeem'
operationId: redeemChallenge
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/auth/challenge/v1.0.1/model.json'
x-apiture-namespace: auth
x-apiture-composition:
- $ref: '#/components/schemas/summaryChallenge'
- properties:
- _id
- authenticators
- redeemable
- verifiedAt
- failedAt
- expiresAt
- redemptionHistory
- code
properties:
_links:
description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
allOf:
- $ref: '#/components/schemas/links'
_embedded:
description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
type: object
_profile:
description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
type: string
format: uri
_error:
description: An object which describes an error. This value is omitted if the operation succeeded without error.
type: object
allOf:
- $ref: '#/components/schemas/error'
reason:
description: >-
The reason the application or service has issued a challenge requesting the user verify their identity. This is for labeling or
informational purposes.
type: string
x-apiture-todo:
- Should this be a reasonCode (non-localizable identifier and reason label?
contextUri:
description: >-
The URI of a resource that establishes the context in which the user is asked to authenticate their identity. For example, for this may be
for a pending transfer, a user's mailing address, or an account if adding a joint owner.
type: string
format: uri
maxLength: 2048
userId:
description: >-
The user ID of the user who is requested to verify their identity. The default is the userID of the authenticated person creating the
challenge.
type: string
minimumAuthenticatorCount:
description: The minimum number of different authenticators the user must verify in order to satisfy the identity challenge. The default is 1.
type: integer
minimum: 0
maximum: 4
maximumRedemptionCount:
description: The maximum number of times the challenge may be used or redeemed. The default is 1.
type: integer
minimum: 1
_id:
description: The unique identifier for this challenge resource. This is an immutable opaque string assigned upon creation.
readOnly: true
type: string
redemptionCount:
description: How many times the challenge has been redeemed.
type: integer
readOnly: true
state:
description: The state of this authenticator.
allOf:
- $ref: '#/components/schemas/challengeState'
readOnly: true
createdAt:
description: >-
The time stamp when challenge was created, in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC date-time format
(`YYYY-MM-DDThh:mm:ss.sssZ`).
type: string
format: date-time
readOnly: true
authenticators:
description: >-
An array of authenticators with which the user can verify their identity. This is derived; the array and the authenticators are
constructed in the `createChallenge` operation.
type: array
items:
$ref: '#/components/schemas/authenticator'
readOnly: true
redeemable:
description: >-
`true` if and only if the challenge may be redeemed. This is derived from the states of the challenge's authenticators; if the number of
`verified` authenticators meets or exceeds the `minimumAuthenticatorCount`, the challenge becomes `verified` and may be redeemed via a
`POST` to href in the challenge's `apiture:redeem` link.
type: boolean
readOnly: true
verifiedAt:
description: >-
The time stamp when challenge was verified in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC date-time format
(`YYYY-MM-DDThh:mm:ss.sssZ`).
type: string
format: date-time
readOnly: true
failedAt:
description: >-
The time stamp when the user failed to verify their identity verification (authentication) for this challenge, in [RFC
3339](https://tools.ietf.org/html/rfc3339) UTC date-time format (`YYYY-MM-DDThh:mm:ss.sssZ`).
type: string
format: date-time
readOnly: true
expiresAt:
description: >-
The time stamp when the this challenge expires, in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC date-time format
(`YYYY-MM-DDThh:mm:ss.sssZ`).
type: string
format: date-time
readOnly: true
redemptionHistory:
description: >-
The time stamps when a service or operation redeemed this challenge, in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC date-time
format (`YYYY-MM-DDThh:mm:ss.sssZ`). Item 0 is the time stamp the challenge was first redeemed, item 1 is the time stamp of the next
redemption, and so on.
readOnly: true
type: array
items:
type: string
format: date-time
readOnly: true
code:
description: >-
An optional authentication code which is only returned in the challenge resource if both a) the platform assigned the `code` when
[constructing the challenge](#op-createChallenge)), _and_ b) the user has successfully verified the challenge. The client must [re-fetch
the verified challenge](#op-getChallenge) in order to access this property.
type: string
minLength: 16
maxLength: 128
readOnly: true
type: object
x-apiture-flattened: true
summaryChallenge:
title: Summary Challenge (v1.0.0)
description: 'Summary representation of a challenge, used in the challenge collection.'
x-apiture-version: 1.0.0
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/auth/summaryChallenge/v1.0.0/model.json'
x-apiture-namespace: auth
x-apiture-composition:
- $ref: '#/components/schemas/abstractResource'
- $ref: '#/components/schemas/challengeFields'
- properties:
- _id
- redemptionCount
- state
- createdAt
properties:
_links:
description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
allOf:
- $ref: '#/components/schemas/links'
_embedded:
description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
type: object
_profile:
description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
type: string
format: uri
_error:
description: An object which describes an error. This value is omitted if the operation succeeded without error.
type: object
allOf:
- $ref: '#/components/schemas/error'
reason:
description: >-
The reason the application or service has issued a challenge requesting the user verify their identity. This is for labeling or
informational purposes.
type: string
x-apiture-todo:
- Should this be a reasonCode (non-localizable identifier and reason label?
contextUri:
description: >-
The URI of a resource that establishes the context in which the user is asked to authenticate their identity. For example, for this may be
for a pending transfer, a user's mailing address, or an account if adding a joint owner.
type: string
format: uri
maxLength: 2048
userId:
description: >-
The user ID of the user who is requested to verify their identity. The default is the userID of the authenticated person creating the
challenge.
type: string
minimumAuthenticatorCount:
description: The minimum number of different authenticators the user must verify in order to satisfy the identity challenge. The default is 1.
type: integer
minimum: 0
maximum: 4
maximumRedemptionCount:
description: The maximum number of times the challenge may be used or redeemed. The default is 1.
type: integer
minimum: 1
_id:
description: The unique identifier for this challenge resource. This is an immutable opaque string assigned upon creation.
readOnly: true
type: string
redemptionCount:
description: How many times the challenge has been redeemed.
type: integer
readOnly: true
state:
description: The state of this authenticator.
allOf:
- $ref: '#/components/schemas/challengeState'
readOnly: true
createdAt:
description: >-
The time stamp when challenge was created, in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC date-time format
(`YYYY-MM-DDThh:mm:ss.sssZ`).
type: string
format: date-time
readOnly: true
type: object
x-apiture-flattened: true
authenticator:
title: Authenticator (v1.0.1)
x-apiture-version: 1.0.1
description: >
Representation of authenticators which verify a user's identity.
Links
Response and request bodies using this authenticator
schema may contain
the following links:
example:
_id: 7fadd35b-6f6b-4901-b1ba-d3b91c9dcee3
_profile: 'https://api.apiture.com/schemas/auth/authenticator/v1.0.1/profile.json'
userId: b2720469-3497-4b82-8b85-30f2155aa66d
state: started
type:
name: sms
label: SMS Code
description: Enter a code sent via SMS to the user's preferred mobile device.
category: device
schema:
title: SMS attributes
description: Schema for an authenticator's `attributes` when the authenticator type is `sms`.
type: object
required:
- code
- length
properties:
code:
type: string
description: >-
A code that was sent to the user's mobile device via SMS. The user should enter the code in the app, then set `attributes.code` to
that. The length of the code (the number of characters or digits) must equal the `length'.
minLength: 3
maxLength: 10
length:
description: The number of digits/characters that are sent to the user via SMS.
type: integer
minimum: 3
maximum: 10
example: 6
maximumRetries: 3
retryCount: 1
createdAt: '2019-08-23T12:42:50.375Z'
expiresAt: '2019-08-23T13:12:50.375Z'
_links:
self:
href: /auth/challenges/2e61e506-1568-4f1a-a93e-4d0a48a06d0e/authenticators/7fadd35b-6f6b-4901-b1ba-d3b91c9dcee3
'apiture:challenge':
href: /auth/challenges/challenges/b59438cd-5efb-4915-916b-0600bb2a4e1e
'apiture:retry':
href: /auth/challenges/retriedAuthenticators?authenticator=7fadd35b-6f6b-4901-b1ba-d3b91c9dcee3
'apiture:verify':
href: /auth/challenges/verifiedAuthenticators
x-apiture-links:
- rel: 'apiture:retry'
operationId: retryAuthenticator
- rel: 'apiture:start'
operationId: startAuthenticator
- rel: 'apiture:verify'
operationId: verifyAuthenticator
- rel: 'apiture:challenge'
operationId: getChallenge
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/auth/authenticator/v1.0.1/model.json'
x-apiture-namespace: auth
x-apiture-composition:
- $ref: '#/components/schemas/abstractResource'
- $ref: '#/components/schemas/authenticatorFields'
- properties:
- _id
- userId
- state
- retryCount
- attributes
- createdAt
- verifiedAt
- failedAt
- expiresAt
properties:
_links:
description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
allOf:
- $ref: '#/components/schemas/links'
_embedded:
description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
type: object
_profile:
description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
type: string
format: uri
_error:
description: An object which describes an error. This value is omitted if the operation succeeded without error.
type: object
allOf:
- $ref: '#/components/schemas/error'
type:
description: The type of this authenticator. This must be one of the items in the `/authenticatorTypes` resource.
allOf:
- $ref: '#/components/schemas/authenticatorType'
maximumRetries:
description: >-
The maximum number of times the user may retry this authenticator. If `0`, the user must authenticate correctly on the first try. When an
authenticator is retried, the client should `POST` to the `apiture:retry` link on the authenticators; absence of the link means the user
cannot retry the authenticator. The default is `3`.
type: integer
minimum: 0
maximum: 10
_id:
description: The unique identifier for this authenticator resource. This is an immutable opaque string assigned upon creation.
readOnly: true
type: string
userId:
description: The user ID of the user who is requested to verify their identity.
type: string
state:
description: The state of this authenticator. This is derived and read-only.
allOf:
- $ref: '#/components/schemas/authenticatorState'
readOnly: true
retryCount:
description: The actual number of times a user has retried this authenticator.
type: integer
minimum: 0
maximum: 10
readOnly: true
attributes:
description: >-
Data collected from the user that is used to verify this authenticator. This data conforms to the schema defined in the `type`. For
example, for `sms`, the `attributes` must contains a `code`.
type: object
createdAt:
description: >-
The time stamp when authenticator was created, in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC date-time format
(`YYYY-MM-DDThh:mm:ss.sssZ`).
type: string
format: date-time
readOnly: true
verifiedAt:
description: >-
The time stamp when authenticator was verified in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC date-time format
(`YYYY-MM-DDThh:mm:ss.sssZ`).
type: string
format: date-time
readOnly: true
failedAt:
description: >-
The time stamp when the user failed to verify their identity verification (authentication) for this challenge, in [RFC
3339](https://tools.ietf.org/html/rfc3339) UTC date-time format (`YYYY-MM-DDThh:mm:ss.sssZ`).
type: string
format: date-time
readOnly: true
expiresAt:
description: >-
The time stamp when the this challenge expires, in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC date-time format
(`YYYY-MM-DDThh:mm:ss.sssZ`).
type: string
format: date-time
readOnly: true
type: object
x-apiture-flattened: true
challengeFields:
title: Challenge Fields (v1.0.0)
description: Properties of challenge objects.
x-apiture-fragment: true
properties:
reason:
description: >-
The reason the application or service has issued a challenge requesting the user verify their identity. This is for labeling or
informational purposes.
type: string
x-apiture-todo:
- Should this be a reasonCode (non-localizable identifier and reason label?
contextUri:
description: >-
The URI of a resource that establishes the context in which the user is asked to authenticate their identity. For example, for this may be
for a pending transfer, a user's mailing address, or an account if adding a joint owner.
type: string
format: uri
maxLength: 2048
userId:
description: >-
The user ID of the user who is requested to verify their identity. The default is the userID of the authenticated person creating the
challenge.
type: string
minimumAuthenticatorCount:
description: The minimum number of different authenticators the user must verify in order to satisfy the identity challenge. The default is 1.
type: integer
minimum: 0
maximum: 4
maximumRedemptionCount:
description: The maximum number of times the challenge may be used or redeemed. The default is 1.
type: integer
minimum: 1
x-apiture-version: 1.0.0
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/auth/challengeFields/v1.0.0/model.json'
x-apiture-namespace: auth
type: object
x-apiture-flattened: true
challengeState:
title: Challenge States (v1.0.0)
description: |+
The state of an identity challenge resource. This is derived based on the state of the challenge's authenticators.
challengeState
strings may have one of the following
[enumerated values](https://developer.apiture.com/concepts/label-groups#enumerations):
Value | Description |
pending | Pending: The challenge is created but not yet started. |
started | Started: The user has started the challenge and associated authenticator(s). |
verified | Verified: The user correctly verified the corresponding authenticator(s), marking the challenge as verified. |
failed | Failed: The challenge has failed, often because the user failed one or more of the authenticators. |
redeemed | Redeemed: The user has redeemed (used) the challenge. |
expired | Expired: The challenge has expired without being verified. |
x-apiture-enum: challengeState
type: string
enum:
- pending
- started
- verified
- failed
- redeemed
- expired
x-apiture-version: 1.0.0
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/auth/challengeState/v1.0.0/model.json'
x-apiture-namespace: auth
x-apiture-flattened: true
authenticatorFields:
title: Authenticator Fields (v1.0.0)
description: Common fields of an authenticator.
x-apiture-fragment: true
properties:
type:
description: The type of this authenticator. This must be one of the items in the `/authenticatorTypes` resource.
allOf:
- $ref: '#/components/schemas/authenticatorType'
maximumRetries:
description: >-
The maximum number of times the user may retry this authenticator. If `0`, the user must authenticate correctly on the first try. When an
authenticator is retried, the client should `POST` to the `apiture:retry` link on the authenticators; absence of the link means the user
cannot retry the authenticator. The default is `3`.
type: integer
minimum: 0
maximum: 10
x-apiture-version: 1.0.0
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/auth/authenticatorFields/v1.0.0/model.json'
x-apiture-namespace: auth
type: object
x-apiture-flattened: true
authenticatorState:
title: Authenticator State (v1.0.0)
description: |+
The state of a challenge authenticator resource.
* The `startAuthenticator` operation (link `apiture:start`) changes the state
from `pending` to `started`.
* The `retryAuthenticator` operation (link `apiture:retry`) changes the state
to `started` and is only allowed if the authenticator has more retries available.
* The `verifyAuthenticator` operation (link `apiture:verify`) validates
the `attributes` and changes the state
to `verified` if valid or
to `failed` if invalid.
authenticatorState
strings may have one of the following
[enumerated values](https://developer.apiture.com/concepts/label-groups#enumerations):
Value | Description |
pending | Pending: The authenticator is created but not yet started. |
started | Started: The user has started the authenticator. |
verified | Verified: The user corresponding verified the authenticator. |
failed | Failed: The user failed the authenticators criteria. |
expired | Expired: The authenticator expired before the user completed the criteria. |
x-apiture-enum: authenticatorState
type: string
enum:
- pending
- started
- verified
- failed
- expired
x-apiture-version: 1.0.0
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/auth/authenticatorState/v1.0.0/model.json'
x-apiture-namespace: auth
x-apiture-flattened: true
authenticatorType:
title: Authenticator Type (v1.0.0)
description: An authenticator type description.
properties:
name:
type: string
description: The name of this authenticator; also the key in the `authenticatorTypes` object.
example: sms
label:
type: string
description: A localized label or title which may be used labels or other UI controls which present a value.
example: SMS code
description:
type: string
description: A more detailed localized description of an authenticator type.
language:
type: string
description: >-
The actual natural language tag to which this authentication type description is associated, as per [RFC
7231](https://tools.ietf.org/html/rfc7231#section-3.1.3.1). If omitted, this serves as the _default_.
example: en-us
category:
type: string
description: The authentication category.
allOf:
- $ref: '#/components/schemas/authenticatorCategory'
schema:
type: object
description: >-
The JSON schema which describe the `attributes` object for all authenticators of this type. For example, for `sms`, the schema defines a
required `code` string.
example:
name: sms
label: SMS code
description: Enter a code sent via SMS to the user's preferred mobile device.
category: device
schema:
title: SMS attributes
description: Schema for an authenticator's `attributes` when the authenticator type is `sms`.
type: object
required:
- code
- length
properties:
code:
type: string
description: >-
A code that was sent to the user's mobile device via SMS. The user should enter the code in the app, then set `attributes.code` to
that. The length of the code (the number of characters or digits) must equal the `length'.
minLength: 3
maxLength: 10
length:
description: The number of digits/characters that are sent to the user via SMS.
type: integer
minimum: 3
maximum: 10
example: 6
x-apiture-version: 1.0.0
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/auth/authenticatorType/v1.0.0/model.json'
x-apiture-namespace: auth
type: object
x-apiture-flattened: true
authenticatorCategory:
title: authenticatorCategory (v1.0.0)
description: |+
Categories which help classify and organize different authenticator types:
* `knowledge` - Something you know, such as a password or
answers to personal questions.
* `biometric` - Something you are, such as
facial recognition or fingerprints.
* `device` - Something you have, such as a mobile phone
(for confirmation via a code sent via text message) or an electronic key.
authenticatorCategory
strings may have one of the following
[enumerated values](https://developer.apiture.com/concepts/label-groups#enumerations):
Value | Description |
knowledge | Knowledge: Authenticate with information the user knows, such as a password or answers to personal questions. |
biometric | Biometric: Authenticate with physical characteristics of the user, such as fingerprints, voiceprint, or faceprint. |
device | Device: Authenticate with a device that the user has, such as a mobile phone or an electronic key. |
x-apiture-enum: authenticatorCategory
type: string
enum:
- knowledge
- biometric
- device
x-apiture-version: 1.0.0
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/auth/authenticatorCategory/v1.0.0/model.json'
x-apiture-namespace: auth
x-apiture-flattened: true
responses:
'304':
description: Not Modified. The resource has not been modified since it was last fetched.
'400':
description: >-
Bad Request. The request body or one or more of the query parameters was not well formed. The `_error` field in the response will contain
details about the request error.
content:
application/hal+json:
schema:
$ref: '#/components/schemas/errorResponse'
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
'412':
description: >-
Precondition Failed. The supplied `if-Match` header value does not match the most recent `ETag` response header value. The resource has
changed in the interim.
content:
application/hal+json:
schema:
$ref: '#/components/schemas/errorResponse'
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
'422':
description: >-
Unprocessable Entity. One or more of the query parameters was well formed but otherwise invalid. The `_error` field in the response will
contain details about the request error.
content:
application/hal+json:
schema:
$ref: '#/components/schemas/errorResponse'
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
422CardShippingEstimate:
description: >-
Unprocessable Entity. One or more of the query parameters was well formed but otherwise invalid. The `_error` field in the response will
contain details about the request error.
This error response may have one of the following `type` values:
* [`cardRefNotFound`](#err-cardRefNotFound)
* [`invalidAccountLink`](#err-invalidAccountLink)
x-apiture-errors:
- cardRefNotFound
- invalidAccountLink
content:
application/hal+json:
schema:
$ref: '#/components/schemas/errorResponse'
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
400CompleteCardRequest:
description: |-
Bad Request. The cardRequest parameter was malformed or does not refer to an existing or accessible card request.
This error response may have one of the following `type` values:
* [`cardRequestRefNotFound`](#err-cardRequestRefNotFound)
x-apiture-errors:
- cardRequestRefNotFound
content:
application/hal+json:
schema:
$ref: '#/components/schemas/errorResponse'
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
409CompleteCardRequestConflict:
description: >-
Conflict. The request to complete the card request is not allowed. The `_error` field in the response will contain details about the request
error.
content:
application/hal+json:
schema:
$ref: '#/components/schemas/errorResponse'
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
400RejectCardRequest:
description: |-
Bad Request. The cardRequest parameter was malformed or does not refer to an existing or accessible card request.
This error response may have one of the following `type` values:
* [`cardRequestRefNotFound`](#err-cardRequestRefNotFound)
x-apiture-errors:
- cardRequestRefNotFound
content:
application/hal+json:
schema:
$ref: '#/components/schemas/errorResponse'
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
409RejectCardRequestConflict:
description: >-
Conflict. The request to reject the card request is not allowed. The `_error` field in the response will contain details about the request
error.
content:
application/hal+json:
schema:
$ref: '#/components/schemas/errorResponse'
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
400CancelCardRequest:
description: |-
Bad Request. The cardRequest parameter was malformed or does not refer to an existing or accessible card request.
This error response may have one of the following `type` values:
* [`cardRequestRefNotFound`](#err-cardRequestRefNotFound)
x-apiture-errors:
- cardRequestRefNotFound
content:
application/hal+json:
schema:
$ref: '#/components/schemas/errorResponse'
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
409CancelCardRequestConflict:
description: >-
Conflict. The request to cancel the card request is not allowed. The `_error` field in the response will contain details about the request
error.
content:
application/hal+json:
schema:
$ref: '#/components/schemas/errorResponse'
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
400UnlockCard:
description: |-
Bad Request. The card parameter was malformed or does not refer to an existing or accessible card.
This error response may have one of the following `type` values:
* [`cardRefNotFound`](#err-cardRefNotFound)
x-apiture-errors:
- cardRefNotFound
content:
application/hal+json:
schema:
$ref: '#/components/schemas/errorResponse'
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
409UnlockCardConflict:
description: Conflict. The request to unlock the card is not allowed. The `_error` field in the response will contain details about the request error.
content:
application/hal+json:
schema:
$ref: '#/components/schemas/errorResponse'
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
400CloseCard:
description: |-
Bad Request. The card parameter was malformed or does not refer to an existing or accessible card.
This error response may have one of the following `type` values:
* [`cardRefNotFound`](#err-cardRefNotFound)
x-apiture-errors:
- cardRefNotFound
content:
application/hal+json:
schema:
$ref: '#/components/schemas/errorResponse'
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
409CloseCardConflict:
description: Conflict. The request to close the card is not allowed. The `_error` field in the response will contain details about the request error.
content:
application/hal+json:
schema:
$ref: '#/components/schemas/errorResponse'
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
400LockCard:
description: |-
Bad Request. The card parameter was malformed or does not refer to an existing or accessible card.
This error response may have one of the following `type` values:
* [`cardRefNotFound`](#err-cardRefNotFound)
x-apiture-errors:
- cardRefNotFound
content:
application/hal+json:
schema:
$ref: '#/components/schemas/errorResponse'
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
409LockCardConflict:
description: Conflict. The request to lock the card is not allowed. The `_error` field in the response will contain details about the request error.
content:
application/hal+json:
schema:
$ref: '#/components/schemas/errorResponse'
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
400ActivateCard:
description: |-
Bad Request. The card parameter was malformed or does not refer to an existing or accessible card.
This error response may have one of the following `type` values:
* [`cardRefNotFound`](#err-cardRefNotFound)
x-apiture-errors:
- cardRefNotFound
content:
application/hal+json:
schema:
$ref: '#/components/schemas/errorResponse'
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
409ActivateCardConflict:
description: Conflict. The request to activate the card is not allowed. The `_error` field in the response will contain details about the request error.
content:
application/hal+json:
schema:
$ref: '#/components/schemas/errorResponse'
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
404CardRequest:
description: >-
Not Found. There is no such card card request resource at the specified `{cardRequestId}`. The `_error` field in the response will contain
details about the request error.
content:
application/hal+json:
schema:
$ref: '#/components/schemas/errorResponse'
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
404Card:
description: >-
Not Found. There is no such card resource at the specified `{cardId}`. The `_error` field in the response will contain details about the
request error.
content:
application/hal+json:
schema:
$ref: '#/components/schemas/errorResponse'
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
204Deleted:
description: No Content. The resource was deleted successfully.
parameters:
apitureChallengeHeaderParam:
name: Apiture-Challenge
description: >-
The unique identifier of a Challenge resource which demonstrates the user has recently verified their identity. See the discussion of
_Multi-factor authentication challenges_ above. The value must be the `_id` string of a valid, redeemable Challenge resource which matches the
challenge context.
in: header
required: false
schema:
type: string
cardRequestQueryParam:
name: cardRequest
required: true
in: query
description: >-
A string which uniquely identifies a card request which is to added to the canceled card requests resource set. This may be the unique
cardRequestId or the URI of the card request.
schema:
type: string
unmaskedQueryParam:
name: unmasked
description: >-
For security reasons, the default response includes only a [_masked_ banking account number](#schema-accountNumbers), for partial
identification purposes. For `?unmasked=true`, the response body includes the _full_ account number for each of the requested cards. Requests
for full account numbers are auditable.
Note that card numbers are _always_ masked.
in: query
required: false
schema:
type: boolean
default: false
cardsQueryParam:
name: card
required: true
in: query
description: 'A string which uniquely identifies a card. This may be the unique `{cardId}` or the URI of the card.'
schema:
type: string
cardRequestIdPathParam:
name: cardRequestId
description: The unique identifier of this card request resource. This is an opaque string.
in: path
required: true
schema:
type: string
filterQueryParam:
name: filter
in: query
description: 'Optional filter criteria. See [filtering](http://developer.apiture.com/docs/concepts/filtering).'
schema:
type: string
qQueryParam:
name: q
in: query
description: 'Optional search string. See [searching](http://developer.apiture.com/docs/concepts/searching).'
schema:
type: string
cardIdPathParam:
name: cardId
description: The unique identifier of this card. This is an opaque string.
in: path
required: true
schema:
type: string
ifMatchHeaderParam:
name: If-Match
description: The entity tag that was returned in the `ETag` response. This must match the current entity tag of the resource.
in: header
required: true
schema:
type: string
ifNoneMatchHeaderParam:
name: If-None-Match
description: >-
The entity tag that was returned in the `ETag` response. If the resource's current entity tag matches, the `GET` will return 304 (Not
Modified) and no response body, else the resource representation will be returned.
in: header
schema:
type: string
typeIdPathParam:
name: typeId
description: The unique identifier of this policy type. This is the policy name.
in: path
required: true
schema:
type: string
securitySchemes:
apiKey:
type: apiKey
name: API-Key
in: header
description: >-
API Key based authentication. Each client application must pass its private, unique API key, allocated in the developer portal, via the
`API-Key: {api-key}` request header.
accessToken:
type: oauth2
description: >-
OAuth2 client access token authentication. The client authenticates against the server at `authorizationUrl`, passing the client's private
`clientId` (and optional `clientSecret`) as part of this flow. The client obtains an access token from the server at `tokenUrl`. It then
passes the received access token via the `Authorization: Bearer {access-token}` header in subsequent API calls. The authorization process also
returns a refresh token which the client should use to renew the access token before it expires.
flows:
authorizationCode:
authorizationUrl: 'https://auth.apiture.com/oauth2/authorize'
tokenUrl: 'http://auth.apiture.com/auth/oauth2/token'
scopes:
card/read: Read access to cards and card replacements.
card/write: Write (update) access to cards and card replacements.
card/delete: Delete access to cards and card replacements.
card/full: Full access to cards and card replacements.
admin/write: Administrative write (update) access to cards and card replacements.