Documentation

# 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

  • Active Developer Account

# Configuration Steps

  1. Setting up Poynt Collect

  2. Creating a Nonce

  3. Creating a Payment Token

  4. Charging a Payment Token

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

TIP

This guide shows the URLs for the staging environment. Make sure to change to production URLs when going live. For fixed versions refer to version history

Development URL Staging URL Production URL
https://cdn.poynt.net/ci/collect-ci.js https://cdn.poynt.net/ote/collect-ote.js https://cdn.poynt.net/collect.js
https://services-ci.poynt.net 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.

Example 1:

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

Example 2:

<script>
  const poyntCollect = document.createElement("script");
  poyntCollect.src = "https://cdn.poynt.net/ote/collect-ote.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 JavaScript code shown below.
var collect = new TokenizeJs("<businessId>", "<applicationId>");

You can find your appId, businessId, and API key under the Business Settings tab in the Poynt HQ portal.

App Keys

The Application ID section in PoyntHQ will follow the structure shown below:

0bc36d74-a978-55c6-dbce-a82735f8aeed=urn:aid:7a4e2ae7-99e9-40df-jiv5-t09b76543bc5

The separation between businessId and applicationId is marked by the equal (=) sign.

businessId Separation applicationId
bc36d74-a978-55c6-dbce-a82735f8aeed = urn:aid:7a4e2ae7-99e9-40df-jiv5-t09b76543bc5
  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);

# Methods

A method is a specific block of code that only runs when you call it. Poynt Collect Methods are used to perform certain actions, and they are also known as functions. Below is the primary method for Poynt Collect.

# collect.mount

collect.mount(domElementId, document, options);

  • domElementId (string): This string is referencing the DOM element where the payment form is added by Poynt.

  • document: This is a constant element within the JS code.

  • options (object): These are the options for the customization of the payment form

Example:

const options = {
  iFrame: {
    width: "500px",
    height: "400px",
    border: "1px",
    borderRadius: "4px",
    boxShadow: "0 7px 14px rgba(50, 50, 93, 0.1), 0 3px 6px rgba(0, 0, 0, 0.08)"
  },
  style: {
    theme: "default" // theme: "customer", (alternative default theme)
  },
  displayComponents: {
    firstName: false, // toggle these to true if you wish to show the forms
    lastName: false,
    emailAddress: false,
    submitButton: false,
    showEndingPage: true // controls ending page,
    labels: false
  },
  fields: {
    emailAddress: customerEmail,
    firstName: firstName,
    lastName: lastName
  },
  additionalFieldsToValidate: ["firstName", "lastName", "zip"] // fields to validate
}

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

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.

# Creating a Payment 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 Payment 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:tid: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: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",
        "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: 12/19/2022, 4:56:11 PM

← Transaction Pricing →

Contents