# Creating a Payment Nonce

A nonce is known in the commerce and blockchain industries as an abbreviation of a "number used once". For Poynt Collect, this number is added to an encrypted block that acts as the first security layer for payment processing requests.

TIP

If you wish to send a receipt to the customer, you must set the emailReceipt attribute to true and provide the recipient email ID in the receiptEmailAddress section.

# collect.getNonce

This first endpoint allows you to obtain a nonce from the GoDaddy Poynt's API service to use in future API calls. To get the nonce back from collect.getNonce, you can refer to event listeners.

TIP

You can pass customer data directly to the getNonce method instead of collecting it in the payment form if you already have it. Note that data passed to the getNonce method takes priority over data entered by the customer in the payment form if you use both.

The code block shown below is the expected object to get the nonce.

NoncePayload Interface:

interface NoncePayload {
  firstName?: string;
  lastName?: string;
  emailAddress?: string;
  phone?: string;
  zipCode?: string;
  line1?: string;
  line2?: string;
  city?: string;
  territory?: string;
  countryCode?: string; // must be a valid country code in ISO 3166-1 format
  shippingLine1?: string;
  shippingLine2?: string;
  shippingCity?: string;
  shippingTerritory?: string;
  shippingZip?: string;
}

interface NonceEvent {
  data: {
    nonce: string;
    zipCode?: string;
    firstName?: string;
    lastName?: string;
    emailAddress?: string;
    phone?: string;
    line1?: string;
    line2?: string;
    city?: string;
    territory?: string;
    countryCode?: string;
    shippingLine1?: string;
    shippingLine2?: string;
    shippingCity?: string;
    shippingTerritory?: string;
    shippingZip?: string;
  };
}

Example:

const payload: NoncePayload = {
  emailAddress: "test@test.test",
};

collect.getNonce(payload);

collect.on("nonce", event: NonceEvent => {
// handle nonce event
});

TIP

If you would like to see this code in action, you can refer to our Code Samples section to see a complete example of a Poynt Collect integration using HTML.

# Charging a Nonce

Once you have obtained a validated nonce, it will allow you to process a charge with it. This request should originate from your server and use the same OAuth2 flow described below.

# Understanding Transaction Actions

The action field in the request body determines how the transaction will be processed:

# SALE Action

Use "action": "SALE" when you want to immediately capture the transaction:

Funds are authorized and captured in a single step
Settlement occurs automatically during the merchant's settlement cycle
Ideal for immediate delivery of goods or services

# AUTHORIZE Action

Use "action": "AUTHORIZE" when you want to control the capture separately:

Only verifies and reserves funds on the customer's payment method
Requires a subsequent capture operation to collect the funds
Useful for pre-orders, backorders, or when the final amount might change

# authOnly Parameter Behavior

The authOnly boolean attribute controls the capture behavior for AUTHORIZE transactions:

If authOnly=true: Explicit manual operation is required to capture funds
- The authorization remains open until you manually create a CAPTURE transaction
- No automatic capture will occur during settlement
- Provides complete control over when funds are captured
If authOnly=false or the parameter is missing: Automatic capture is enabled
- You can still manually capture the transaction at any time
- If not manually captured, the authorization will be automatically captured during the merchant's settlement time
- Ensures transactions don't remain indefinitely in an authorized state

Note: Authorizations typically expire after 7 days (varies by card network), so ensure you capture funds before the authorization expires.

TIP

The storeId value can be obtained by doing a GET call to the stores endpoint:

GET /businesses/{businessId}/stores To obtain the stores under a specific business.

Note: The storeDeviceId field does not need to be provided in your request, as it is automatically determined by internal logic.

Request URL: https://services.poynt.net/businesses/{businessId}/cards/tokenize/charge
Request method: POST
Request headers: Authorization: bearer ACCESS_TOKEN

Request body:

{
  "action": "<SALE/AUTHORIZE>",
  "context": {
    "businessId": "807v27cf-5e7d-4158-bd32-b27e4d3ce038",
    "storeId": "b3v6cc9b-40bd-413e-b3e0-8e0355516c00"
  },
  "amounts": {
    "transactionAmount": 300,
    "orderAmount": 300,
    "currency": "USD"
  },
  "fundingSource": {
    "nonce": "<payment nonce>"
  },
  "emailReceipt" : true,
  "receiptEmailAddress" : "joe@example.com"
}

Response body:

{
  "createdAt": "2020-10-29T18:15:18Z",
  "updatedAt": "2020-10-29T18:26:56Z",
  "context": {
    "businessType": "TEST_MERCHANT",
    "transmissionAtLocal": "2020-03-30T16:55:29Z",
    "storeDeviceId": "urn:tid:12345678-1234-1234-12345789012",
    "mcc": "1234",
    "source": "INSTORE",
    "businessId": "12345678-1234-1234-12345789012",
    "storeId": "12345678-1234-1234-12345789012"
  },
  "fundingSource": {
    "debit": false,
    "card": {
      "cardBrand": {
        "createdAt": "2020-04-15T04:35:31Z",
        "scheme": "VISA",
        "logoUrl": "",
        "displayName": "Visa",
        "id": "11111111-1234-1234-12345789012"
      },
      "type": "VISA",
      "expirationMonth": 00,
      "expirationYear": 0000,
      "id": 000000,
      "numberFirst6": "000000",
      "numberLast4": "0000",
      "numberMasked": "000000******0000",
      "numberHashed": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
      "serviceCode": "101",
      "cardId": "11111111-1234-1234-12345789012"
    },
    "entryDetails": {
      "customerPresenceStatus": "MOTO",
      "entryMode": "KEYED"
    },
    "type": "CREDIT_DEBIT",
    "nonce": "<payment nonce>"
  },
  "customerUserId": 0000,
  "processorResponse": {
    "approvedAmount": 300,
    "emvTags": {
      "0x8A": "3030"
    },
    "processor": "ELAVON",
    "acquirer": "ELAVON",
    "status": "Successful",
    "statusCode": "AA",
    "statusMessage": "APPROVAL",
    "transactionId": "0000000",
    "approvalCode": "00000",
    "batchId": "000"
  },
  "action": "<SALE/AUTHORIZE>",
  "amounts": {
    "transactionAmount": 300,
    "orderAmount": 300,
    "tipAmount": 0,
    "cashbackAmount": 0,
    "currency": "USD"
  },
  "status": "<AUTHORIZED/DECLINED>",
  "id": "c5d3730e-3774-4af6-b513-592249771092"
}

← reCAPTCHA Integration Payment Token →