Create Payment Invoice

Creates a dynamic invoice tied to a specific payment link template, allowing merchants to pass customer and product details.

POST https://checkout-server.apara.com/checkout/payment-link/invoice

The API URLs are the same for Sandbox and Production. Only the API keys change.

Headers

Header	Required	Value
`Content-Type`	✅	`application/json`
`x-api-key`	✅	Your Public Key (`pk_...`)
`x-timestamp`	✅	Current time in milliseconds since the Unix epoch
`x-signature`	✅	HMAC-SHA256 hash of the request
`X-Api-Version`	✅	`v1`
`x-trace-id`	❌	Optional identifier for request tracking

HMAC Signature

The message is the HTTP method, API path, timestamp and JSON request body concatenated together, signed with HMAC-SHA256 using your secret key.

const method = 'POST';
const path = '/checkout/payment-link/invoice';
const timestamp = Date.now().toString();
const body = JSON.stringify(requestBody);

const message = method + path + timestamp + body;
const signature = crypto.createHmac('sha256', SECRET_KEY)
  .update(message)
  .digest('hex');

Body Parameters

Parameter	Type	Required	Description
`paymentLinkId`	string	✅	Unique ID of the payment link template created in the Merchant Dashboard (pattern `^[a-f0-9]{24}$`)
`amount`	string	✅	Payment amount, passed as a string to avoid floating-point precision errors (pattern `^\d+(\.\d{1,2})?$`)
`currency`	string	✅	Three-letter currency code (ISO 4217) — USD, EUR, GBP, JPY, AUD, CAD, CHF, CNY, INR, SGD, HKD, NZD, SEK, KRW, NOK, MXN, BRL, ZAR, RUB, TRY and others
`productDetails`	object	✅	Product information shown at checkout
`individual`	object	✅	Customer information
`successRedirectUrl`	URI	✅	URL to redirect the user to after a successful payment
`failureRedirectUrl`	URI	✅	URL to redirect the user to after a failed payment
`customerOrderId`	string	✅	Unique order identifier from the merchant's system (1–100 characters)

See SDK Reference → Parameters for the full field breakdown of productDetails, individual and address.

Example Request

{
  "paymentLinkId": "69c39577e1a0100cf92c3406",
  "amount": "49.99",
  "currency": "USD",
  "productDetails": {
    "name": "Premium Annual Plan",
    "description": "12-month access to all premium features",
    "imageUrl": "https://example.com/product-image.png"
  },
  "individual": {
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "jane@example.com"
  },
  "successRedirectUrl": "https://yourapp.com/payment/success",
  "failureRedirectUrl": "https://yourapp.com/payment/failure",
  "customerOrderId": "order-12345"
}

Example Response

{
  "success": true,
  "data": {
    "paymentUrl": "https://checkout-widget.apara.com/checkout/payment-link/..."
  }
}

Response Codes

Code	Meaning
`200`	Invoice created successfully — returns the payment URL for customer checkout
`400`	Bad Request — invalid request data, missing required fields, or validation errors
`401`	Unauthorized — invalid API key, missing/invalid timestamp, or invalid HMAC signature
`403`	Forbidden — API key inactive or expired, IP not whitelisted, or environment not authorized
`404`	Not Found — payment link ID does not exist or has been deleted
`500`	Internal Server Error — unexpected server error during invoice creation

Was this page helpful?