# Getting Started

As a payment processing solution, Poynt Collect must be installed within your site's code following a series of steps. The steps to follow are determined by the normal flow of the service, starting with the installation of the source code. However, you must keep in mind the are a couple of important prerequisites.

# Prerequisites

# Configuration Steps

  1. Set up Poynt Collect

  2. Create a Nonce

  3. Create a Token

  4. Charge a Token

  5. Handle success, error and testing cases using Event Listeners.

TIP

Please remember that this guide shows the URLs for the staging environment. Make sure to change to production URLs when going live. The main difference between a staging URL and a production URL is the ote indicator.

Staging URL Production URL
https://ote.poynt.net/snippet/poynt-collect/bundle-ote.js https://poynt.net/snippet/poynt-collect/bundle.js
https://services-ote.poynt.net https://services.poynt.net

# Setting up Poynt Collect

  1. To begin working with Poynt Collect, you must select and insert one of the following scripts on your webpage's frontend.

First input option:

<script
  type="text/javascript"
  src= "https://ote.poynt.net/snippet/poynt-collect/bundle-st.js"
  async
  defer
></script>

Second input option:

<script>
  const poyntCollect = document.createElement("script");
  poyntCollect.src = "https://ote.poynt.net/snippet/poynt-collect/bundle-st.js";
  poyntCollect.async = true;
  poyntCollect.onload = () => {
  // put the upcoming collect initialization steps and create transaction steps here
  };
  document.head && document.head.appendChild(poyntCollect);
</script>
  1. Create an instance of Poynt Collect with the following JavaScript code. You can also find the API key under Business Profile in the Poynt HQ portal.
var collect = new TokenizeJs("<businessId>", "<applicationId>");
  1. To add the credit card form to your page, create an empty DOM container with a unique ID and send the ID back to Poynt Collect.

For example:

<html>
<head></head>
<body>
<div id="card-element">
<!-- Credit card form iFrame will be inserted here -->
</div>
<button>Pay</button>
</body>
</html>
  1. Once your page has loaded, use your Poynt Collect instance to mount the iFrame to your container.
collect.mount("card-element", document, options);

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

# 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

Please note that any field with a question mark '?' is optional.

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

Input:

interface NoncePayload {
  businessId: string;
}
collect.getNonce(noncePayload);

Output:

{ "nonce" : <token> }

# Creating a Token

The nonce obtained will be used in the /tokenize call to get a payment token, which is a JWT. As a part of the response, GoDaddy Poynt will send you back the AVS and CVV response that the processor has provided.

You must save the token by interpreting the processor validation response. The tokenize output will also contain the status of the payment token to identify the processor validation status.

To obtain the ACCESS_TOKEN, please refer to the linked documentation.

TIP

Remember to place your businessId in the {businessId} section in the Request URL

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

Request body:

{
  "nonce": "12345678-1234-1234-12345789012"
}

Response body:

{
  "card": {
    "type": "VISA",
    "status": "ACTIVE",
    "expirationMonth": 0,
    "expirationYear": 00,
    "id": 000000,
    "numberFirst6": "000000",
    "numberLast4": "0000",
    "numberMasked": "000000******0000",
    "numberHashed": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "cardId": "11111111-1234-1234-12345789012"
  },
  "applicationId": "urn:aid:12345678-1234-1234-12345789012",
  "token": "<token>",
  "paymentToken": "<Payment JWT>",
  "avsResponse": {
    "addressResult": "MATCH",
    "postalCodeResult": "MATCH"
  },
  "cvvResponse": "MATCH",
  "status" : "ACTIVE"
}

If the processor is unable to verify a card, which can be due to an invalid card, the tokenize sample output data will be the folllowing:

{
  "card": {
    "type": "VISA",
    "status": "ACTIVE",
    "expirationMonth": 00,
    "expirationYear": 00,
    "id": 000000,
    "numberFirst6": "000000",
    "numberLast4": "0000",
    "numberMasked": "000000******0000",
    "numberHashed": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "cardId": "11111111-1234-1234-12345789012"
  },
  "applicationId": "urn:aid:12345678-1234-1234-12345789012",
  "avsResponse": {
    "addressResult": "UNAVAILABLE",
    "postalCodeResult": "UNAVAILABLE"
  },
  "cvvResponse": "NOT_APPLICABLE",
  "status" : "INVALID"
}

# Charging a Token

Once you have obtained a validated token, 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.

The payment token JWT will be used to charge the card.

TIP

To send a receipt to the customer set the emailReceipt attribute to true and provide the recipient email ID in receiptEmailAddress.

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

Request body:

{
  "action": "<SALE/AUTHORIZE>",
  "context": {
    "businessId": "12345678-1234-1234-12345789012",
    "storeId": "01234567-1234-1234-12345789012",
    "storeDeviceId": "urn:aid:12345678-1234-1234-12345789012",
  },
  "amounts": {
    "transactionAmount": 300,
    "orderAmount": 300,
    "currency": "USD"
  },
  "fundingSource": {
    "cardToken": "<payment JWT>"
  },
  "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:aid: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",
        "cardToken": "<payment JWT>"
    },
    "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"
}

# Event Listeners

An event is an important part of any operation. Web pages respond according to an event that has recently occurred. Some events are generated by users, and some are generated by API’s.

A Poynt Collect Event Listener is a procedure in JavaScript that waits for an event to occur. A simple example of an event is a user clicking the mouse or pressing a key on the keyboard.

Below are all the event listeners supported by Poynt Collect.

# Ready

This event listener is normally used to guarantee that Poynt Collect is ready and functional.

collect.on("ready", event => {
// handle ready event, proceed.
});

# getNonce

This code will add an event listener for whenever you get a nonce.

collect.on("nonce", function(nonce) {
// do something with the nonce
});

# error

Placing this on your code will automatically add a listener to get notified of any errors on the form.

collect.on("error", event => {
// handle error event
});

TIP

If you want to learn more about Poynt Collect's features, check out our section for Advanced Topics.

Last Updated: 5/10/2022, 10:14:16 AM