# 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.

TIP

The values for storeId and storeDeviceId can be obtained by doing a GET call to the businessId endpoint.

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

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",
    "storeDeviceId":"urn:tid:a9f18c08-eb53-31b3-b3c9-e1aaf334gd3f",
  },
  "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 →