Webhook for One-Time Payments Made with a Card

Kushki can send webhook events notifying your application when one of the following events occurs:

  • When a credit or debit card transaction is approved or rejected.
  • When a cancellation or credit card refund is approved

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

VariableType
ticket_numberstring
transaction_idstring
transaction_referencestring
amountobject
amount.subtotalIva0number
amount.subtotalIvanumber
amount.ivanumber
amount.icenumber
amount.currencystring
metadataobject
metadata.key0string
metadata.key1string
metadata.key2string
currency_codestring
transaction_type"SALE"
transaction_status"APPROVAL" "DECLINED"
creatednumber (Unix Timestamp Format)
sync_modestring
merchant_idstring
processor_idstring
processor_namestring
last_four_digitsstring
approval_codestring
request_amountnumber
approved_transaction_amountnumber
subtotal_iva0number
subtotal_ivanumber
iva_valuenumber
countrystring
processor_typestring
response_codestring
card_holder_namestring
payment_brandstring
fullResponsenumber
token_typestring
maskedCardNumberstring
transaction_detailsobject
transaction_details.cardTypestring
transaction_details.binCardstring
transaction_details.processorBankNamestring
transaction_details.isDeferredstring
issuing_bankstring
foreign_cardboolean
response_textstring
ipstring
merchant_namestring
acquirerBankstring
card_typestring
tokenstring
credential_aliasstring
processor_bank_namestring
bin_cardstring
ice_valuestring
credential_idstring
processorCodestring
processorobject
processor.codestring
processor.messagestring
channelstring

Examples

  • JSON
  • JSON
// Approved transaction
{
"country": "Colombia",
"metadata": {
"contractID": "157AB"
},
"processor_type": "gateway",
"response_code": "000",
"transaction_status": "APPROVAL",
"card_holder_name": "TESTING",
"payment_brand": "Visa",
"request_amount": 16.98,
"fullResponse": true,
"merchant_id": "20000000XXXXXXXX2000",
"approved_transaction_amount": 16.98,
"productDetails": {
"product": [
{
"quantity": 1,
"price": 6990000,
"id": "198952AB",
"sku": "10101042",
"title": "eBook Digital Services"
},
{
"quantity": 1,
"price": 9990000,
"id": "198953AB",
"sku": "004834GQ",
"title": "eBook Virtual Selling"
}
]
},
"token_type": "transaction-token",
"maskedCardNumber": "438626XXXXXX7714",
"currency_code": "USD",
"transaction_details": {
"cardType": "Visa",
"binCard": "438626",
"processorBankName": "0032~BANCO INTERNACIONAL",
"isDeferred": "N"
},
"subtotal_iva": 0,
"issuing_bank": null,
"processor_id": "6000000000158776275865741143200",
"processor_name": "Credibanco Processor",
"foreign_card": true,
"response_text": "Transacción aprobada",
"transaction_reference": "55d28261-c446-4592-a8d6-17c20aee3bb0",
"last_four_digits": "7714",
"user_agent": "Go-http-client/1.1",
"transaction_id": "781482485839103928",
"approval_code": "000000",
"amount": {
"subtotalIva0": 16.98,
"iva": 0,
"subtotalIva": 0,
"currency": "USD",
"ice": 0
},
"created": 1601587937000,
"ip": "35.193.164.95",
"iva_value": 0,
"merchant_name": "Tu Gran Empresa",
"contact_details": {
"firstName": "Diego",
"lastName": "Cadena",
"phoneNumber": "0988734644",
"documentType": "CC",
"documentNumber": "1009283738",
"email": "test@test.com"
},
"acquirerBank": null,
"card_type": null,
"ticket_number": "992823152575262637",
"transaction_type": "SALE",
"token": "fca0fe160b5048aca584e30fbf652edf",
"sync_mode": "online",
"orderDetails": {
"billingDetails": {
"country": "Ecuador",
"zipCode": "170402",
"address": "Eloy Alfaro 139 y Catalina Aldaz",
"city": "Quito",
"phone": "0988734644",
"name": "Diego Cadena",
"region": "Pichincha"
},
"shippingDetails": {
"country": "Ecuador",
"zipCode": "170402",
"address": "Eloy Alfaro 139 y Catalina Aldaz",
"city": "Quito",
"phone": "0988734644",
"name": "Diego Cadena",
"region": "Pichincha"
},
"siteDomain": "tuebook.com"
},
"credential_alias": "Kushki Test",
"processor_bank_name": "0032~BANCO INTERNACIONAL",
"bin_card": "438626",
"ice_value": 0,
"credential_id": "b18653307844446bbfcb4783d2711a47",
"subtotal_iva0": 16.98,
"transactionReference": "55d28261-c446-4592-a8d6-17c20aee3bb0"
}
// Declined transaction
{
"country": "Colombia",
"metadata": {
"contractID": "157AB"
},
"processor_type": "gateway",
"response_code": "017",
"transaction_status": "DECLINED",
"card_holder_name": "TESTING",
"payment_brand": "Visa",
"request_amount": 16.98,
"fullResponse": true,
"merchant_id": "20000000XXXXXXXX2000",
"approved_transaction_amount": 0,
"productDetails": {
"product": [
{
"quantity": 1,
"price": 6990000,
"id": "198952AB",
"sku": "10101042",
"title": "eBook Digital Services"
},
{
"quantity": 1,
"price": 9990000,
"id": "198953AB",
"sku": "004834GQ",
"title": "eBook Virtual Selling"
}
]
},
"maskedCardNumber": "434900XXXXXX7015",
"currency_code": "USD",
"transaction_details": {
"cardType": "Visa",
"binCard": "434900",
"processorBankName": "0032~BANCO INTERNACIONAL",
"isDeferred": "N"
},
"subtotal_iva": 0,
"issuing_bank": "BANCO DE LA PRODUCCION S.A. (PRODUBANCO)",
"processor_id": "6000000000XXXXXXXXXXXXXXXXX3200",
"processor_name": "Credibanco Processor",
"foreign_card": true,
"response_text": "Tarjeta no válida",
"transaction_reference": "abe4a9a6-0a80-4156-aeb1-77efd422c3f7",
"last_four_digits": "7015",
"transaction_id": "398726433762481304",
"approval_code": null,
"amount": {
"subtotalIva0": 16.98,
"iva": 0,
"subtotalIva": 0,
"currency": "USD",
"ice": 0
},
"created": 1601651651000,
"ip": "1.1.1.1",
"iva_value": 0,
"merchant_name": "Tu Gran Empresa",
"contact_details": {
"firstName": "Diego",
"lastName": "Cadena",
"phoneNumber": "+593988734644",
"documentType": "CC",
"documentNumber": "1009283738",
"email": "test@test.com"
},
"acquirerBank": null,
"card_type": "CREDIT",
"transaction_type": "SALE",
"processor": {
"code": "K006",
"message": "Transacción declinada."
},
"token": "43764c2dca3042dda127ffe8f1194488",
"sync_mode": "online",
"orderDetails": {
"billingDetails": {
"country": "Ecuador",
"zipCode": "170402",
"address": "Eloy Alfaro 139 y Catalina Aldaz",
"city": "Quito",
"phone": "+593988734644",
"name": "Diego Cadena",
"region": "Pichincha"
},
"shippingDetails": {
"country": "Ecuador",
"zipCode": "170402",
"address": "Eloy Alfaro 139 y Catalina Aldaz",
"city": "Quito",
"phone": "+593988734644",
"name": "Diego Cadena",
"region": "Pichincha"
},
"siteDomain": "tuebook.com"
},
"credential_alias": "Kushki Test",
"processor_bank_name": "0032~BANCO INTERNACIONAL",
"bin_card": "434900",
"ice_value": 0,
"processorCode": null,
"credential_id": "b18653307844446bbfcb4783d2711a47",
"subtotal_iva0": 16.98,
"transactionReference": "abe4a9a6-0a80-4156-aeb1-77efd422c3f7"
}

Cancellation or Refund Notification

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

Method: POST

Body: Object

VariableType
ticketNumberstring
transactionIdstring
transactionReferencestring
amountobject
amount.subtotalIva0number
amount.subtotalIvanumber
amount.ivanumber
amount.icenumber
amount.currencystring
currencyCodestring
transactionType"VOID" "REFUND"
transactionStatus"APPROVAL"
creatednumber (Timestamp format)
syncModestring
merchantIdstring
processorIdstring
processorNamestring
lastFourDigitsstring
approvalCodestring
requestAmountnumber
approvedTransactionAmountnumber
countrystring
forceRefundboolean
processorTypestring
contactPersonstring
binCardstring
terminalIdstring
merchantNamestring
processorMerchantIdstring
uniqueCodestring
nitstring
idstring
emailstring
isSandboxTransactionboolean
foreignCardboolean
visibilitystring
cardHolderNamestring
paymentBrandstring
cardTypestring
voidTicketNumberstring
saleCreatednumber (Timestamp format)
saleTicketNumberstring
paymentMethodstring
saleApprovalCodestring
privateProcessorIdstring

Example

// Initialized Void
{
"country": "Colombia",
"ticketNumber": "661601925198724758",
"approvalCode": "000000",
"forceRefund": false,
"processorType": "gateway",
"partialVoid": false,
"contactPerson": "Kushki Test",
"binCard": "438626",
"terminalId": "123456",
"requestAmount": 16.98,
"merchantName": "Tu Gran Empresa",
"saleTransactionType": "SALE",
"processorId": "6000000000XXXXXXXXXXXXXXXX3200",
"processorMerchantId": "543210",
"uniqueCode": "12345",
"merchantId": "20000000XXXXXXXX2000",
"nit": "1234567780",
"syncMode": "api",
"processorName": "Credibanco Processor",
"id": "1e2c8522-82ce-498b-b653-1745d01fd330",
"saleTransactionReference": "55d28261-c446-4592-a8d6-17c20aee3bb0",
"email": "test@kushkipagos.com",
"isSandboxTransaction": true,
"amount": {
"subtotalIva0": 16.98,
"iva": 0,
"subtotalIva": 0,
"currency": "USD",
"ice": 0
},
"foreignCard": true,
"visibility": "hidden",
"cardHolderName": "TESTING",
"transactionReference": "1e2c8522-82ce-498b-b653-1745d01fd330",
"transactionStatus": "APPROVAL",
"created": 1601925217451,
"paymentBrand": "Visa",
"cardType": null,
"voidTicketNumber": "661601925198724758",
"saleCreated": 1601587937000,
"transactionId": "1601925217451279",
"token": "fca0fe160b5048aca584e30fbf652edf",
"saleTicketNumber": "992823152575262637",
"transactionType": "REFUND",
"lastFourDigits": "7714",
"paymentMethod": "card",
"approvedTransactionAmount": 16.98,
"currencyCode": "USD",
"saleApprovalCode": "000000",
"privateProcessorId": "6000000000XXXXXXXXXXXXXXXXX1092"
}