API docs by Redocly

Digital Cash Core API (2.6.0)

Download OpenAPI specification:Download

The core component connects all the components in a Digital Cash system. It utilizes the Signing Service to verify and sign data from and to the Digital Cash SDK. The wallet settings for each activated wallet are stored in a database.

For more information see the developer portal Digital Cash Core

SDK

Requests coming from the Digital Cash SDK.

Generic wallet request

Will parse the wallet request and route to matching endpoint for handling

Request Body schema: application/json
required
encoded
required
string

Base64 encoded wallet request.

Responses

Request samples

Content type
application/json
{
  • "encoded": "string"
}

Response samples

Content type
application/json
{
  • "encoded": "string"
}

Activates a wallet

Called by the client upon activating a new wallet. The client determines the wallet address that shoulde be used, and it has to be globally unique.

For more information see Wallet Activation.

Request Body schema: application/json
required
encoded
required
string

Base64 encoded wallet request.

Responses

Request samples

Content type
application/json
{
  • "encoded": "string"
}

Response samples

Content type
application/json
{
  • "encoded": "string"
}

Syncs a wallet

Called by the client upon sync request. The request will be verified and update the wallet states in the database. A new set of WalletSetings are sent back to the client to set the current state. For more information see

For more information see Wallet Sync

Request Body schema: application/json
required
encoded
required
string

Base64 encoded wallet request.

Responses

Request samples

Content type
application/json
{
  • "encoded": "string"
}

Response samples

Content type
application/json
{
  • "encoded": "string"
}

Transfer funds to and from wallet

Called by the client to transfer funds from and to the wallet. The request is validated and will result in a call to the balance exchange hook to inform the issuer about the transaction.

For more information see Balance Exchange

Request Body schema: application/json
required
encoded
required
string

Base64 encoded wallet request.

Responses

Request samples

Content type
application/json
{
  • "encoded": "string"
}

Response samples

Content type
application/json
{
  • "encoded": "string"
}

Resets the wallet passphrase

Called by the client to reset the wallet passphrase. The server validates the request and if the request is signed by properly by the wallet private key a response will be generated in order for the wallet to allow seting a new passphrase.

For more information see Passphrase

Request Body schema: application/json
required
encoded
required
string

Base64 encoded wallet request.

Responses

Request samples

Content type
application/json
{
  • "encoded": "string"
}

Response samples

Content type
application/json
{
  • "encoded": "string"
}

Upload wallet payment

Called by the client to upload pending payments. The payment is verified and then sent to the issuer in the payments hook. Note that the same payment can be uploaded multiple times and the issuer is responsible to only settle the transaction once.

For more information see Payment Upload

Request Body schema: application/json
required
encoded
required
string

Base64 encoded wallet request.

Responses

Request samples

Content type
application/json
{
  • "encoded": "string"
}

Response samples

Content type
application/json
{
  • "encoded": "string"
}

Uploads a private payment

Called by the client to upload pending private payments. The payment is verified and then sent to the issuer in the payments hook.

Note that the same payment can be uploaded multiple times and the issuer is responsible to only settle the transaction once.

For more information see Payment Upload

Request Body schema: application/json
required
encoded
required
string

Base64 encoded wallet request.

Responses

Request samples

Content type
application/json
{
  • "encoded": "string"
}

Response samples

Content type
application/json
{
  • "encoded": "string"
}

Uploads a verifier payment

Called by the client (verifier) to upload pending payments. The payment is verified and then sent to the issuer in the payments hook.

Note that the same payment can be uploaded multiple times and the issuer is responsible to only settle the transaction once.

For more information see Payment Upload

Request Body schema: application/json
required
encoded
required
string

Base64 encoded wallet request.

Responses

Request samples

Content type
application/json
{
  • "encoded": "string"
}

Response samples

Content type
application/json
{
  • "encoded": "string"
}

Issuer

Called from the issuer to help parse and verify data.

Decode and verify a compact payment

Helper function to re-create a compact payment. This function should be called by the issuer when a compact payment is received. The payment is re-created using the stored certificate in the database. The function will then call the payments hook as a regular payment.

For more information see Compact Payments

Request Body schema: application/json
required
data
required
string

Hex encoded data as received by the issuer in the SMS or other compact method.

paymentAddress
required
string

Wallet address of the payer

currency
required
string (Currency)

The currency in which the request is made. It is compatible with, but not restricted to, ISO 4217.

Responses

Request samples

Content type
application/json
{
  • "data": "string",
  • "paymentAddress": "string",
  • "currency": "string"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "timestamp": 0,
  • "requestId": "string",
  • "requestTimeOffset": 0,
  • "amount": 0,
  • "currency": "string",
  • "senderSignature": "string",
  • "senderAddress": "string",
  • "receiverAddress": "string",
  • "senderCertificateChain": [
    • "string"
    ],
  • "remainingBalanceHops": 0,
  • "backed": true,
  • "private": true,
  • "senderWalletId": 0
}

General

General endpoints not related to Digital Cash.

Checks server health

Responses

Response samples

Content type
application/json
{
  • "version": "string",
  • "certificateFactory": {
    • "success": true,
    • "error": "string",
    • "result": { }
    },
  • "signingService": {
    • "success": true,
    • "error": "string",
    • "result": { }
    }
}

Admin

Admin endpoints to modify wallet settings.

Sets the wallet settings for a specific user

The provided settings will be set for the provided wallet address. Use with caution so no lock reasons are unintentionally removed.

path Parameters
walletAddress
required
string
Request Body schema: application/json
required
id
integer

Globally unique identifier for the wallet.

commonName
string

CN field of the certificate, the same as the wallet address.

certificate
string

The issued wallet certificate.

csr
string

The certificate signing request used to create the certificate.

maxPassphraseAttempts
integer

The number of attempts allowed for a failed passphrase.

maxUnsyncedDays
integer

A restriction on the maximum number of days allowed without performing a successful sync.

maxBalanceHops
integer

The number of times the offline balance can be used in payments before it must be synced. Mandatory when the PayForward capability is set.

senderMaxNewPaymentAmount
integer

An amount restriction that applies to new offline payments for creating a payment. A payment request with a larger amount than this cannot be created or signed by a wallet.

senderMaxPendingPaymentsAmount
integer

An amount restriction that applies to all sent pending payments (i.e., those that haven’t been settled online), including the new payment.

This value will limit the sum of all pending payments in the Wallet. This ensures that pending payments are uploaded.

senderMaxPendingPayments
integer

The total number of pending sent payments allowed before uploading is required.

receiverMaxNewPaymentAmount
integer

An amount restriction that applies to new offline payments for requesting a payment. A payment request with a larger amount than this cannot be created or signed by a wallet.

receiverMaxPendingPaymentsAmount
integer

An amount restriction that applies to all received pending payments (i.e., those that haven’t been settled online), including the new payment.

This value will limit the sum of all pending payments in the Wallet. This ensures that pending payments are uploaded.

receiverMaxPendingPayments
integer

The total number of pending received payments allowed before uploading is required.

Array of objects (WalletLockedReason)

List of reasons why the wallet is locked. Empty list if it is not locked.

Array of PayStatic (object) or PayForward (object) or PayToVerifier (string) (WalletCapability)
deactivated
boolean

Set to true if the wallet has been deactivated.

Responses

Request samples

Content type
application/json
{
  • "id": 0,
  • "commonName": "string",
  • "certificate": "string",
  • "csr": "string",
  • "maxPassphraseAttempts": 0,
  • "maxUnsyncedDays": 0,
  • "maxBalanceHops": 0,
  • "senderMaxNewPaymentAmount": 0,
  • "senderMaxPendingPaymentsAmount": 0,
  • "senderMaxPendingPayments": 0,
  • "receiverMaxNewPaymentAmount": 0,
  • "receiverMaxPendingPaymentsAmount": 0,
  • "receiverMaxPendingPayments": 0,
  • "lockedReasons": [
    • {
      • "name": "Unknown",
      • "code": 0,
      • "markedForRemoval": true
      }
    ],
  • "walletCapabilities": [
    • {
      • "payStatic": {
        • "allowUnbackedPayments": true
        }
      }
    ],
  • "deactivated": true
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "commonName": "string",
  • "certificate": "string",
  • "csr": "string",
  • "maxPassphraseAttempts": 0,
  • "maxUnsyncedDays": 0,
  • "maxBalanceHops": 0,
  • "senderMaxNewPaymentAmount": 0,
  • "senderMaxPendingPaymentsAmount": 0,
  • "senderMaxPendingPayments": 0,
  • "receiverMaxNewPaymentAmount": 0,
  • "receiverMaxPendingPaymentsAmount": 0,
  • "receiverMaxPendingPayments": 0,
  • "lockedReasons": [
    • {
      • "name": "Unknown",
      • "code": 0,
      • "markedForRemoval": true
      }
    ],
  • "walletCapabilities": [
    • {
      • "payStatic": {
        • "allowUnbackedPayments": true
        }
      }
    ],
  • "deactivated": true
}

Retrieves the wallet settings for a specific user

path Parameters
walletAddress
required
string

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "commonName": "string",
  • "certificate": "string",
  • "csr": "string",
  • "maxPassphraseAttempts": 0,
  • "maxUnsyncedDays": 0,
  • "maxBalanceHops": 0,
  • "senderMaxNewPaymentAmount": 0,
  • "senderMaxPendingPaymentsAmount": 0,
  • "senderMaxPendingPayments": 0,
  • "receiverMaxNewPaymentAmount": 0,
  • "receiverMaxPendingPaymentsAmount": 0,
  • "receiverMaxPendingPayments": 0,
  • "lockedReasons": [
    • {
      • "name": "Unknown",
      • "code": 0,
      • "markedForRemoval": true
      }
    ],
  • "walletCapabilities": [
    • {
      • "payStatic": {
        • "allowUnbackedPayments": true
        }
      }
    ],
  • "deactivated": true
}

Deletes the wallet for a specific user

path Parameters
walletAddress
required
string

Responses

Retrieves the lock reasons for a user's wallet

path Parameters
walletAddress
required
string

Responses

Response samples

Content type
application/json
[
  • {
    • "name": "Unknown",
    • "code": 0,
    • "markedForRemoval": true
    }
]

Adds a lock reason to a user's wallet

path Parameters
walletAddress
required
string
Request Body schema: application/json
required
name
string
Enum: "Unknown" "MaxPassphraseAttemptsExceeded" "MaxUnsyncedDaysExceeded" "IncompleteSettings" "WalletCertificateExpired" "WalletCertificateRevoked" "EndOfLife" "IssuerSpecified" "ThreatDetected" "AppSpecified" "DeviceRebooted" "PendingDeactivation"
code
integer or null
markedForRemoval
boolean

Responses

Request samples

Content type
application/json
{
  • "name": "Unknown",
  • "code": 0,
  • "markedForRemoval": true
}

Response samples

Content type
application/json
{
  • "name": "Unknown",
  • "code": 0,
  • "markedForRemoval": true
}

Updates the lock reasons for a user's wallet

path Parameters
walletAddress
required
string
Request Body schema: application/json
required
Array
name
string
Enum: "Unknown" "MaxPassphraseAttemptsExceeded" "MaxUnsyncedDaysExceeded" "IncompleteSettings" "WalletCertificateExpired" "WalletCertificateRevoked" "EndOfLife" "IssuerSpecified" "ThreatDetected" "AppSpecified" "DeviceRebooted" "PendingDeactivation"
code
integer or null
markedForRemoval
boolean

Responses

Request samples

Content type
application/json
[
  • {
    • "name": "Unknown",
    • "code": 0,
    • "markedForRemoval": true
    }
]

Hooks

Endpoints called by the Digital Cash Core. The url can be configured so these are documented for the purpose of showing the example data.

Get wallet balance

Called when the system needs to know the balance of a wallet address. The request will include the client balance for sync requests and will be empty if it is called during activation of a wallet.

Request Body schema: application/json
required
walletAddress
required
string

Address to get the balance information for.

spendableBalance
integer <int64>

The balance reported by the client in the sync operation.

settleableBalance
integer <int64>

The settleable balance reported by the client in the sync operation.

For private payments only.

currency
string (Currency)

The currency in which the request is made. It is compatible with, but not restricted to, ISO 4217.

Array of objects (SubWallet)

Responses

Request samples

Content type
application/json
{
  • "walletAddress": "string",
  • "spendableBalance": 0,
  • "settleableBalance": 0,
  • "currency": "string",
  • "subWallets": [
    • {
      • "id": 0,
      • "paymentCategories": [
        • 0
        ],
      • "spendableBalance": 0
      }
    ]
}

Response samples

Content type
application/json
{
  • "walletAddress": "string",
  • "balance": 0,
  • "currency": "string",
  • "subWallets": [
    • {
      • "id": 0,
      • "paymentCategories": [
        • 0
        ],
      • "spendableBalance": 0
      }
    ]
}

Exchange wallet balance

Called when client has uploaded a balance exchange request. The issuer should update wallet balance for the wallet and transfer funds if needed.

For more information see Balance Exchange

Request Body schema: application/json
required
balanceExchangeId
required
integer <uint32>
walletAddress
required
string
amount
required
integer <uint64>
currency
required
string
requestType
required
string
walletId
integer <uint8>

Responses

Request samples

Content type
application/json
{
  • "balanceExchangeId": 0,
  • "walletAddress": "string",
  • "amount": 0,
  • "currency": "string",
  • "requestType": "string",
  • "walletId": 0
}

Response samples

Content type
application/json
{
  • "walletAddress": "string",
  • "balance": 0,
  • "currency": "string",
  • "subWallets": [
    • {
      • "id": 0,
      • "paymentCategories": [
        • 0
        ],
      • "spendableBalance": 0
      }
    ]
}

Upload payment information

Called when a client uploads a pending payment. Note that same payment can be called multiple times.

See Developer Portal for more information Payment Upload

Request Body schema: application/json
required
required
object (Payment)

Representation of an offline payment. See developer portal for more information.

type
required
string
result
required
string (PaymentResult)
Enum: "Success" "BadCertificate" "CertificateExpired" "SignatureMismatch"

The verification result of the payment. This field needs to be checked before performing any transactions.

object (HooksPaymentOrigin)
object (HooksPaymentOrigin)

Responses

Request samples

Content type
application/json
{
  • "payment": {
    • "id": 0,
    • "timestamp": 0,
    • "requestId": "string",
    • "requestTimeOffset": 0,
    • "amount": 0,
    • "currency": "string",
    • "senderSignature": "string",
    • "senderAddress": "string",
    • "receiverAddress": "string",
    • "senderCertificateChain": [
      • "string"
      ],
    • "remainingBalanceHops": 0,
    • "backed": true,
    • "private": true,
    • "senderWalletId": 0
    },
  • "type": "string",
  • "result": "Success",
  • "origin": {
    • "paymentAddress": "string",
    • "requestId": "string",
    • "timestamp": 0,
    • "amount": 0,
    • "currency": "string",
    • "supportsPrivatePayments": true,
    • "version": 0,
    • "paymentCategories": [
      • 0
      ]
    },
  • "request": {
    • "paymentAddress": "string",
    • "requestId": "string",
    • "timestamp": 0,
    • "amount": 0,
    • "currency": "string",
    • "supportsPrivatePayments": true,
    • "version": 0,
    • "paymentCategories": [
      • 0
      ]
    }
}

Upload private payment information

Called when a client uploads a pending private payment.

See Developer Portal for more information Payment Upload

Request Body schema: application/json
required
walletAddress
required
string

Wallet address of the paying wallet.

paymentUniqueId
required
string

Unique identifier for the payment

payment
required
string

SHA-256 digest of the encoded Payment

result
required
string (PaymentResult)
Enum: "Success" "BadCertificate" "CertificateExpired" "SignatureMismatch"

The verification result of the payment. This field needs to be checked before performing any transactions.

Responses

Request samples

Content type
application/json
{
  • "walletAddress": "string",
  • "paymentUniqueId": "string",
  • "payment": "string",
  • "result": "Success"
}

Wallet event

Called to notify the issuer about different events for wallets.

Request Body schema: application/json
required
walletAddress
string

Wallet address related to the event.

details
string

Detailed information about the event.

event
string
Enum: "Activate" "Deactivate"

Responses

Request samples

Content type
application/json
{
  • "walletAddress": "string",
  • "details": "string",
  • "event": "Activate"
}

Wallet locked by client

Called to notify the issuer that the client has locked the wallet for some reason.

Request Body schema: application/json
required
walletAddress
string
Array of objects (WalletLockedReason)

Responses

Request samples

Content type
application/json
{
  • "walletAddress": "string",
  • "lockReasons": [
    • {
      • "name": "Unknown",
      • "code": 0,
      • "markedForRemoval": true
      }
    ]
}