> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dintero.com/llms.txt
> Use this file to discover all available pages before exploring further.
## Submitting Feedback
If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:
POST https://docs.dintero.com/feedback
```json
{
"path": "/api-reference/cards/batch-create-cards",
"feedback": "Description of the issue"
}
```
Only submit feedback when you have something specific and actionable to report.
# Batch create cards
> Batch create cards. The cards created from the batch operation will
all have zero balance and status `inactive`. They all need to be
activated before use.
scopes:
- admin:wallets
- write:wallets
## OpenAPI
````yaml /mintlify-docs/openapi/spec-wallets.yaml post /accounts/{aid}/wallets/cards/batch
openapi: 3.0.0
info:
title: Wallet / Cards API
description: >
API for managing virtual cards, digital gift cards and transactions
# Changelog
All notable changes to the API.
## 2026-06-06
> **new**: Add support for batch create cards that can be activated.
Intended
> for use case where physical cards will be issued from the Wallet cards.
The
> cards created will all have status `created` and needs to be activated
before
> use
>
> - [POST
/v1/accounts/{aid}/wallets/cards/batch](#tag/cards/operation/aid_cards_batch_post)
> - [POST
/v1/accounts/{aid}/wallets/cards/{card_id}/activate](#tag/cards/operation/aid_cards_cardid_activate_post)
## 2025-02-06
> **new**: Add optional query parameter `includes` and extend card details
with pin and token format
> - [GET
/v1/accounts/{aid}/wallets/cards/{card_id}](#tag/cards/operation/aid_cards_cardid_get)
## 2025-01-30
> **new**: Add endpoint for rotating or generating pin for card
> - [POST
/v1/accounts/{aid}/wallets/cards/{card_id}/rotate-pin](#tag/cards/operation/aid_cards_cardid_rotate_pin_post)
## 2024-12-16
> **new**: Add `amount_reserved` on card balance, add `status` to card
properties
>
> - [GET
/v1/accounts/{aid}/wallets/cards](#tag/cards/operation/aid_cards_get)
> - [GET
/v1/accounts/{aid}/wallets/cards/{card_id}](#tag/cards/operation/aid_cards_cardid_get)
## 2024-12-11
> **new**: Add `amount_available` query param filter on getting cards
>
> - [GET
/v1/accounts/{aid}/wallets/cards](#tag/cards/operation/aid_cards_get)
## 2024-12-05
> **new**: Add `amount_funds`, `amount_drawdown`, `amount_pending` on card
balance
>
>
> - [GET
/v1/accounts/{aid}/wallets/cards](#tag/cards/operation/aid_cards_get)
> - [GET
/v1/accounts/{aid}/wallets/cards/{card_id}](#tag/cards/operation/aid_cards_cardid_get)
## 2024-11-28
> **update**: Revert adding deletion properties to cards
>
> **new**: Add `originated_by` to card and transaction properties
>
> - [GET
/v1/accounts/{aid}/wallets/cards](#tag/cards/operation/aid_cards_get)
> - [GET
/v1/accounts/{aid}/wallets/cards/{card_id}](#tag/cards/operation/aid_cards_cardid_get)
> - [GET
/v1/accounts/{aid}/wallets/cards/{card_id}/transactions](#tag/cards/operation/aid_cards_cardid_transactions_tid_get)
> - [POST
/v1/accounts/{aid}/wallets/transactions](#tag/transactions/operation/aid_cards_transactions_post)
> - [POST
/v1/accounts/{aid}/wallets/transactions/{transaction_id}/capture](#tag/transactions/operation/aid_cards_cardid_transactions_capture_post)
> - [POST
/v1/accounts/{aid}/wallets/transactions/{transaction_id}/void](#tag/transactions/operation/aid_cards_cardid_transactions_void_post)
## 2024-11-27
> **new**: Add endpoint for deleting a card
>
> **new**: `include_deleted` query parameter for including deleted cards
>
> - [DELETE
/v1/accounts/{aid}/wallets/cards/{card_id}](#tag/cards/operation/aid_cards_cardid_delete)
> - [GET
/v1/accounts/{aid}/wallets/cards](#tag/cards/operation/aid_cards_get)
## 2024-11-13
> **new**: Add endpoint for getting cards on account
>
> **new**: Add support for defining type of card
>
> - [GET
/v1/accounts/{aid}/wallets/cards](#tag/cards/operation/aid_cards_get)
> - [POST
/v1/accounts/{aid}/wallets/cards](#tag/cards/operation/aid_cards_post)
## 2024-11-01
> **update**: Adjust minimum length of PIN when creating a new card from 6
to 4.
>
> - [POST
/v1/accounts/{aid}/wallets/cards](#tag/cards/operation/aid_cards_post)
## 2024-06-10
> **new**: Allow more currencies: `SEK`, `DKK`, `EUR`, and `USD`.
>
> - [POST
/v1/accounts/{aid}/wallets/cards](#tag/cards/operation/aid_cards_post)
> - [POST
/v1/accounts/{aid}/wallets/transactions](#tag/transactions/operation/aid_cards_transactions_post)
> - [GET
/v1/accounts/{aid}/wallets/cards/{card_id}](#tag/cards/operation/aid_cards_cardid_get)
> - [GET
/v1/accounts/{aid}/wallets/customers/{customer_id}/cards/{card_id}](#tag/customers/operation/aid_customers_cid_card_cid_get)
## 2024-02-01
> **new**: Add option to create card with `pin` and support for
> including pin when getting card info and when creating new
> transaction
>
> - [POST
/v1/accounts/{aid}/wallets/cards](#tag/cards/operation/aid_cards_post)
> - [POST /v1/accounts/{aid}/wallets/info](#operation/aid_cards_token_post)
> - [POST
/v1/accounts/{aid}/wallets/transactions](#operation/aid_cards_transactions_post)
## 2023-07-07
> **new**: Add optional `name` field to `Card`.
>
> - [POST
/v1/accounts/{aid}/wallets/cards](#tag/cards/operation/aid_cards_post)
> - [GET
/v1/accounts/{aid}/wallets/cards/{card_id}](#tag/cards/operation/aid_cards_cardid_get)
> - [GET
/v1/accounts/{aid}/wallets/customers/{customer_id}/cards](#tag/customers/operation/aid_customers_cid_cards_get)
> - [GET
/v1/accounts/{aid}/wallets/customers/{customer_id}/cards/{card_id}](#tag/customers/operation/aid_customers_cid_card_cid_get)
## 2023-06-12
> **new**: Get details on customer card using `customer_id` and `card_id`.
>
> - [GET
/v1/accounts/{aid}/wallets/customers/{customer_id}/cards/{card_id}](#tag/customers/operation/aid_customers_cid_card_cid_get)
## 2023-06-01
> **new** Support creating card with `active_from` to control when
> the created card is activated and allows `drawdown` transactions to be
> created
>
> - [POST
/v1/accounts/{aid}/wallets/cards](#tag/cards/operation/aid_cards_post)
> **new** Support creating fund transaction using `type` property.
>
> - [POST
/v1/accounts/{aid}/wallets/transactions](#tag/transactions/operation/aid_cards_transactions_post)
> **new** Support creating transaction using `card_id`.
>
> - [POST
/v1/accounts/{aid}/wallets/transactions](#tag/transactions/operation/aid_cards_transactions_post)
> **new**: Support listing cards by customer_id, allow customer with
> access to `user:wallets` scope to list their cards with balance
>
> - [GET
/v1/accounts/{aid}/wallets/customers/{cid}/cards](#tag/customers/operation/aid_customers_cid_cards_get)
contact:
name: API Integration Support
email: integration@dintero.com
version: 1.0.0
license:
name: UNLICENSED
url: https://dintero.com
servers:
- url: https://api.dintero.com/v1
security:
- JWT: []
paths:
/accounts/{aid}/wallets/cards/batch:
post:
tags:
- cards
summary: Batch create cards
description: |
Batch create cards. The cards created from the batch operation will
all have zero balance and status `inactive`. They all need to be
activated before use.
scopes:
- admin:wallets
- write:wallets
operationId: aid_cards_batch_post
parameters:
- $ref: '#/components/parameters/accountId'
requestBody:
content:
application/json:
schema:
type: object
allOf:
- required:
- cards
properties:
cards:
type: array
maxItems: 1000
items:
type: object
required:
- card_id
- type
properties:
card_id:
type: string
description: |
The card id you have defined for the card.
(must not have trailing or leading spaces)
maxLength: 255
type:
type: string
description: >
The type of the card. The value is one of the
following:
- `gift_card` - a gift card
- `credit_note` - a credit note
example: gift_card
enum:
- gift_card
- credit_note
options:
type: object
description: Options for the cards to create
properties:
pin:
type: object
required:
- format
properties:
format:
$ref: '#/components/schemas/PinFormat'
card_token:
type: object
required:
- format
properties:
format:
allOf:
- $ref: '#/components/schemas/Format'
- description: >
specify the format for the token, default
format
is an UUID prefixed with `DINCARD`
description: card details
required: true
responses:
'200':
description: Cards created
content:
application/json:
schema:
type: object
required:
- cards
properties:
cards:
type: array
items:
allOf:
- $ref: '#/components/schemas/Card'
- properties:
status:
type: string
enum:
- inactive
pin:
$ref: '#/components/schemas/PinGenerator'
card_token:
$ref: '#/components/schemas/TokenGenerator'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/AccessForbidden'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/ServerError'
security:
- JWT: []
components:
parameters:
accountId:
name: aid
description: |
An id that uniquely identifies the account.
in: path
required: true
schema:
type: string
format: ^[PT]{1}\d{8}$
minLength: 9
maxLength: 9
schemas:
PinFormat:
description: PIN format used for generation
type: object
properties:
length:
description: |
The length of the PIN (exclusive length of the prefix).
type: integer
default: 36
minimum: 4
prefix:
type: string
description: |
Prefix the PIN, the length of the prefix will affect
the total length of the PIN.
example: 'DINCARD:'
maxLength: 12
symbols:
type: boolean
description: Allow characters like `@#$%` in the created PIN.
default: true
numbers:
type: boolean
description: Allow characters like `123456` in the created PIN.
default: true
characters:
type: boolean
description: Allow characters like `acbABC` in the created PIN.
barcode:
default: false
description: |
Include the PIN as a base64 encoded barcode image.
type: boolean
Format:
description: Specify the format to generate
type: object
properties:
length:
description: |
The length of the token (exclusive length of the prefix)
type: integer
default: 36
minimum: 6
prefix:
type: string
description: |
Prefix the token, the length of the prefix will affect
the total length of the token
example: 'DINCARD:'
maxLength: 12
symbols:
type: boolean
description: Allow characters like `@#$%` in the created token
default: true
numbers:
type: boolean
description: Allow characters like `123456` in the created token
default: true
characters:
type: boolean
description: Allow characters like `acbABC` in the created token
barcode:
default: false
description: |
Include token as base64 encoded barcode image
type: boolean
Card:
type: object
allOf:
- $ref: '#/components/schemas/CardProperties'
- $ref: '#/components/schemas/ImmutableEntity'
- $ref: '#/components/schemas/Metadata'
- $ref: '#/components/schemas/Operation'
- $ref: '#/components/schemas/CardBalance'
- $ref: '#/components/schemas/CardActivePeriod'
PinGenerator:
type: object
description: How the PIN should be generated.
properties:
format:
$ref: '#/components/schemas/PinFormat'
pin:
type: object
readOnly: true
properties:
value:
type: string
example: '012345'
maxLength: 48
barcode_128:
type: string
description: >
Code 128 barcode representation of the PIN value. A base64
encoded
image in format `data:[][;charset=][;base64],`
example: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAADIA...
TokenGenerator:
type: object
description: Specify how token should be generated
required:
- expires_in
properties:
format:
allOf:
- $ref: '#/components/schemas/Format'
- description: |
specify the format for the token, default format
is an UUID prefixed with `DINCARD`
expires_after_transaction:
type: boolean
description: |
The token can only be used to create one transaction, card lookup by
token will be available until token expires by date
default: true
expires_in:
description: |
The lifetime in seconds for the card token. For
example, the value "3600" denotes that the token will
expire in one hour from the time the response was generated.
minimum: 1
type: integer
token:
type: object
readOnly: true
properties:
value:
type: string
example: DINCARD:6ccfec5d-3a53-47de-910a-97d6dda22e5f
maxLength: 48
barcode_128:
type: string
description: >
Code 128 barcode representation of the token value. A base64
encoded
image in format `data:[][;charset=][;base64],`
example: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAADIA...
CardProperties:
type: object
required:
- card_id
allOf:
- $ref: '#/components/schemas/OriginatedBy'
- properties:
card_id:
type: string
description: |
The card id you have defined for the card.
(must not have trailing or leading spaces)
maxLength: 255
customer_id:
type: string
description: |
The customer id you have defined as the owner
of the card. (must not have trailing or leading spaces)
maxLength: 255
name:
type: string
description: Display name for the card
type:
type: string
description: |
The type of the card. The value is one of the following:
- `gift_card` - a gift card
- `credit_note` - a credit note
Defaults to `gift_card`
example: gift_card
enum:
- gift_card
- credit_note
status:
type: string
description: >
The status of the card. The value is one of the following:
- `inactive` - Inactive card created by batch, needs to be
activated
- `unused` - the card is unused
- `used` - the card has 0 balance
- `partially_used` - the card has been used partially
- `expired` - the card has expired
Defaults to `unused`
example: unused
enum:
- inactive
- unused
- used
- partially_used
- expired
pin:
type: object
properties:
format:
allOf:
- $ref: '#/components/schemas/PinFormat'
ImmutableEntity:
type: object
properties:
id:
type: string
format: uuid
description: |
An UUID that uniquely identifies the resource
readOnly: true
created_at:
type: string
format: date-time
description: |
The date-time when the resource was created
readOnly: true
created_by:
type: string
example: 1c92f7e1-2897-4d46-bdcc-c127a914fb4e
description: |
The ID of the user/client that created the resource
readOnly: true
Metadata:
type: object
properties:
metadata:
type: object
description: |
A key-value JSON object to store any additional
information. The dintero_* namespace for keys
is reserved
example:
order_id: xk39592f
Operation:
type: object
allOf:
- required:
- amount
- currency
properties:
amount:
type: integer
example: 50000
minimum: 0
description: |
Monetary amount in smallest unit for the currency
currency:
type: string
example: NOK
enum:
- NOK
- SEK
- DKK
- EUR
- USD
description: |
The three-character ISO-4217 currency.
https://en.wikipedia.org/wiki/ISO_4217
CardBalance:
type: object
properties:
amount_balance:
type: number
readOnly: true
example: 50000
minimum: 0
description: |
The balance, including amount locked by pending transaction.
Monetary amount in smallest unit for the currency
amount_available:
type: number
readOnly: true
example: 50000
minimum: 0
description: |
The amount available for drawdown
(exclusive amount locked by pending transactions).
Monetary amount in smallest unit for the currency
amount_funds:
type: number
readOnly: true
example: 50000
minimum: 0
description: |
The sum of all fund transactions.
Monetary amount in smallest unit for the currency
amount_drawdown:
type: number
readOnly: true
example: 50000
minimum: 0
description: |
The sum of all drawdown transactions.
Monetary amount in smallest unit for the currency
amount_pending:
type: number
readOnly: true
example: 50000
minimum: 0
description: |
The sum of all pending transactions.
Monetary amount in smallest unit for the currency
amount_reserved:
type: number
readOnly: true
example: 50000
minimum: 0
description: |
The sum of all reserved transactions.
Monetary amount in smallest unit for the currency
CardActivePeriod:
type: object
properties:
active_from:
type: string
format: date-time
description: |
Optional time when the card is activated. No `drawdown` transaction
will be allowed before if set. (`fund` transaction is allowed)
expires_at:
type: string
format: date-time
description: |
Optional expiration time for the card. No transaction will be
allowed on an expired card
Error:
type: object
required:
- error
properties:
error:
type: object
required:
- message
properties:
code:
type: string
description: The code used to identify the error/warning
errors:
type: array
description: The nested error(s) encountered during validation
items:
type: object
message:
type: string
description: The human readable description of the error/warning
OriginatedBy:
type: object
properties:
originated_by:
type: string
description: |
The reference to where the entity was created.
(must not have trailing or leading spaces)
maxLength: 255
responses:
BadRequest:
description: Bad / Invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
AccessForbidden:
description: Access forbidden, invalid JWT token was used
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Forbidden:
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
ServerError:
description: Unexpected Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
securitySchemes:
JWT:
type: http
description: >
Bearer authentication (token authentication) should be used for
accessing the API.
Use [Get
Token](https://docs.dintero.com/api.html#operation/aid_auths_oauth_token_post)
to get an access token for client credentials.
Pass the token in the request header:
Authorization: Bearer {access_token}
where the **access_token** is JSON Web Tokens (JWT).
scheme: bearer
bearerFormat: JWT
````