Card information

The Card Information endpoints give you lookup and query tools for Card Present flows: retrieve card type and deferred availability from a BIN, fetch instalment options for a specific card, and list transactions recorded on a POS terminal.

Endpoints at a glance

Endpoint	Purpose
`POST /pos/v1/bin`	BIN lookup — returns card type and deferred availability
`GET /deferred/v2/bin/{bin}`	Deferred options v2 — instalment types and months for a BIN
`GET /card/v1/deferred/{bin}`	Deferred options v1 — available instalment months for a BIN
`POST /pos/v1/transaction`	Transaction list — query transactions on a POS terminal

BIN lookup

Call POST /pos/v1/bin with the card BIN (first 6–8 digits) to know whether the card supports deferred payments before proceeding.

Request:

{
  "bin": "43810200",
  "pos_details": {
    "terminal_id": "T00000000000",
    "brand": "SUNMI",
    "model": "P2-EU",
    "version": "1.1.13"
  }
}

Response:

{
  "card_type": "debit",
  "country": "PER",
  "deferred": false
}

Response field	Description
`card_type`	`"credit"`, `"debit"`, or `"prepaid"`.
`country`	ISO 3166-1 alpha-3 of the card-issuing country.
`deferred`	`true` if the card supports deferred instalments.

Deferred options

Use these endpoints to retrieve the valid instalment configurations for a specific BIN before creating a deferred charge.

Credit cards only

Deferred options are only available for credit cards.

v2 — `GET /deferred/v2/bin/{bin}`

Returns card metadata together with deferred options.

GET /deferred/v2/bin/43810200
Public-Merchant-Id: <your-public-key>

Response fields:

Field	Description
`bank`	Issuing bank name.
`brand`	Card network (e.g., `"visa"`, `"mastercard"`).
`cardType`	`"credit"`, `"debit"`, or `"prepaid"`.
`country`	Card-issuing country.

v1 — `GET /card/v1/deferred/{bin}`

Returns the available deferred types and instalment months.

GET /card/v1/deferred/43810200
Public-Merchant-Id: <your-public-key>

Response example:

[
  {
    "months": ["2", "3", "4", "5", "6", "7"],
    "monthsOfGrace": [],
    "type": "all"
  }
]

Use the type and months values when constructing the deferred object in a charge request.

Transaction list

POST /pos/v1/transaction with transaction_type: "balanceInquiry" returns a list of transactions recorded on a POS terminal. Apply filters to narrow results.

WARNING

Returns a maximum of 10,000 transactions.

Request:

{
  "transaction_type": "balanceInquiry",
  "transaction_mode": "Authorization",
  "country": "PER",
  "amount": {
    "currency": "PEN",
    "subtotal_iva": 0,
    "subtotal_iva0": 0,
    "iva": 0
  },
  "pos_details": {
    "brand": "SUNMI",
    "model": "P2-EU",
    "version": "1.1.13",
    "has_print": true
  }
}

Response item fields:

Field	Description
`transaction_reference`	Merchant-side transaction reference.
`transaction_status`	`APPROVED`, `DECLINED`, etc.
`transaction_type`	Type of the original transaction.
`payment_brand`	Card network used.
`reading_type`	`ICC`, `MCR`, or `NFC`.
`amount`	Amount object with the transaction totals.
`deferred`	Deferred details, if applicable.
`merchant_id`	Merchant identifier.
`pos_details`	Terminal details.

Authentication

Endpoint	Header
`POST /pos/v1/bin`	`Private-Credential-Id: <your-private-credential>`
`POST /pos/v1/transaction`	`Private-Credential-Id: <your-private-credential>`
`GET /deferred/v2/bin/{bin}`	`Public-Merchant-Id: <your-public-key>`
`GET /card/v1/deferred/{bin}`	`Public-Merchant-Id: <your-public-key>`

Using the API

🟢 Production

🧪 Sandbox (UAT)

https://api.kushkipagos.com/

Available Endpoints

BIN Lookup

Query a card BIN to retrieve card type and deferred availability.

Deferred Options v2

Retrieve BIN metadata and available instalment configurations (v2).

Deferred Options v1

Retrieve available instalment months for a BIN (v1).

Transaction List

Query transactions recorded on a POS terminal with optional filters.

Got a suggestion on this documentation? Contact us.

Endpoints at a glance#

BIN lookup#

Deferred options#

v2 — GET /deferred/v2/bin/{bin}#

v1 — GET /card/v1/deferred/{bin}#

Transaction list#

Authentication#

Using the API#

Available Endpoints#

Endpoints at a glance

BIN lookup

Deferred options

v2 — `GET /deferred/v2/bin/{bin}`

v1 — `GET /card/v1/deferred/{bin}`

Transaction list

Authentication

Using the API

Available Endpoints