Skip to main content

Using Paylinks

Pre-requisites​

  1. An account on NGnair.
  2. An active merchant account. You will see an active status for ready-to-use accounts.
  3. An API Key. If you don't have one, follow the steps in the API Keys guide.

API Request​

Create a Paylink - Request (curl)
curl -X 'POST' \
  'https://demo-be.ngnair.com/api/gateway/createCheckoutData' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "groupID": "string",
  "token": "string",
  "data": {
    "form": {
      "pricing": {
        "methodVerifyOrProcess": "process",
        "lineItems": [
          {
            "productId": "string",
            "product": {
              "sku": "string",
              "name": "string",
              "description": "string",
              "price": 0,
              "isRecurring": true,
              "recurringMode": "string",
              "recurringInterval": 0,
              "recurringFrequency": 0,
              "recurringTotalCycles": 0,
              "recurringTrialDays": 0,
              "recurringSetupFee": 0,
              "recurringRefundable": true
            },
            "amount": 0,
          }
        ],
        "amount": 0,
        "tip": 0,
        "tipType": "fixed",
        "tax": 0,
        "taxType": "fixed",
        "discountCodes": ["string"],
        "shipping": 0
      },
      "meta": {
        "dynamic": {
          "discountCodes": ["string"],
          "paymentType": "card",
          "tip": {
            "amount": 0,
            "type": "percentage"
          },
          "quantityAmounts": [
            {
              "id": "string",
              "quantity": 0
            }
          ]
        },
      },
      "allowEdit": true,
      "allowExtraDiscount": true,
      "allowTip": true,
      "disableCC": true,
      "disableACH": true,
      "validUntil": "string",
      "referenceID": "string",
      "onSuccessURL": "string",
      "onFailureURL": "string",
      "customerID": "string",
      "customerPaymentID": "string",
      "prefilledAddress": {
        "email": "string",
        "phone": "string",
        "country": "string",
        "state": "string",
        "city": "string",
        "zip": "string",
        "address": "string",
        "nameOnCard": "string"
      },
      "disableCustomAddress": true,
      "disableCustomPayment": true,
      "disablePreselectCard": true
    }
  }
}'

To breakdown the request:

  1. Base URL and Headers: https://demo-be.ngnair.com/api/gateway/createCheckoutData

    • This is the endpoint for creating a new paylink. The root url may change based on the environment (sandbox, production).
    • The headers are set to accept JSON data.

  2. Request Body:

    • groupID: Your merchant group identifier
    • token: Your API key token. Specifically your private token.
    • data.form: Contains the payment form configuration
      • pricing: Payment details
        • methodVerifyOrProcess: Set to "process" for direct processing
        • lineItems: Array of products/services. You can either:
          • Provide a productId to fetch product data from server, or
          • Include a complete product object with details
          • Note: If both lineItems and amount are provided, lineItems takes priority
          • productId: Unique identifier for the product (if fetching from server)
          • product: Product details
            • sku: Stock keeping unit
            • name: Product name
            • description: Product description
            • price: Product price
            • isRecurring: Whether this is a subscription product
            • recurringMode: Subscription mode (e.g., "MONTHLY", "YEARLY"). Omittable, will be treated as DAILY.
            • recurringInterval: Interval between recurring payments
            • recurringFrequency: Number of times per interval
            • recurringTotalCycles: Total number of billing cycles
            • recurringTrialDays: Number of trial days
            • recurringSetupFee: One-time setup fee
            • recurringRefundable: Whether setup fee is refundable
          • amount: Quantity of the item
        • amount: Total transaction amount
        • tip: Tip amount (optional)
        • tipType: "fixed" or "percentage"
        • tax: Tax amount (optional)
        • taxType: "fixed" or "percentage"
        • discountCodes: Array of applicable discount codes
        • shipping: Shipping cost (optional)
      • meta: Additional metadata
        • dynamic: Dynamic form settings
          • discountCodes: Dynamic discount codes
          • paymentType: Preferred payment method
          • tip: Dynamic tip settings
          • quantityAmounts: Dynamic quantity settings
        • reference: Reference information
      • allowEdit: Enable/disable payment form editing
      • allowExtraDiscount: Enable/disable discount input
      • allowTip: Enable/disable tipping
      • disableCC: Disable credit card payments
      • disableACH: Disable ACH payments
      • validUntil: Expiration date for the paylink
      • referenceID: Your internal reference number
      • onSuccessURL: Redirect URL after successful payment
      • onFailureURL: Redirect URL after failed payment
      • customerID: Existing customer ID
      • customerPaymentID: Existing customer payment method ID
      • prefilledAddress: Pre-filled customer information
      • disableCustomAddress: Disable address editing
      • disableCustomPayment: Disable custom payment method entry
      • disablePreselectCard: Disable card preselection

Response​

Create a Paylink - Response
{
  "data": {
    "payLinkID": "string",
    "paymentData": "string",
    "token": "string",
    "groupID": "string",
    "url": "string"
  },
  "token": "string",
  "groupID": "string",
  "url": "string"
}

To breakdown the response:

  1. Response Body:
    • data: Contains the paylink details
      • paymentData: Encrypted payment information
      • token: The public key that will be used to verify the paymentData
      • groupID: Your merchant group identifier
      • url: The payment URL to share with customers
    • token: Same as data.token
    • groupID: Same as data.groupID
    • url: Same as data.url

To create a subscription paylink, you'll need to set the recurring parameters in the product object. Here's an example:

Subscription Paylink Example
{
  "groupID": "MID-840-04-2025-000003",
  "token": "your-private-token",
  "data": {
    "form": {
      "pricing": {
        "methodVerifyOrProcess": "process",
        "lineItems": [
          {
            "product": {
              "sku": "SUBSCRIPTION-001",
              "name": "Premium Monthly Plan",
              "description": "Access to premium features",
              "price": 2999,
              "isRecurring": true,
              "recurringMode": "MONTHLY",
              "recurringInterval": 1,
              "recurringFrequency": 1,
              "recurringTotalCycles": 12,
              "recurringTrialDays": 7,
              "recurringSetupFee": 0,
              "recurringRefundable": false
            },
            "amount": 1
          }
        ],
      },
      "referenceID": "SUB123",
      "onSuccessURL": "https://your-store.com/success",
      "onFailureURL": "https://your-store.com/failed"
    }
  }
}

In this example:

  • The subscription is billed MONTHLY at $29.99
  • It includes a 7-day free trial
  • The subscription runs for 12 months
  • No setup fee is charged
  • The setup fee is not refundable
  • The recurringMode is set to "MONTHLY" (can also be "YEARLY" or omitted)

Note: The recurringMode parameter is optional. When omitted, the system will use the default recurring mode based on your account settings.

You can create a paylink with pre-filled customer information to streamline the checkout process:

Prefilled Paylink Example
{
  "groupID": "MID-840-04-2025-000003",
  "token": "your-private-token",
  "data": {
    "form": {
      "pricing": {
        "methodVerifyOrProcess": "process",
        "lineItems": [
          {
            "product": {
              "sku": "PRODUCT-001",
              "name": "Premium Product",
              "description": "Product description",
              "price": 2999
            },
            "amount": 1
          }
        ],
      },
      "prefilledAddress": {
        "email": "customer@example.com",
        "phone": "+1234567890",
        "country": "US",
        "state": "CA",
        "city": "San Francisco",
        "zip": "94105",
        "address": "123 Main St",
        "nameOnCard": "John Doe"
      },
      "disableCustomAddress": true,
      "referenceID": "ORDER123",
      "onSuccessURL": "https://your-store.com/success",
      "onFailureURL": "https://your-store.com/failed"
    }
  }
}

In this example:

  • Customer information is pre-filled
  • Address editing is disabled
  • The customer can still modify their payment information

To create a paylink for an existing customer using their saved payment method:

Existing Customer Paylink Example
{
  "groupID": "MID-840-04-2025-000003",
  "token": "your-private-token",
  "data": {
    "form": {
      "pricing": {
        "methodVerifyOrProcess": "process",
        "lineItems": [
          {
            "product": {
              "sku": "PRODUCT-001",
              "name": "Premium Product",
              "description": "Product description",
              "price": 2999
            },
            "amount": 1
          }
        ],
      },
      "customerID": "CUST-123",
      "customerPaymentID": "PAY-456",
      "disableCustomPayment": true,
      "referenceID": "ORDER123",
      "onSuccessURL": "https://your-store.com/success",
      "onFailureURL": "https://your-store.com/failed"
    }
  }
}

In this example:

  • Uses an existing customer's ID
  • Uses their saved payment method
  • Disables custom payment method entry
  • The customer can only use their saved payment method

Note: You can fetch the list of customers and their payment methods using the customer fetch list and customer get endpoints. The customer ID and payment method ID are also available in the webhook event payment_success.

Important Notes​

  • We highly recommend the usage of referenceID to track the payment against your own system. You can use it to see if the payment was successful or not. For example, to check if a customer already paid for your product, listen for a webhook event with the referenceID. If it has the 'payment_success' status, then the payment was successful, also take note if the 'payment_failed' status is present or a 'payment_refund' was made.

Next Steps​

To intercept if the payment was succesful or failed, we will send a webhook notification to the webhook endpoint you will provide. You can find more information about this in the Webhooks guide.