Authorization

Authorization is a process of placing a hold on the available credit of the consumer for the requested amount, no settlement will be created.

This process is useful for reserving funds from the consumer, after a successful authorization you will get token in order to create payment transaction based on the funds reserved.

The funds will be reserved until a payment will be made or void will be called to release the funds.

Create an Authorization

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

The amount field can be sent blank for future authorization transaction, the amount will be sent later using "authorize" API

URL: /transactions/init

Request Body:

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

Response body:

{
    "TransactionNumber": "5f3275249792ee75b41322e636617ee039e2e1a49cc80c11f2177233",
    "date": "2022-08-14T10:09:05.810Z",
    "amount": "2",
    "currency": "USD",
    "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": "Authorize"
    }
}

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

Authorization Token

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

See our docs regarding Transaction Events

Example of callback response:

{
    "TransactionNumber": "5f3275249792ee75b41322e636617ee039e2e1a49cc80c11f2177233",
    "date": "2022-08-14T10:09:05.810Z",
    "amount": "2",
    "currency": "USD",
    "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": "Authorize",
        "paymentMethod": "Sensepass PCI",
        "created": "2022-11-16T09:09:11.951Z",
        "token": "fpwotdbb1ggzg07j1pbhmhfw6tyozttq427nucb6um4ku",
        "requestID": "754144919",
        "cardType": "amex",
        "lastFourDigits": "7767",
        "cardMask": "375510*****7767",
        "expiration": "0125",
        "approvedBy": "Cardknox Sandbox"
    },
    "callbackType": "transaction_status"
}

The token field in "paymentDetails" object is the authorization token.

Now that we have our authorization token you can make a capture will the full authorization amount, or capture smaller amount than the authorization amount multiple times, or you can void the authorization.

Capture using Token

Capturing can be made with the full authorization amount once, or with smaller amount multiple times until you reach the authorization amount.

The "token" field represents authorization token from the previous section, or token from Tokenization API.

URL: /transactions/pay

Request Body:

{
  "deviceId": "2ooeww5ufzg3nkuf8a10g15i5epu8o58jv1rznif3o1tr6xsb1rm",
  "amount": 200,
  "token": "fpwotdbb1ggzg07j1pbhmhfw6tyozttq427nucb6um4ku"
}

The amount fields represents the amount in cents, value of 100 represents 1.00

Request Body for Authorize.net token:

{
  "deviceId": "2ooeww5ufzg3nkuf8a10g15i5epu8o58jv1rznif3o1tr6xsb1rm",
  "amount": 200,
  "tokenSource": "Authorize.net",
  "tokenData": {
    "profile_id": "12121212",
    "payment_id": "32323232",
    "auth_code": "ABC123"
  }
}

Response body:

{
    "success": true,
    "transactionNumber": "73ca0ed84245b7812d18613f30e3393159f11fc216505ec1892021f9",
    "transactionStatus": "TransactionApproved",
    "confirmation": {
        "fullConfirmationCode": "174-85762A",
        "confirmationNumber": "174-85762A",
        "approvedBy": "Cardknox Sandbox",
        "providerId": "6wMjGG7cJ5KPTvzLOXKTIJjwdREImIsJGNpmGckfBiU=",
        "dateApproval": "2022-11-16T09:19:15.486Z",
        "approvalDate": "2022-11-16T09:19:15.486Z",
        "paymentMethodName": "Credit Card",
        "lastFourDigits": "7767",
        "cardExpiration": "0125",
        "sensePassReferenceId": "epr2dxpyxit3ro3jlp8l"
    },
    "cardMask": "375510*****7767",
    "token": "fpwotdbb1ggzg07j1pbhmhfw6tyozttq427nucb6um4ku"

Void

Void is the process of cancelling a pending authorization and release the credit on the consumer.

Void will not refund the payment already settled.

URL: /transactions/void

Request Body:

{
  "deviceId": "2ooeww5ufzg3nkuf8a10g15i5epu8o58jv1rznif3o1tr6xsb1rm",
  "transactionNumber": "05e5559cb40db534cf526472b4d9609733a438d232d4a94d03aa292c"
}

Request Body for Authorize.net token:

{
  "deviceId": "2ooeww5ufzg3nkuf8a10g15i5epu8o58jv1rznif3o1tr6xsb1rm",
  "tokenSource": "Authorize.net",
  "tokenData": {
    "refNum": "8K0TYW"
  }
}

Response body:

{
    "success": true,
    "transactionNumber": "05e5559cb40db534cf526472b4d9609733a438d232d4a94d03aa292c",
    "transactionStatus": "TransactionAuthoriziationVoided",
    "error": null
}

Re-Authorization

Re-Authorization enables you to place an hold on the available credit of the consumer for the requested amount again, using the same token of the original authorization.

URL: /transactions/authorize

Request Body:

{
  "deviceId": "2ooeww5ufzg3nkuf8a10g15i5epu8o58jv1rznif3o1tr6xsb1rm",
  "amount": 200,
  "token": "fpwotdbb1ggzg07j1pbhmhfw6tyozttq427nucb6um4ku"
}

The amount fields represents the amount in cents, value of 100 represents 1.00

Request body for Authorize.net token:

{
  "deviceId": "2ooeww5ufzg3nkuf8a10g15i5epu8o58jv1rznif3o1tr6xsb1rm",
  "amount": 200,
  "tokenSource": "Authorize.net",
  "tokenData": {
    "profile_id": "12121212",
    "payment_id": "32323232",
    "auth_code": "ABC123"
  }
}

Response body:

{
    "success": true,
    "transactionNumber": "73ca0ed84245b7812d18613f30e3393159f11fc216505ec1892021f9",
    "transactionStatus": "TransactionApproved",
    "confirmation": {
        "fullConfirmationCode": "174-85762A",
        "confirmationNumber": "174-85762A",
        "approvedBy": "Cardknox Sandbox",
        "providerId": "6wMjGG7cJ5KPTvzLOXKTIJjwdREImIsJGNpmGckfBiU=",
        "dateApproval": "2022-11-16T09:19:15.486Z",
        "approvalDate": "2022-11-16T09:19:15.486Z",
        "paymentMethodName": "Credit Card",
        "lastFourDigits": "7767",
        "cardExpiration": "0125",
        "sensePassReferenceId": "epr2dxpyxit3ro3jlp8l"
    },
    "cardMask": "375510*****7767",
    "token": "fpwotdbb1ggzg07j1pbhmhfw6tyozttq427nucb6um4ku"
}

Close Authorization

POST /transactions/:transactionNumber/closeAuth

Supported only for "Cardknox" processor.

Close Authorization is the process of closing an active authorization after at least one payment has been made and release the remaining credit.

To activate Close Authorization all these should exist:

  1. The transaction's method type has to be of type Authorization

  2. At least one successful payment has been made (if there aren't any successful payments, use Void endpoint to release the remaining credit).

  3. The sum of successful payments under the Authorization transaction must be less than the original auth amount.

Path Parameters

Name
Type
Description

transactionNumber

string

Transaction Number

Request Body:

{
    "deviceId": "027dpi0gyi1ir8bv20vtrm6yd0aas5i8rzjw94xro3gvroh5b79my3uv06vt"
}

Response body:

{
    "success": true,
    "transactionNumber": "bf6421709bd9bb107e3914ccc698bf3aa7d61f871cf9c29029578da1",
    "transactionStatus": "TransactionAuthorizationClosed",
    "approvalID": "10203715865",
    "message": "Transaction Authorization Closed Successfully"
}

Last updated