Documentation # Sale/Authorization
# Endpoint
http://{terminalIp}/devices/cat/authorizeSales
# Request
| Property | Type | Description |
|---|---|---|
| HTTP Headers | ||
| Siganture | String | Sha-256 hmac of the JSON payload. |
| Content-Type | text/plain | Even if the payload is a JSON object, POS Bridge parses it as a string, therefore it is important to pass content-type as "text/plain" or the authentication will fail. |
| JSON | ||
| poyntRequestId | String | UUID of the request |
| timeout | int | Client timeout in milliseconds. Once client timeout is reached, POS Bridge will return an error. |
| payment | JSON Object | Contains options for the payment session. Encloses all the properties below. |
| currency | String | 3 digit currency code. This property will be inside the payment object. |
| referenceId | String | Optional. Reference ID that can be set by the POS. If not set, POS Bridge sets it by default to a UUID. |
| orderId | String | Optional. UUID. If there is an order Object created in the Poynt cloud, setting orderId will link this payment with the order object. |
| order | JSON Object | Optional. For more information please refer to Poynt API reference: https://poynt.com/docs/api/#model-order. |
| amount | int | Transaction amount in cents. |
| tipAmount | int | Optional. Tip amount in cents (this is in addition to amount). |
| cashbackAmount | int | Optional. Cashback amount in cents (can only be used for debit transactions.) |
| disableCash | boolean | Optional. If set to true, cash won't be an option for this payment session. |
| disableDebitCards | boolean | Optional. If set to true, debit won't be an option on Poynt for this payment session. |
| disableTip | boolean | Optional. Tip screen will be disabled for this payment session. Tip screen only shows if the merchant account is configured for tip adjustment. |
| skipReceiptScreen | boolean | Optional. If set to true, the receipt screen is skipped on the terminal. Receipt screen allows customers to request printed receipts or receipts via email and SMS. |
| cashOnly | boolean | Optional. If set to true, payment session will default to cash tender. |
| multiTender | boolean | Optional. If set to true, merchant will be able to do a split tender transaction if needed. |
| creditOnly | boolean | Optional. Disable any other tender options except credit. |
| manualEntry | boolean | Optional. Terminal prompts for card to be entered manually. |
# Response
| Property | Type | Description |
|---|---|---|
| HTTP Headers | ||
| Content-Type | application/json | Content-type of the payload. |
| Siganture | String | Sha-256 hmac of the JSON payload. |
| JSON | ||
| poyntRequestId | String | UUID |
| Signature | String | Sha-256 hmac of the json payload. |
| catResponse | JSON Object | DO NOT USE |
| amount | int | Transaction amount processed in cents |
| tipAmount | int | Tip amount in cents. Note: for multi-tender payments look at the "tipAmounts" object, which is a map of the Poynt Transaction id (key) and tip amount (value.) |
| payment | JSON Object | Encloses an array of Transaction objects as well as payment session properties set in the request. If the payment session resulted in one transaction, the array will contain only one transaction object. |
| status | String | "CANCELED" if the merchant canceled the transaction, "DECLINED" if a transaction was declined and "COMPLETED" otherwise. |
| orderId | String | Order UUID set in the request. |
| order | JSON Object | Order object set in the request. |
| referenceId | String | Reference ID set in the request. This reference ID gets copied into references array inside the transaction object as well. |
| currency | String | 3 letter currency code set in the request. |
| transactions | JSON Array | Array of transaction objects. For a complete transaction model please refer to the Poynt API documentation: https://poynt.com/docs/api/#model-transaction |
| Transaction Properties | ||
| action | String | "SALE" is for debit transactions, AUTHORIZE for authorizations and pre-authorizations. |
| amounts | JSON Object | This contains a list of various amounts: cashBackamount - Amount of cashback requested by customer after paying by debit. The merchant must be enabled for the cashback feature. currency - 3 letter currency code. orderAmount - The portion of the transactionAmount that went towards the item/service being purchased. transactionAmount - The total amount to be charged on the tender, which equals orderAmount + tipAmount + cashbackAmount. tipAmount - tip amount in cents. Note: this field may not reflect if the customer leaves a tip until the adjustment call is completed by the terminal. Always check payment.tipAmount and/or payment.tipAmounts to see if the customer left a tip. |
| authOnly | boolean | If set to "true", this is a pre-authorization. |
| context | JSON Object | Additional transaction context. Please refer to: https://poynt.com/docs/api/#model-clientcontext |
| createdAt | String | Transaction time in ISO-8601 format. |
| customerUserId | int | ID of Customer object which is stored in the Poynt cloud. For more details: https://poynt.com/docs/api/#model-customer. |
| fundingSource | JSON Object | Contains information about the funding source for this transaction. Additional details at: https://poynt.com/docs/api/#model-fundingsource. |
| card | JSON Object | A property of fundingSource. Set if the payment was done by a credit or debit card. Contains the following fields (full list at https://poynt.com/docs/api/#model-card): cardHolderFirstName - First Name cardHolderLastName - Last Name expirationDate - Expiration Day of Month expirationMonth - Expiration Month expirationYear - Expiration Year numberFirst6 - Card BIN Number (first 6 digits) numberLast4 - Last 4 numbers of the card type - VISA, AMERICAN_EXPRESS, etc. |
| emvData | JSON Object | Currently only contains property emvTags. |
| emvTags | JSON dictionary | Property of emvData. Keys are EMV tags, values are tag values. |
| type | String | Funding source type. "CREDIT_DEBIT" for bank cards. |
| entryDetails | JSON dictionary | Contains info about customer presence status and card entry mode. |
| id | String | UUID of the transaction in the Poynt system. Use this ID for subsequent operations like void, capture, and adjustment. |
| processorResponse | JSON dictionary | Contains approvalCode from issuing bank, approvedAmount and additional information. Refer to https://poynt.com/docs/api/#model-processorresponse for more details. |
| references | JSON array | List of transaction references. Refer to https://poynt.com/docs/api/#model-transactionreference for additional details. |
| signatureCaptured | boolean | Note: this field gets set to true only after terminal made an adjustment call. |
| status | String | "CAPTURED" if transaction action is SALE (debit), "AUTHORIZED" otherwise. |
Request Example
POST /devices/cat/authorizeSales HTTP/1.1
Host: 10.255.140.195:55555
User-Agent: curl/7.43.0
Accept: */*
Content-Type: text/plain
Signature: 5421c0acc92fc510c38f5e85e152c3a5545ea1216c46012eca00bd2083e3c4fc
Content-Length: 856
{
"timeout": 60000,
"poyntRequestId": "467A5CCD-5F0A-4C23-8E39-1D43E07D39A1",
"payment": {
"currency": "USD",
"referenceId": "0665DF40-4049-4B0E-8C76-A39F434E01A7",
"orderId": "984B3CFD-0C19-4D27-999F-D1B4B4D75AE1",
"order": {
"amounts": {
"currency": "USD",
"subTotal": 1000
},
"id": "984B3CFD-0C19-4D27-999F-D1B4B4D75AE1",
"items": [
{
"name": "Item1",
"quantity": 1,
"status": "ORDERED",
"tax": 0,
"unitOfMeasure": "EACH",
"unitPrice": 100
},
{
"name": "Item2",
"quantity": 1,
"status": "ORDERED",
"tax": 0,
"unitOfMeasure": "EACH",
"unitPrice": 100
},
{
"name": "Item3",
"quantity": 8,
"status": "ORDERED",
"tax": 0,
"unitOfMeasure": "EACH",
"unitPrice": 100
}
],
"statuses": {
"status": "OPENED"
}
},
"amount": 1000,
"tipAmount": 0,
"cashbackAmount": 0,
"disableDebitCards": false,
"disableCash": false,
"debit": false,
"disableTip": false,
"skipReceiptScreen": false,
"cashOnly": false,
"nonReferencedCredit": false,
"multiTender": false
}
}
Response Example (Sucess)
HTTP/1.1 200 OK
Connection: Keep-Alive
Signature: F2AD208276FDCDA2B70C08A53FB5FD6DF3AE9D38C7D5C69003EE31A25D91ED19
Content-Length: 4436
Content-Type: application/json
{
"catResponse": {
"accountNumber": "371740******7008",
"approvalCode": "415554",
"cardCompanyID": "A",
"cardHolderFirstName": "JOHSN",
"cardHolderLastName": "SMITH",
"centerResultCode": "",
"sequenceNumber": 752,
"paymentCondition": 0,
"transactionType": 10
},
"payment": {
"transactions": [
{
"action": "SALE",
"amounts": {
"cashbackAmount": 0,
"currency": "USD",
"orderAmount": 1000,
"tipAmount": 0,
"transactionAmount": 1000
},
"authOnly": false,
"context": {
"businessId": "469e957c-57a7-4d54-a72a-9e8f3296adad",
"businessType": "TEST_MERCHANT",
"employeeUserId": 1526454,
"mcc": "5812",
"source": "INSTORE",
"sourceApp": "co.poynt.services",
"storeAddressCity": "Palo Alto",
"storeAddressTerritory": "CA",
"storeDeviceId": "urn:tid:df0f23b3-1d90-3466-91a9-0f2157da5687",
"storeId": "c2855b41-1dd5-4ecc-8258-f0c89ae40338",
"storeTimezone": "America/Los_Angeles",
"transmissionAtLocal": "2017-03-10T23:56:28Z"
},
"createdAt": "2017-03-10T23:56:29Z",
"customerUserId": 2196430,
"fundingSource": {
"card": {
"cardHolderFirstName": "JOSHN",
"cardHolderFullName": "SMITH/JOHN",
"cardHolderLastName": "SMITH",
"encrypted": false,
"expirationDate": 31,
"expirationMonth": 5,
"expirationYear": 2020,
"id": 674974,
"numberFirst6": "371740",
"numberLast4": "7008",
"numberMasked": "371740******7008",
"serviceCode": "201",
"type": "AMERICAN_EXPRESS"
},
"debit": false,
"emvData": {
"emvTags": {
"0x5F24": "XXXXXX",
"0x95": "000000XXXX",
"0x5F20": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"0x9F34": "XXXXXX",
"0x9F35": "XX",
"0x9F33": "XXXXXX",
"0x50": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"0x9A": "XXXXXX",
"0x9B": "XXXX",
"0x9F36": "XXXX",
"0x9C": "00",
"0x9F37": "XXXXXXXX",
"0x9F10": "XXXXXXXXXXXX",
"0x84": "XXXXXXXXXXXXX",
"0x82": "XXXX",
"0x9F1A": "XXXX",
"0x5F2A": "XXXX",
"0x9F26": "XXXXXXXXXXXXXX",
"0x9F27": "XX",
"0x9F03": "000000000000",
"0x9F06": "XXXXXXXXXXXXXX",
"0x9F02": "XXXXXXXXXX",
"0x5F34": "00",
"0x9F0E": "0000000000",
"0x9F0F": "XXXXXXXXX",
"0x5A": "XXXXXXXXXXXXXX",
"0x9F0D": "XXXXXXXX",
"0x5F28": "XXXX",
"0x5F25": "XXXXXX",
"0x9F16": "XXXXXXXXXXXXX",
"0x9F15": "XXXX",
"0x57": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"0x9F39": "XX",
"0x9F1E": "XXXXXXXXXXXXX",
"0x87": "XX",
"0x1F8104": "XXXXXXXXX",
"0x1F8103": "XXXXXXXXXX",
"0x1F815E": "XX",
"0x9F1C": "XXXXXXX",
"0x1F8102": "XXXXXXXXXXXXXX",
"0x9F08": "XXXX",
"0x5F30": "XXXX",
"0x9F07": "XXXX",
"0x9F09": "XXXX",
"0x9F40": "XXXXXXXXX",
"0x9F41": "XXXXXXX",
"0x1F8160": "XX",
"0x1F8162": "XX",
"0x9F21": "XXXXXX"
}
},
"entryDetails": {
"customerPresenceStatus": "PRESENT",
"entryMode": "INTEGRATED_CIRCUIT_CARD"
},
"type": "CREDIT_DEBIT"
},
"id": "30d3978a-da81-455c-91d6-c7c79ee378d2",
"processorResponse": {
"acquirer": "CHASE_PAYMENTECH",
"approvalCode": "415554",
"approvedAmount": 1000,
"batchId": "1",
"emvTags": {
"0x8A": "XXXX",
"0x89": "XXXXXXXX"
},
"processor": "MOCK",
"retrievalRefNum": "30d3978a-da81-455c-91d6-c7c79ee378d2",
"status": "Successful",
"statusCode": "1",
"statusMessage": "Successful",
"transactionId": "30d3978a-da81-455c-91d6-c7c79ee378d2"
},
"references": [
{
"id": "984b3cfd-0c19-4d27-999f-d1b4b4d75ae1",
"type": "POYNT_ORDER"
}
],
"signatureCaptured": false,
"status": "CAPTURED",
"updatedAt": "2017-03-10T23:56:29Z"
}
],
"tipAmounts": {
"30d3978a-da81-455c-91d6-c7c79ee378d2": 220
},
"status": "COMPLETED",
"currency": "USD",
"referenceId": "0665DF40-4049-4B0E-8C76-A39F434E01A7",
"orderId": "984b3cfd-0c19-4d27-999f-d1b4b4d75ae1",
"order": {
"amounts": {
"currency": "USD",
"subTotal": 1000
},
"id": "984b3cfd-0c19-4d27-999f-d1b4b4d75ae1",
"items": [
{
"name": "Item1",
"quantity": 1.0,
"status": "ORDERED",
"tax": 0,
"unitOfMeasure": "EACH",
"unitPrice": 100
},
{
"name": "Item2",
"quantity": 1.0,
"status": "ORDERED",
"tax": 0,
"unitOfMeasure": "EACH",
"unitPrice": 100
},
{
"name": "Item3",
"quantity": 8.0,
"status": "ORDERED",
"tax": 0,
"unitOfMeasure": "EACH",
"unitPrice": 100
}
],
"statuses": {
"status": "OPENED"
}
},
"amount": 1000,
"tipAmount": 220,
"cashbackAmount": 0,
"disableEMVCT": false,
"disableEbtCashBenefits": false,
"disableEbtFoodStamps": false,
"disableEbtVoucher": false,
"disableMSR": false,
"disableManual": false,
"disableOther": false,
"disablePaymentOptions": false,
"disableTip": false,
"disableDCC": false,
"isBalanceInquiry": false,
"manualEntry": false,
"multiTender": false,
"nonReferencedCredit": false,
"disableCheck": false,
"disableChangeAmount": false,
"disableCash": false,
"readCardDataOnly": false,
"debitOnly": false,
"debit": false,
"skipReceiptScreen": false,
"creditOnly": false,
"disableEMVCL": false,
"disableDebitCards": false,
"cashOnly": false,
"authzOnly": false,
"disableDebit": false,
"adjustToAddCharges": false,
"verifyOnly": false,
"voucher": false
},
"poyntRequestId": "467A5CCD-5F0A-4C23-8E39-1D43E07D39A1"
}
Merchant Canceled Transaction
HTTP/1.1 200 OK
Connection: Keep-Alive
Signature: 591697B2DD2EF2F7EAE2B56149B483E3FADF2F4FDF924E9BF4CD51A2F8EB1C45
Content-Length: 1099
Content-Type: application/json
{
"payment": {
"status": "CANCELED",
"currency": "USD",
"referenceId": "2e4ce83a-316d-4cd4-9752-71a69a7ca411",
"amount": 1000,
"tipAmount": 0,
"cashbackAmount": 0,
"disableEMVCT": false,
"disableEbtCashBenefits": false,
"disableEbtFoodStamps": false,
"disableEbtVoucher": false,
"disableMSR": false,
"disableManual": false,
"disableOther": false,
"disablePaymentOptions": false,
"disableTip": false,
"disableDCC": false,
"isBalanceInquiry": false,
"manualEntry": false,
"multiTender": true,
"nonReferencedCredit": false,
"disableCheck": false,
"disableChangeAmount": false,
"disableCash": false,
"readCardDataOnly": false,
"debitOnly": false,
"debit": false,
"skipReceiptScreen": false,
"creditOnly": false,
"disableEMVCL": false,
"disableDebitCards": false,
"cashOnly": false,
"authzOnly": false,
"disableDebit": false,
"adjustToAddCharges": false,
"verifyOnly": false,
"voucher": false
},
"poyntRequestId": "8f2f881d-df1e-4a6f-add6-efa5182c983e"
}