Documentation

# Payment Actions

Below, we have outlined some of the most common payment actions you can use depending on each use case.

TIP

You can refer to the Payment Fragment article for the complete list of supported options.

# Request Message Format

Once you have selected the charge option, you must perform an API request to the https://services.poynt.net/cloudMessages endpoint following the parameters detailed below.

# Message Parameters

The following message parameters are applicable for all the payment actions of this API.

  • storeId - Optional
  • businessId - Mandatory
  • deviceId - Mandatory

    NOTE

    If you do not include deviceId, the payment request will be sent to all the Smart Terminals in the store.

  • ttl - Mandatory

    TIP

    This parameter manages cases where the Poynt server is unable to deliver the message to the terminal. After TTL (in seconds) is reached the request will be discarded.

  • data - Mandatory
    The data parameter is the actual payload, which must be serialized to make the call:
    • Format: {"action":"sale", "purchaseAmount": 1000, "tipAmount": 100, "currency":"USD", "referenceId":”ABC1234”, “callbackUrl”: “-urlencoded-url-"}

# Request Body Example

{
    "ttl": 45,
    "businessId": "{{businessId}}",
    "storeId": "{{storeId}}",
    "deviceId": "{{deviceId}}",
    "data": "{{paymentDataStr}}"
}

# Data Parameters

TIP

You can also introduce any of the fields used within the transaction object in the data parameters to provide more details about each API call.

  • action: String - This item refers to the action being carried out. It can be authorize, sale, void, refund, and non-referenced-credit.
  • purchaseAmount: Number - This item refers to the transaction amount, excluding tip amounts.
  • tipAmount: Number - This field corresponds to the tip amount if it is enabled for the merchant.
  • currency: String - This wll be a 3 digit currency value (e.g. "USD")
  • references: - List - This allows the application to pass custom reference information, such as custom order id and other metadata. This list is returned inside Transaction object once the payment is completed.
  • multiTender: - Boolean - This value starts the payment fragment in the multiTender mode which allows the buyer to pay using 2 or more tenders
  • referenceId: - This item corresponds to the external referenceId that you can use to correlate transactions across systems.
  • orderId: - This field corresponds to the order id of a previously created order or the order that will be created after the payment.
  • callbackUrl: where you will receive a callback (HTTP POST) with Poynt Payment object (opens new window)
  • transactionId: - This field is the transactionId to use for void, refund operations.
  • custom-http-header: - This is the custom HTTP header name and value that will be set by GoDaddy Poynt in the callback request.
  • skipReceiptScreen: - This field in a value of true will force the receipt options screen to be skipped.
  • debit: - A value of true on this field will default payment method to debit.

# Python Example

Below is a python example of a function to call the cloudMessages endpoint. A more comprehensive version of this example can be found in the Python Sample (opens new window) repository on GitHub.

def sendCloudMessage(self, businessId, storeId, packageName, className, data):
        pcmUrl = self.apiHost + "/cloudMessages"
        if not packageName:
            cloudMessage = {
                "businessId": businessId,
                "storeId": storeId,
                "ttl": 500,
                "data": data
            }
        else:
            cloudMessage = {
                "businessId": businessId,
                "storeId": storeId,
                "ttl": 500,
                "recipient": {
                    "className": className,
                    "packageName": packageName
                },
                "data": data
            }

#poyntAPI.sendCloudMessage(BUSINESS_ID, STORE_ID, "com.my.android.package", "com.my.android.package.MyBroadcastReceiverClass", "Hello from the cloud.")

# Sale

Endpoint

https://services.poynt.net/cloudMessages

Data Parameters

Whenever you are doing a sale/authorization, you can use payment, which is a serialized payment object. The payment object contains a large number of options to configure the payment session.

{
  "ttl": 30,
  "businessId": "d9f90edd-53d0-49ed-9589-22d92b9bfda4",
  "storeId": "8a545d2b-e5d8-4cf0-b766-0fe32870813b",
  "deviceId": "urn:tid:9a645d2b-e3c8-7cf0-d766-9fe32870813b",
  "data": "{\"callbackUrl\":\"https://www.domain.com/callback\",\"custom-http-header\":\"Headername: HeaderValue\",\"payment\":\"{\\\"amount\\\":345,\\\"currency\\\":\\\"USD\\\",\\\"multiTender\\\":\\\"true\\\",\\\"skipReceiptScreen\\\":true,\\\"skipSignatureScreen\\\":true,\\\"disableTip\\\":true,\\\"notes\\\":\\\"A note about my txn\\\",\\\"referenceId\\\":\\\"6199fce8-c434-4a06-a13e-f95396c1d3ab\\\"}\"}"
}

# AuthOnly

Endpoint

https://services.poynt.net/cloudMessages

Data Parameters

  • payment serialized payment object.
{
  "ttl": 30,
  "businessId": "d9f90edd-53d0-49ed-9589-22d92b9bfda4",
  "storeId": "8a545d2b-e5d8-4cf0-b766-0fe32870813b",
  "deviceId": "urn:tid:9a645d2b-e3c8-7cf0-d766-9fe32870813b",
  "data": "{\"callbackUrl\":\"https://www.domain.com/callback\",\"custom-http-header\":\"Headername: HeaderValue\",\"payment\":\"{\\\"amount\\\":345,\\\"currency\\\":\\\"USD\\\",\\\"multiTender\\\":\\\"true\\\",\\\"skipReceiptScreen\\\":true,\\\"skipSignatureScreen\\\":true,\\\"disableTip\\\":true,\\\"notes\\\":\\\"A note about my txn\\\",\\\"authzOnly\\\":true,\\\"referenceId\\\":\\\"6199fce8-c434-4a06-a13e-f95396c1d3ab\\\"}\"}"
}

# Refund

Endpoint

https://services.poynt.net/cloudMessages

Data Parameters

  • referenceId - This field is the unique ID returned in the postback response.
  • transactionId - This field corresponds to the ID of the SALE or CAPTURE to refund.
  • action - This field should be set to refund.
{
  "ttl": 30,
  "businessId": "d9f90edd-53d0-49ed-9589-22d92b9bfda4",
  "storeId": "8a545d2b-e5d8-4cf0-b766-0fe32870813b",
  "deviceId": "urn:tid:9a645d2b-e3c8-7cf0-d766-9fe32870813b",
  "data": "{\"callbackUrl\":\"https://www.domain.com/callback\",\"referenceId\":\"8a545d2b-e5d8-aabb-b766-0fe32870813b\",\"transactionId\":\"f24bc381-adb7-481c-9ae9-761275bb0c0a\",\"action\":\"refund\"}"
}

TIP

In cases where you need to submit a Partial Refund, you can do so by specifying the amount in the parameters (see example below.)

{
    "businessId": "a3f24e9e-6764-42f2-bbcd-5541e7f3be38",
    "storeId": "f9dad6b0-1039-4f0d-b505-65ff93c7ad0d",
    "storeDeviceId": "P6SW248JS005466",
    "ttl": 500,
    "data": "{\"action\":\"refund\",\"transactionId\":\"8e66838b-c331-4fae-8f87-ba731a825f57\",\"purchaseAmount\": 1000, \"tipAmount\": 100, \"currency\":\"USD\",\"referenceId\":\"ABC1234\", \"callbackUrl\":\"https://enk673h4zbz3l.x.pipedream.net\"}"
}'

# Non-referenced Refund (Credit)

Endpoint

https://services.poynt.net/cloudMessages

Data Parameters

  • payment serialized payment object.
{
  "ttl": 30,
  "businessId": "803833ba-cb97-434d-b158-30db6973173b",
  "storeId": "b4c4d6e6-6a5e-4ca9-86ee-a086ff2fc9c9",
  "deviceId": "urn:tid:23df48cd-b11e-3ff2-b537-fdcc787ad21b",
  "data": "{\"callbackUrl\":\"https://www.domain.com/callback\",\"custom-http-header\":\"Headername: HeaderValue\",\"payment\":\"{\\\"amount\\\":345,\\\"currency\\\":\\\"USD\\\",\\\"nonReferencedCredit\\\":true}\"}"
}

# Void

Endpoint

https://services.poynt.net/cloudMessages

Data Parameters

  • referenceId - This field is the unique ID returned in the postback response.
  • transactionId - This field corresponds to the ID of the AUTHORIZATION to void.
  • action - This field should be set to void.
{
  "ttl": 30,
  "businessId": "803833ba-cb97-434d-b158-30db6973173b",
  "storeId": "b4c4d6e6-6a5e-4ca9-86ee-a086ff2fc9c9",
  "deviceId": "urn:tid:23df48cd-b11e-3ff2-b537-fdcc787ad21b",
  "data": "{\"callbackUrl\":\"https://www.domain.com/callback\",\"referenceId\":\"8a545d2b-e5d8-aabb-b766-0fe32870813b\",\"transactionId\":\"5805d5b4-016b-1000-4924-5a010638b565\",\"action\":\"void\"}"
}

# Capture

Endpoint

https://services.poynt.net/cloudMessages

Data Parameters

  • referenceId - This field is the unique ID returned in the postback response.
  • transactionId - This field corresponds to the ID of the AUTHORIZATION to capture.
  • action This field should be set to capture.
{
  "ttl": 30,
  "businessId": "803833ba-cb97-434d-b158-30db6973173b",
  "storeId": "b4c4d6e6-6a5e-4ca9-86ee-a086ff2fc9c9",
  "deviceId": "urn:tid:23df48cd-b11e-3ff2-b537-fdcc787ad21b",
  "data": "{\"callbackUrl\":\"https://www.domain.com/callback\",\"referenceId\":\"8a545d2b-e5d8-aabb-b766-0fe32870813c\",\"transactionId\":\"4e75b270-016b-1000-9b65-3708f2205b64\",\"action\":\"capture\"}"
}

# Cancel Payment

This API can be used to cancel a payment in progress. This API does not generate a callback response. However, the pending sale/auth/credit request will return a callback response with the status CANCELED.

Endpoint

https://services.poynt.net/cloudMessages

Data Parameters

  • action cancelPayment
{
  "ttl": 30,
  "businessId": "803833ba-cb97-434d-b158-30db6973173b",
  "storeId": "b4c4d6e6-6a5e-4ca9-86ee-a086ff2fc9c9",
  "deviceId": "urn:tid:23df48cd-b11e-3ff2-b537-fdcc787ad21b",
  "data": "{\"action\":\"cancelPayment\"}"
}

# Generate Receipt

PROCESSOR SPECIFIC

Please note that this API is currently only supported for the processor NEXI.

Endpoint

https://services.poynt.net/cloudMessages

Data Parameters

{
  "ttl": 500,
  "businessId": "df5638be-faca-4367-84c9-b568b776f14a",
  "storeId": "b63ca176-2875-41b9-814c-f207cb0c0ae9",
  "deviceId": "urn:tid:cc60a9d8-7ef8-37ce-b469-84fc6c0264c5",
  "data": "{\"action\":\"generateReceipt\", \"callbackUrl\":\"http://192.168.1.116:9999/\",\"transaction\":\"{\\\"action\\\":\\\"AUTHORIZE\\\",\\\"adjustmentHistory\\\":[],\\\"amounts\\\":{\\\"currency\\\":\\\"EUR\\\",\\\"orderAmount\\\":22,\\\"tipAmount\\\":0,\\\"transactionAmount\\\":22},\\\"authOnly\\\":false,\\\"context\\\":{\\\"businessId\\\":\\\"df5638be-faca-4367-84c9-b568b776f14a\\\",\\\"employeeUserId\\\":3692,\\\"mcc\\\":\\\"5812\\\",\\\"source\\\":\\\"INSTORE\\\",\\\"storeId\\\":\\\"b63ca176-2875-41b9-814c-f207cb0c0ae9\\\",\\\"tid\\\":\\\"d0up\\\",\\\"transmissionAtLocal\\\":{\\\"year\\\":2018,\\\"month\\\":9,\\\"dayOfMonth\\\":4,\\\"hourOfDay\\\":14,\\\"minute\\\":19,\\\"second\\\":40}},\\\"createdAt\\\":{\\\"year\\\":2018,\\\"month\\\":9,\\\"dayOfMonth\\\":4,\\\"hourOfDay\\\":14,\\\"minute\\\":19,\\\"second\\\":41},\\\"customerLanguage\\\":\\\"en\\\",\\\"fundingSource\\\":{\\\"card\\\":{\\\"numberFirst6\\\":\\\"370295\\\",\\\"numberLast4\\\":\\\"3111\\\",\\\"type\\\":\\\"AMERICAN_EXPRESS\\\"},\\\"emvData\\\":{\\\"emvTags\\\":{\\\"0x1F8103\\\":\\\"333730323935\\\",\\\"0x1F8206\\\":\\\"0F\\\",\\\"0x1F8151\\\":\\\"3C\\\",\\\"0x9F35\\\":\\\"22\\\",\\\"0x95\\\":\\\"8000000000\\\",\\\"0x5F30\\\":\\\"728F\\\",\\\"0x9F34\\\":\\\"1F0002\\\",\\\"0x9F39\\\":\\\"91\\\",\\\"0x1F8104\\\":\\\"33313131\\\",\\\"0x9F06\\\":\\\"A000000025010901\\\",\\\"0x1F8204\\\":\\\"25\\\"}},\\\"entryDetails\\\":{\\\"customerPresenceStatus\\\":\\\"PRESENT\\\",\\\"entryMode\\\":\\\"CONTACTLESS_MAGSTRIPE\\\"},\\\"type\\\":\\\"CREDIT_DEBIT\\\"},\\\"id\\\":\\\"40f35692-0166-1000-3741-56a451933b19\\\",\\\"processorResponse\\\":{\\\"avsResult\\\":{}},\\\"references\\\":[{\\\"customType\\\":\\\"referenceId\\\",\\\"id\\\":\\\"40f34377-0166-1000-3741-56a451933b19\\\",\\\"type\\\":\\\"CUSTOM\\\"}],\\\"signatureRequired\\\":false}\"}"
}

# Callback

Callback allows the external system to get notified when the payment action requested is processed. The terminal will use the callback URL provided in the request to POST the json payload shown below.

Note

Since the postback payload is a serialized version of the Payment object and from time to time we may add new parameters, it is important that you do not use strict validation while parsing the payload, which means ignoring unknown parameters.

{"referenceId":"<your-reference-id>","status":"CANCELED or RECEIVED or STARTED or PROCESSED", "transactions":[{<processed-transaction>}]}

Example of a canceled payment:

{
  "referenceId": "8c8cf949-4f5c-4aa4-8b90-05d43592bfbe",
  "status": "CANCELED"
}

TIP

Please keep in mind that by default, callback statuses are not sent. If you would like to receive status updates, you will need to include the flag enableStatusUpdates and set it with a true value in your request.

Example response posted back to the callback url

POST /callback HTTP/1.1
Content-Type: application/json; charset=utf-8
Content-Length: 1510
Host: myserver.com:8080
Connection: Keep-Alive
Accept-Encoding: gzip
User-Agent: okhttp/2.5.0

{
  "readCardDataOnly": false,
  "transactions": [
    {
      "authOnly": false,
      "status": "AUTHORIZED",
      "customerLanguage": "en",
      "updatedAt": "2018-09-06T01:23:23Z",
      "id": "f24bc381-adb7-481c-9ae9-761275bb0c0a",
      "references": [
        {
          "type": "CUSTOM",
          "id": "b6c9f791-c3e8-4b8a-8eee-5567c2d7956c",
          "customType": "referenceId"
        }
      ],
      "customerUserId": 60731166,
      "amounts": {
        "tipAmount": 0,
        "transactionAmount": 4500,
        "orderAmount": 4500,
        "cashbackAmount": 0,
        "currency": "USD"
      },
      "createdAt": "2018-09-06T01:23:21Z",
      "signatureRequired": false,
      "context": {
        "storeDeviceId": "urn:tid:e9e65b1b-1a58-3e55-a828-3f49096cc661",
        "source": "INSTORE",
        "storeAddressTerritory": "California",
        "mcc": "5812",
        "storeAddressCity": "Palo Alto",
        "sourceApp": "co.poynt.services",
        "employeeUserId": 26835234,
        "businessType": "TEST_MERCHANT",
        "businessId": "803833b1-cb97-434d-b158-30db6973173b",
        "storeTimezone": "America/Los_Angeles",
        "storeId": "b4c4d6e6-6a1e-4ca9-86ee-a086ff2fc9c9",
        "transmissionAtLocal": "2018-09-06T01:23:21Z"
      },
      "action": "AUTHORIZE",
      "processorResponse": {
        "statusCode": "1",
        "transactionId": "0eb6c86b-73b1-e811-bc5d-0050569277e2",
        "avsResult": {

        },
        "status": "Successful",
        "emvTags": {
          "0x9F02": "000000004500"
        },
        "acquirer": "CHASE_PAYMENTECH",
        "approvedAmount": 4500,
        "approvalCode": "6A4FEE",
        "processor": "CREDITCALL"
      },
      "fundingSource": {
        "card": {
          "numberMasked": "370123******1111",
          "cardId": "daa2dbe1-0b61-423a-a46c-73647e1e58de",
          "numberFirst6": "370123",
          "cardHolderFullName": "VALUED CUSTOMER      00304",
          "expirationDate": 31,
          "cardHolderLastName": "VALUED CUSTOMER      00304",
          "type": "AMERICAN_EXPRESS",
          "id": 59070137,
          "encrypted": false,
          "expirationYear": 2022,
          "expirationMonth": 7,
          "serviceCode": "728",
          "numberLast4": "1111",
          "cardHolderFirstName": ""
        },
        "debit": false,
        "type": "CREDIT_DEBIT",
        "entryDetails": {
          "entryMode": "CONTACTLESS_MAGSTRIPE",
          "customerPresenceStatus": "PRESENT"
        },
        "emvData": {
          "emvTags": {
            "0x5F24": "220731",
            "0x95": "8000001000",
            "0x1F815D": "3C",
            "0x5F20": "56414C55454420435553544F4145522020202020203030333034",
            "0x1F8104": "33313131",
            "0x1F8103": "333731323935",
            "0x1F815F": "04",
            "0x1F8102": "FFFF9876541210E00062",
            "0x1F815E": "25",
            "0x5F30": "728F",
            "0x9F34": "1F0002",
            "0x9F35": "22",
            "0x9F06": "A000000025010901",
            "0x1F8160": "03",
            "0x1F8161": "00",
            "0x1F8162": "00",
            "0x57": "37F8DBB4289118DC0707827101BB3E7D0A4DAF62AA38DED4192FCDBFEA6E5AB78E1351E27A993E15",
            "0x9F39": "91",
            "0x56": "6881AE9183767E18358A391DB1D74914DC212BD7744BB160D1C16AF5BE490028143BAB50F4B9EEF103A6EE255E8028B4C975C74FCAEBDF6798DD15883CB2C38E"
          }
        }
      }
    }
  ],
  "disableManual": false,
  "authzOnly": false,
  "disableOther": false,
  "multiTender": true,
  "disableCheck": false,
  "nonReferencedCredit": false,
  "applicationIndex": -1,
  "currency": "USD",
  "disableDebit": false,
  "amount": 4500,
  "tipAmount": 0,
  "isBalanceInquiry": false,
  "creditOnly": false,
  "disableEbtVoucher": false,
  "disableMSR": false,
  "cashOnly": false,
  "disableEbtCashBenefits": false,
  "manualEntry": false,
  "disableChangeAmount": false,
  "skipReceiptScreen": false,
  "disableDebitCards": false,
  "disableEMVCL": false,
  "status": "PROCESSED",
  "disableCash": false,
  "callerPackageName": "co.poynt.services",
  "referenceId": "b6c9179b-c3e8-4b8a-8eee-5567c2d7956c",
  "disableTip": false,
  "debitOnly": false,
  "skipPaymentConfirmationScreen": false,
  "adjustToAddCharges": false,
  "disableEbtFoodStamps": false,
  "disableEMVCT": false,
  "disablePaymentOptions": false,
  "skipSignatureScreen": false,
  "voucher": false,
  "offlineAuth": false,
  "cashbackAmount": 0
}

Postback Retry Logic

The terminal waits 3 seconds to get HTTP 200 from the postback listener. If your listener fails to repond within that timeframe the terminal will attempt to re-deliver 5 and 10 seconds later.

Last Updated: 4/2/2024, 6:17:20 AM

← General Overview →

Contents