Payment Token | Documentation

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

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.

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

NOTE

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

Request URL: https://services.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.

# 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": {
    "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"
}

← Payment Nonce Event Listeners →