Appearance

Use Tokenized Data ​

After successfully receiving the tokenized card data, you can use it to make payment transactions via the PayNetWorx Payment API.

Overview ​

The tokenized card data allows you to process payments without handling sensitive card information directly. The token can be used for various payment operations while maintaining PCI compliance.

Response Format ​

The tokenized data you received has the following structure:

ts
{
  payment_session: {
    /** Format: KSUID */
    payment_session_request_id: string
  }
  tokenized_card: {
    approved: boolean
    /** Present if approved = true */
    cvc_check?: string
    /** Present if approved = true */
    token?: {
      token_id: string
      token_name: string
    }
  }
}

Using the Token with Payment API ​

Once you have the token_id, you can use it to make payment requests to the PayNetWorx Payment API.

Example: Authorization Capture ​

js
async function processPayment(tokenData) {
  const tokenId = tokenData.token.token_id;

  const paymentRequest = {
    Amount: {
      Total: 100.0,
      Tax: 8.0,
      Currency: "USD",
    },
    PaymentMethod: {
      Card: {
        Token: {
          TokenID: tokenId,
        },
      },
    },
    TransactionType: "AUTHCAPTURE",
  };

  try {
    const response = await fetch("https://{{PNX_API_URL}}/v0/transaction/authcapture", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: "Basic " + btoa("{{YOUR_API_KEY}}:"),
      },
      body: JSON.stringify(paymentRequest),
    });

    const result = await response.json();

    if (result.Approved) {
      console.log("Payment approved:", result);
      showSuccessMessage("Payment successful!");
    } else {
      console.error("Payment declined:", result);
      showErrorMessage("Payment was declined. Please try another payment method.");
    }
  } catch (error) {
    console.error("Payment error:", error);
    showErrorMessage("An error occurred processing your payment.");
  }
}

Token Properties ​

  • token_id: The unique identifier for the tokenized card. Use this in Payment API requests.
  • token_name: A human-readable description of the card (e.g., "Visa ending in 1234"). Use this for display purposes.
  • cvc_check: Indicates whether the CVC check passed during tokenization.

Available Payment Operations ​

You can use the token with various Payment API operations:

  • AUTHCAPTURE - Authorization and capture in a single step
  • AUTH - Authorization only (capture later)
  • VERIFY - Verify card without charging

Token Lifecycle ​

Token Management

  • Reusable: Tokens can be used for multiple transactions
  • Storage: Store tokens securely in your database for recurring payments
  • Security: Never store actual card numbers - always use tokens
  • Expiration: Tokens remain valid until the associated card expires or is deleted

Best Practices ​

  1. Server-Side Processing: Always make payment requests from your server, never from client-side JavaScript
  2. Error Handling: Implement comprehensive error handling for declined transactions
  3. User Feedback: Provide clear feedback to users about payment status
  4. Logging: Log payment attempts and results for debugging and reconciliation
  5. PCI Compliance: Even with tokenization, follow PCI DSS requirements for your integration

Complete Flow Example ​

js
// Complete flow from tokenization to payment
window.addEventListener("message", async (event) => {
  // Validate origin - use appropriate URL for your environment
  const allowedOrigin = "https://{{PNX_HOSTED_FORM_URL}}"; // QA: hosted-payments-qa.paynetworx.cloud, Production: hosted-payments.paynetworx.cloud

  if (event.origin !== allowedOrigin) {
    return;
  }

  if (event.data?.type === "pnx-tokenized-payment-info") {
    const tokenizedData = event.data.payload;

    if (tokenizedData.tokenized_card.approved) {
      // Show loading state
      showLoadingIndicator();

      try {
        // Process payment with token
        await processPayment(tokenizedData.tokenized_card);

        // Show success
        showSuccessMessage("Payment completed successfully!");

        // Redirect or update UI
        window.location.href = "/order-confirmation";
      } catch (error) {
        // Handle error
        console.error("Payment failed:", error);
        showErrorMessage("Payment failed. Please try again.");
      } finally {
        hideLoadingIndicator();
      }
    } else {
      showErrorMessage("Card validation failed. Please check your information.");
    }
  }
});

For detailed information about Payment API operations, see:

Support ​

If you encounter issues or have questions about using tokenized data, please refer to: