Tokenization

Tokenization is the proccess of representing sensitive payment information with a token that does not contain data and represents the payment method of the consumer in SensePass.

Tokenization is useful for recurring payments or any kind of future payments with interaction with the consumer.

Create a Tokenization request

Call "transactions/init" in order to create an tokenization request and add the "methodType" field with "Tokenize".

URL: /transactions/init

Request Body:

{
  "timeOut": 600,
  "deviceId": "2ooeww5ufzg3nkuf8a10g15i5epu8o58jv1rznif3o1tr6xsb1rm",
  "methodType": "Tokenize"
}

Response body:

{
    "TransactionNumber": "5f3275249792ee75b41322e636617ee039e2e1a49cc80c11f2177233",
    "date": "2022-08-14T10:09:05.810Z",
    "status": 0,
    "statusName": "Initialize",
    "timeoutDate": "2022-08-14T10:19:05.872Z",
    "paymentCommit": {
        "messsage": "Payment commit is enabled for this transaction"
    },
    "businessId": "339978940107456",
    "businessName": "Coffee Bar",
    "pos": "POS 1",
    "businessOwnerPhone": "3587292",
    "businessCountry": "US",
    "businessCity": "Virginia Beach",
    "businessStreet": "123 Street",
    "businessAddress": "123 Street, Virginia Beach",
    "branchNumber": "1",
    "branchId": "1",
    "transactionPage": {
        "iOSLink": "https://pay.sandbox.sensepass.com/orderSummary/5f3275249792ee75b41322e636617ee039e2e1a49cc80c27f2177233",
        "androidLink": "https://pay.sandbox.sensepass.com/orderSummary/5f3275249792ee75b41322e636617ee039e2e1a49cc80c27f2177233",
        "qrURL": "https://pay.sandbox.sensepass.com/orderSummary/5f3275249792ee75b41322e636617ee039e2e1a49cc80c27f2177233"
    },
    "paymentDetails": {
        "type": "Tokenize"
    }
}

The consumer tap the sticker, or get the payment link through e-mail or SMS, and choose a payment method.

Create a Capture request with Tokenization

Call "transactions/init" in order to create an capture and tokenization request - add the "methodType" field with "Capture+Tokenize".

URL: /transactions/init

Request Body:

{
  "timeOut": 600,
  "amount": 3000,
  "deviceId": "2ooeww5ufzg3nkuf8a10g15i5epu8o58jv1rznif3o1tr6xsb1rm",
  "methodType": "Capture+Tokenize"
}

Response body:

{
    "TransactionNumber": "5f3275249792ee75b41322e636617ee039e2e1a49cc80c11f2177233",
    "date": "2022-08-14T10:09:05.810Z",
    "status": 0,
    "statusName": "Initialize",
    "timeoutDate": "2022-08-14T10:19:05.872Z",
    "paymentCommit": {
        "messsage": "Payment commit is enabled for this transaction"
    },
    "businessId": "339978940107456",
    "businessName": "Coffee Bar",
    "pos": "POS 1",
    "businessOwnerPhone": "3587292",
    "businessCountry": "US",
    "businessCity": "Virginia Beach",
    "businessStreet": "123 Street",
    "businessAddress": "123 Street, Virginia Beach",
    "branchNumber": "1",
    "branchId": "1",
    "transactionPage": {
        "iOSLink": "https://pay.sandbox.sensepass.com/orderSummary/5f3275249792ee75b41322e636617ee039e2e1a49cc80c27f2177233",
        "androidLink": "https://pay.sandbox.sensepass.com/orderSummary/5f3275249792ee75b41322e636617ee039e2e1a49cc80c27f2177233",
        "qrURL": "https://pay.sandbox.sensepass.com/orderSummary/5f3275249792ee75b41322e636617ee039e2e1a49cc80c27f2177233"
    },
    "paymentDetails": {
        "type": "Capture+Tokenize"
    }
}

The consumer tap the sticker, or get the payment link through e-mail or SMS, and choose a payment method.

Convert credit cards details to Tokens

URL: /transactions/tokenize

Request Body:

{
    "apiKey": "2ooeww5ufzg3nkuf8a10g15i5epu8o58jv1rznif3o1tr6xsb1rm",
    "creditCardDetails": [
        {
            "cardNumber": "4580458045804580",
            "cardExpiration": "12/34",
            "securityCode": "567"
        },
        {
            "cardNumber": "4580458045804580",
            "cardExpiration": "12/34",
            "securityCode": "567"
        }
    ]
}

Response body:

[
    {
        "cardNumber": "4580458045804580",
        "cardExpiration": "1234",
        "securityCode": "567",
        "uid": "f0de8e51-e886-4b99-9a2b-c5a4189df164",
        "token": "f0de8e51-e886-4b99-9a2b-cda4189df164"
    },
    {
        "cardNumber": "4580458045804580",
        "cardExpiration": "1234",
        "securityCode": "567",
        "uid": "7c2b58db-8985-4547-9e38-f96f9a78d801",
        "token": "7c2b58db-8985-4547-9e38-fa6f9a78d801"
    }
]

Payment Token Callback

The consumer choose the payment method as usual and you will get an update regarding this transaction by websocket, callback and transaction status API.

Example of callback response:

{
    "TransactionNumber": "5f3275249792ee75b41322e636617ee039e2e1a49cc80c11f2177233",
    "date": "2022-08-14T10:09:05.810Z",
    "status": 0,
    "statusName": "Initialize",
    "timeoutDate": "2022-08-14T10:19:05.872Z",
    "paymentCommit": {
    "businessId": "339978940107456",
    "businessName": "Coffee Bar",
    "pos": "POS 1",
    "businessOwnerPhone": "3587292",
    "businessCountry": "US",
    "businessCity": "Virginia Beach",
    "businessStreet": "123 Street",
    "businessAddress": "123 Street, Virginia Beach",
    "paymentDetails": {
        "type": "Tokenize",
        "paymentMethod": "Sensepass PCI",
        "created": "2022-11-17T08:31:10.154Z",
        "token": "kkAl8zuss9men3mvu6rp4fhuwppek9yht6vn8r9z3kza6hyzfmnm",
        "cardType": "visa",
        "lastFourDigits": "1111",
        "cardMask": "458010*****1111",
        "expiration": "1234",
        "approvedBy": "Credit Card"
    },
    "callbackType": "transaction_status"
}

See the token in "paymentDetails.token".

The token length is 256 characters.

Pay with Token

URL: /transactions/pay

Amount field only supports cents. This API does not support sending isCent=false

Request Body:

{
  "amount": 200,
  "currency": "USD",
  "deviceId": "2ooeww5ufzg3nkuf8a10g15i5epu8o58jv1rznif3o1tr6xsb1rm",
  "token": "kkAl8zuss9men3mvu6rp4fhuwppek9yht6vn8r9z3kza6hyzfmnm"
}

Request Body for Authroize.net token:

{
  "amount": 200,
  "currency": "USD",
  "deviceId": "2ooeww5ufzg3nkuf8a10g15i5epu8o58jv1rznif3o1tr6xsb1rm",
  "tokenSource": "Authorize.net",
  "tokenData": {
      "profile_id": "12345",
      "payment_id": "55555"
  }
}

Response body:

{
    "success": true,
    "transactionNumber": "dff8c53f80b25527666a5935b56fc431d8a68cc82e53234d907103d2",
    "transactionStatus": "TransactionApproved",
    "confirmation": {
        "fullConfirmationCode": "166-60202801955",
        "confirmationNumber": "166-60202801955",
        "approvedBy": "AuthorizeNet Sandbox",
        "providerId": "jDPPZyn8zdGtBcKUP4EbxTfwy62j+JShtQGDlbwx4/c=",
        "dateApproval": "2022-10-20T17:34:31.778Z",
        "approvalDate": "2022-10-20T17:34:31.778Z",
        "paymentMethodName": "Credit Card",
        "lastFourDigits": "1111",
        "cardExpiration": "1234"
    },
    "cardMask": "",
    "token": "kkAl8zuss9men3mvu6rp4fhuwppek9yht6vn8r9z3kza6hyzfmnm"
}

Token Validation

URL: /transactions/token-validation

This API checks wheter the payment method associated with this token is currently valid using the payment provider - It will fail for example after the card blocked or expired.

Request Body:

{
  "deviceId": "2ooeww5ufzg3nkuf8a10g15i5epu8o58jvrznif3o1tr6xsb1rm",
  "token": "fd269cce79496def3add8157511d2571562221641140aa5edc870ea7fc4ebad"
}

Response:

201: OK

{
    "success": true,
    "message": "The token is valid",
    "AVS": {
        "code": "NNN",
        "message": "Address: No Match & 5 Digit Zip: No Match"
    },
    "CVV": {
        "code": "M",
        "message": "Match"
    }
}