API docs by Redocly

Wallet / Cards API (1.0.0)

Download OpenAPI specification:Download

API Integration Support: integration@dintero.com License: UNLICENSED

API for managing virtuall cards, digital gift cards and transactions

Changelog

All notable changes to the API.

2024-12-16

new: Add amount_reserved on card balance, add status to card properties

2024-12-11

new: Add amount_available query param filter on getting cards

2024-12-05

new: Add amount_funds, amount_drawdown, amount_pending on card balance

2024-11-27

new: Add endpoint for deleting a card

new: include_deleted query parameter for including deleted cards

2024-11-13

new: Add endpoint for getting cards on account

new: Add support for defining type of card

2024-11-01

update: Adjust minimum length of PIN when creating a new card from 6 to 4.

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

2023-06-12

new: Get details on customer card using customer_id and card_id.

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

new Support creating fund transaction using type property.

new Support creating transaction using card_id.

new: Support listing cards by customer_id, allow customer with access to user:wallets scope to list their cards with balance

cards

Create a card

Create a new card

scopes:

  • admin:wallets
  • write:wallets
scopes: ["admin:wallets","write:wallets"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

Request Body schema: application/json
required

card details

card_id
required
string <= 255 characters

The card id you have defined for the card. (must not have trailing or leading spaces)

amount
required
integer >= 0

Monetary amount in smallest unit for the currency

currency
required
string
Enum: "NOK" "SEK" "DKK" "EUR" "USD"

The three-character ISO-4217 currency. https://en.wikipedia.org/wiki/ISO_4217

customer_id
string <= 255 characters

The customer id you have defined as the owner of the card. (must not have trailing or leading spaces)

name
string

Display name for the card

type
string
Enum: "gift_card" "credit_note"

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

deleted_at
string <date-time>

The date-time when the resource was deleted

deleted_by
string

The ID of the user/client that deleted the resource

status
string
Enum: "unused" "used" "partially_used" "expired"

The status of the card. The value is one of the following:

  • 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

metadata
object

A key-value JSON object to store any additional information. The dintero_* namespace for keys is reserved

active_from
string <date-time>

Optional time when the card is activated. No drawdown transaction will be allowed before if set. (fund transaction is allowed)

expires_at
string <date-time>

Optional expiration time for the card. No transaction will be allowed on an expired card

object (PinGenerator)

How the PIN should be generated.

object (TokenGenerator)

Specify how token should be generated

Responses

Request samples

Content type
application/json
{
  • "card_id": "string",
  • "customer_id": "string",
  • "name": "string",
  • "type": "gift_card",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "status": "unused",
  • "metadata": {
    },
  • "amount": 50000,
  • "currency": "NOK",
  • "active_from": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "pin": {
    },
  • "card_token": {
    }
}

Response samples

Content type
application/json
{
  • "card_id": "string",
  • "customer_id": "string",
  • "name": "string",
  • "type": "gift_card",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "status": "unused",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "metadata": {
    },
  • "amount": 50000,
  • "currency": "NOK",
  • "amount_balance": 50000,
  • "amount_available": 50000,
  • "amount_funds": 50000,
  • "amount_drawdown": 50000,
  • "amount_pending": 50000,
  • "amount_reserved": 50000,
  • "active_from": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "pin": {
    },
  • "card_token": {
    }
}

Get cards

Get all cards for an account

scopes:

  • admin:wallets
  • read:wallets
scopes: ["admin:wallets","read:wallets"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

query Parameters
limit
integer [ 1 .. 100 ]
Default: 10

A limit on the number of objects to be returned. Limit can range between 1 and 100 items, and the default is 10 items.

starting_after
string

cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, end the result contains paging_token=pt1, your subsequent call can include starting_after=pt1 in order to fetch the next page of the list.

search
string

Will try to match the search to either card_id, customer_id or amount

created_at.gte
string <isodate>

Card created after (ISO 8601. We recommend using a localised ISO 8601 datetime like 2017-07-21T17:32:28Z. If a timezone is not specified we assume UTC)

created_at.lte
string <isodate>

Card created before a date (ISO 8601. We recommend using a localised ISO 8601 datetime like 2017-07-21T17:32:28Z. If a timezone is not specified we assume UTC)

type
string
Enum: "gift_card" "credit_note"

Filter cards by type

status
string
Enum: "unused" "partially_used" "used" "expired"

Filter cards by amount and expiry status

expires_at.gte
string <isodate>

Card expires after (ISO 8601. We recommend using a localised ISO 8601 datetime like 2017-07-21T17:32:28Z. If a timezone is not specified we assume UTC)

expires_at.lte
string <isodate>

Card expires before a date (ISO 8601. We recommend using a localised ISO 8601 datetime like 2017-07-21T17:32:28Z. If a timezone is not specified we assume UTC)

amount_balance
integer

Exact card balance

amount_balance.gte
integer

Lower limit for filtering on card balance.

amount_balance.lte
integer

Upper limit for filtering on card balance.

amount_available
integer

Amount available on the card

amount_available.gte
integer

Lower limit for filtering on available amount on card.

amount_available.lte
integer

Upper limit for filtering on available amount on card.

currency
Array of strings

The currency of the card. ?currency=NOK&currency=SEK

customer
string

Filter cards by customer_id

include_deleted
boolean

Include deleted cards in the response

Responses

Response samples

Content type
application/json
{
  • "cards": [
    ],
  • "starting_after": "string"
}

Retrieve card by card ID

Get all details about a card

scopes:

  • admin:wallets
  • read:wallets
scopes: ["admin:wallets","read:wallets"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

card_id
required
string <= 255 characters

The card id you have defined for the card. (must not have trailing or leading spaces)

Responses

Response samples

Content type
application/json
{
  • "card_id": "string",
  • "customer_id": "string",
  • "name": "string",
  • "type": "gift_card",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "status": "unused",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "metadata": {
    },
  • "amount": 50000,
  • "currency": "NOK",
  • "amount_balance": 50000,
  • "amount_available": 50000,
  • "amount_funds": 50000,
  • "amount_drawdown": 50000,
  • "amount_pending": 50000,
  • "amount_reserved": 50000,
  • "active_from": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "tokens": [
    ]
}

Delete card by card ID

Delete a card

scopes:

  • admin:wallets
  • write:wallets
scopes: ["admin:wallets","write:wallets"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

card_id
required
string <= 255 characters

The card id you have defined for the card. (must not have trailing or leading spaces)

Responses

Response samples

Content type
application/json
{
  • "card_id": "string",
  • "customer_id": "string",
  • "name": "string",
  • "type": "gift_card",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "status": "unused",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "metadata": {
    },
  • "amount": 50000,
  • "currency": "NOK",
  • "amount_balance": 50000,
  • "amount_available": 50000,
  • "amount_funds": 50000,
  • "amount_drawdown": 50000,
  • "amount_pending": 50000,
  • "amount_reserved": 50000,
  • "active_from": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "tokens": [
    ]
}

Create a token for the card

Create a temporary token (also referred as Card Code) for the card, an temporary alias that must be used when when creating a drawdown transaction

The token can be stored in a barcode to allow use of virtuell card in purchase in POS or webstore

scopes:

  • admin:wallets
  • write:wallets
scopes: ["admin:wallets","write:wallets"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

card_id
required
string <= 255 characters

The card id you have defined for the card. (must not have trailing or leading spaces)

Request Body schema: application/json
required

token details

ref_id
required
string

Unique ref ID provided by the client to support safely retrying requests without accidentally performing the same operation twice

All card transaction must have a unique ref ID, but it is not required that the ref ID is globally unique.

expires_in
required
integer >= 1

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.

metadata
object

A key-value JSON object to store any additional information. The dintero_* namespace for keys is reserved

object

specify the format for to generate

expires_after_transaction
boolean
Default: true

The token can only be used to create one transaction, card lookup by token will be available until token expires by date

Responses

Request samples

Content type
application/json
{
  • "metadata": {
    },
  • "ref_id": "string",
  • "format": {
    },
  • "expires_after_transaction": true,
  • "expires_in": 1
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "metadata": {
    },
  • "ref_id": "string",
  • "format": {
    },
  • "expires_after_transaction": true,
  • "expires_in": 1,
  • "token": {
    }
}

Retrieve card by Token

Get details about a card, including the current balance and available funds. No details will be returned for expired tokens

scopes:

  • admin:wallets
  • write:wallets
  • write:wallets:/info
scopes: ["admin:wallets","write:wallets","write:wallets:/info"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

Request Body schema: application/json
required
token
required
string

temporary token for a Card

pin
string

PIN for the Card

Responses

Request samples

Content type
application/json
{
  • "token": "string",
  • "pin": "string"
}

Response samples

Content type
application/json
{
  • "card_id": "string",
  • "customer_id": "string",
  • "name": "string",
  • "type": "gift_card",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "status": "unused",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "metadata": {
    },
  • "amount": 50000,
  • "currency": "NOK",
  • "amount_balance": 50000,
  • "amount_available": 50000,
  • "amount_funds": 50000,
  • "amount_drawdown": 50000,
  • "amount_pending": 50000,
  • "amount_reserved": 50000,
  • "active_from": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z"
}

customers

List customer cards

Get the cards active for a customer

scopes:

  • admin:wallets
  • read:wallets
  • user:wallets
scopes: ["admin:wallets","read:wallets","user:wallets"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

customer_id
required
string <= 255 characters

The customer id you have defined for the customer. (must not have trailing or leading spaces)

query Parameters
limit
integer [ 1 .. 100 ]
Default: 10

A limit on the number of objects to be returned. Limit can range between 1 and 100 items, and the default is 10 items.

starting_after
string

cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, end the result contains paging_token=pt1, your subsequent call can include starting_after=pt1 in order to fetch the next page of the list.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get customer card details

Get all details about a customer card

scopes:

  • admin:wallets
  • read:wallets
  • user:wallets
scopes: ["admin:wallets","read:wallets","user:wallets"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

customer_id
required
string <= 255 characters

The customer id you have defined for the customer. (must not have trailing or leading spaces)

card_id
required
string <= 255 characters

The card id you have defined for the card. (must not have trailing or leading spaces)

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "metadata": {
    },
  • "active_from": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "card_id": "string",
  • "customer_id": "string",
  • "name": "string",
  • "type": "gift_card",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "status": "unused",
  • "tokens": [
    ],
  • "amount_balance": 50000,
  • "amount_available": 50000,
  • "amount_funds": 50000,
  • "amount_drawdown": 50000,
  • "amount_pending": 50000,
  • "amount_reserved": 50000,
  • "currency": "NOK"
}

transactions

List card transactions

Retrieve a list of Card's Transaction based on card id

scopes:

  • admin:wallets
  • read:wallets
scopes: ["admin:wallets","read:wallets"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

card_id
required
string <= 255 characters

The card id you have defined for the card. (must not have trailing or leading spaces)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create transaction

Create a transaction against a Card using token or card_id. If the Transactions is created as pending, the value will be locked until it is either captured or voided. Transaction ID must be used when capturing or voiding a transaction.

Using card_id or creating a fund transaction requires authorization scope admin:wallets or write:wallets

scopes:

  • admin:wallets
  • write:wallets
  • write:wallets:/transactions
scopes: ["admin:wallets","write:wallets","write:wallets:/transactions"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

Request Body schema: application/json
required

transaction details

ref_id
required
string

Unique ref ID provided by the client to support safely retrying requests without accidentally performing the same operation twice

All card transaction must have a unique ref ID, but it is not required that the ref ID is globally unique.

amount
required
integer >= 0

Monetary amount in smallest unit for the currency

currency
required
string
Enum: "NOK" "SEK" "DKK" "EUR" "USD"

The three-character ISO-4217 currency. https://en.wikipedia.org/wiki/ISO_4217

token
string

required if card_id is not set (cannot be combined with card_id)

card_id
string

required if token is not set (cannot be combined with token)

metadata
object

A key-value JSON object to store any additional information. The dintero_* namespace for keys is reserved

type
string
Default: "drawdown"
Enum: "drawdown" "fund"
pending
boolean
Default: false

If true, the transaction will be created as pending, i.e. the value will be locked until it is either captured or voided.

Only supported when creating a drawdown transaction.

Responses

Request samples

Content type
application/json
{
  • "token": "string",
  • "card_id": "string",
  • "metadata": {
    },
  • "ref_id": "string",
  • "amount": 50000,
  • "currency": "NOK",
  • "type": "drawdown",
  • "pending": false
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "metadata": {
    },
  • "ref_id": "string",
  • "amount": 50000,
  • "currency": "NOK",
  • "type": "drawdown",
  • "parent_id": "1c6ca187-e61f-4301-8dcb-0e9749e89eef"
}

Capture pending transaction

Capture a pending Transaction, thereby collection the amount withheld by the pending transaction.

Option to specify an amount that should be captured. Defaults to capture the full transaction. When the amount specified is less than the reserved/pending, the remaining amount will still be reserved/pending and can be captured later.

scopes:

  • admin:wallets
  • write:wallets
  • write:wallets:/transactions
scopes: ["admin:wallets","write:wallets","write:wallets:/transactions"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

transaction_id
required
string <uuid>

An id that uniqely idetifies a transaction

Request Body schema: application/json
required

capture details

ref_id
required
string

Unique ref ID provided by the client to support safely retrying requests without accidentally performing the same operation twice

All card transaction must have a unique ref ID, but it is not required that the ref ID is globally unique.

metadata
object

A key-value JSON object to store any additional information. The dintero_* namespace for keys is reserved

amount
integer >= 0

Monetary amount in smallest unit for the currency

Responses

Request samples

Content type
application/json
{
  • "metadata": {
    },
  • "ref_id": "string",
  • "amount": 50000
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "metadata": {
    },
  • "ref_id": "string",
  • "amount": 50000,
  • "currency": "NOK",
  • "type": "drawdown",
  • "parent_id": "1c6ca187-e61f-4301-8dcb-0e9749e89eef"
}

Void pending transaction

Void a pending Transaction by unlocking the amount withheld by the pending transaction

scopes:

  • admin:wallets
  • write:wallets
  • write:wallets:/transactions
scopes: ["admin:wallets","write:wallets","write:wallets:/transactions"]
Authorizations:
JWT
path Parameters
aid
required
string <^[PT]{1}\d{8}$> = 9 characters

An id that uniquely identifies the account.

transaction_id
required
string <uuid>

An id that uniqely idetifies a transaction

Request Body schema: application/json
required

void details

ref_id
required
string

Unique ref ID provided by the client to support safely retrying requests without accidentally performing the same operation twice

All card transaction must have a unique ref ID, but it is not required that the ref ID is globally unique.

metadata
object

A key-value JSON object to store any additional information. The dintero_* namespace for keys is reserved

Responses

Request samples

Content type
application/json
{
  • "metadata": {
    },
  • "ref_id": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
  • "metadata": {
    },
  • "ref_id": "string",
  • "amount": 50000,
  • "currency": "NOK",
  • "type": "drawdown",
  • "parent_id": "1c6ca187-e61f-4301-8dcb-0e9749e89eef"
}