API docs by Redocly

Issuer Bank Integration APIs - Booking API (2025.4.0)

Download OpenAPI specification:Download

Operations exposed by the Issuer Bank for amiko to submit booking events.

Booking Request

Submitting booking events

Submit a cardholder accounts adjustment or write-off booking event including the relevant booking data (e.g. type of booking, amount) as well as meta-data defining the context and reason of the booking.

header Parameters
tracing-id
required
string

Tracing ID that can be used to track interactions.

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

A JSON object containing the booking event and booking meta-data

agentOidcId
string

OpenID of the agent performing the operation.

amikoBookingId
required
string <uuid>

Unique identifier for the booking generated by amiko

amikoCaseType
required
string
Enum: "cardholder_dispute" "fraud"

Type of amiko case. Can be fraud or cardholder dispute.

bookingAmount
string

Optional field, contains the partial booking amount if isFullAmount = false. E.g. 123.45

isFullAmount
required
boolean

Whether the booking amount is equal to the amount of the related transaction or if it is a partial amount

bookingAmountPercentage
string

Deprecated param, will be removed in future versions

currencyCode
string

Optional field, contains the partial booking currency provided as a three digit code based on ISO 4217:2015 if isFullAmount = false. E.g. the currencyCode for U.S. dollar is 840

currencyCodeAlpha
string

Optional field, contains the partial booking currency provided as a three letter code based on ISO 3166/1 if isFullAmount = false. E.g. the currencyCodeAlpha for U.S. dollar is USD

cardId
required
string

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

bookingTarget
required
string
Enum: "card_account" "general_ledger"

The target ledger of the booking, which is either Card Account or General Ledger (for write-off)

bookingOperation
required
string
Enum: "credit" "debit" "write_off" "write_off_reversal"

The type of booking, which for Card Account is either "credit" or "debit" and for General Ledger is either "write_off" or "write_off_reversal"

bookingReason
required
string
Enum: "credit_permanent_refund" "credit_temporary_refund" "debit_cardholder_deductible" "debit_cardholder_liability" "debit_direct_merchant_credit" "write_off_goodwill" "write_off_handling_mistake" "write_off_issuer_liability" "write_off_issuer_policy" "write_off_reversal_cardholder_liability" "write_off_reversal_direct_merchant_credit"

The reason for this booking. For more information on the possible combinations of target, operation and reasons, see documentation.

disputeReasonCode
string
Enum: "4880" "4863" "4840" "4855" "4859" "4841" "4860" "4831" "4842" "4846" "4807" "4812" "4808" "4853" "4837" "4849" "4870" "4871" "4834" "4850" "4999" "2001" "2002" "2003" "2004" "2005" "2008" "2011" "2700" "2701" "2702" "2703" "2704" "2705" "2706" "2707" "2708" "2709" "2710" "2713" "2870" "2871" "10.1" "10.2" "10.3" "10.4" "10.5" "11.1" "11.2" "11.3" "12.1" "12.2" "12.3" "12.4" "12.5" "12.6.1" "12.6.2" "12.7" "13.1" "13.2" "13.3" "13.4" "13.5" "13.6" "13.7" "13.8" "13.9"

An optional field that if applicable in this context contains the dispute reason code related to this booking. Example values: "4837" "13.9"

transactionLifecycle
required
string
Enum: "dispute_rejected" "dispute_reversed" "dispute_submitted" "dispute_pending" "outgoing_arbitration_lost_failed" "outgoing_arbitration_rebutted" "outgoing_arbitration_submitted" "outgoing_arbitration_withdrawn" "outgoing_arbitration_won" "outgoing_case_filing_escalated" "outgoing_case_filing_lost_failed" "outgoing_case_filing_rejected" "outgoing_case_filing_submitted" "outgoing_case_filing_withdrawn" "outgoing_case_filing_won" "outgoing_compliance_lost_failed" "outgoing_compliance_rebutted" "outgoing_compliance_submitted" "outgoing_compliance_withdrawn" "outgoing_compliance_won" "outgoing_pre_arbitration_lost_failed" "outgoing_pre_arbitration_rejected" "outgoing_pre_arbitration_submitted" "outgoing_pre_arbitration_withdrawn" "outgoing_pre_arbitration_won" "outgoing_pre_compliance_lost_failed" "outgoing_pre_compliance_rejected" "outgoing_pre_compliance_submitted" "outgoing_pre_compliance_withdrawn" "outgoing_pre_compliance_won" "pre_dispute_failed" "pre_dispute_pending" "pre_dispute_successful" "representment_or_dispute_response" "none" "incoming_arbitration_lost_failed" "incoming_arbitration_received" "incoming_arbitration_withdrawn" "incoming_arbitration_won" "incoming_case_filing_escalated" "incoming_case_filing_lost_failed" "incoming_case_filing_received" "incoming_case_filing_rejected" "incoming_case_filing_withdrawn" "incoming_case_filing_won" "incoming_compliance_lost_failed" "incoming_compliance_received" "incoming_compliance_withdrawn" "incoming_compliance_won" "incoming_pre_arbitration_lost_failed" "incoming_pre_arbitration_received" "incoming_pre_arbitration_rejected" "incoming_pre_arbitration_withdrawn" "incoming_pre_arbitration_won" "incoming_pre_compliance_lost_failed" "incoming_pre_compliance_received" "incoming_pre_compliance_rejected" "incoming_pre_compliance_withdrawn" "incoming_pre_compliance_won"

Provides the information about the life-cycle stage of the dispute, if no action has been taking before the booking the stage is "none". Values incoming/outgoing-case-filing-* are sent instead of more detailed statuses only if legacy lifecycle support is enabled.

bookingReference
required
Array of strings

A list of issuerBookingId that amiko received in response to previous booking request. If no previous issuerBookingId is available this can be an empty list.

required
object
issuerWriteOffReason
string

Responses

Request samples

Content type
application/json
{
  • "agentOidcId": "61f925fa-653b-46f0-9117-d03040e9b775",
  • "amikoBookingId": "37b48334-3ad1-43e3-aa84-26075e513683",
  • "amikoCaseType": "fraud",
  • "bookingAmount": "100.35",
  • "isFullAmount": true,
  • "bookingAmountPercentage": "94.450000",
  • "currencyCode": "840",
  • "currencyCodeAlpha": "USD",
  • "cardId": "b8ba25f3-c945-4ed0-9d4d-e3153a0dd048",
  • "bookingTarget": "card_account",
  • "bookingOperation": "credit",
  • "bookingReason": "credit_temporary_refund",
  • "disputeReasonCode": "4880",
  • "transactionLifecycle": "dispute_submitted",
  • "bookingReference": [
    ],
  • "transaction": {
    },
  • "issuerWriteOffReason": "string"
}

Response samples

Content type
application/json
{
  • "status": "failed",
  • "amikoBookingId": "37b48334-3ad1-43e3-aa84-26075e513683",
  • "issuerBookingId": "id_provided_by_ledger",
  • "failure": {
    }
}

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/

Responses

Response samples

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