Subscription Transactions

The Subscription Transactions API returns the complete details of a subscription alongside the list of transactions charged against it. Use it to inspect billing history, audit individual charges, and build customer-facing payment dashboards.

Get Subscription Transactions

GET /data/v1/subscription/{subscriptionId}

Pass the subscriptionId as a path parameter. All other parameters are optional.

Path parameter

Parameter	Required	Description
`subscriptionId`	✅	Unique identifier of the subscription. Returned as `subscriptionId` when the subscription is created via `POST /subscriptions/v1/card`.

Query parameters

Parameter	Default	Description
`start`	5 days before the request	Start of the date range filter (`YYYY-MM-DD`). Only transactions created on or after this date are returned.
`end`	Moment of the request	End of the date range filter (`YYYY-MM-DD`). Only transactions created on or before this date are returned.
`size`	`100`	Maximum number of transactions to return. Must be a positive integer.

Example request:

GET /data/v1/subscription/177493387604666666?start=2026-01-01&end=2026-03-31&size=50
Private-Merchant-Id: <your-private-key>

Response structure

The response combines two sections: subscription metadata (static details about the subscription) and a transactions array (the charges executed within the requested date range).

Subscription metadata fields

Plan and schedule

Field	Description
`subscription_code`	Unique subscription identifier (same as `subscriptionId`)
`plan_name`	Name of the plan associated with the subscription
`active_indicator`	`true` if the subscription is currently active
`periodicity_type`	Charge frequency — see values below
`day_of_month`	Day of the month configured for the charge. `-2` for on-demand (`custom`) subscriptions
`day_of_week`	Day of the week for weekly charges. `"-"` when not applicable
`month`	Month configured for the charge. `"-"` when not applicable
`start_timestamp`	Unix timestamp (seconds) of the subscription's configured start date
`create_timestamp`	Unix timestamp (seconds) of when the subscription was created
`last_charge_timestamp`	Unix timestamp (seconds) of the most recent charge

periodicity_type values:

Value	Description
`daily`	Every day
`weekly`	Once a week
`biweekly`	Every two weeks
`monthly`	Once a month
`threefortnights`	Every three fortnights
`bimonthly`	Every two months
`quarterly`	Every three months
`fourmonths`	Every four months
`halfyearly`	Every six months
`yearly`	Once a year
`custom`	On-demand — charged manually via API

Card details

Field	Description
`card_holder_name`	Full name of the cardholder
`card_type`	`credit`, `debit`, or `prepaid`
`last_four_digit_code`	Last four digits of the registered card
`expiry_month` / `expiry_year`	Card expiration (MM / YY format)
`bin_info_object.bin`	First 6 digits of the card (BIN)
`bin_info_object.brand`	Card network brand (e.g., `VISA`, `MASTERCARD`)
`bin_info_object.bank`	Name of the card-issuing bank
`bin_info_object.info.type`	Card type from BIN database (`credit`, `debit`, `prepaid`)
`bin_info_object.info.country`	Issuing country — `alpha3` code and `name`
`bin_info_object.originalBinFullLength`	Full 8-digit BIN where available
`bin_info_object.validBin8`	Whether the 8-digit BIN was resolved successfully

Amount configuration

Field	Description
`amount_object.currency`	Always `COP` for Colombia
`amount_object.subtotalIva`	Subtotal subject to VAT
`amount_object.subtotalIva0`	Subtotal not subject to VAT
`amount_object.iva`	VAT amount
`amount_object.ice`	ICE tax amount

Contact and merchant

Field	Description
`contact_details_object.email`	Email address of the subscription owner
`contact_details_object.firstName` / `lastName`	Name of the subscription owner
`merchant_code`	Unique identifier of the merchant who owns the subscription
`merchant_country_name`	Country of the merchant
`provider_name`	Payment provider (always `kushki`)
`reference_transaction_code`	Reference code of the initial card validation transaction
`metadata_object`	Custom key-value metadata attached at subscription creation

`transactions` array fields

Each item in the transactions array represents one charge executed under the subscription.

Transaction identifiers

Field	Description
`ticket_code`	Unique Kushki ticket number for this charge
`transaction_code`	Unique transaction identifier assigned by Kushki
`reference_transaction_code`	UUID-based reference code
`recap_code`	Reconciliation code
`subscription_code`	The subscription this transaction belongs to
`approval_code`	Authorization code returned by the issuer
`response_code`	Processor response code. `"000"` = successful
`response_description`	Human-readable processor response (e.g., `"Transacción aprobada"`)

Transaction details

Field	Description
`create_timestamp`	Unix timestamp (milliseconds) of when the transaction was created
`transaction_type`	Type of transaction (e.g., `SALE`)
`transaction_status_type`	`APPROVED`, `DECLINED`, `INITIALIZED`, `VOIDED`, or `REFUNDED`
`subscription_trigger_type`	`onDemand` (manually triggered) or `scheduled` (automatic)
`payment_method_type`	Payment method — always `CARD` for subscription charges
`payment_submethod_type`	Payment sub-method (e.g., `CARD VPC`)
`payment_brand_name`	Card brand (e.g., `Visa`, `Mastercard`)
`sync_mode_type`	Processing mode — `online` or `offline`
`kushki_info_origin_type`	Always `SUBSCRIPTION` for subscription charges

Amount

Field	Description
`currency_code`	Always `COP` for Colombia
`request_amount`	Amount requested for this transaction
`approved_transaction_amount`	Total amount approved
`subtotal_iva_amount`	Subtotal subject to VAT
`subtotal_iva0_amount`	Subtotal not subject to VAT
`iva_value`	VAT applied to this transaction
`ice_value`	ICE tax applied to this transaction

Card and cardholder

Field	Description
`card_holder_name`	Cardholder name at the time of the transaction
`card_type`	`credit`, `debit`, or `prepaid`
`last_four_digit_code`	Last four digits of the card used
`bin_code`	BIN of the card used
`card_country_code`	ISO 3166-1 alpha-2 code of the card's issuing country
`card_country_name`	Full name of the card's issuing country
`foreign_card_indicator`	`true` if the card was issued outside Colombia
`prepaid_indicator`	`true` if the card is a prepaid card
`issuing_bank_name`	Name of the card-issuing bank
`acquirer_bank_name`	Name of the acquiring bank

Contact and merchant

Field	Description
`contact_detail.email`	Cardholder email at the time of the transaction
`contact_detail.first_name` / `last_name`	Cardholder name
`contact_detail.phone`	Cardholder phone in E.164 format
`contact_email`	Primary contact email (same as `contact_detail.email`)
`merchant_code`	Merchant identifier
`merchant_name`	Merchant display name
`country_name`	Country where the transaction was processed
`processor_name`	Payment processor that handled the transaction
`processor_type`	Processing model (e.g., `aggregator_formal`, `acquirer`)
`metadata_object`	Custom metadata attached at charge time (may include `fraudData`)
`subscription_metadata_object`	Metadata stored at the subscription level

Example Response

{
  "active_indicator": true,
  "subscription_code": "177493387604666666",
  "plan_name": "Plan mensual Colombia",
  "periodicity_type": "monthly",
  "day_of_month": 5,
  "card_holder_name": "Carlos Pérez",
  "card_type": "credit",
  "last_four_digit_code": "4321",
  "expiry_month": "09",
  "expiry_year": "27",
  "amount_object": {
    "currency": "COP",
    "subtotalIva0": 50000,
    "subtotalIva": 0,
    "iva": 0,
    "ice": 0
  },
  "contact_details_object": {
    "email": "carlos.perez@example.com",
    "firstName": "Carlos",
    "lastName": "Pérez"
  },
  "create_timestamp": 1760313600,
  "last_charge_timestamp": 1774459991,
  "merchant_code": "20000000106913436000",
  "merchant_country_name": "Colombia",
  "transactions": [
    {
      "ticket_code": "754812488659082161",
      "transaction_code": "526505389111678151",
      "transaction_status_type": "APPROVED",
      "transaction_type": "SALE",
      "subscription_trigger_type": "scheduled",
      "currency_code": "COP",
      "approved_transaction_amount": 50000,
      "request_amount": 50000,
      "iva_value": 0,
      "card_holder_name": "Carlos Pérez",
      "card_type": "credit",
      "last_four_digit_code": "4321",
      "payment_brand_name": "Visa",
      "response_code": "000",
      "response_description": "Transacción aprobada",
      "approval_code": "123456",
      "create_timestamp": 1774459991000
    }
  ],
  "pagination": null
}

Authentication

⚠️ Keep this credential secure. Never expose your Private-Merchant-Id in client-side or frontend code.

Using the API

🟢 Production

🧪 Sandbox (UAT)

https://api.kushkipagos.com/

Available Endpoints

Get Subscription Transactions

Returns the full details of a subscription and the list of transactions charged within the requested date range.

Got a suggestion on this documentation? Contact us.

Get Subscription Transactions#

Path parameter#

Query parameters#

Response structure#

Subscription metadata fields#

transactions array fields#

Example Response#

Authentication#

Using the API#

Available Endpoints#

Get Subscription Transactions

Path parameter

Query parameters

Response structure

Subscription metadata fields

`transactions` array fields

Example Response

Authentication

Using the API

Available Endpoints