Transactions

October 30, 2024

Get a list of your transactions with helpful information for your operation. Apply filters for better results.

This service is available for integrations via Cloud terminal API, App-to-app, Terminal SDK and Raw card-present API.

Environments

Make any adjustments to your system by testing in a dev development environment. Remember that no real transactions will be processed in this environment.

When ready, you can switch to the live environment to process real transactions.

Environment	Base Url	Availability
`dev`	https://valquiria.billpocket.dev	Cloud Terminal API, App to app and Terminal SDK
`dev`	https://api-uat.kushkipagos.com	Raw Card-Present API
`live`	https://valquiria.billpocket.com	Cloud Terminal API, App to app y Terminal SDK
`live`	https://api.kushkipagos.com	Raw Card-Present API

Cloud terminal API, App to app and Terminal SDK

Token

It is necessary to generate an application token through the Get token endpoint to request the API. If the request is correct, you will obtain the application token, which you must use when obtaining the transaction list.

Token request example:

{
  "token": "48d8fc2257eb61d4814e9cae3fd7385dfedf51133017b35f7a86d113620da413"
}

Response example:

{
  "token": "eyJhbGciOiJIUzI1NiIsInC5cCI6LppXVCJ9.eyJ1c2VyX3Rva2VuIjoiNDhkOGZjMjI1N2VjNjFkNDgzNGU5Y2FlM2ZkNzM4NgRmXWRmNTExOTQ8MTdiMzVmN2E4NmQxMTM2MjBkYTQxMyIsImlhdCI6MTY5NDQ3Mjc2NywiZXhwIjoxNak0NDb2Mzs3fQ.KWgOEItUQhjWQR1gp8-lU1CjugQCVRMd4_lHXGGkDac"
}

Please review the api reference for more information.

Transaction list

Get the list of transactions in a specific date range. By default, 100 items are returned per request but you can configure up to a maximum of 600 items per request. Transactions are ordered by most recent first.

Call the Get transaction list or Get transaction list v2 endpoint by sending your application token in the Authorization header and setting the filters as parameters in the url.

Discover all the filters you can set when sending a request to obtain the list of transactions.

V1:

Property	Required	Allowed values	Description
dateFrom	Yes		Find transactions from a specific date. yyyy-mm-ddthh:mm:ss format.
dateTo	Yes		Find transactions up to a specific date. yyyy-mm-ddthh:mm:ss format.
bin	No		Filter by BIN number.
captureMethod	No	`ec`, `emvf`, `nfc`, `msc`, `key`, `rec`,	Filter by capture method.
card	No		Filter by masked card number.
device	No		Filter by device name.
page	No		Indicates the page number of the results.
size	No		Number of transactions to return. Default: 100. Max: 600.
transactionStatus	No	`aprobada`, `pendiente`, `rechazadaRiesgo`, `rechazada`, `rechazadaProsa`	Filter by transaction status.
transactionType	No	`venta`, `devolucion`, `checkout`	Filter by transaction type.
transactionId	No		Filter by transaction ID.
reference	No		Filter by transaction reference.

V2:

Property	Required	Allowed values	Description
dateFrom	Yes		Find transactions from a specific date. yyyy-mm-ddthh:mm:ss format.
dateTo	Yes		Find transactions up to a specific date. yyyy-mm-ddthh:mm:ss format.
bin	No		Filter by BIN number.
captureMethod	No	`ec`, `emvf`, `nfc`, `msc`, `key`, `rec`,	Filter by capture method.
card	No		Filter by masked card number.
device	No		Filter by device name.
page	No		Indicates the page number of the results.
size	No		Number of transactions to return. Default: 100. Max: 600.
transactionStatus	No	`aprobada`, `pendiente`, `rechazadaRiesgo`, `rechazada`, `rechazadaProsa`	Filter by transaction status.
transactionType	No	`venta`, `devolucion`, `checkout`	Filter by transaction type.
transactionId	No		Filter by transaction ID.
reference	No		Filter by transaction reference.
uniqueReference	No		Filter by unique identifier per transaction generated on the client side to avoid duplicates. For example, UUID. App version 5.0.3 or higher is required to receive this property via Cloud Terminal API integrations.

Example of request with filters:

https://valquiria.billpocket.dev/api/v1/transactions/?dateFrom=2022-01-11T10:20:00&dateTo=2023-06-20T11:59:00&size=4&page=2&device=test&bin=557908&captureMethod=ec&transactionStatus=rechazadaRiesgo&transactionType=devolucion&card=310583******5037

Response

If the information submitted is correct and there are transactions in the specified range, you will receive an item with the list of available transactions.

Successful request example:

V1:

{
  "data": [
    {
      "transaction_id": 194402170,
      "authorization_number": "",
      "bank": "BANCOMER",
      "card_brand": "Visa",
      "card_type": "DEBIT",
      "capture_method": "nfc",
      "commission": 0.88,
      "countercharged": false,
      "date": "2024-05-14T10:40:57.000Z",
      "details": "Prueba 2",
      "device": "Test device 0001",
      "error_detail": "Transacción no procesada. Fondos insuficientes. Contactar al emisor",
      "masked_card": "424242******4242",
      "msi": null,
      "retention": 0,
      "rejection_code": "51",
      "subtotal": 23.98,
      "surcharge": 0,
      "tip": 0,
      "total_amount": 25,
      "transaction_type": "venta",
      "transaction_status": "rechazadaProsa",
      "vat": 0.14
    },
    {
      "transaction_id": 105242,
      "authorization_number": "BP4460",
      "bank": "BANCOMER",
      "card_brand": "Visa",
      "card_type": "CREDIT",
      "capture_method": "ec",
      "commission": 8.94,
      "countercharged": false,
      "date": "2022-03-11T13:48:12.000Z",
      "details": "Prueba 1",
      "device": "ECOMMDEV01",
      "error_detail": "",
      "masked_card": "424242******4242",
      "msi": null,
      "retention": 0.93,
      "rejection_code": null,
      "subtotal": 437.71,
      "surcharge": 0,
      "tip": 0,
      "total_amount": 449,
      "transaction_type": "venta",
      "transaction_status": "aprobada",
      "vat": 1.43
    }
  ],
  "currentPage": 1,
  "perPage": 4,
  "total": 456
}

V2:

{
  "data": [
    {
      "msi": null,
      "tip": 0,
      "vat": 0.08,
      "bank": null,
      "date": "2024-07-11T16:53:29.000Z",
      "device": "Device 1",
      "details": null,
      "cardType": null,
      "subtotal": 13.48,
      "cardBrand": "Visa",
      "retention": 0,
      "surcharge": 0,
      "chargeback": false,
      "commission": 0.49,
      "maskedCard": "400000******0002",
      "errorDetail": "",
      "totalAmount": 14.05,
      "captureMethod": "msc",
      "rejectionCode": null,
      "transactionId": 130001,
      "transactionType": "devolucion",
      "uniqueReference": "3740d203-c6fb-46fb-83f5-6b29c9195fa8",
      "transactionStatus": "pendiente",
      "authorizationNumber": ""
    },
    {
      "msi": null,
      "tip": 0,
      "vat": 0.08,
      "bank": null,
      "date": "2024-07-11T16:46:18.000Z",
      "device": "Device 1",
      "details": null,
      "cardType": "CREDIT",
      "subtotal": 13.48,
      "cardBrand": "Visa",
      "retention": 0,
      "surcharge": 0,
      "chargeback": false,
      "commission": 0.49,
      "maskedCard": "400000******0002",
      "errorDetail": "",
      "totalAmount": 14.05,
      "captureMethod": "msc",
      "rejectionCode": null,
      "transactionId": 130002,
      "transactionType": "venta",
      "uniqueReference": "2d20aa4b-a26e-4117-90a0-9b0c0d9a19e1",
      "transactionStatus": "aprobada",
      "authorizationNumber": "BP6001"
    },
    {
      "msi": null,
      "tip": 0,
      "vat": 0.56,
      "bank": null,
      "date": "2024-07-11T15:09:44.000Z",
      "device": "ECOMMDEV00061529",
      "details": null,
      "cardType": null,
      "subtotal": 95.94,
      "cardBrand": "Visa",
      "retention": 0,
      "surcharge": 0,
      "chargeback": false,
      "commission": 3.5,
      "maskedCard": "400000******0002",
      "errorDetail": "Rechazo por reglas internas",
      "totalAmount": 100,
      "captureMethod": "ec",
      "rejectionCode": null,
      "transactionId": 130003,
      "transactionType": "devolucion",
      "uniqueReference": "",
      "transactionStatus": "rechazada",
      "authorizationNumber": ""
    }
  ],
  "total": 31,
  "perPage": 100,
  "currentPage": 1
}

Example of failed request (V1 and V2):

{
  "message": [
    "dateTo is required"
  ]
}

Please review the Transactions reference for more information.

Raw card-present API

Transaction list

Get the list of transactions by setting the number of items to return and the results page (if there are multiple). Maximum 10,000 results returned per request.

Consume the Transaction Search endpoint by sending your private key in the Private-Credential-Id header and setting the necessary filters in the request body.

Discover all the filters you can set when sending a request to obtain the list of transactions.

Property	Required	Allowed values	Description
page	Yes		Set the page number of the results.
size	Yes		Set the number of items returned per request. Maximum 500 items per page.
filters.bin	No		Filter by BIN number.
filters.client_transaction_id	No		Filter by transaction id generated on your side.
filters.start_date	No		Find transactions from a specific date.
filters.end_date	No		Find transactions up to a specific date.
filters.last_four_digits	No		Filter by the last 4 digits of the card.
filters.transaction_reference	No		Filter by transaction id (generated by Kushki).
filters.transaction_type	No	`balanceInquiry`, `capture`, `charge`, `checkIn`, `checkout`, `preAuth`, `reAuthorization`, `tip`, `posTip`	Filter by operation type.

Example of request with filters:

{
  "page": 1,
  "size": 10,
  "filters": {
    "bin": "541333",
    "end_date": 1712322035152,
    "start_date": 1712286000000,
    "last_four_digits": "0653",
    "transaction_type": "preAuth",
    "client_transaction_id": "5bba557f-3df8-4f07-be20-ed1ad6b28c1d",
    "transaction_reference": "62c64ab2-1b09-48bd-ab98-4fa9b1893250"
  }
}

Response

If the information submitted is correct and there are transactions in the specified range, you will receive an item with the list of available transactions:

{
  "items": [
    {
      "amount": {
        "extra_taxes": {}
      },
      "deferred": {},
      "merchant_id": "20000000106781760000",
      "pos_details": {},
      "reading_type": "ICC",
      "payment_brand": "VISA",
      "transaction_type": "PREAUTH",
      "transaction_status": "DECLINED",
      "transaction_reference": "Test_Webhook_PREAUTH_D"
    }
  ]
}

Please review the Transactions reference for more information.

Cancel payments

Cancel a previously authorized payment.