Callback

Adding callback URL using "callbackURL" field to request body enables you to get POST request from SensePass on any transaction update events.

It is required to implement a POST endpoint on your server based on the same interface as #get-transaction-object-by-transaction-number

In event of communication error from SensePass to your server - SensePass will retry multiple times to call your server will the callback URL over a period of days.

Make sure the URL provided in "callbackURL" is fully accessible from the internet and does not contain local IP or private DNS.

SensePass IP's are dynamic - Limiting your endpoint to specific IP address is not possible.

Simple request example to create new transaction with callback URL data.

URL: /transactions/init

Request Body:

{
  "timeOut": 600,
  "amount": 200,
  "isCent": true,
  "currency": "USD",
  "deviceId": "2ooeww5ufzg3nkuf8a10gu5n695yolixlbgb042o03to9bxfkr7t815i5epu8o58jv1rznif3o1tr6xsb1rm",
  "callbackURL": "https://google.com/callback/api/callback"
}

Creating a new transaction object (Payment Request)

POST /transactions/init

This API creates new payment request based on the fields below.

Request Body

Name	Type	Description
amount*	number	The required amount for this transaction (Cents). If products are a part of the transaction - they are all summed up & calculated via the following formula: (amount + vat - discount) * quantity e.g. (10 + 1.7 - 1) * 2.
isCent	boolean	Determines if Amount represents in cents or not
timeOut	number	Time until the transaction will be timed out (seconds)
currency*	string	[ USD, CAD, ILS, EUR, RUB ]
deviceId	string	Terminal unique device ID provided by SensePass (For Device based Transactions) - Required if apiKey is empty
callbackURL	string	URL to your POST endpoint Interface: #get-transaction-object-by-transaction-number

200: OK OK

See Transactions entity schema: #transaction-entity

{
  "TransactionNumber": "14a4334a32c852aeb0cfae52cbff1314649da7f175a8e140b35c147c",
  "date": "2019-12-19T09:47:59.105Z",
  "amount": 1234.56,
  "currency": "ILS",
  "status": 0,
  "statusName": "Transaction Approved",
  "pos": "POS 3, Branch Tel Aviv",
  "posReceiptsEndpoint": "http://pay.sensepass-api.com/api/invoicesReceipts/receipt/save/hofai3478o8o78o4s849j3920ckj",
  "posData": {
    "foo": "bar",
    "hello": [
      "world"
    ]
  },
  "businessName": "Coffee Bar",
  "businessId": 144,
  "timeoutDate": "2019-12-19T09:47:59.105Z",
  "paymentMethodData": {
    "PaymentType": "Bit",
    "directAppLinks": {
      "iOSLink": "paymentsBIT://www.bitpay.co.il/app/bitcom-info",
      "androidLink": "intent://www.bitpay.co.il/app/bitcom-info;scheme=bit;package=com.bnhp.payments.paymentsapp;end",
      "qrURL": "https://www.bitpay.co.il/app/bitcom-info"
    }
  },
  "SMS": "Sent",
  "paymentCommit": {
    "messsage": "Payment commit is enabled for this transaction",
    "isPaymentCommitted": false,
    "secondsToCommit": 60,
    "commitLink": "https://pay.sensepass-api.com/api/transactions/commitPayment/ec2dc489d161aa27a803f48bcf5ffcf"
  },
  "products": [
    {
      "name": "Coffee",
      "quantity": 2,
      "amount": 100,
      "discount": 0,
      "posIdentifier": "1234A"
    },
    {
      "name": "Beer",
      "quantity": 1,
      "amount": 600,
      "discount": 0,
      "posIdentifier": "1234B"
    }
  ],
  "productSumMismatch": true,
  "confirmations": [
    {
      "paymentType": "Regular",
      "confirmationNumber": "063-d9j09YsY1",
      "fullConfirmationCode": "063-d9j09YsY1",
      "dateApproval": "2019-12-19T09:47:59.105Z",
      "installments": 1,
      "paymentMethodName": "PayPal",
      "approvedBy": "PayPal",
      "providerId": "uGfNuwEGiP18SUnTUEo1/atTdesDnhDhZ/8i7G9NAEg=",
      "requestID": "a4dbf66e-d3f1-4a29-baf7-2591424a9a0c",
      "authNumber": "123213dsf13111",
      "referenceNumber": "1778298289",
      "acquirer": "Visa",
      "voucher": "yyyAbnlmlfm1323",
      "lastFourDigits": "8858",
      "sensePassReferenceId": "34e209ea8b24cc831cf"
    }
  ],
  "confirmation": {
    "paymentType": "Regular",
    "confirmationNumber": "063-d9j09YsY1",
    "fullConfirmationCode": "063-d9j09YsY1",
    "dateApproval": "2019-12-19T09:47:59.105Z",
    "installments": 1,
    "paymentMethodName": "PayPal",
    "approvedBy": "PayPal",
    "providerId": "uGfNuwEGiP18SUnTUEo1/atTdesDnhDhZ/8i7G9NAEg=",
    "requestID": "a4dbf66e-d3f1-4a29-baf7-2591424a9a0c",
    "authNumber": "123213dsf13111",
    "referenceNumber": "1778298289",
    "acquirer": "Visa",
    "voucher": "yyyAbnlmlfm1323",
    "lastFourDigits": "8858",
    "sensePassReferenceId": "34e209ea8b24cc831cf"
  },
  "transactionPage": {
    "iOSLink": "https://mbeta.sensepass-api.com/orderSummary/027e4e48d59fdbe83f5a78cab62a53c676b7f111fa9d0ee0a36d1872",
    "androidLink": "https://mbeta.sensepass-api.com/orderSummary/027e4e48d59fdbe83f5a78cab62a53c676b7f111fa9d0ee0a36d1872",
    "qrURL": "https://mbeta.sensepass-api.com/orderSummary/027e4e48d59fdbe83f5a78cab62a53c676b7f111fa9d0ee0a36d1872"
  },
  "balance": 0
}

400: Bad Request Invalid Input

{
    // Response
}

500: Internal Server Error Internal Error

{
    // Response
}

Security - HMAC Signature

HMAC (Hash-based Message Authentication Code) signature authentication for callbacks is a security mechanism used to ensure the integrity and authenticity of a message between two systems.

This authentication logic will enables you to verify that the callback API call was originated by SensePass.

HMAC Verification steps:

1. Extract "HMAC-Random-Key" header from the callback API request

2. Concat the header from #1 to the request body

3. Perform HMAC 256 calculation with the concatenated string and using your secret HMAC key

4. Compare the result from #3 against the value of the request header "HMAC-Authorization"

Retries

Our system expects for 200-299 status code as an indication for a successful callback handling.

Failure to get these status codes triggers retries logic of 6 attempts with these intervals:

1. 15 seconds

2. 60 seconds

3. 120 seconds

4. 600 seconds

5. 2000 seconds

6. 32000 seconds

Callbacks with GET method

By default all the callbacks are sent with JSON body and POST method, it is possible to choose GET method callback without request body.

Callback with GET method will be sent with TransactionNumber as query param.

URL: /transactions/init

Request Body for GET callbacks:

{
  "timeOut": 600,
  "amount": 200,
  "isCent": true,
  "currency": "USD",
  "deviceId": "2ooeww5ufzg3nkuf8a10gu5n695yolixlbgb042o03to9bxfkr7t815i5epu8o58jv1rznif3o1tr6xsb1rm",
  "callbackURL": "https://google.com/callback/api/callback",
  "callbackMethod": "GET"
}

This API call will be sent to this URL:

https://google.com/callback/api/callback?TransactionNumber=573942fsdqe90342k304242&callbackType=transaction_status