API docs by Redocly

Issuer Bank Integration APIs - Document Store (2025.4.0)

Download OpenAPI specification:Download

Operations exposed by the Issuer Bank for amiko to integrate with. In order for Amiko to not store any document that can potentially contain sensitive information, the edge connector stores all unstructured data into an object or document store provided by the Issuer Bank.

Document

Stores a new document. Returns a unique documentId and optional mime type (in case it's different than the one provided in request).

The Issuer is responsible for the backup and recovery of this data store and to ensure data retention according to the applicable laws. For the document ID, the Issuer has to ensure that the IDs are unique across all existing and future documents. When storing a new document amiko will also provide the cardId, cardholderId and caseId as optional data fields. This allows the Issuer Bank to use this meta data to connect the stored document to a specific card, cardholder and amiko case. This can be useful if the document store has document search capabilities and/or if the document store is also connected to other business applications (e.g. a CRM system). Amiko does not require these data fields to be stored. If the document is stored in a different format than the mime type provided in the request, the new mime type must be returned in the response.

header Parameters
tracing-id
required
string

Tracing ID that can be used to track interactions.

bank-case-id
string

Issuer case ID for crossreferencing with issuer systems.

auth_header
string

This is going to be where we send the API key. The header will consist of a custom api key or standardised JWT auth.

Request Body schema: application/json
required
agentOidcId
string

OpenID of the agent performing the operation.

fileName
required
string

The filename of the document including the filename extension

mimeType
required
string
Enum: "application/pdf" "image/jpeg" "image/tiff"

The MIME type of the document according to IANA

content
required
string <byte>

The file content as a base64-encoded string

digest
string

A digest (checksum) of the tile content

cardId
string

Unique identifier of a card that is not the PAN and is not to be classified as account data or PII

cardholderId
string

Unique identifier for a cardholder that is not to be classified as account data or PII

caseId
string

The amiko-internal identifier for a chargeback case

source
required
string
Enum: "acquirer" "issuer" "unknown"
parentDocumentId
string

The unique identifier for the document (used to retrieve the actual file)

Responses

Request samples

Content type
application/json
{
  • "agentOidcId": "string",
  • "fileName": "myfile.pdf",
  • "mimeType": "application/pdf",
  • "content": "string",
  • "digest": "string",
  • "cardId": "b8ba25f3-c945-4ed0-9d4d-e3153a0dd048",
  • "cardholderId": "2bd52a45-129d-4723-9143-e1c5b5ed34e7",
  • "caseId": "1234",
  • "source": "acquirer",
  • "parentDocumentId": "50c23df4-c8b3-4860-89d2-2d9b2a43b009"
}

Response samples

Content type
application/json
{
  • "documentId": "50c23df4-c8b3-4860-89d2-2d9b2a43b009",
  • "mimeType": "application/pdf",
  • "filename": "myfile.pdf"
}

Returns the document object for a given documentId.

Returns the exact same data as submitted when storing the document.

path Parameters
documentId
required
string
header Parameters
tracing-id
required
string

Tracing ID that can be used to track interactions.

bank-case-id
string

Issuer case ID for crossreferencing with issuer systems.

auth_header
string

This is going to be where we send the API key. The header will consist of a custom api key or standardised JWT auth.

Responses

Response samples

Content type
application/json
{
  • "fileName": "myfile.pdf",
  • "mimeType": "application/pdf",
  • "content": "string",
  • "cardId": "b8ba25f3-c945-4ed0-9d4d-e3153a0dd048",
  • "cardholderId": "2bd52a45-129d-4723-9143-e1c5b5ed34e7",
  • "caseId": "1234",
  • "digest": "string",
  • "source": "acquirer"
}

Delete a document stored under a existing documentId

Deletes a document stored under a existing documentId. Amiko will only allow users to delete documents if the document has been uploaded by mistake and the document has not yet been submitted to the card schemes. Documents provided directly by the cardholder can't be deleted by the user. If an Issuer Bank can't offer the delete operation, amiko will just drop the documentId from the database making the document inaccessible from amiko but won't be able to remove it from the document store.

path Parameters
documentId
required
string
header Parameters
tracing-id
required
string

Tracing ID that can be used to track interactions.

bank-case-id
string

Issuer case ID for crossreferencing with issuer systems.

auth_header
string

This is going to be where we send the API key. The header will consist of a custom api key or standardised JWT auth.

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Utility

Returns the health status for this API

The specification is based on the IETF draft linked below. Its content consists of a single mandatory root field (“status”) and several optional fields. Health Check Response Format for HTTP APIs: https://inadarei.github.io/rfc-healthcheck/

header Parameters
auth_header
string

This is going to be where we send the API key. The header will consist of a custom api key or standardised JWT auth.

Responses

Response samples

Content type
application/json
{
  • "status": "fail"
}