Webhook for One-Time Payments in Cash

August 03, 2023

Cash

Kushki can send events to the webhook notifying your application in case an authorization is required for accepting a payment made after the deadline (Preauthorization) or to notify the time when your customer made a payment correctly (Payment Notification).

Payment Notification

Structure

The webhooks sent by Kushki will contain the headers listed here.
These are the possible variables that are submitted in the webhook body:

Method: POST

Body: Object

Variable	Type
`ticketNumber`	`string`
`token`	`string`
`totalAmount`	`number`
`amount`	`object`
`amount.iva`	`number`
`amount.subtotalIva`	`number`
`amount.subtotalIva0`	`number`
`amount.extraTaxes`	`object`
`amount.extraTaxes.agenciaDeViajes`	`number`
`amount.extraTaxes.iac`	`number`
`amount.extraTaxes.propina`	`number`
`amount.extraTaxes.tasaAeroportuaria`	`number`
`currency`	`string`
`created`	`number (Unix Timestamp Format)`
`expiration`	`number (Unix Timestamp Format)`
`status`	`"approvedTransaction" "declinedTransaction" "expiredTransaction"`
`identification`	`string`
`name`	`string`
`lastName`	`string`
`merchantId`	`string`
`merchantName`	`string`
`processorName`	`string`
`processorId`	`string`
`transactionId`	`string`
`completedAt`	`number (Unix Timestamp Format)`
`metadata`	`object`
`metadata.key0`	`string`
`metadata.key1`	`string`
`description`	`string`
`pin`	`string`
`email`	`string`
`documentType`	`string`

Examples

JSON
JSON

// Approved Transaction
{
  "country": "Colombia",
  "lastName": "Castro",
  "ticketNumber": "2302011714922359",
  "amount": {
    "subtotalIva0": 49.99,
    "iva": 0,
    "subtotalIva": 0
  },
  "completedAt": 1602011733626,
  "documentType": "CC",
  "created": 1602011714779,
  "processorType": "gateway",
  "description": "Description of the payment",
  "transactionId": "aaa6c0ce-bd05-4df2-9012-833fa32efa84",
  "merchantName": "Tu Gran Empresa",
  "token": "150af7fa762246cc96572d825e3771f6",
  "totalAmount": 49.99,
  "identification": "123456789",
  "processorId": "6000000000XXXXXXXXXXXX50336197",
  "pin": "2011731304",
  "merchantId": "20000000*******2000",
  "name": "Juan",
  "currency": "COP",
  "expiration": 1602025005000,
  "processorName": "Banco Bogota Processor",
  "email": "kushki@kushkipagos.com",
  "status": "approvedTransaction",
  "transactionReference": "aaa6c0ce-bd05-4df2-9012-833fa32efa84"
}

// Expired Transaction
{
  "country": "Colombia",
  "lastName": "Castro",
  "ticketNumber": "2302010277786922",
  "amount": {
    "subtotalIva0": 49.99,
    "iva": 0,
    "subtotalIva": 0
  },
  "completedAt": 1602010834213,
  "documentType": "CC",
  "created": 1602010277778,
  "processorType": "gateway",
  "description": "Description of the payment",
  "transactionId": "0cbe6419-9bc0-46a0-be78-fc81c5c18dea",
  "merchantName": "Tu Gran Empresa",
  "token": "8220ed4ea9fb407abdcfff87ab0f406c",
  "totalAmount": 49.99,
  "identification": "9999999999",
  "processorId": "6000000000XXXXXXXXXXXX50336197",
  "pin": "2010319472",
  "merchantId": "20000000*******2000",
  "name": "Juan",
  "currency": "COP",
  "expiration": 1602010319000,
  "processorName": "Banco Bogota Processor",
  "email": "kushki@kushkipagos.com",
  "status": "expiredTransaction",
  "transactionReference": "0cbe6419-9bc0-46a0-be78-fc81c5c18dea"
}

Preauthorization

Kushki can send webhook events notifying your application at the time when your authorization is required to obtain a payment (Preauthorization).

This event occurs when the user tries to make a payment after the reference has expired. At that time, you will be notified that the user wishes to pay a certain reference, and one of the following responses will be required from you according to your decision.

StatusCode	Event Description	Object
200	Payment is authorized for collection	`null`
418	Payment cannot be collected	`Code (KSH1,KSH2 O KSH3)` `message` `(NOTFOUND,PAID,EXPIRED)`

An example of a response would be as follows:

{
  "statuscode": "418",
  {
    "code": "KSH3",
    "message": " EXPIRED"
  }
}

These are the possible variables that are submitted in the webhook body:

Method: POST

Body: Object

Variable	Type
`ticketNumber`	`string`
`token`	`string`
`totalAmount`	`number`
`amount`	`object`
`amount.iva`	`number`
`amount.subtotalIva`	`number`
`amount.subtotalIva0`	`number`
`amount.extraTaxes`	`object`
`amount.extraTaxes.iac`	`number`
`amount.extraTaxes.propina`	`number`
`amount.extraTaxes.tasaAeroportuaria`	`number`
`currency`	`string`
`created`	`number (Timestamp format)`
`expiration`	`number (Timestamp format)`
`status`	`"initializedTransaction" "expiredTransaction"`
`identification`	`string`
`name`	`string`
`lastName`	`string`
`merchantId`	`string`
`merchantName`	`string`
`processorName`	`string`

Example

// Initialized Transaction
{
  "ticketNumber": "2301998764353705",
  "currency": "COP",
  "processorType": "gateway",
  "totalAmount": 49.99,
  "documentType": "CC",
  "lastName": "Castro",
  "status": "initializedTransaction",
  "created": 1601998764347,
  "expiration": 1601998890000,
  "merchantName": "Tu Gran Empresa",
  "email": "kushki@kushkipagos.com",
  "country": "Colombia",
  "transactionId": "a116a500-feec-44c5-b89f-46595f70c904",
  "name": "Juan",
  "token": "0cfb89f23afd46b8ac7e461569e308e8",
  "pin": "1998868506",
  "identification": "1718171671",
  "amount": {
    "iva": 0,
    "subtotalIva": 0,
    "subtotalIva0": 49.99
  },
  "processorName": "Banco Bogota Processor",
  "description": "Description of the payment",
  "processorId": "6000000000XXXXXXXXXXXX50336197",
  "merchantId": "20000000*******2000"
}